@wtfalch/auth 0.29.0 → 0.31.0

package/dist/names.d.ts

@@ -39,9 +39,11 @@ export interface NameRules {
 }
 export declare const DEFAULT_RULES: NameRules;
 /**
- * Lowercase letters with the digits read as letters and nothing else, runs
- * collapsed. Every reading, since `1` may be an `i` or an `l`; the first is
- * the one a list entry is stored under.
+ * NFKC-normalised and confusables-resolved -- so a look-alike from another
+ * script (Cyrillic `а` in `аdmin`) reads as the Latin letter it imitates
+ * instead of being dropped -- then lowercase letters with the digits read as
+ * letters and nothing else, runs collapsed. Every reading, since `1` may be
+ * an `i` or an `l`; the first is the one a list entry is stored under.
  */
 export declare function flattenings(name: string): string[];
 /** Every entry checkName holds back: the system names, the people's and the reserved-usernames list, once each. */

package/dist/names.js

@@ -82,14 +82,22 @@ const LETTERS = {
     '8': ['b'],
     '9': ['g'],
 };
+/** Confusables resolved per character, outside any matcher, so a plain string can be normalised. */
+const confusablesTransform = resolveConfusablesTransformer().transform;
 /**
- * Lowercase letters with the digits read as letters and nothing else, runs
- * collapsed. Every reading, since `1` may be an `i` or an `l`; the first is
- * the one a list entry is stored under.
+ * NFKC-normalised and confusables-resolved -- so a look-alike from another
+ * script (Cyrillic `а` in `аdmin`) reads as the Latin letter it imitates
+ * instead of being dropped -- then lowercase letters with the digits read as
+ * letters and nothing else, runs collapsed. Every reading, since `1` may be
+ * an `i` or an `l`; the first is the one a list entry is stored under.
  */
 export function flattenings(name) {
+    const resolved = Array.from(name.normalize('NFKC'), (char) => {
+        const codePoint = char.codePointAt(0);
+        return String.fromCodePoint(confusablesTransform(codePoint) ?? codePoint);
+    }).join('');
     let forms = [''];
-    for (const char of name.toLowerCase()) {
+    for (const char of resolved.toLowerCase()) {
         const readings = /[a-z]/.test(char) ? [char] : (LETTERS[char] ?? []);
         if (readings.length === 0)
             continue;
@@ -147,7 +155,9 @@ export function checkName(name, rules = DEFAULT_RULES) {
         return { ok: false, reason: 'disallowed' };
     }
     // Last, so that a number that means something (`14.88` reads as `lab`) is refused for what it is.
-    if (flattenings(typed).some((form) => reserved.has(form))) {
+    // Digits on the ends are also read as a counter, so `admin1` is `admin`.
+    const forms = [typed, typed.replace(/^\d+|\d+$/g, '')].flatMap(flattenings);
+    if (forms.some((form) => reserved.has(form))) {
         return { ok: false, reason: 'reserved' };
     }
     return { ok: true };

package/dist/namespace-browser.js

@@ -1,8 +1,7 @@
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import { resolveNamespaceContext } from './namespaces.js';
 import { safeLoginHint, safeNextPath } from './redirect.js';
-import { base64url } from './util.js';
-const OWNER = 'urn:zitadel:iam:user:resourceowner:id';
+import { ORG_CLAIM, base64url } from './util.js';
 const ttl = 10 * 60_000;
 const random = () => base64url(crypto.getRandomValues(new Uint8Array(32)));
 function read(storage, key) {
@@ -173,7 +172,7 @@ export function createNamespaceBrowserAuth(options, selection) {
                 clockTolerance: 60,
             });
             if (payload.nonce !== tx.nonce ||
-                payload[OWNER] !== binding.organizationId ||
+                payload[ORG_CLAIM] !== binding.organizationId ||
                 (payload.azp !== undefined && payload.azp !== binding.clientId) ||
                 (Array.isArray(payload.aud) && payload.aud.length > 1 && payload.azp !== binding.clientId))
                 return reject();
@@ -201,6 +200,8 @@ export function createNamespaceBrowserAuth(options, selection) {
     return {
         accountChanged,
         currentSession,
+        // This path keeps no ID token, so there is no hint to build a sign-out URL from.
+        endSessionUrl: () => null,
         silentSignInAvailable,
         completeSignIn,
         async refresh() {

package/dist/namespace-session.js

@@ -3,7 +3,7 @@ import * as client from 'openid-client';
 import { BrokerError } from './broker.js';
 import { contextDigest, digest, openHandle, openRecord, sealHandle, sealRecord, } from './cookies.js';
 import { AuthError, isOAuthRefusal, rejected } from './oidc.js';
-import { expiryOf, issuedAtOf } from './util.js';
+import { expiryOf, issuedAtOf, recheckSeconds } from './util.js';
 /** How long a binding status answer is trusted. The propagation bound for a suspension. */
 export const STATUS_FRESH_MS = 60_000;
 /** How long the last good answer carries on while the service cannot be asked. */
@@ -435,7 +435,7 @@ export function namespaceSessions(deps) {
         const exp = expiryOf(loaded.tokens.idt);
         const iat = issuedAtOf(loaded.tokens.idt);
         const valid = exp !== null && exp > now() - 60;
-        const stale = iat !== null && now() - iat >= options().freshness;
+        const stale = iat !== null && now() - iat >= recheckSeconds(options().freshness);
         const due = force || exp === null || exp - options().refreshWindow <= now() || stale;
         if (due && loaded.tokens.rt) {
             loaded = await refresh(loaded, valid);

package/dist/next.js

@@ -99,7 +99,7 @@ export function nextAuth(options) {
      * fresh id, which fails the same way — two requests to the issuer per lap,
      * no error page, nothing in a log, forever. That is not hypothetical: a
      * client id missing from the broker's registry produced exactly this on
-     * manage.wtfalch.dev, and the visible symptom was Cloudflare rate-limiting
+     * boule.companyincluded.com, and the visible symptom was Cloudflare rate-limiting
      * the operator, twenty minutes before anybody could see a 403 underneath
      * it. The refusal was diagnosable from the first request and the loop hid
      * it behind thousands.

package/dist/oidc.d.ts

@@ -1,6 +1,7 @@
 import * as jose from 'jose';
 import type { ResolvedOptions } from './config.js';
-export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
+import { ORG_CLAIM } from './util.js';
+export { ORG_CLAIM };
 /**
  * How long a rotated refresh token still answers with the tokens it rotated
  * to. A request that started just before another one finished the same
@@ -32,6 +33,19 @@ export interface Tokens {
     /** Epoch ms `accessToken` expires at. Present exactly when `accessToken` is and the issuer sent `expires_in`. */
     accessTokenExpiresAt?: number;
 }
+/**
+ * The oldest a logout token may be, by its `iat`, before it is refused (the
+ * 60 s clock tolerance comes on top). There is no `jti` store, so this and
+ * the required `exp` are all that stop a captured token being replayed.
+ */
+export declare const LOGOUT_TOKEN_MAX_AGE_SECONDS = 120;
+/** The `events` claim key a back-channel logout token carries (OpenID Connect Back-Channel Logout 1.0 §2.4). */
+export declare const BACKCHANNEL_LOGOUT_EVENT = "http://schemas.openid.net/event/backchannel-logout";
+/** What a verified logout token named: the issuer's user id, its own session id, or (rarely) both. */
+export interface LogoutTokenClaims {
+    sub?: string;
+    sid?: string;
+}
 export declare class Oidc {
     private readonly options;
     private configuration;
@@ -62,6 +76,15 @@ export declare class Oidc {
     endSessionUrl(idToken: string, postLogoutRedirectUri: string): Promise<URL | null>;
     private tokensFrom;
     verify(idToken: string): Promise<jose.JWTPayload>;
+    /**
+     * A back-channel logout token (OpenID Connect Back-Channel Logout 1.0
+     * §2.4-2.5): signed by this issuer for this client, carrying the
+     * back-channel-logout event and neither a `nonce` (the spec forbids one,
+     * since this token never rode a browser redirect) nor an empty `sub`/`sid`
+     * pair. Throws the same rejected-token errors `verify` does; the caller
+     * decides what that means for its own HTTP response.
+     */
+    verifyLogoutToken(logoutToken: string): Promise<LogoutTokenClaims>;
     private assertIdentityClaims;
     private assertOrganization;
 }

package/dist/oidc.js

@@ -1,6 +1,7 @@
 import * as jose from 'jose';
 import * as client from 'openid-client';
-export const ORG_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
+import { ORG_CLAIM } from './util.js';
+export { ORG_CLAIM };
 /**
  * How long a rotated refresh token still answers with the tokens it rotated
  * to. A request that started just before another one finished the same
@@ -39,6 +40,14 @@ export function scopeFor(organizationId, extraScopes) {
     }
     return scopes.join(' ');
 }
+/**
+ * The oldest a logout token may be, by its `iat`, before it is refused (the
+ * 60 s clock tolerance comes on top). There is no `jti` store, so this and
+ * the required `exp` are all that stop a captured token being replayed.
+ */
+export const LOGOUT_TOKEN_MAX_AGE_SECONDS = 120;
+/** The `events` claim key a back-channel logout token carries (OpenID Connect Back-Channel Logout 1.0 §2.4). */
+export const BACKCHANNEL_LOGOUT_EVENT = 'http://schemas.openid.net/event/backchannel-logout';
 export class Oidc {
     options;
     configuration = null;
@@ -181,6 +190,53 @@ export class Oidc {
         this.assertOrganization(payload);
         return payload;
     }
+    /**
+     * A back-channel logout token (OpenID Connect Back-Channel Logout 1.0
+     * §2.4-2.5): signed by this issuer for this client, carrying the
+     * back-channel-logout event and neither a `nonce` (the spec forbids one,
+     * since this token never rode a browser redirect) nor an empty `sub`/`sid`
+     * pair. Throws the same rejected-token errors `verify` does; the caller
+     * decides what that means for its own HTTP response.
+     */
+    async verifyLogoutToken(logoutToken) {
+        let payload;
+        try {
+            ({ payload } = await jose.jwtVerify(logoutToken, await this.keys(), {
+                issuer: this.options.issuer,
+                audience: this.options.clientId,
+                algorithms: ['RS256'],
+                clockTolerance: 60,
+                maxTokenAge: LOGOUT_TOKEN_MAX_AGE_SECONDS,
+                requiredClaims: ['iat', 'exp', 'events'],
+            }));
+        }
+        catch (error) {
+            // A kid this issuer's published keys do not contain refuses the logout
+            // token. It is deliberately not part of `rejected()`: for a session's
+            // id token the same error can be a just-rotated key inside the JWKS
+            // cooldown, which must not sign the person out.
+            if (error instanceof jose.errors.JWKSNoMatchingKey) {
+                throw new AuthError('exchange', 'the logout token is signed with an unknown key');
+            }
+            throw error;
+        }
+        if (payload.nonce !== undefined) {
+            throw new AuthError('exchange', 'a logout token must not carry a nonce');
+        }
+        const events = payload.events;
+        if (typeof events !== 'object' ||
+            events === null ||
+            Array.isArray(events) ||
+            !Object.hasOwn(events, BACKCHANNEL_LOGOUT_EVENT)) {
+            throw new AuthError('exchange', 'the logout token carries no back-channel-logout event');
+        }
+        const sub = typeof payload.sub === 'string' && payload.sub ? payload.sub : undefined;
+        const sid = typeof payload.sid === 'string' && payload.sid ? payload.sid : undefined;
+        if (!sub && !sid) {
+            throw new AuthError('exchange', 'the logout token names neither a subject nor a session');
+        }
+        return { sub, sid };
+    }
     // Both grant responses and stored/device tokens become a User. Keep their
     // identity and time shapes consistent, including optional freshness claims.
     assertIdentityClaims(claims) {

package/dist/onboarding.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The onboarding hold: what the broker hands an app's onboarding page during an
+ * MCP sign-in (ADR 0002), and what the app checks before it trusts the page's
+ * caller. Only WebCrypto, so this entry runs on workerd and in Node alike.
+ *
+ * `HOLD = base64url(JSON {h, s, o, e}) . base64url(HMAC-SHA256(appKey, firstPart))`
+ * where `h` is the hold id, `s` the person's ZITADEL user id, `o` their
+ * organisation id and `e` the expiry in epoch seconds. The key is the app's
+ * broker key (`AUTH_APP_KEY`), which only the broker and that app hold. A hold
+ * is a bearer proof that the broker just signed this person in; it carries no
+ * token and it is single use at the broker.
+ */
+export interface OnboardingHold {
+    holdId: string;
+    sub: string;
+    organizationId: string;
+}
+/** Signs a hold for `appKey`. `expiresAt` is epoch seconds. */
+export declare function signOnboardingHold(input: OnboardingHold & {
+    expiresAt: number;
+}, appKey: string): Promise<string>;
+/**
+ * The hold's contents when it is well formed, signed with `appKey` and not
+ * expired; otherwise null, with no hint which check failed. `now` is unix
+ * seconds, the unit of the hold's `e` (a test seam). The signature is compared by `crypto.subtle.verify`,
+ * which is constant time.
+ */
+export declare function verifyOnboardingHold(hold: string, appKey: string, now?: number): Promise<OnboardingHold | null>;

package/dist/onboarding.js

@@ -0,0 +1,91 @@
+/**
+ * The onboarding hold: what the broker hands an app's onboarding page during an
+ * MCP sign-in (ADR 0002), and what the app checks before it trusts the page's
+ * caller. Only WebCrypto, so this entry runs on workerd and in Node alike.
+ *
+ * `HOLD = base64url(JSON {h, s, o, e}) . base64url(HMAC-SHA256(appKey, firstPart))`
+ * where `h` is the hold id, `s` the person's ZITADEL user id, `o` their
+ * organisation id and `e` the expiry in epoch seconds. The key is the app's
+ * broker key (`AUTH_APP_KEY`), which only the broker and that app hold. A hold
+ * is a bearer proof that the broker just signed this person in; it carries no
+ * token and it is single use at the broker.
+ */
+const encoder = new TextEncoder();
+const HOLD_RE = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/;
+const MAX_HOLD_LENGTH = 2048;
+const toBase64Url = (bytes) => {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+const fromBase64Url = (value) => {
+    try {
+        const padded = value.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+        return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+};
+const hmacKey = (appKey, usage) => crypto.subtle.importKey('raw', encoder.encode(appKey), { name: 'HMAC', hash: 'SHA-256' }, false, [
+    usage,
+]);
+/** Signs a hold for `appKey`. `expiresAt` is epoch seconds. */
+export async function signOnboardingHold(input, appKey) {
+    const payload = toBase64Url(encoder.encode(JSON.stringify({
+        h: input.holdId,
+        s: input.sub,
+        o: input.organizationId,
+        e: input.expiresAt,
+    })));
+    const mac = await crypto.subtle.sign('HMAC', await hmacKey(appKey, 'sign'), encoder.encode(payload));
+    return `${payload}.${toBase64Url(new Uint8Array(mac))}`;
+}
+/**
+ * The hold's contents when it is well formed, signed with `appKey` and not
+ * expired; otherwise null, with no hint which check failed. `now` is unix
+ * seconds, the unit of the hold's `e` (a test seam). The signature is compared by `crypto.subtle.verify`,
+ * which is constant time.
+ */
+export async function verifyOnboardingHold(hold, appKey, now = Math.floor(Date.now() / 1000)) {
+    if (typeof hold !== 'string' || hold.length > MAX_HOLD_LENGTH || !appKey)
+        return null;
+    const match = HOLD_RE.exec(hold);
+    if (!match)
+        return null;
+    const [, payload, signature] = match;
+    const mac = fromBase64Url(signature);
+    if (!mac)
+        return null;
+    let valid;
+    try {
+        valid = await crypto.subtle.verify('HMAC', await hmacKey(appKey, 'verify'), mac, encoder.encode(payload));
+    }
+    catch {
+        return null;
+    }
+    if (!valid)
+        return null;
+    const bytes = fromBase64Url(payload);
+    if (!bytes)
+        return null;
+    let claims;
+    try {
+        claims = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (claims === null || typeof claims !== 'object')
+        return null;
+    const { h, s, o, e } = claims;
+    if (typeof h !== 'string' || !h || typeof s !== 'string' || !s)
+        return null;
+    if (typeof o !== 'string' || !o || typeof e !== 'number' || !Number.isFinite(e))
+        return null;
+    if (e <= now)
+        return null;
+    return { holdId: h, sub: s, organizationId: o };
+}

package/dist/person-token.d.ts

@@ -26,21 +26,55 @@ import { type JWTPayload } from 'jose';
  *
  * A network failure or a non-2xx from either the discovery document or the
  * introspection endpoint fails closed: `verify` returns `null`, exactly
- * like a bad token, never treated as good. There is no second outcome for
- * "could not check" versus "checked and refused" -- a caller has only one
- * response to either, refuse.
+ * like a bad token, never treated as good. `verify` has no second outcome
+ * for "could not check" versus "checked and refused" -- a caller that needs
+ * one calls `verifyOutcome` instead. That method also introspects a JWT
+ * (live revocation only shows up there), so it needs the introspection
+ * credentials for every token, and tells `invalid`, `expired`, `revoked`
+ * and `unavailable` apart. A positive introspection answer is cached for at
+ * most 60 seconds; a refusal or an `unavailable` never is.
  */
+export interface PersonIdentity {
+    sub: string;
+    /** The ZITADEL organisation that issued the token. Absent when the claim
+     *  is absent, empty or not a string: a malformed claim is treated as
+     *  missing and the token still verifies. */
+    organizationId?: string;
+}
+/** Why `verifyOutcome` refused a token. `unavailable` means the issuer could
+ *  not be asked (network error, non-2xx, unreadable answer): retry, and never
+ *  remember it as a refusal. The others are verdicts: `invalid` (bad
+ *  signature, issuer, audience, shape or claims; also no introspection
+ *  credentials), `expired`, and `revoked` (the issuer reports the token
+ *  inactive). */
+export type PersonTokenRefusal = 'invalid' | 'expired' | 'revoked' | 'unavailable';
+export type PersonTokenOutcome = {
+    ok: true;
+    identity: PersonIdentity;
+} | {
+    ok: false;
+    reason: PersonTokenRefusal;
+};
 export interface PersonTokenVerifier {
-    /** The token's subject (`sub`), or null for anything that does not stand
-     *  up: bad signature, wrong issuer/audience, expired, inactive, or
-     *  unreachable. Refusals never say which. */
-    verify(accessToken: string): Promise<{
-        sub: string;
-    } | null>;
+    /** The token's subject (`sub`) and organisation, or null for anything that
+     *  does not stand up: bad signature, wrong issuer/audience, expired,
+     *  inactive, or unreachable. Refusals never say which.
+     *
+     *  `organizationId` is read from the verified JWT claims or the
+     *  introspection response, same claim either way. Present only when the
+     *  claim is a non-empty string (every token minted through this SDK's own
+     *  `scopeFor` carries it); never guessed or defaulted. Neither path checks
+     *  it against anything fixed: see the module doc above. */
+    verify(accessToken: string): Promise<PersonIdentity | null>;
+    /** Like `verify`, but says why a token was refused, and also introspects a
+     *  JWT after its signature checks pass, so a revoked JWT is refused as
+     *  `revoked` before its `exp`. Needs `introspectionClientId`/`Secret`:
+     *  without them every token is `invalid`. */
+    verifyOutcome(accessToken: string): Promise<PersonTokenOutcome>;
 }
 export interface PersonTokenConfig {
     /** The issuer every token must have been minted by, e.g.
-     *  `https://auth.wtfalch.dev`. */
+     *  `https://auth.companyincluded.com`. */
     issuer: string;
     /** The ZITADEL project id a person's token must carry in `aud` --
      *  requested by whatever app mints the token (an `extraScopes` entry of

package/dist/person-token.js

@@ -1,5 +1,5 @@
 import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
-import { timeoutSignal } from './util.js';
+import { ORG_CLAIM, timeoutSignal } from './util.js';
 /** A JWT is three base64url segments; a ZITADEL opaque token is not shaped
  *  like that at all, so this is enough to route between `jwtVerify` and
  *  introspection without ever trying to parse either kind as the other. */
@@ -8,6 +8,8 @@ const JWT_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
  *  checks again -- bounded well under the token's own `exp` so a revoked
  *  token can't outlive a ZITADEL-side revocation for long. */
 const INTROSPECTION_CACHE_TTL_MS = 60_000;
+/** How long the issuer's discovery document, and the key set built from it, are reused before they are fetched again, so a moved `jwks_uri` or `introspection_endpoint` is picked up without a restart. */
+const DISCOVERY_TTL_MS = 10 * 60_000;
 /** An optional endpoint from the discovery document, required to be on the
  *  issuer's own origin -- a compromised or misconfigured discovery
  *  response must never point signature checking, or a token's liveness,
@@ -77,24 +79,50 @@ class PositiveIntrospectionCache {
         this.entries.set(token, { payload, expiresAt });
     }
 }
+/** A key-set request that did not complete (network failure, abort). Tagged so it is told apart from every other error a verification can raise. */
+class KeyFetchError extends Error {
+    constructor() {
+        super('person-token: the key set could not be fetched');
+        this.name = 'KeyFetchError';
+    }
+}
 /** @internal */
 export function createPersonTokenCore(config) {
     const fetchImpl = config.fetch ?? fetch;
     let discovery = null;
+    let discoveredAt = 0;
     let jwks = null;
     const introspectionCache = new PositiveIntrospectionCache();
     const document = () => {
-        discovery ??= discoverDocument(config.issuer, fetchImpl).catch((error) => {
+        if (discovery && Date.now() - discoveredAt >= DISCOVERY_TTL_MS) {
             discovery = null;
-            throw error;
-        });
+            jwks = null;
+        }
+        if (!discovery) {
+            discoveredAt = Date.now();
+            const fetched = discoverDocument(config.issuer, fetchImpl).catch((error) => {
+                if (discovery === fetched) {
+                    discovery = null;
+                    jwks = null;
+                }
+                throw error;
+            });
+            discovery = fetched;
+        }
         return discovery;
     };
     const keys = () => {
         jwks ??= document()
             .then((doc) => createRemoteJWKSet(new URL(doc.jwksUri), {
             cooldownDuration: config.jwksCooldownMs ?? 5_000,
-            [customFetch]: (url, init) => fetchImpl(url, init),
+            [customFetch]: async (url, init) => {
+                try {
+                    return await fetchImpl(url, init);
+                }
+                catch {
+                    throw new KeyFetchError();
+                }
+            },
         }))
             .catch((error) => {
             jwks = null;
@@ -125,8 +153,13 @@ export function createPersonTokenCore(config) {
             const code = error?.code;
             if (code === 'ERR_JWT_EXPIRED')
                 return { ok: false, reason: 'expired' };
-            // A key fetch that failed or timed out is the issuer being down, not the token being bad.
-            if (code === 'ERR_JWKS_TIMEOUT' || typeof code !== 'string') {
+            // A key fetch that failed, timed out or got a non-200/unreadable answer
+            // is the issuer being down, not the token being bad. jose reports the
+            // last two as a bare JOSEError; anything else without a code is a defect
+            // in the token or the call, so it is a refusal.
+            if (error instanceof KeyFetchError ||
+                code === 'ERR_JWKS_TIMEOUT' ||
+                code === 'ERR_JOSE_GENERIC') {
                 return { ok: false, reason: 'unavailable' };
             }
             return { ok: false, reason: 'invalid' };
@@ -137,30 +170,30 @@ export function createPersonTokenCore(config) {
         return outcome.ok ? outcome.payload : null;
     }
     /**
-     * RFC 7662 token introspection for an opaque access token: POSTs
-     * `token=<accessToken>` to the issuer's `introspection_endpoint`,
-     * authenticating as this resource server with `client_secret_basic`.
-     * Fails closed on anything that keeps this from reaching a real
-     * `active`/`exp`/`aud` verdict: no credentials configured, no endpoint
-     * published, a network failure, a non-2xx response, or an unparseable
-     * body -- every one of those returns `null`, refused, never accepted.
+     * RFC 7662 token introspection: POSTs `token=<accessToken>` to the
+     * issuer's `introspection_endpoint`, authenticating as this resource
+     * server with `client_secret_basic`. Fails closed on anything that keeps
+     * this from reaching a real `active`/`exp`/`aud`/`iss` verdict. A network
+     * failure, a non-2xx or an unreadable body is `unavailable`; the issuer's
+     * own answer is `revoked` (inactive), `expired` or `invalid`.
      */
-    async function introspect(accessToken) {
-        if (!config.introspectionClientId || !config.introspectionClientSecret)
-            return null;
+    async function introspectOutcome(accessToken) {
+        if (!config.introspectionClientId || !config.introspectionClientSecret) {
+            return { ok: false, reason: 'invalid' };
+        }
         const now = Date.now();
         const cached = introspectionCache.get(accessToken, now);
         if (cached)
-            return cached;
+            return { ok: true, payload: cached };
         let endpoint;
         try {
             ({ introspectionEndpoint: endpoint } = await document());
         }
         catch {
-            return null;
+            return { ok: false, reason: 'unavailable' };
         }
         if (!endpoint)
-            return null;
+            return { ok: false, reason: 'invalid' };
         const credentials = Buffer.from(`${config.introspectionClientId}:${config.introspectionClientSecret}`).toString('base64');
         let response;
         try {
@@ -175,30 +208,48 @@ export function createPersonTokenCore(config) {
             });
         }
         catch {
-            return null;
+            return { ok: false, reason: 'unavailable' };
         }
         if (!response.ok)
-            return null;
+            return { ok: false, reason: 'unavailable' };
         let body;
         try {
-            body = (await response.json());
+            const parsed = await response.json();
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { ok: false, reason: 'unavailable' };
+            }
+            body = parsed;
         }
         catch {
-            return null;
+            return { ok: false, reason: 'unavailable' };
         }
         if (body.active !== true)
-            return null;
-        if (typeof body.exp !== 'number' || body.exp <= now / 1000)
-            return null;
+            return { ok: false, reason: 'revoked' };
+        if (typeof body.exp !== 'number')
+            return { ok: false, reason: 'invalid' };
+        if (body.exp <= now / 1000)
+            return { ok: false, reason: 'expired' };
         const aud = body.aud;
         const audiences = Array.isArray(aud) ? aud : aud === undefined ? [] : [aud];
         if (!audiences.includes(config.audience))
-            return null;
-        if (typeof body.iss === 'string' && body.iss !== config.issuer)
-            return null;
+            return { ok: false, reason: 'invalid' };
+        if (body.iss !== config.issuer)
+            return { ok: false, reason: 'invalid' };
         const payload = body;
         introspectionCache.set(accessToken, payload, Math.min(body.exp * 1000, now + INTROSPECTION_CACHE_TTL_MS));
-        return payload;
+        return { ok: true, payload };
+    }
+    async function introspect(accessToken) {
+        const outcome = await introspectOutcome(accessToken);
+        return outcome.ok ? outcome.payload : null;
+    }
+    function identityOf(payload) {
+        if (typeof payload.sub !== 'string' || !payload.sub)
+            return null;
+        const organizationId = payload[ORG_CLAIM];
+        return typeof organizationId === 'string' && organizationId
+            ? { sub: payload.sub, organizationId }
+            : { sub: payload.sub };
     }
     return {
         async verifyJwtClaims(accessToken) {
@@ -213,13 +264,34 @@ export function createPersonTokenCore(config) {
             const payload = JWT_SHAPE.test(accessToken)
                 ? await verifyJwt(accessToken)
                 : await introspect(accessToken);
-            if (!payload || typeof payload.sub !== 'string' || !payload.sub)
-                return null;
-            return { sub: payload.sub };
+            return payload ? identityOf(payload) : null;
+        },
+        async verifyOutcome(accessToken) {
+            let payload;
+            if (JWT_SHAPE.test(accessToken)) {
+                const jwt = await verifyJwtOutcome(accessToken);
+                if (!jwt.ok)
+                    return jwt;
+                const live = await introspectOutcome(accessToken);
+                if (!live.ok)
+                    return live;
+                if (typeof live.payload.sub === 'string' && live.payload.sub !== jwt.payload.sub) {
+                    return { ok: false, reason: 'invalid' };
+                }
+                payload = jwt.payload;
+            }
+            else {
+                const live = await introspectOutcome(accessToken);
+                if (!live.ok)
+                    return live;
+                payload = live.payload;
+            }
+            const identity = identityOf(payload);
+            return identity ? { ok: true, identity } : { ok: false, reason: 'invalid' };
         },
     };
 }
 export function createPersonTokenVerifier(config) {
-    const { verify } = createPersonTokenCore(config);
-    return { verify };
+    const { verify, verifyOutcome } = createPersonTokenCore(config);
+    return { verify, verifyOutcome };
 }