identity: token exchange — downscope into an independent token (RFC 8693, +8 tests)

oauth.sx gains token_exchange(SubjectToken, RequestedScope): a valid access
token is downscoped into a NEW independent grant for the same subject
(subset only, else invalid_scope; inactive subject token → invalid_grant).
The exchanged token's lifecycle is independent of the subject token
(revoking either leaves the other active); exchanges chain. Least-privilege
handoff to downstream services. New tests/exchange.sx. 201/201.

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

lib/identity/conformance.sh

@@ -45,6 +45,7 @@ SUITES=(
   "facade|id-facade-test-pass|id-facade-test-count"
   "delegation|id-deleg-test-pass|id-deleg-test-count"
   "session-mgmt|id-smgmt-test-pass|id-smgmt-test-count"
+  "exchange|id-xchg-test-pass|id-xchg-test-count"
 )
 
 cat > "$TMPFILE" << 'EPOCHS'
@@ -85,6 +86,7 @@ cat > "$TMPFILE" << 'EPOCHS'
 (load "lib/identity/tests/facade.sx")
 (load "lib/identity/tests/delegation.sx")
 (load "lib/identity/tests/session_mgmt.sx")
+(load "lib/identity/tests/exchange.sx")
 (epoch 100)
 (eval "(list id-session-test-pass id-session-test-count)")
 (epoch 101)
@@ -119,6 +121,8 @@ cat > "$TMPFILE" << 'EPOCHS'
 (eval "(list id-deleg-test-pass id-deleg-test-count)")
 (epoch 116)
 (eval "(list id-smgmt-test-pass id-smgmt-test-count)")
+(epoch 117)
+(eval "(list id-xchg-test-pass id-xchg-test-count)")
 EPOCHS
 
 timeout 600 "$SX_SERVER" < "$TMPFILE" > "$OUTFILE" 2>&1

lib/identity/scoreboard.json

@@ -1,7 +1,7 @@
 {
   "language": "identity",
-  "total_pass": 193,
-  "total": 193,
+  "total_pass": 201,
+  "total": 201,
   "suites": [
     {"name":"session","pass":11,"total":11,"status":"ok"},
     {"name":"token","pass":24,"total":24,"status":"ok"},
@@ -19,6 +19,7 @@
     {"name":"device","pass":10,"total":10,"status":"ok"},
     {"name":"facade","pass":9,"total":9,"status":"ok"},
     {"name":"delegation","pass":8,"total":8,"status":"ok"},
-    {"name":"session-mgmt","pass":8,"total":8,"status":"ok"}
+    {"name":"session-mgmt","pass":8,"total":8,"status":"ok"},
+    {"name":"exchange","pass":8,"total":8,"status":"ok"}
   ]
 }

lib/identity/scoreboard.md

@@ -1,6 +1,6 @@
 # identity-on-sx Scoreboard
 
-**Total: 193 / 193 tests passing**
+**Total: 201 / 201 tests passing**
 
 |  | Suite | Pass | Total |
 |---|---|---|---|
@@ -21,6 +21,7 @@
 | ✅ | facade | 9 | 9 |
 | ✅ | delegation | 8 | 8 |
 | ✅ | session-mgmt | 8 | 8 |
+| ✅ | exchange | 8 | 8 |
 
 
 Generated by `lib/identity/conformance.sh`.

lib/identity/tests/exchange.sx

