Skip to content

docs: close gaps in the live session order - #40

Merged
uniqueg merged 7 commits into
devfrom
docs/38-live-session-order
Nov 17, 2026
Merged

uniqueg merged 7 commits into
devfrom
docs/38-live-session-order

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Closes the gaps that a dress rehearsal of T1-T5 on the mock found in the order for a live session (one item per point of #38):

  1. Terminal 1 builds the image first (docker compose -f compose.lslogin.yaml build), so that an image from before a git pull doesn't run.
  2. The expiry session goes first: the callback only listens during a login (up to 5 minutes), so login exp and login user mustn't overlap. Run its first three lines, start wait-expiry, then open the main session (index and T4).
  3. Revoking consent ends both sessions' grants, so it comes last, after the expiry session's "Binding and reuse". New section "Revoking consent, last" at the end of T5, as it uses T5's newest refresh token r3: a refresh right after revoking and one 5 minutes later, one in the expiry session, and a record row.
  4. T1 "Hop 2: which form names the node": exchanges as the gateway with the node's ID in audience and in resource, its URL form, and both; show and call node; which TESTBED_TARGET_PARAM to set for T2-T5, including what resource-url does to the orchestrator variant. New record row.
  5. "Four or five clients"; the public-client variant is skipped without one, recorded as "not registered".
  6. Account B logs in on the session's machine, within 5 minutes of login b; plan a 10-minute slot (T3 and "Prepare" step 1).
  7. T4's 10-minute pause is counted next to the expiry hour.
  8. Both record files are named, and quit in each session.
  9. What to do if only real accounts can be used: tell the holders what is recorded and go on only with their agreement, records stay out of the repository and are deleted, placeholders for sub, names and emails (client registration, linked from configuration).
  10. T3 "Runs against": B's 403 on the mock needs --mock-user outside.

Stacked on #39 (it touches the same lines of T1 and T3): merge #39 first. Until then, this diff also shows #39's commits; only the last two commits (docs: close gaps in the live session order, docs: fix the revocation check and node probes) belong here.

Verification

  • pytest: 253 passed, coverage 100%. tests/test_docs.py parses every new tb> line.
  • mkdocs build --strict (anchors validated): passed.
  • pre-commit run --all-files: passed, with gitleaks and actionlint skipped locally (Go toolchain can't be downloaded in the sandbox; no workflow changed). CI runs them.
  • The end-to-end run in CI runs the new tb> lines of T1, T4 and T5 against the mock.
  • CI: all checks passed on afae521 (Lint, Test, Docs, End-to-end tests, CI passed, Sourcery review, Read the Docs).

Light lane: docs only. The reviewer subagents were skipped; I reviewed the diff myself against each point of #38. Sourcery's findings on the docs (revocation from a spent token, the expiry session unchecked, a missing probe) were fixed in afae521.

Declined review findings

Open questions

None.

Closes #38

🤖 Generated with Claude Code

Summary by Sourcery

Make the live test-session documentation executable end to end by defining the correct order, timing, account setup, target selection, recording, and cleanup procedures.

New Features:

  • Document a complete live-session order covering session startup, token expiry, node target forms, account timing, and consent revocation.

Bug Fixes:

  • Close documented gaps that could cause stale images, overlapping logins, invalid session sequencing, incomplete revocation checks, or incorrect mock-account behavior.

Enhancements:

  • Clarify client registration requirements, result handling, recorded claims, public-client availability, and expected outcomes across T1–T5.

Documentation:

  • Add guidance for using real accounts safely when test accounts are unavailable, including consent, placeholders, and result cleanup.

uniqueg and others added 5 commits November 17, 2026 22:43
The node read entitlements only from the user info claim
`entitlements`, as the operator's docs say. LS Login released them to
other clients of the same issuer in `eduperson_entitlement`
(generic-issues#46). The node would then refuse account A with
`refused: entitlement`, which looks exactly like a missing group
release in T3.

The node now reads every claim in `TESTBED_ENTITLEMENT_CLAIMS`
(default `entitlements,eduperson_entitlement`) and takes the union of
their values. Its report names the claims it found
(`entitlement_claims` in the session's rows), and `discovery` shows
`scopes_supported` and `claims_supported`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Document `TESTBED_ENTITLEMENT_CLAIMS` (configuration, template), what
generic-issues#46 observed, and what T1 and T3 record: the entitlement
scopes and claims the provider lists, the claim and scope the values
came with, and a one-off login with the scope `eduperson_entitlement`
if user info shows neither claim.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A claim of another type made the whole result an error, so a user
whose entitlement was in the other claim got 502. Now such a claim is
skipped and named in `error`, `null` counts as absent, and `claims` is
in every result. Document the behaviour, the trust in both claims, and
the claim fields of `discovery` and `call` (review findings).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A skipped claim now shows as `entitlements_error` on an allowed
request, too. Say so in troubleshooting and the command reference, test
that the session's rows carry it, and update the policy's docstring.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Found in a dress rehearsal of T1-T5 on the mock:

- build the image before starting the services against LS Login;
- start the expiry session first, as the callback only listens during
  a login, and count T4's 10-minute pause;
- revoke consent only after both sessions are done, with commands for
  the check (new T4 section);
- T1 tries each form that names the node, and says which
  TESTBED_TARGET_PARAM to set for T2-T5;
- four or five clients; skip the public variant without one;
- account B logs in on the session's machine; plan the slot;
- name both record files;
- what to do if only real accounts can be used;
- B's 403 on the mock needs --mock-user outside.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg added this to the BioHackEU26 milestone Nov 17, 2026
@uniqueg uniqueg self-assigned this Nov 17, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Documentation

Update the live-session order and privacy guidance, covering account setup, image builds, expiry and consent timing, record cleanup, and mock-specific behavior.

  • docs/setup/client-registration.md L15-20
  • docs/setup/configuration.md L58
  • docs/tests/index.md L20-30 (+3 small edits)
  • docs/tests/t3-groups.md L7, L53
  • docs/tests/t4-lifetime.md L84
  • docs/tests/t5-attribution.md L51-65, L83

Document the T1 node-target probes, how to choose TESTBED_TARGET_PARAM, and when to skip the public-client variant.

  • docs/tests/t1-call-chain.md L70-84 (+3 small edits)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@read-the-docs-community

read-the-docs-community Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

@uniqueg
uniqueg marked this pull request as ready for review November 17, 2026 23:07
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Linked issues

Checked at commit 9455b8b

#38 docs: close gaps in the live session order · 10 of 10 met

# Requirement Status Notes
1 Build the image first in Terminal 1 ✅ Met The live-session steps build before starting the services.
2 Run the expiry session's first three lines and start wait-expiry before opening the main session ✅ Met The order explains the callback's five-minute login window and gives this sequence.
3 Revoke consent after both sessions' steps, and check refresh immediately and five minutes later ✅ Met T5 puts revocation last, after T4 binding and reuse, and documents refresh checks in both sessions.
4 Try the node's ID and URL forms, use show and call node on a working exchange, and set TESTBED_TARGET_PARAM for T2-T5 ✅ Met T1 includes all four combinations, including the node ID in resource, and explains the settings and orchestrator consequence.
5 Allow four or five clients; skip and record the public-client variant as not registered when absent ✅ Met T1 describes four or five clients and the skip and recording instruction.
6 Have account B log in on the session machine within five minutes, and plan about ten minutes ✅ Met The preparation step and T3 both explain the machine, timing, and slot.
7 Count T4's ten-minute pause next to the expiry hour ✅ Met The live-session preparation steps explicitly count the pause next to the expiry hour.
8 Name both record files and quit in each session ✅ Met The order names session.jsonl and expiry.jsonl and says to quit in each session.
9 Explain what to do if only real accounts can be used ✅ Met Client registration requires informing account holders and getting agreement, keeping records out of the repository and deleting them, and using placeholders.
10 Use --mock-user outside for B's 403 on the mock ✅ Met T3's mock instructions specify this option.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="src/testbed/settings.py" line_range="31" />
<code_context>
 TARGET_PARAMS = ("audience", "resource", "resource-url", "both")
+# The claim of AARC-G069 and the operator's Entitlements page, and the one that
+# LS Login released to other clients of the same issuer
+ENTITLEMENT_CLAIMS = ("entitlements", "eduperson_entitlement")


</code_context>
<issue_to_address>
**Unassigned users gain access**

When LS Login returns the required value in `eduperson_entitlement` from a source other than the assigned Perun group, `_entitlements` merges that value with `entitlements`, and `_apply_policy` accepts a matching value without checking its provenance, so the node returns 200 to a user who lacks the required group assignment.

Restrict authorization to a claim whose value is established by the required group assignment, or otherwise verify that provenance before allowing access.

Also at `src/testbed/service.py:143-154`.
</issue_to_address>

### Comment 2
<location path="src/testbed/settings.py" line_range="83" />
<code_context>
     algorithms: tuple[str, ...] = ("RS256",)
     token_types: tuple[str, ...] = ("at+jwt", "application/at+jwt")
     required_entitlement: str | None = None
+    entitlement_claims: tuple[str, ...] = ENTITLEMENT_CLAIMS
     target_param: str = "audience"
     exchange_scope: str | None = None
</code_context>
<issue_to_address>
**Positional settings callers misconfigure services**

When an external caller constructs `Settings` using the previous positional argument order, an existing caller passing `target_param` as the eighth positional `Settings` argument now assigns it to `entitlement_claims`; the target parameter falls back to `audience`, and the node iterates the supplied string as claim names, so calls use the wrong exchange target and entitlement claims.

Append `entitlement_claims` after the existing fields or make the new field keyword-only to preserve the prior positional order.
</issue_to_address>

### Comment 3
<location path="docs/tests/t4-lifetime.md" line_range="116" />
<code_context>
+Optional, and only after every other step of T1-T5, in both sessions: it ends the refresh tokens of both, as both log in account A with `tx-test-client` ([Can users see and revoke what a service holds?](index.md#can-users-see-and-revoke-what-a-service-holds)). In the profile of account A, revoke the consent of the client. Then, in the main session, refresh right away, and again 5 minutes later, so that a delayed revocation shows:
+
+```text
+tb> refresh rv1 --as client --from r2
+tb> refresh rv2 --as client --from r2
+```
</code_context>
<issue_to_address>
**Revocation check uses spent token**

When the provider rotates and invalidates refresh tokens during T5's `refresh r3 --from r2`, lS Login invalidates `r2` when T5 refreshes it into `r3`, but the revocation check still submits `r2`; `refresh rv1` is refused before consent revocation is tested, so the result does not show whether revocation ended the grant.

Use the latest refresh token (`r3`) for `rv1`, then use `rv1` for the second check if it rotated.
</issue_to_address>

### Comment 4
<location path="docs/tests/t4-lifetime.md" line_range="113" />
<code_context>

+### Revoking consent, last
+
+Optional, and only after every other step of T1-T5, in both sessions: it ends the refresh tokens of both, as both log in account A with `tx-test-client` ([Can users see and revoke what a service holds?](index.md#can-users-see-and-revoke-what-a-service-holds)). In the profile of account A, revoke the consent of the client. Then, in the main session, refresh right away, and again 5 minutes later, so that a delayed revocation shows:
+
+```text
</code_context>
<issue_to_address>
**One session’s grant goes unchecked**

When consent revocation affects the main session’s grant but leaves the expiry session’s refresh token usable, the revocation procedure refreshes only the main session’s `r2` token (`rv1` and `rv2`), so a refresh token from the expiry session that remains usable goes unnoticed and the record can imply that both sessions’ grants ended.

After revoking consent, attempt a refresh using a token held by each session and record both outcomes.
</issue_to_address>

### Comment 5
<location path="docs/tests/t1-call-chain.md" line_range="83" />
<code_context>

 Use test accounts only: sessions record their claims. If you need one, [Life Science Hostel accounts](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/1741881406/Using+Life+Science+Hostel+account) don't depend on an institution. To see what an account belongs to, see [Checking your membership](https://perunaai.atlassian.net/wiki/spaces/PERUN/pages/1742635055/Checking+your+membership). How to add one to a group depends on the group's managers.

</code_context>
<issue_to_address>
**URL-only setup blocks refresh test**

When only the URL form works in T1 and the operator follows the instruction to use `resource-url` for T2–T5, the instruction sets `TESTBED_TARGET_PARAM=resource-url` for T2–T5 when only the URL form works. T4 then exchanges a client token for the orchestrator using its URL, and tries to exchange that token as the orchestrator; because its `aud` contains only the URL, LS Login refuses the second exchange, so T4 cannot test whether an exchange returns a refresh token.

Document that T4's refresh-token-from-exchange check cannot run with URL-only audiences, and record it as blocked rather than attempting the second exchange.
</issue_to_address>

### Comment 6
<location path="docs/tests/t1-call-chain.md" line_range="75-77" />
<code_context>
+The gateway's own exchange names the node as `TESTBED_TARGET_PARAM` says, by default its bare client ID (`audience`). If the gateway's registration only lists the node's URL form, hop 2 fails with `refused: exchange`. Either way, try each form as the gateway:
+
+```text
+tb> exchange t1-node-id --as gateway --from to-gw --audience @node
+tb> exchange t1-node-url --as gateway --from to-gw --resource @node.url
+tb> exchange t1-node-both --as gateway --from to-gw --audience @node --resource @node.url
+tb> show t1-node-id
+tb> call node --token t1-node-id
</code_context>
<issue_to_address>
**Resource-only form goes undiscovered**

When LS Login accepts the node's bare client ID only in the `resource` parameter, the documented probes never try the bare client ID with `resource`, so none identifies the working form and the operator cannot select `TESTBED_TARGET_PARAM=resource` for T2–T5.

Add a probe that exchanges to the node using its bare client ID in `resource`, and explain how to use that result to set `TESTBED_TARGET_PARAM`.
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 6 findings to address first, and the node authorizes a user if the required entitlement appears in either configured user-info claim, and both claims are enabled by default. If eduperson_entitlement can contain values not derived from the intended group release, users may gain access without the required membership; reverting stops future grants but cannot undo access or data already exposed.

Blocking findings: src/testbed/settings.py:31, src/testbed/settings.py:83, docs/tests/t4-lifetime.md:116, docs/tests/t4-lifetime.md:113, docs/tests/t1-call-chain.md:83, and 1 more


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread src/testbed/settings.py Resolved
Comment thread src/testbed/settings.py Resolved
Comment thread docs/tests/t4-lifetime.md Resolved
Comment thread docs/tests/t4-lifetime.md Resolved
Comment thread docs/tests/t1-call-chain.md Resolved
Comment thread docs/tests/t1-call-chain.md Resolved
uniqueg and others added 2 commits November 18, 2026 00:18
Sourcery review of #40:

- the revocation check refreshes from the newest refresh token, `r3`
  of T5, so it moves to the end of T5, and the expiry session refreshes
  once, too;
- T1 also tries the node's bare ID in `resource`, which maps to
  `TESTBED_TARGET_PARAM=resource`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rder

# Conflicts:
#	docs/tests/t1-call-chain.md
@uniqueg
uniqueg merged commit e9472a3 into dev Nov 17, 2026
7 checks passed
@uniqueg
uniqueg deleted the docs/38-live-session-order branch November 17, 2026 23:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: close gaps in the live session order

1 participant