Skip to content

Six operator-doc sentences on sign-in and step-up match the auth code (BACKLOG #1133) - #2577

Open
wshallwshall wants to merge 4 commits into
mainfrom
b447-1133-doc-sentences
Open

wshallwshall wants to merge 4 commits into
mainfrom
b447-1133-doc-sentences

Conversation

@wshallwshall

@wshallwshall wshallwshall commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Merge danger

Low. Docs only: six operator-doc passages, plus same-document siblings, on sign-in, step-up and the load-balancer probe token. No code or test changes. Line conflict expected with open PR 2564, which edits another cell of the same docs/ASVS-L2-PHASE0-CHANGES.md AD row. Many open PRs also touch docs/SECURITY.md and docs/CONFIGURATION.md. git merge-tree against origin/main at open time was clean.

Evidence

The Builder read each passage against the auth code at engine origin/main. All six were wrong, and none needed a code change. pytest over every test that reads the changed docs: 2654 passed, 90 skipped, plus 2309 passed in an earlier pass over the rest. ruff clean. mypy was not run, because no Python changed. Code review ran at xhigh, two rounds, both repaired; the QA line is posted as a comment.

BACKLOG #1133: research an honest pass for ASVS 6.1.3 -- whether documenting an inconsistently enforced strength can satisfy the verb

Batch 447. Source branch b447-1133-doc-sentences, head 5b3c9d447674b61fd99bcdf891860054a6193656 (three commits: the fix, then review rounds 1 and 2).

  • docs/CLOUD-DEPLOYMENT.md 3.1: there is no static monitoring token and no route that mints one. The only bearer is a sign-in session token, so something beside the LB must sign in non-interactively (local password, or Kerberos through POST /auth/negotiate) and refresh it. It names which token to hand over under require_mfa.
  • docs/AOAG-DEPLOYMENT.md: cut to one sentence that links to CLOUD 3.1.
  • docs/ASVS-L2-PHASE0-CHANGES.md, AD "login binds" row: directory password sign-in is retired. The bind as the user now happens only on a directory account's password step-up. The row label is kept because tests key on it.
  • docs/REMOTE-CONSOLE.md: step-up now says what each sign-in type re-proves.
  • docs/CONFIGURATION.md (step_up_max_age_seconds) and the docs/SECURITY.md step-up section: both now include the combined passkey sign-in.
  • docs/SECURITY.md Table A lockout row and first-seen-address rows: the lock exception now includes the passkey form.

Checks run: /simplify; ruff check; ruff format --check; targeted pytest as above. Skipped: mypy (no Python changed); the full suite. Legs to read: the pytest legs and the docs drift tests.

Proposed ledger banner: "ENGINE FIX 2026-10-27: six operator-doc sentences (and their same-doc siblings) corrected; a vault re-read of the cell is owed".

Critic notes, open and not built, for follow-up rows:

  • docs/SECURITY.md account lockout row (~5913) names only the TOTP combined form.
  • docs/EARLY-ADOPTER-GUIDE.md (~777) and the /metrics docstring in api/app.py still promise a "service token", the same false premise.
  • docs/CLOUD-DEPLOYMENT.md 3.3 is loose.
  • "Combined sign-in" is defined in several places in SECURITY.md and should be defined once.
  • An L7 probe needs an automated refresher that holds a password and a TOTP seed. Admitting the existing mTLS service identity on /cluster/status would remove that need.

RetriggerView in GreptileConfidence Score: 5/5

The documentation changes appear safe to merge.

Summary

Corrects six operator guides to match the existing sign-in and step-up code.

  • Load-balancer guides explain how to keep an authenticated status probe working.
  • The directory bind table puts password checks at step-up, not sign-in.
  • The console guide explains what each sign-in type re-proves.
  • Security guidance includes eligible passkeys in combined sign-in rules.

Acknowledged follow-ups from wshallwshall, not reported again:

  • The account-lockout row still names only combined TOTP sign-in; deferred.
  • docs/EARLY-ADOPTER-GUIDE.md and the /metrics docstring still promise a service token; deferred.
  • Section 3.3 of docs/CLOUD-DEPLOYMENT.md remains loose; deferred.
  • Repeated combined-sign-in definitions in docs/SECURITY.md should be consolidated; deferred.
  • Allowing an mTLS service identity on /cluster/status would remove the probe refresher’s password and TOTP-seed requirement; deferred.

Reviews (1) · Last reviewed commit: "docs: review round 2 on the sign-in and ..." · Reviewed by Greptile

BACKLOG #1133 ("research an honest pass for ASVS 6.1.3 -- whether
documenting an inconsistently enforced strength can satisfy the verb").
Each sentence below described sign-in or step-up behaviour more broadly
than messagefoundry/auth/ does; each is rewritten against the code.

- CLOUD-DEPLOYMENT.md and AOAG-DEPLOYMENT.md, L7 cluster probe: no
  static or mintable API token exists; the only bearer is a sign-in
  session token, which expires, so something must refresh it (and the
  account owes MFA under require_mfa). AOAG now links to CLOUD 3.1.
- ASVS-L2-PHASE0-CHANGES.md, AD row: directory password sign-in is
  retired; the bind as the user happens only on a directory account's
  password step-up (_reauth_ad).
- REMOTE-CONSOLE.md: step-up re-proves by sign-in type (local password,
  directory re-bind, OIDC at the IdP); a code or passkey is asked only
  of a session that has not met its second factor.
- CONFIGURATION.md step_up_max_age_seconds and SECURITY.md step-up
  section: a combined passkey sign-in is also seeded from any address.
- SECURITY.md Table A lockout row: the sign-in lock also lets a combined
  passkey sign-in through.

Proposed PR title: Six operator-doc sentences on sign-in and step-up match the auth code (BACKLOG #1133)
Proposed ledger banner: ENGINE FIX 2026-10-27: six operator-doc sentences corrected; a vault re-read of the cell is owed
BACKLOG #1133, code-review round 1 fixes:
- CLOUD-DEPLOYMENT.md probe paragraph: names [security].require_mfa
  (the [auth] key is refused), says the account must be local, that no
  built-in role holds monitoring:read alone, that the token to hand
  over is the one POST /auth/mfa-verify returns, and drops the
  "long-lived" claim, which configuration can make false.
- AOAG-DEPLOYMENT.md: the link no longer claims a complete recipe.
- ASVS-L2-PHASE0-CHANGES.md AD row: names the equalizing decoy bind.
- CONFIGURATION.md and SECURITY.md: the combined sign-in now covers the
  passkey form at the Table A first-seen address rows and the tripped-
  control paragraph too, and the passkey conditions link to the
  WebAuthn passkeys section instead of being restated.

Proposed PR title: Six operator-doc sentences on sign-in and step-up match the auth code (BACKLOG #1133)
Proposed ledger banner: ENGINE FIX 2026-10-27: six operator-doc sentences (and their same-doc siblings) corrected; a vault re-read of the cell is owed
BACKLOG #1133, code-review round 2 fixes:
- CLOUD-DEPLOYMENT.md probe paragraph: a probe keeps the idle clock
  fresh, so only the absolute limit bounds the session; Kerberos via
  POST /auth/negotiate is a non-interactive option; a custom role can
  hold monitoring:read alone; a new account must replace its generated
  password first; a combined POST /auth/login already returns the final
  token; names require_mfa_scope beside require_mfa.
- ASVS-L2-PHASE0-CHANGES.md AD row: the lookup list is a floor, and the
  decoy bind equalizes the code path only, not wall-clock time.
- SECURITY.md and CONFIGURATION.md: the passkey form of the combined
  sign-in names its account condition rather than "an assertion the
  sign-in accepts", and the TOTP form names its enrolment condition.

Proposed PR title: Six operator-doc sentences on sign-in and step-up match the auth code (BACKLOG #1133)
Proposed ledger banner: ENGINE FIX 2026-10-27: six operator-doc sentences (and their same-doc siblings) corrected; a vault re-read of the cell is owed
@wshallwshall

Copy link
Copy Markdown
Collaborator Author

QA (BACKLOG #1133): code-review skill at level xhigh, two rounds, both repaired; round 2 nonce round-1a865754; review_tag.py exit 0; tag verbatim: "xhigh effort -> 10 inline angles -> dedup (no verify) -> sweep -> <=15 findings". Note: inline review with no verifier pass, per the tag.

@wshallwshall wshallwshall added the qa Builder QA record posted; not a merge gate label Oct 27, 2026
@github-actions github-actions Bot added the ci-red A required check went red. Attribute it before retrying. label Oct 27, 2026
@wshallwshall

Copy link
Copy Markdown
Collaborator Author

Manager 784448: one re-run of the failed legs (run 40586462740). This PR changes docs only. The one failure is tests/test_coord_lane_statement.py::test_show_with_no_lanes_dir_creates_nothing_and_says_absent, which is unrelated to this diff. Failed log: https://github.com/MEFORORG/MessageFoundry/actions/runs/40586462740/job/122479191787. Head 5b3c9d4. A second red on the same leg is a finding, not another re-run.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-red A required check went red. Attribute it before retrying. qa Builder QA record posted; not a merge gate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant