@astram/guard 0.7.0 → 0.8.0

package/dist/request-auth/session-token-binder.js

@@ -12,7 +12,10 @@
  * establish/rotate time and reads it per request. Zero Core changes.
  *
  * The binding: `shield:at:<accessToken>` → JSON {@link BoundPrincipalClaims}
- * ({ id, tenantId, roleIds, kind }), TTL = the access-token lifetime. The token
+ * ({ id, tenantId, roleIds, kind }), TTL ≤ the access-token lifetime (security hardening
+ * #8). Alongside it: `shield:sessclaims:<sessionId>` (the liveness entry, TTL = the refresh
+ * idle window when configured) and `shield:sessat:<sessionId>` (the session's current
+ * access token, so a rotation can grace-expire the old one and a revoke can drop it). The token
  * stays fully opaque (carries no data itself); the mapping is server-side, so the
  * session is server-REVOCABLE (drop the key) and the read is FAIL-CLOSED (absent or
  * Redis-unavailable → no principal → the guard denies).
@@ -22,6 +25,19 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionTokenBinder = void 0;
+exports.factsSlot = factsSlot;
+exports.liveRoleIds = liveRoleIds;
+/** A valid stamp: a non-negative safe integer. */
+function isSubtreeVersion(v) {
+    return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+}
+/** Return the claims with any `scopeSubtreeVersion` stamp removed. */
+function stripSubtreeVersion(claims) {
+    if (!('scopeSubtreeVersion' in claims))
+        return claims;
+    const { scopeSubtreeVersion: _drop, ...rest } = claims;
+    return rest;
+}
 /**
  * Structurally validate a value pulled from the (untrusted) Redis payload as
  * {@link CoarseGrants}. Returns the parsed facts or `undefined` — a `null`/junk/legacy
@@ -40,11 +56,52 @@ function parseCachedFacts(slot) {
     for (const k of c.grantedPermissionKeys)
         if (typeof k !== 'string')
             return undefined;
+    // The OPTIONAL time bound (ADR-0035): kept only when it is a finite number. A junk bound is
+    // dropped together with the facts (fail-closed: unusable facts → reload), never ignored.
+    if (c.validUntilMs !== undefined && !Number.isFinite(c.validUntilMs))
+        return undefined;
     return {
         permissionsVersion: c.permissionsVersion,
         grantedPermissionKeys: [...c.grantedPermissionKeys],
+        ...(typeof c.validUntilMs === 'number' ? { validUntilMs: c.validUntilMs } : {}),
     };
 }
+/**
+ * The `cachedFacts` slot a binding stores (ADR-0035): the version, the keys and the optional time
+ * bound. The projection's `roleIds` are NOT kept here — they are the claims' own `roleIds`, written
+ * in the same payload, so there is one copy of the roles.
+ */
+function factsSlot(grants) {
+    return {
+        permissionsVersion: grants.permissionsVersion,
+        grantedPermissionKeys: [...grants.grantedPermissionKeys],
+        ...(typeof grants.validUntilMs === 'number' && Number.isFinite(grants.validUntilMs)
+            ? { validUntilMs: grants.validUntilMs }
+            : {}),
+    };
+}
+/** The projection's live roles when it reported them (a string array), else `undefined`. */
+function liveRoleIds(grants) {
+    const roles = grants?.roleIds;
+    if (!Array.isArray(roles))
+        return undefined;
+    return roles.filter((r) => typeof r === 'string' && r.length > 0);
+}
+/**
+ * Whether `next` is at least as fresh as the binding's current facts `current` (ADR-0035): a newer
+ * version, or the same version with a later (or no) time bound. A slower request that reloaded
+ * older facts must never overwrite fresher ones.
+ */
+function isFresher(next, current) {
+    if (current === undefined)
+        return true;
+    if (next.permissionsVersion !== current.permissionsVersion) {
+        return next.permissionsVersion > current.permissionsVersion;
+    }
+    const a = next.validUntilMs ?? Number.POSITIVE_INFINITY;
+    const b = current.validUntilMs ?? Number.POSITIVE_INFINITY;
+    return a > b;
+}
 /**
  * Structurally validate the OPTIONAL `scopeSubtreeNodeIds` slot from the (untrusted) Redis
  * payload. Returns a fresh string[] of the non-empty node ids, or `undefined` when the slot is
@@ -80,16 +137,34 @@ function stripCachedFacts(claims) {
 const AT_KEY_PREFIX = 'shield:at:';
 /** Redis key prefix for the session-id → claims binding (survives token rotation). */
 const SESS_CLAIMS_PREFIX = 'shield:sessclaims:';
