identity: service facade api.sx — login/verify/revoke/logout (10 tests, Phase 1 complete)

identity:start() spawns one coordinator owning the token table + session
registry and exposes the whole-domain ops. The coordinator is the owner
sessions notify on idle timeout, so an expired session deregisters itself
— timeout-driven, never swept. verify/2 answers identity only ({active,
Subject, Client, Scope}); permission is delegated to acl. 39/39.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lib/identity/api.sx

@@ -0,0 +1,35 @@
+;; identity/api.sx — the identity service facade.
+;;
+;; `identity:start()` spawns one coordinator process that owns a token
+;; table and a session registry and ties them together. It exposes the
+;; whole-domain operations the architecture sketch names:
+;;
+;;   login(Svc, Subject, Client, Scope[, Ttl]) -> {ok, SessionId, Token}
+;;   verify(Svc, Token)        -> {active, Subject, Client, Scope} | {inactive}
+;;   revoke(Svc, Token)        -> ok        (revokes the token; real, immediate)
+;;   logout(Svc, SessionId)    -> ok        (tombstones + deregisters a session)
+;;   session_status(Svc, Sid)  -> active | expired | revoked | gone
+;;
+;; The coordinator is also the Owner the sessions notify on idle timeout,
+;; so an expired session deregisters itself from the directory — the
+;; timeout is the only liveness driver; nothing sweeps.
+;;
+;; Delegation boundary: verify/2 answers IDENTITY only — who the token
+;; belongs to and what scope was granted. It deliberately does NOT answer
+;; \"may they do X\"; that question belongs to acl-on-sx, which keys off the
+;; {active, Subject, Client, Scope} this returns.
+
+(define
+  identity-api-source
+  "-module(identity).\n\n   start() ->\n     spawn(fun () ->\n       TokReg = identity_tokens:start(),\n       SessReg = identity_registry:start(),\n       loop(TokReg, SessReg, 1)\n     end).\n\n   login(Svc, Subject, Client, Scope) ->\n     login(Svc, Subject, Client, Scope, infinity).\n\n   login(Svc, Subject, Client, Scope, Ttl) ->\n     Svc ! {login, Subject, Client, Scope, Ttl, self()},\n     receive {identity_reply, R} -> R end.\n\n   verify(Svc, Token) ->\n     Svc ! {verify, Token, self()},\n     receive {identity_reply, R} -> R end.\n\n   revoke(Svc, Token) ->\n     Svc ! {revoke, Token, self()},\n     receive {identity_reply, R} -> R end.\n\n   logout(Svc, SessionId) ->\n     Svc ! {logout, SessionId, self()},\n     receive {identity_reply, R} -> R end.\n\n   session_status(Svc, SessionId) ->\n     Svc ! {session_status, SessionId, self()},\n     receive {identity_reply, R} -> R end.\n\n   loop(TokReg, SessReg, NextId) ->\n     receive\n       {login, Subject, Client, Scope, Ttl, From} ->\n         SessionId = NextId,\n         Self = self(),\n         S = identity_session:start(SessionId, Subject, Client, Self, Ttl),\n         identity_registry:register(SessReg, SessionId, Subject, Client, S),\n         {ok, Token} = identity_tokens:issue(TokReg, Subject, Client, Scope),\n         From ! {identity_reply, {ok, SessionId, Token}},\n         loop(TokReg, SessReg, NextId + 1);\n       {verify, Token, From} ->\n         From ! {identity_reply, identity_tokens:introspect(TokReg, Token)},\n         loop(TokReg, SessReg, NextId);\n       {revoke, Token, From} ->\n         identity_tokens:revoke(TokReg, Token),\n         From ! {identity_reply, ok},\n         loop(TokReg, SessReg, NextId);\n       {logout, SessionId, From} ->\n         case identity_registry:whereis_session(SessReg, SessionId) of\n           {ok, Pid} -> identity_session:revoke(Pid);\n           {error, _} -> ok\n         end,\n         identity_registry:deregister(SessReg, SessionId),\n         From ! {identity_reply, ok},\n         loop(TokReg, SessReg, NextId);\n       {session_status, SessionId, From} ->\n         R = case identity_registry:whereis_session(SessReg, SessionId) of\n               {ok, Pid} ->\n                 case identity_session:lookup(Pid) of\n                   {ok, {_, _, _, St}} -> St;\n                   {error, St} -> St\n                 end;\n               {error, _} -> gone\n             end,\n         From ! {identity_reply, R},\n         loop(TokReg, SessReg, NextId);\n       {session_expired, SessionId} ->\n         identity_registry:deregister(SessReg, SessionId),\n         loop(TokReg, SessReg, NextId)\n     end.")
+
+(define identity-load-api! (fn () (erlang-load-module identity-api-source)))
+
+(define
+  identity-load-all!
+  (fn
+    ()
+    (identity-load-session!)
+    (identity-load-token!)
+    (identity-load-registry!)
+    (identity-load-api!)))

