Teammate self-onboarding (deployment-wide auth method)

[ashwin-agami]

Summary

Completes teammate onboarding. An admin creates a teammate by email + name (a pending user who
can't yet sign in); this lets them finish setting up — following a deployment-wide auth method,
uniform for everyone, set by what's configured:

• OIDC deployment (a Google/Microsoft client is configured): a pending teammate signs in with that
  provider at the connector — the IdP verifies their email and binds the account on first login. No
  link to share.
• Password deployment (no OIDC): the admin copies a setup link from the Users tab and shares it
  out-of-band; the teammate opens it and sets their own password. The link is a signed, time-boxed
  token (no new table) and is single-use — it stops working once the account is set up.

Because a deployment offers one method, a user can never hold two credentials — so there's no per-user
choice and no lock-juggling. Login surfaces show only the configured method (the admin keeps a
password break-glass fallback on /admin/login).

Changes

• user_store.py — claim_pending_oidc / claim_pending_password: guarded
  UPDATE … WHERE password_hash IS NULL AND oidc_provider IS NULL (race-safe, mirrors the ACE-006 bind).
• oauth_server.py — _resolve_oidc_user gains a pending branch (bind on first OIDC login, then
  re-read and require the binding is ours); login_body_html renders only the configured method, and
  /oauth/authorize refuses a password POST server-side in an OIDC deployment.
• onboarding.py (NEW) — the setup token (purpose-marked HS256, no new table) + the /claim setup
  page/handler. Unforgeable, single-use, never overwrites a claimed account; hashes only after the token
  • pending checks.
• admin.py — the Users tab shows a copy-able setup link for pending users, only in a
  password deployment (the page is session-gated).
• mcp_http.py — /claim routes + the bearer public-skip (boundary-matched). Docs + previews.

Test plan

• tests/test_onboarding.py — token round-trip + forged/expired/wrong-purpose rejection; /claim sets a
  password for a pending user; single-use (replay refused, original password still works, attacker's
  rejected); short/bad-token refused; can't overwrite a claimed/admin account; roster shows the setup
  link for pending users only in a password deployment.
• tests/test_oidc.py — pending user binds on first OIDC login; a password user is never a pending OIDC
  claim; first-claim-locks both directions; connector login shows only the configured method; a
  password POST is refused server-side in an OIDC deployment.
• Gate green: ruff + ruff-format + full pytest (890) + gitleaks; patch coverage 100% (onboarding 96% — the
  3 uncovered lines are defensive store-unavailable guards).
• Reviewed with /code-review + /security-review (new public credential surface); findings addressed.

Checklist

• Tests added and passing; gate green
• No real customer names / data / credentials — neutral placeholders only
• No new network egress (OIDC reuses oidc.py, the existing single egress module)
• Flat access preserved (no role/permission column)
• Manual end-to-end smoke behind a Cloudflare tunnel — OIDC bind + the setup-link password path

Spec: ACE-011

[Copilot]

Pull request overview

Implements deployment-wide teammate self-onboarding, where an admin can create pending users (email + name) and the deployment’s configured auth method determines how those users complete setup: first-login OIDC binding when OIDC is configured, or a signed setup-link flow for password deployments.

Changes:

• Added a password-deployment setup-link flow (/claim) backed by a signed, time-boxed, purpose-marked token and a guarded “pending-only” password-claim update.
• Added “pending teammate” first-login OIDC binding (race-safe guarded update + re-read verification) and enforced “only configured method” on connector login surfaces (including server-side refusal of password POSTs in OIDC deployments).
• Updated admin Users roster to display copyable setup links for pending users only in password deployments; added tests and preview fixtures/docs.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_onboarding.py	New tests covering setup token validation, /claim password setup, replay refusal, and admin roster link visibility.
tests/test_oidc.py	Tests ensuring connector login shows only configured method, password POST is refused in OIDC deployments, and pending OIDC binding works as intended.
render_previews.py	Updates HTML previews to include setup-link UI and /claim pages.
packages/agami-core/src/user_store.py	Adds guarded “pending-only” claim helpers for OIDC binding and password setting.
packages/agami-core/src/onboarding.py	New module implementing setup token mint/verify, /claim pages + handler, and public path declaration.
packages/agami-core/src/oauth_server.py	Adds pending-branch OIDC binding, hides password UI when OIDC configured, and refuses password POSTs server-side in OIDC deployments.
packages/agami-core/src/mcp_http.py	Mounts /claim routes and includes them in bearer-auth public-path skipping.
packages/agami-core/src/admin.py	Adds “Setup link” display for pending users (password deployments only) and generates per-user setup links.
packages/agami-core/README.md	Documents deployment-wide onboarding flows and operational trust/rate-limit notes.
packages/agami-core/pyproject.toml	Exposes the new onboarding module as a flat top-level module.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ashwin-agami]

Thanks @copilot — fixed in 3e2e07c. You're right that the JWT sub is base64url-readable; the docstring now says the token is signed (unforgeable) rather than "opaque", and clarifies the no-enumeration property comes from the handler returning the same generic page regardless of token/user state — not from the token hiding who it's for. Doc-only; no behavior change.