+/** Redis key prefix for the session-id → its CURRENT access token (for grace/unbind). */
+const SESS_AT_PREFIX = 'shield:sessat:';
 function atKey(accessToken) {
     return `${AT_KEY_PREFIX}${accessToken}`;
 }
 function sessClaimsKey(sessionId) {
     return `${SESS_CLAIMS_PREFIX}${sessionId}`;
 }
+function sessAtKey(sessionId) {
+    return `${SESS_AT_PREFIX}${sessionId}`;
+}
+/** Default grace for the previous access token after a rotation (plan decision D7). */
+const DEFAULT_ROTATE_GRACE_MS = 30_000;
+/** How long refresh waits for Redis to answer PING before answering 503 (ADR-0035, F1). */
+const DEFAULT_PING_TIMEOUT_MS = 1_000;
 class SessionTokenBinder {
     redis;
-    constructor(redis) {
+    options;
+    constructor(redis, options = {}) {
         this.redis = redis;
+        this.options = options;
+    }
+    /** TTL for the session-claims entry + current-token pointer. */
+    sessionTtl(accessTtlMs) {
+        const configured = this.options.sessionClaimsTtlMs;
+        return configured !== undefined && configured > 0
+            ? configured
+            : Math.max(accessTtlMs * 4, accessTtlMs);
     }
     /**
      * Bind an access token to its principal claims for `ttlMs` (the access-token
@@ -97,22 +172,47 @@ class SessionTokenBinder {
      * controller (it holds both the freshly-minted access token and the Principal).
      * ALSO writes a session-id → claims entry so a later `rebindOnRotate` can carry the
      * full claims (roles/kind/root) forward across a token rotation, where the
-     * durable session row alone lacks them.
+     * durable session row alone lacks them, and records the session's CURRENT access
+     * token so a rotation can grace-expire it and a revoke can drop it.
      */
     async bind(accessToken, claims, ttlMs) {
         const payload = JSON.stringify(claims);
+        const sessTtl = this.sessionTtl(ttlMs);
         await this.redis.set(atKey(accessToken), payload, 'PX', ttlMs);
-        // The session-claims entry gets a longer TTL cushion so it survives across
-        // multiple short-lived access tokens within one session's lifetime.
-        await this.redis.set(sessClaimsKey(claims.sessionId), payload, 'PX', Math.max(ttlMs * 4, ttlMs));
+        // The session-claims entry lives for the refresh idle window (configured), so it
+        // survives across the session's short-lived access tokens — and no longer.
+        await this.redis.set(sessClaimsKey(claims.sessionId), payload, 'PX', sessTtl);
+        await this.redis.set(sessAtKey(claims.sessionId), accessToken, 'PX', sessTtl);
+    }
+    /**
+     * Grace-expire the session's previous access token after a rotation (plan D7): it stays
+     * usable for at most `rotateGraceMs` (never longer than it already had), then expires.
+     * Best-effort — a failure leaves the old binding to its own (≤ access TTL) expiry.
+     */
+    async graceExpire(previousToken, newToken) {
+        if (previousToken === null || previousToken === '' || previousToken === newToken)
+            return;
+        const grace = this.options.rotateGraceMs ?? DEFAULT_ROTATE_GRACE_MS;
+        try {
+            const remaining = await this.redis.pttl(atKey(previousToken));
+            if (remaining === -1 || remaining > grace) {
+                await this.redis.pexpire(atKey(previousToken), grace);
+            }
+        }
+        catch {
+            // best-effort; the old binding still expires at its own access TTL.
+        }
     }
     /**
      * On refresh/rotate the controller has the NEW access token + the session, but not
      * the full Principal (roles/kind/root live only in the binding, not the
      * durable session row). Re-bind by reading the session-claims entry and writing the
      * new access-token binding with the SAME claims. Returns true if it carried claims
-     * forward, false if the session-claims entry was gone (then the caller has nothing
-     * to bind — a later request will 401 and the user re-logs in; fail-closed).
+     * forward, false if the session-claims entry was gone or unreadable — the caller MUST
+     * then refuse the refresh (the auth controller answers 401: an unbound token is never
+     * handed out). A Redis error on the writes propagates (the caller fails closed too).
+     * The new binding's TTL is `ttlMs` (≤ the access TTL); the session's previous access
+     * token is grace-expired (≤ 30 s by default, plan D7).
      *
      * `freshFacts` (ADR-0011 eager projection at REFRESH):
      *   - `undefined` (omitted, the default) → carry whatever `cachedFacts` the session
@@ -124,7 +224,27 @@ class SessionTokenBinder {
      *   - `null` → STRIP `cachedFacts` (a projection that yielded nothing → the next
      *     request DB-reloads; fail-closed).
      */
-    async rebindOnRotate(newAccessToken, sessionId, ttlMs, freshFacts, freshSubtree) {
+    async rebindOnRotate(newAccessToken, sessionId, ttlMs, freshFacts, freshSubtree, 
+    /**
+     * The permission version read just before `freshSubtree` was resolved (Phase 1C). Stamped
+     * when the fresh subtree is applied; absent → the stamp is dropped (unknown → re-derive once
+     * at the next reload). Ignored when no fresh subtree is applied (the carried subtree keeps its
+     * own stamp).
+     */
+    freshSubtreeVersion, 
+    /**
+     * The principal's LIVE role ids from the same projection as `freshFacts` (ADR-0035, GAPS #4).
+     * Given → they REPLACE the carried roles (roles and facts are written together). Absent → the
+     * carried roles stay (a projector that does not report roles, or no projection at all).
+     */
+    freshRoleIds, 
+    /**
+     * The node the fresh facts/roles/subtree were projected for (review follow-up: a scope-switch
+     * moves the claims off the login tenant). Given and the claims are now on a DIFFERENT node (a
+     * switch raced the refresh) → nothing fresh is applied and the cached facts are stripped (the
+     * next request reloads for the right node). Absent → applied as before.
+     */
+    freshForTenantId) {
         let raw;
         try {
             raw = await this.redis.get(sessClaimsKey(sessionId));
@@ -134,9 +254,23 @@ class SessionTokenBinder {
         }
         if (raw === null)
             return false;
+        if (freshForTenantId !== undefined) {
+            let onNode = false;
+            try {
+                onNode = JSON.parse(raw)?.tenantId === freshForTenantId;
+            }
+            catch {
+                onNode = false;
+            }
+            if (!onNode) {
+                freshFacts = null;
+                freshSubtree = undefined;
+                freshRoleIds = undefined;
+            }
+        }
         // Default: carry the existing payload forward byte-for-byte (facts + subtree unchanged).
         let payload = raw;
-        if (freshFacts !== undefined || freshSubtree !== undefined) {
+        if (freshFacts !== undefined || freshSubtree !== undefined || freshRoleIds !== undefined) {
             // A refresh-time projection and/or subtree was supplied → rewrite those slots on the
             // carried-forward claims. A parse failure here is treated as "nothing to update" and we
             // carry the original payload forward (fail-safe: never drop the whole binding on a
@@ -146,7 +280,12 @@ class SessionTokenBinder {
                 let next = parsed;
                 if (freshFacts !== undefined) {
                     next =
-                        freshFacts === null ? stripCachedFacts(next) : { ...next, cachedFacts: freshFacts };
+                        freshFacts === null
+                            ? stripCachedFacts(next)
+                            : { ...next, cachedFacts: factsSlot(freshFacts) };
+                }
+                if (freshRoleIds !== undefined) {
+                    next = { ...next, roleIds: [...freshRoleIds] };
                 }
                 // The subtree (the stale-subtree-after-move fix): a non-empty fresh set REPLACES the
                 // carried-forward one (a re-parented session gets its correct, possibly-smaller subtree).
@@ -154,7 +293,10 @@ class SessionTokenBinder {
                 // forward (fail-safe, non-widening — never narrow to self-node on a transient resolver
                 // hiccup, never fail the refresh).
                 if (freshSubtree !== undefined && freshSubtree.length > 0) {
-                    next = { ...next, scopeSubtreeNodeIds: [...freshSubtree] };
+                    next = stripSubtreeVersion({ ...next, scopeSubtreeNodeIds: [...freshSubtree] });
+                    if (isSubtreeVersion(freshSubtreeVersion)) {
+                        next = { ...next, scopeSubtreeVersion: freshSubtreeVersion };
+                    }
                 }
                 payload = JSON.stringify(next);
             }
@@ -162,11 +304,140 @@ class SessionTokenBinder {
                 payload = raw;
             }
         }
+        // The session's previous access token (best-effort read — a miss only skips the grace).
+        let previousToken = null;
+        try {
+            previousToken = await this.redis.get(sessAtKey(sessionId));
+        }
+        catch {
+            previousToken = null;
+        }
+        const sessTtl = this.sessionTtl(ttlMs);
         await this.redis.set(atKey(newAccessToken), payload, 'PX', ttlMs);
-        // Refresh the session-claims TTL cushion too (with the same, possibly-updated payload).
-        await this.redis.set(sessClaimsKey(sessionId), payload, 'PX', Math.max(ttlMs * 4, ttlMs));
+        // Refresh the session-claims TTL (with the same, possibly-updated payload) + pointer.
+        // `XX` (Phase 2 review F2): only while the entry still exists. A logout that deleted it
+        // between our read and this write wins — the claims are NOT re-created, the new token's
+        // binding is dropped, and the caller refuses the refresh (no resurrected session).
+        const kept = await this.redis.set(sessClaimsKey(sessionId), payload, 'PX', sessTtl, 'XX');
+        if (kept !== 'OK') {
+            await this.unbind(newAccessToken);
+            return false;
+        }
+        await this.redis.set(sessAtKey(sessionId), newAccessToken, 'PX', sessTtl);
+        await this.graceExpire(previousToken, newAccessToken);
+        return true;
+    }
+    /**
+     * SILENT RECOVERY (ADR-0013 / ADR-0035, GAPS #5): write a session binding REBUILT from durable
+     * state after the session-claims entry was lost (Redis restart/flush). The caller (refresh) has
+     * already rotated the durable refresh token and assembled `claims` from the durable session
+     * record + live roles + the root allowlist + the subtree resolver.
+     *
+     * The claims entry is written with `NX`: if one appeared meanwhile, nothing is overwritten and
+     * the rebuild is refused (`false`). The caller MUST then re-read the durable session and call
+     * {@link unbindSession} if it is no longer active (a logout racing the rebuild). A Redis error
+     * propagates (the caller fails closed).
+     */
+    async bindRecovered(accessToken, claims, ttlMs) {
+        const payload = JSON.stringify(claims);
+        const sessTtl = this.sessionTtl(ttlMs);
+        const created = await this.redis.set(sessClaimsKey(claims.sessionId), payload, 'PX', sessTtl, 'NX');
+        if (created !== 'OK')
+            return false;
+        await this.redis.set(atKey(accessToken), payload, 'PX', ttlMs);
+        await this.redis.set(sessAtKey(claims.sessionId), accessToken, 'PX', sessTtl);
         return true;
     }
+    /**
+     * The node a live session currently acts under (its claims' `tenantId` — the scope-switch target
+     * when it switched), or `null` when the claims are gone, unreadable, or Redis errors. Refresh uses
+     * it to project for the ACTIVE node; `null` → the durable login tenant.
+     */
+    async sessionTenant(sessionId) {
+        try {
+            const raw = await this.redis.get(sessClaimsKey(sessionId));
+            if (raw === null)
+                return null;
+            const tenantId = JSON.parse(raw)?.tenantId;
+            return typeof tenantId === 'string' && tenantId.length > 0 ? tenantId : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Whether Redis answers right now (Phase 2 review F1). Refresh asks BEFORE the durable rotate
+     * spends the refresh token, so a Redis outage answers a retryable 503 instead of burning the
+     * token on a binding that cannot be written. A client without `ping` (a test double) counts as
+     * reachable.
+     *
+     * Bounded by `timeoutMs` (default 1 s): the framework's client queues commands while
+     * disconnected (`maxRetriesPerRequest: null`), so an unbounded PING would wait for Redis to come
+     * back and the refresh would then spend the token for a client that already gave up.
+     */
+    async isAvailable(timeoutMs = DEFAULT_PING_TIMEOUT_MS) {
+        const client = this.redis;
+        if (typeof client.ping !== 'function')
+            return true;
+        let timer;
+        try {
+            const timedOut = new Promise((resolve) => {
+                timer = setTimeout(() => resolve('timeout'), timeoutMs);
+            });
+            const answer = await Promise.race([
+                client.ping().then(() => 'ok', () => 'error'),
+                timedOut,
+            ]);
+            return answer === 'ok';
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * LIVE GRANTS re-bind (ADR-0035, GAPS #4/#6). Gate 5 reloaded this session's coarse grants (a
+     * version bump, an expired time bound, or no cache yet); write them, and the live roles from the
+     * same projection, onto the access-token entry AND the session-claims entry, so the next requests
+     * are served from the cache and every role-keyed path sees the new roles. Nothing else changes.
+     *
+     * Each entry is rewritten only when it still belongs to `sessionId` + `tenantId` (a concurrent
+     * scope-switch moved it → left alone) and `facts` is fresher than what it holds (a slower request
+     * never overwrites newer facts). Each keeps its remaining TTL and is written with `XX` (a logout
+     * that deleted it wins). Best-effort: any Redis error or miss → that entry is skipped; the caller
+     * still uses the reloaded roles for the current request. Returns `true` when the access-token
+     * entry was rewritten.
+     */
+    async refreshGrants(accessToken, sessionId, tenantId, facts, roleIds) {
+        const slot = factsSlot(facts);
+        const rewrite = async (key) => {
+            try {
+                const raw = await this.redis.get(key);
+                if (raw === null)
+                    return false;
+                const current = JSON.parse(raw);
+                if (current?.sessionId !== sessionId || current?.tenantId !== tenantId)
+                    return false;
+                if (!isFresher(slot, parseCachedFacts(current.cachedFacts)))
+                    return false;
+                const ttl = await this.redis.pttl(key);
+                if (ttl <= 0)
+                    return false;
+                const next = {
+                    ...current,
+                    cachedFacts: slot,
+                    ...(roleIds !== undefined ? { roleIds: [...roleIds] } : {}),
+                };
+                return (await this.redis.set(key, JSON.stringify(next), 'PX', ttl, 'XX')) === 'OK';
+            }
+            catch {
+                return false;
+            }
+        };
+        const tokenRewritten = await rewrite(atKey(accessToken));
+        await rewrite(sessClaimsKey(sessionId));
+        return tokenRewritten;
+    }
     /**
      * SCOPE-SWITCH re-bind (Task 5.2, ADR-0027 / ADR-0024). A principal is switching which
      * active node it acts under; re-bind its CURRENT session (the same access token — no
@@ -186,7 +457,25 @@ class SessionTokenBinder {
      * Returns `true` on a successful re-bind, `false` when the binding is gone (logged out /
      * expired) or Redis is unavailable (the caller then denies the switch — fail-closed).
      */
-    async rebindActiveScope(accessToken, sessionId, targetNodeId, subtree) {
+    async rebindActiveScope(accessToken, sessionId, targetNodeId, subtree, 
+    /**
+     * The TARGET node's permission version read just before `subtree` was resolved (Phase 1C).
+     * The old node's stamp is always dropped (versions are per tenant); this one is stamped when
+     * given, else the stamp stays absent (→ one re-derive at the next reload).
+     */
+    subtreeVersion, 
+    /**
+     * The coarse grants projected for the TARGET node (ADR-0035). Given → cached on the re-scoped
+     * binding instead of stripped (the first request under the new scope is served from cache).
+     * Absent/null → stripped (the next request reloads).
+     */
+    targetFacts, 
+    /**
+     * The principal's LIVE roles at the TARGET node (ADR-0035, GAPS #4), from the same projection
+     * as `targetFacts`. Given → they replace the old node's roles (roles are per node). Absent →
+     * the carried roles stay until the first request's reload replaces them.
+     */
+    targetRoleIds) {
         // Read the current claims (from the per-access-token entry) + confirm the session is
         // still live (the session-claims entry exists). Any miss / Redis error → fail closed.
         let rawAt;
@@ -210,12 +499,21 @@ class SessionTokenBinder {
         // Build the re-scoped claims: new active node (tenantId) + new subtree, facts stripped.
         // An empty subtree is stored as absent (→ per-request self-node fallback, non-widening) —
         // but the switch caller always passes at least `[targetNodeId]`, so this is defensive.
-        const next = stripCachedFacts({
-            ...stripScopeSubtree(current),
+        const rescoped = stripCachedFacts({
+            ...stripSubtreeVersion(stripScopeSubtree(current)),
             tenantId: targetNodeId,
             sessionId,
             ...(subtree.length > 0 ? { scopeSubtreeNodeIds: [...subtree] } : {}),
+            ...(subtree.length > 0 && isSubtreeVersion(subtreeVersion)
+                ? { scopeSubtreeVersion: subtreeVersion }
+                : {}),
         });
+        // ADR-0035: the target node's facts + live roles, written together, when projected.
+        const next = {
+            ...rescoped,
+            ...(targetFacts ? { cachedFacts: factsSlot(targetFacts) } : {}),
+            ...(targetRoleIds !== undefined ? { roleIds: [...targetRoleIds] } : {}),
+        };
         const payload = JSON.stringify(next);
         // Preserve each key's remaining TTL — a scope-switch must never extend the session.
         let atTtl;
@@ -230,14 +528,66 @@ class SessionTokenBinder {
         if (atTtl <= 0 || sessTtl <= 0)
             return false; // expired between reads → fail closed.
         try {
-            await this.redis.set(atKey(accessToken), payload, 'PX', atTtl);
-            await this.redis.set(sessClaimsKey(sessionId), payload, 'PX', sessTtl);
+            // `XX` on both: a logout that deleted either entry since the reads wins (never re-created).
+            const at = await this.redis.set(atKey(accessToken), payload, 'PX', atTtl, 'XX');
+            const sess = await this.redis.set(sessClaimsKey(sessionId), payload, 'PX', sessTtl, 'XX');
+            if (at !== 'OK' || sess !== 'OK') {
+                await this.unbind(accessToken);
+                return false;
+            }
         }
         catch {
             return false;
         }
         return true;
     }
+    /**
+     * RE-DERIVED SUBTREE re-bind (security hardening Phase 1C). The enforcement guard saw gate 5
+     * reload the facts at a permission version NEWER than the bound subtree's stamp and resolved
+     * the subtree again; write it (and its stamp) onto the access-token entry AND the session-claims
+     * entry, so this token and any later rotation carry it. Nothing else in the claims changes.
+     *
+     * Each entry is rewritten only when it still belongs to `sessionId` + `tenantId` (a concurrent
+     * scope-switch moved it elsewhere → left alone) and its stamp is absent or OLDER than `version`
+     * (a concurrent refresh already wrote something at least as fresh → left alone). Each keeps its
+     * remaining TTL (a re-derive never extends a session). Best-effort: any Redis error or miss →
+     * `false`; the caller still uses the fresh subtree for the current request and a later reload
+     * retries. Returns `true` when the access-token entry was rewritten.
+     */
+    async rederiveScopeSubtree(accessToken, sessionId, tenantId, subtree, version) {
+        if (subtree.length === 0 || !isSubtreeVersion(version))
+            return false;
+        const rewrite = async (key) => {
+            try {
+                const raw = await this.redis.get(key);
+                if (raw === null)
+                    return false;
+                const current = JSON.parse(raw);
+                if (current?.sessionId !== sessionId || current?.tenantId !== tenantId)
+                    return false;
+                if (isSubtreeVersion(current.scopeSubtreeVersion) &&
+                    current.scopeSubtreeVersion >= version) {
+                    return false;
+                }
+                const ttl = await this.redis.pttl(key);
+                if (ttl <= 0)
+                    return false;
+                const next = {
+                    ...current,
+                    scopeSubtreeNodeIds: [...subtree],
+                    scopeSubtreeVersion: version,
+                };
+                await this.redis.set(key, JSON.stringify(next), 'PX', ttl);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const tokenRewritten = await rewrite(atKey(accessToken));
+        await rewrite(sessClaimsKey(sessionId));
+        return tokenRewritten;
+    }
     /**
      * Resolve an access token to its bound claims, or `null` if the binding is
      * absent/expired. Fail-closed: any Redis error → `null` (the caller denies), never
@@ -275,17 +625,22 @@ class SessionTokenBinder {
         // null` → gate 5 DB-reloads). Present + well-formed → the validated CoarseGrants.
         // Never fabricated. Rebuild the object so a malformed slot cannot ride through.
         const cachedFacts = parseCachedFacts(parsed.cachedFacts);
-        parsed = cachedFacts === undefined
-            ? stripCachedFacts(parsed)
-            : { ...parsed, cachedFacts };
+        parsed = cachedFacts === undefined ? stripCachedFacts(parsed) : { ...parsed, cachedFacts };
         // Normalize the OPTIONAL scope-subtree slot (ADR-0027 / Task 2.2): an absent, empty, or
         // malformed slot is scrubbed to ABSENT (→ `principalFromClaims` falls back to the self-node,
         // non-widening); a well-formed non-empty array is the validated cached subtree. Never
         // fabricated — rebuild the object so a junk slot cannot ride through into a Principal.
         const scopeSubtreeNodeIds = parseScopeSubtree(parsed.scopeSubtreeNodeIds);
-        parsed = scopeSubtreeNodeIds === undefined
-            ? stripScopeSubtree(parsed)
-            : { ...parsed, scopeSubtreeNodeIds };
+        parsed =
+            scopeSubtreeNodeIds === undefined
+                ? stripScopeSubtree(parsed)
+                : { ...parsed, scopeSubtreeNodeIds };
+        // The subtree's version stamp (Phase 1C) rides only beside a validated subtree; a junk or
+        // orphaned stamp is dropped (→ treated as unknown → one re-derive at the next reload).
+        if (scopeSubtreeNodeIds === undefined ||
+            !isSubtreeVersion(parsed.scopeSubtreeVersion)) {
+            parsed = stripSubtreeVersion(parsed);
+        }
         // SESSION-LIVENESS GATE: the per-token binding alone is not enough — a logout
         // revokes the session but cannot reach every outstanding access-token key. So we
         // ALSO require the session-claims entry (which `unbindSession` deletes on logout)
@@ -376,9 +731,25 @@ class SessionTokenBinder {
         }
     }
     /**
-     * Drop the session-claims entry on logout/revoke, so a rotate after logout cannot
-     * re-mint a binding (defense-in-depth: the session is already revoked, but this
-     * removes the claims cushion too). The per-access-token bindings expire by TTL.
+     * The THROWING variant of {@link unbindSession} (Phase 3 review P1): the same keys, but a
+     * Redis error PROPAGATES. An administrative revoke (an account disable through the session
+     * sweeper) must report a failed unbind so the admin can retry, instead of leaving the
+     * session's live access tokens valid until their TTL. Idempotent (absent keys are fine).
+     */
+    async unbindSessionStrict(sessionId) {
+        await this.redis.del(sessClaimsKey(sessionId));
+        const current = await this.redis.get(sessAtKey(sessionId));
+        if (current !== null && current !== '')
+            await this.redis.del(atKey(current));
+        await this.redis.del(sessAtKey(sessionId));
+    }
+    /**
+     * Revoke a session in Redis (logout, password reset, refresh reuse-kill, admin revoke):
+     * drop the session-claims entry — which the {@link resolve} liveness gate requires, so
+     * EVERY access token of the session is denied on its next request — and also the
+     * session's current access-token binding and pointer. A grace-period token from an
+     * earlier rotation is covered by the liveness gate and expires within the grace.
+     * Best-effort per key; TTLs clean up regardless ({@link unbindSessionStrict} throws instead).
      */
     async unbindSession(sessionId) {
         try {
@@ -387,6 +758,15 @@ class SessionTokenBinder {
         catch {
             // best-effort; TTL cleans up regardless.
         }
+        try {
+            const current = await this.redis.get(sessAtKey(sessionId));
+            if (current !== null && current !== '')
+                await this.redis.del(atKey(current));
+            await this.redis.del(sessAtKey(sessionId));
+        }
+        catch {
+            // best-effort; the liveness gate already denies every token of this session.
+        }
     }
 }
 exports.SessionTokenBinder = SessionTokenBinder;

package/dist/secrets/encrypted-file-secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypted-file-secrets.d.ts","sourceRoot":"","sources":["../../src/secrets/encrypted-file-secrets.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AASjF,qBAAa,4BAA6B,YAAW,eAAe;;IAKlE;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG;IAMhD,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAS1C,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvD,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3D,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CA+BxD"}
+{"version":3,"file":"encrypted-file-secrets.d.ts","sourceRoot":"","sources":["../../src/secrets/encrypted-file-secrets.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAYjF,qBAAa,4BAA6B,YAAW,eAAe;;IAKlE;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG;IAMhD,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAS1C,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvD,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3D,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CAmCxD"}

package/dist/secrets/encrypted-file-secrets.js

@@ -84,9 +84,15 @@ class EncryptedFileSecretsProvider {
         try {
             (0, node_fs_1.chmodSync)(this.#file, 0o600);
         }
-        catch { /* best-effort on platforms without chmod */ }
+        catch {
+            /* best-effort on platforms without chmod */
+        }
     }
 }
 exports.EncryptedFileSecretsProvider = EncryptedFileSecretsProvider;
-function toB64(b) { return Buffer.from(b).toString('base64'); }
-function fromB64(s) { return new Uint8Array(Buffer.from(s, 'base64')); }
+function toB64(b) {
+    return Buffer.from(b).toString('base64');
+}
+function fromB64(s) {
+    return new Uint8Array(Buffer.from(s, 'base64'));
+}

package/dist/session/hot-revoking-session-record-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `HotRevokingSessionRecordStore` — a decorator on `SHIELD_SESSION_RECORD_STORE`
+ * (security hardening M-A).
+ *
+ * WHY: core's `SessionAuthority` revokes through the durable store only — the refresh
+ * reuse-kill (`revokeLineage`) and the absolute-cap / logout path (`revokeSession`) mark
+ * MariaDB rows revoked, but the guard's per-request path reads Redis alone (invariant #12)
+ * and never consults MariaDB. Without this decorator a stolen-and-replayed refresh token
+ * kills the lineage durably while the live access token keeps working until its TTL.
+ *
+ * WHAT: after a durable revoke SUCCEEDS, unbind the affected sessions in Redis
+ * (`SessionTokenBinder.unbindSession` drops the session-claims liveness entry, so every
+ * access token of the session is denied on its next request). Durable first; a durable
+ * failure propagates and nothing is unbound. The Redis step is best-effort: a failure there
+ * never fails the durable revoke, and the exposure is bounded by the access TTL (#8).
+ *
+ * No core change: the port is decorated, not extended. The lineage → session lookup is a
+ * guard-side read on the durable adapter ({@link LineageSessionLookup}).
+ */
+import type { CreateSessionInput, InsertRefreshInput, RefreshTokenRecord, SessionRecord, SessionRecordStore } from '@astram/core';
+/** The Redis side of a revoke (the token binder implements it). */
+export interface SessionHotRevoker {
+    unbindSession(sessionId: string): Promise<void>;
+}
+/** Resolve the sessions a refresh lineage belongs to (a lifecycle-time durable read). */
+export interface LineageSessionLookup {
+    sessionIdsForLineage(lineageId: string): Promise<string[]>;
+}
+export declare class HotRevokingSessionRecordStore implements SessionRecordStore {
+    private readonly inner;
+    private readonly hot;
+    private readonly lineages;
+    constructor(inner: SessionRecordStore, hot: SessionHotRevoker, lineages: LineageSessionLookup);
+    createSession(input: CreateSessionInput): Promise<SessionRecord>;
+    insertRefreshRecord(input: InsertRefreshInput): Promise<RefreshTokenRecord>;
+    findRefreshByHash(tokenHash: string): Promise<RefreshTokenRecord | null>;
+    findSessionById(sessionId: string): Promise<SessionRecord | null>;
+    markRotatedIfActive(refreshId: string): Promise<boolean>;
+    markRevoked(refreshId: string): Promise<void>;
+    /** Durable lineage kill, then unbind every session of the lineage in Redis. */
+    revokeLineage(lineageId: string): Promise<void>;
+    /** Durable session revoke, then unbind it in Redis. */
+    revokeSession(sessionId: string): Promise<void>;
+    private unbind;
+}
+//# sourceMappingURL=hot-revoking-session-record-store.d.ts.map

package/dist/session/hot-revoking-session-record-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-revoking-session-record-store.d.ts","sourceRoot":"","sources":["../../src/session/hot-revoking-session-record-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,yFAAyF;AACzF,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5D;AAED,qBAAa,6BAA8B,YAAW,kBAAkB;IAEpE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,oBAAoB;IAGjD,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAIhE,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI3E,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAIxE,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIjE,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIxD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C,+EAA+E;IACzE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD,uDAAuD;IACjD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAKvC,MAAM;CAOrB"}