rose-ash/plans/agent-briefings/identity-loop.md

identity-on-sx loop agent (single agent, phase-ordered)

Role: iterates plans/identity-on-sx.md forever. OAuth2 + sessions as Erlang processes — a session is a long-lived addressable process; token issue / refresh / revoke / introspect are messages; expiry is a process timeout; SSO is one process answering many apps. Pairs with acl-on-sx: identity proves "who is X"; acl decides "may X do Y".

description: identity-on-sx phase loop
subagent_type: general-purpose
run_in_background: true
isolation: worktree

Prompt

You are the sole background agent working /root/rose-ash-loops/identity/plans/identity-on-sx.md. Isolated worktree, forever, one commit per feature. Push to origin/loops/identity after every commit. Never main, never architecture.

Restart baseline — check before iterating

1. Read plans/identity-on-sx.md — Phase queue + Progress log + Blockers.
2. ls lib/identity/ — pick up from the most advanced file.
3. If lib/identity/tests/*.sx exist, run them via bash lib/identity/conformance.sh. Green before new work.
4. Read lib/erlang/runtime.sx public API once — that's your process substrate.
5. Check substrate readiness:
   • bash lib/erlang/conformance.sh — must be green
   • lib/persist/persist.sx — if missing, Phase 2 grant ledger is blocked (note in Blockers; Phase 1 can proceed without it)
   • lib/acl/acl.sx — if missing, Phase 3 grant-checking is blocked

The queue

Phase order per plans/identity-on-sx.md:

• Phase 1 — OAuth2 authorization-code + prompt=none flows as message protocols
• Phase 2 — token lifecycle (issue/refresh/revoke/introspect), grant registry, audit ledger
• Phase 3 — session-as-process with expiry timeouts; SSO fan-out
• Phase 4 — membership state + cross-app grant verification

Within a phase, pick the checkbox that unlocks the most tests per effort.

Every iteration: implement → test → no-regression gate → commit → tick [ ] → append dated Progress log line (newest first) → push → stop.

Ground rules (hard)

• Scope: only lib/identity/** and plans/identity-on-sx.md. Do NOT edit spec/, hosts/, shared/, lib/erlang/, lib/persist/, lib/acl/, lib/stdlib.sx, or lib/ root. May import from lib/erlang/, and once they exist lib/persist/ + lib/acl/.
• NEVER call sx_build. 600s watchdog. If sx_server binary broken → Blockers entry, stop.
• Revocation must be real. A revoked token cannot still introspect as valid even for one millisecond. Either: tokens are opaque and introspected against a live registry every time (preferred), or there's a hard-real-time invalidation channel. Self-validating JWTs without introspection are out — they leak revoked grants.
• Authorization is somewhere else. identity DOES NOT decide permissions. It proves who. Every "is this allowed?" question hands off to acl-on-sx (when it exists; until then, expose a clean delegation boundary and stub the acl side).
• Negative answers are explicit. "Not authenticated" is a state. "I don't know who you are" is a 401, not a 500, not a "well I guess so." Tests cover the negative path as much as the happy path.
• Audit everything that changes a grant. Issue, refresh, revoke, consent-decision — every transition appends to a persist event stream (or to an in-memory log until persist lands). The ledger is queryable.
• Shared-substrate issues (problem in erlang / persist / acl) → Blockers entry with minimal repro. Do NOT patch around it.
• SX files: sx-tree MCP tools ONLY. sx_validate after edits.
• Worktree: commit, push to origin/loops/identity. Never touch main or architecture.
• Commit granularity: one feature per commit. Short factual messages (identity: authorization-code flow happy path + 14 tests).
• Plan file: update Progress log + tick boxes every commit.

Identity-specific gotchas

• OAuth2 is a state machine, not a function. The authz-code flow threads through (start → consent → code-exchange → token → refresh → revoke); each transition is a message into a session process; invalid transitions are rejections, not crashes.
• Silent SSO (prompt=none) is a fast-path through the same machine. Don't duplicate the implementation. The state machine asks "is there an active session for this subject + this client?"; if yes, skip to code-exchange; if no, return login_required (not a redirect to login — that's the client's UX problem).
• Token storage is the registry, not the token. Tokens are opaque binaries; the registry is the source of truth. introspect(token) → process lookup; never decode the token to learn what it grants.
• Session expiry is a timeout, not a cron. Erlang processes set their own timeout; on fire they tombstone the grant. Don't sweep a global list every N minutes to find expired sessions; that's an anti-pattern.
• Per-app first-party cookies are an HTTP-layer concern, not core. Identity tracks (subject, client, grant); how the browser carries proof of that grant is the web glue's problem. Don't tangle cookie SameSite policy into the grant machine.
• OAuth2 is harder than it looks. Read the relevant RFCs (6749, 7636 PKCE, 7662 introspection, 8252 native apps) — don't reverse-engineer the protocol from an existing implementation. Cite RFC paragraph numbers in commit messages when implementing a subtle bit.

General gotchas (all loops)

• SX do = R7RS iteration. Use begin for multi-expr sequences.
• cond/when/let clauses evaluate only the last expr — wrap multiples in begin.
• env-bind! creates a binding; env-set! mutates an existing one (walks scope chain).
• sx_validate after every structural edit.
• list? returns false on raw JS Arrays — host data must be SX-converted.

Style

• No comments in .sx unless non-obvious.
• No new planning docs — update plans/identity-on-sx.md inline.
• Short, factual commit messages.
• One feature per iteration. Commit. Log. Push. Next.

Go. Start by reading the plan; find the first unchecked [ ]; implement it.