lib/identity/conformance.sh

@@ -31,6 +31,7 @@ SUITES=(
   "session|id-session-test-pass|id-session-test-count"
   "token|id-token-test-pass|id-token-test-count"
   "registry|id-registry-test-pass|id-registry-test-count"
+  "api|id-api-test-pass|id-api-test-count"
 )
 
 cat > "$TMPFILE" << 'EPOCHS'
@@ -45,15 +46,19 @@ cat > "$TMPFILE" << 'EPOCHS'
 (load "lib/identity/session.sx")
 (load "lib/identity/token.sx")
 (load "lib/identity/registry.sx")
+(load "lib/identity/api.sx")
 (load "lib/identity/tests/session.sx")
 (load "lib/identity/tests/token.sx")
 (load "lib/identity/tests/registry.sx")
+(load "lib/identity/tests/api.sx")
 (epoch 100)
 (eval "(list id-session-test-pass id-session-test-count)")
 (epoch 101)
 (eval "(list id-token-test-pass id-token-test-count)")
 (epoch 102)
 (eval "(list id-registry-test-pass id-registry-test-count)")
+(epoch 103)
+(eval "(list id-api-test-pass id-api-test-count)")
 EPOCHS
 
 timeout 600 "$SX_SERVER" < "$TMPFILE" > "$OUTFILE" 2>&1

lib/identity/scoreboard.json

@@ -1,10 +1,11 @@
 {
   "language": "identity",
-  "total_pass": 29,
-  "total": 29,
+  "total_pass": 39,
+  "total": 39,
   "suites": [
     {"name":"session","pass":11,"total":11,"status":"ok"},
     {"name":"token","pass":9,"total":9,"status":"ok"},
-    {"name":"registry","pass":9,"total":9,"status":"ok"}
+    {"name":"registry","pass":9,"total":9,"status":"ok"},
+    {"name":"api","pass":10,"total":10,"status":"ok"}
   ]
 }

lib/identity/scoreboard.md

@@ -1,12 +1,13 @@
 # identity-on-sx Scoreboard
 
-**Total: 29 / 29 tests passing**
+**Total: 39 / 39 tests passing**
 
 |  | Suite | Pass | Total |
 |---|---|---|---|
 | ✅ | session | 11 | 11 |
 | ✅ | token | 9 | 9 |
 | ✅ | registry | 9 | 9 |
+| ✅ | api | 10 | 10 |
 
 
 Generated by `lib/identity/conformance.sh`.

lib/identity/tests/api.sx