@@ -0,0 +1,110 @@
+;; identity/tests/exchange.sx — token exchange (RFC 8693 §2.1): downscope a
+;; valid access token into a new independent token for a downstream service.
+
+(define id-xchg-test-count 0)
+(define id-xchg-test-pass 0)
+(define id-xchg-test-fails (list))
+
+(define
+  id-xchg-test
+  (fn
+    (name actual expected)
+    (set! id-xchg-test-count (+ id-xchg-test-count 1))
+    (if
+      (= actual expected)
+      (set! id-xchg-test-pass (+ id-xchg-test-pass 1))
+      (append! id-xchg-test-fails {:name name :expected expected :actual actual}))))
+
+(define idx-ev erlang-eval-ast)
+(define idxnm (fn (v) (get v :name)))
+
+(identity-load-oauth!)
+
+;; Shared prelude: an access token A for alice with scope [read, write].
+(define
+  idx-token
+  "O = identity_oauth:start(),\n   {consent_required, Rq} = identity_oauth:authorize(O, web, uri1, [read, write], alice, v),\n   {code, Cd} = identity_oauth:consent(O, Rq, allow),\n   {ok, A, _R} = identity_oauth:exchange(O, Cd, web, uri1, v)")
+
+;; ── downscoping ──────────────────────────────────────────────────
+
+(id-xchg-test
+  "exchange downscopes to a subset"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", {ok, X} = identity_oauth:token_exchange(O, A, [read]),\n           case identity_oauth:introspect(O, X) of\n             {active, _, _, [read]} -> downscoped;\n             {active, _, _, _} -> other;\n             {inactive} -> inactive\n           end")))
+  "downscoped")
+
+(id-xchg-test
+  "the exchanged token keeps the subject"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", {ok, X} = identity_oauth:token_exchange(O, A, [read]),\n           case identity_oauth:introspect(O, X) of\n             {active, Subject, _, _} -> Subject\n           end")))
+  "alice")
+
+(id-xchg-test
+  "exchange to the same scope is allowed"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", {ok, X} = identity_oauth:token_exchange(O, A, [read, write]),\n           case identity_oauth:introspect(O, X) of\n             {active, _, _, [read, write]} -> full;\n             {active, _, _, _} -> other;\n             {inactive} -> inactive\n           end")))
+  "full")
+
+;; ── scope cannot be widened ──────────────────────────────────────
+
+(id-xchg-test
+  "exchange cannot widen beyond the subject token's scope"
+  (idxnm
+    (idx-ev
+      "O = identity_oauth:start(),\n       {consent_required, Rq} = identity_oauth:authorize(O, web, uri1, [read], alice, v),\n       {code, Cd} = identity_oauth:consent(O, Rq, allow),\n       {ok, A, _R} = identity_oauth:exchange(O, Cd, web, uri1, v),\n       case identity_oauth:token_exchange(O, A, [read, write]) of\n         {ok, _} -> widened;\n         {error, W} -> W\n       end"))
+  "invalid_scope")
+
+;; ── inactive subject token cannot be exchanged ───────────────────
+
+(id-xchg-test
+  "exchanging a revoked subject token is invalid_grant"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", identity_oauth:revoke(O, A),\n           case identity_oauth:token_exchange(O, A, [read]) of\n             {ok, _} -> issued;\n             {error, W} -> W\n           end")))
+  "invalid_grant")
+
+;; ── independent lifecycles ───────────────────────────────────────
+
+(id-xchg-test
+  "revoking the subject token does not revoke the exchanged token"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", {ok, X} = identity_oauth:token_exchange(O, A, [read]),\n           identity_oauth:revoke(O, A),\n           case identity_oauth:introspect(O, X) of\n             {active, _, _, _} -> still_active;\n             {inactive} -> inactive\n           end")))
+  "still_active")
+
+(id-xchg-test
+  "revoking the exchanged token does not revoke the subject token"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", {ok, X} = identity_oauth:token_exchange(O, A, [read]),\n           identity_oauth:revoke(O, X),\n           case identity_oauth:introspect(O, A) of\n             {active, _, _, _} -> still_active;\n             {inactive} -> inactive\n           end")))
+  "still_active")
+
+;; ── chained downscoping ──────────────────────────────────────────
+
+(id-xchg-test
+  "an exchanged token can itself be exchanged (chain)"
+  (idxnm
+    (idx-ev
+      (str
+        idx-token
+        ", {ok, X1} = identity_oauth:token_exchange(O, A, [read, write]),\n           {ok, X2} = identity_oauth:token_exchange(O, X1, [read]),\n           case identity_oauth:introspect(O, X2) of\n             {active, _, _, [read]} -> chained;\n             {active, _, _, _} -> other;\n             {inactive} -> inactive\n           end")))
+  "chained")
+
+(define
+  id-xchg-test-summary
+  (str "exchange " id-xchg-test-pass "/" id-xchg-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` → **193/193** (4 phases + 9 ext)
+`bash lib/identity/conformance.sh` → **201/201** (4 phases + 10 ext)
 
 ## Ground rules
 
@@ -87,8 +87,16 @@ lib/identity/api.sx ── (identity/login) (identity/grant?) (identity/revoke)
 - [ ] OAuth `state` (CSRF) + OIDC `nonce` threaded through authorize→exchange
 - [x] unify `api.sx` over membership + audit (one facade, audited login/logout)
 - [x] subject-wide session management: `sessions(Subject)` + `logout_all` (log out everywhere)
+- [x] token exchange (RFC 8693): downscope a token into a new independent token
 
 ## Progress log
+- 2026-06-07 — token exchange (ext, RFC 8693 §2.1): `oauth.sx` gains
+  `token_exchange(SubjectToken, RequestedScope)` — a valid access token is
+  downscoped into a NEW independent grant for the same subject (subset only,
+  else invalid_scope; inactive subject token → invalid_grant). The new token's
+  lifecycle is independent (revoking either leaves the other active);
+  exchanges chain. Least-privilege handoff to downstream services. New
+  tests/exchange.sx (8). 193→201.
 - 2026-06-07 — subject-wide session management (ext): `api.sx` gains
   `sessions(Subject)` (enumerate) and `logout_all(Subject)` ("log out
   everywhere") — revokes + deregisters every session a subject holds,