@@ -0,0 +1,111 @@
+;; identity/tests/api.sx — the service facade end-to-end: login issues a
+;; session + token, verify proves identity, revoke and logout take effect
+;; immediately. Exercises session + token + registry through one door.
+
+(define id-api-test-count 0)
+(define id-api-test-pass 0)
+(define id-api-test-fails (list))
+
+(define
+  id-api-test
+  (fn
+    (name actual expected)
+    (set! id-api-test-count (+ id-api-test-count 1))
+    (if
+      (= actual expected)
+      (set! id-api-test-pass (+ id-api-test-pass 1))
+      (append! id-api-test-fails {:name name :expected expected :actual actual}))))
+
+(define ida-ev erlang-eval-ast)
+(define idanm (fn (v) (get v :name)))
+
+(identity-load-all!)
+
+;; ── login + verify (happy path) ──────────────────────────────────
+
+(id-api-test
+  "login then verify is active"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, _Sid, Tok} = identity:login(Svc, alice, web, read),\n       case identity:verify(Svc, Tok) of\n         {active, _, _, _} -> active;\n         {inactive} -> inactive\n       end"))
+  "active")
+
+(id-api-test
+  "verify returns the logged-in subject"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, _Sid, Tok} = identity:login(Svc, alice, web, read),\n       case identity:verify(Svc, Tok) of\n         {active, Subject, _, _} -> Subject\n       end"))
+  "alice")
+
+(id-api-test
+  "verify returns the granted scope"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, _Sid, Tok} = identity:login(Svc, bob, cli, write),\n       case identity:verify(Svc, Tok) of\n         {active, _, _, Scope} -> Scope\n       end"))
+  "write")
+
+;; ── revoke is real through the facade ────────────────────────────
+
+(id-api-test
+  "revoked token verifies inactive immediately"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, _Sid, Tok} = identity:login(Svc, alice, web, read),\n       identity:revoke(Svc, Tok),\n       case identity:verify(Svc, Tok) of\n         {active, _, _, _} -> still_valid;\n         {inactive} -> inactive\n       end"))
+  "inactive")
+
+;; ── session lifecycle through the facade ─────────────────────────
+
+(id-api-test
+  "fresh session reports active"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, Sid, _Tok} = identity:login(Svc, alice, web, read),\n       identity:session_status(Svc, Sid)"))
+  "active")
+
+(id-api-test
+  "logout makes the session gone"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, Sid, _Tok} = identity:login(Svc, alice, web, read),\n       identity:logout(Svc, Sid),\n       identity:session_status(Svc, Sid)"))
+  "gone")
+
+(id-api-test
+  "status of an unknown session is gone"
+  (idanm
+    (ida-ev "Svc = identity:start(),\n       identity:session_status(Svc, 999)"))
+  "gone")
+
+;; ── independence: logins do not bleed into each other ────────────
+
+(id-api-test
+  "revoking one login leaves the other active"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, _S1, T1} = identity:login(Svc, alice, web, read),\n       {ok, _S2, T2} = identity:login(Svc, bob, cli, write),\n       identity:revoke(Svc, T1),\n       case identity:verify(Svc, T2) of\n         {active, Subject, _, _} -> Subject;\n         {inactive} -> inactive\n       end"))
+  "bob")
+
+(id-api-test
+  "logging out one session leaves the other active"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, S1, _T1} = identity:login(Svc, alice, web, read),\n       {ok, S2, _T2} = identity:login(Svc, alice, cli, read),\n       identity:logout(Svc, S1),\n       identity:session_status(Svc, S2)"))
+  "active")
+
+;; ── coordinator deregisters on a session_expired notification ────
+;; A live idle session fires its own `after` timeout and notifies its
+;; owner (the coordinator), which then deregisters it — timeout-driven,
+;; never swept. The owner-internal path can't be observed by driving the
+;; scheduler idle from the test's main process, so we assert the handler
+;; directly: the mailbox is FIFO, so the expiry notification is processed
+;; before the following status query.
+
+(id-api-test
+  "session_expired notification deregisters the session"
+  (idanm
+    (ida-ev
+      "Svc = identity:start(),\n       {ok, Sid, _Tok} = identity:login(Svc, alice, web, read, 50),\n       active = identity:session_status(Svc, Sid),\n       Svc ! {session_expired, Sid},\n       identity:session_status(Svc, Sid)"))
+  "gone")
+
+(define
+  id-api-test-summary
+  (str "api " id-api-test-pass "/" id-api-test-count))

plans/identity-on-sx.md

@@ -19,7 +19,7 @@ through the event log, all authorization questions delegated to `acl-on-sx`.
 
 ## Status (rolling)
 
-`bash lib/identity/conformance.sh` → **29/29** (Phase 1: session, token, registry)
+`bash lib/identity/conformance.sh` → **39/39** (Phase 1 complete: session, token, registry, api)
 
 ## Ground rules
 
@@ -60,7 +60,7 @@ lib/identity/api.sx ── (identity/login) (identity/grant?) (identity/revoke)
 - [x] `session.sx` — session process, create/lookup/expire
 - [x] `token.sx` — issue/introspect/revoke (opaque, grant-backed)
 - [x] `registry.sx` — route by subject/client
-- [ ] `api.sx` + tests + scoreboard + conformance.sh
+- [x] `api.sx` + tests + scoreboard + conformance.sh
 
 ## Phase 2 — OAuth2 flows
 - [ ] authorization-code flow as a message protocol
@@ -78,6 +78,13 @@ lib/identity/api.sx ── (identity/login) (identity/grant?) (identity/revoke)
 - [ ] tests: audit completeness, cross-instance subject mapping
 
 ## Progress log
+- 2026-06-06 — `api.sx`: service facade. `identity:start()` spawns one
+  coordinator owning the token table + session registry; exposes
+  login/verify/revoke/logout/session_status. Coordinator is the sessions'
+  owner, so an expired session deregisters itself (timeout-driven, no
+  sweep). `verify` answers IDENTITY only ({active, Subject, Client, Scope});
+  permission is acl's job — explicit delegation boundary. **Phase 1 complete.**
+  +10 → 39/39.
 - 2026-06-06 — `registry.sx`: directory process routing sessions by id and
   by (subject, client). Answers the SSO probe `lookup(Subject, Client)` and
   the fan-out `sessions_for(Subject)` (one subject, many clients). Routes