@wtfalch/auth 0.20.0 → 0.23.0

package/README.md

@@ -257,7 +257,7 @@ refresh token to begin with.
 | `appUrl` | This app's origin. Every URL the SDK builds starts here, never from the request's `Host`. |
 | `clientId` | The OIDC client for this origin. Each URL an app runs at is its own client, because the issuer holds one login URL per application. |
 | `organizationId` | Scopes every sign-in, and is checked on every token. |
-| `cookieSecret` | 32 bytes, `openssl rand -base64 32`. One per app. |
+| `cookieSecret` | 32 bytes, `openssl rand -base64 32`. **Each app needs its own** -- see below. |
 | `appKey` | This app's key for the sign-in service. Needed for anything that checks or creates a credential. |
 
 Values are read on first use rather than at import, so `next build` needs none
@@ -269,6 +269,13 @@ unset: the error waits until something actually reaches for the key. A secret
 that is *supplied and wrong* still throws at startup, because that is a typo
 rather than a deployment that does not need one.
 
+**Each app's `cookieSecret` must be its own, not shared with another app.**
+The AES key `cookies.ts` actually encrypts and decrypts with is HKDF-SHA256
+derived from `cookieSecret` using a fixed info string common to every
+consumer of this package -- two apps given the same `cookieSecret` would
+derive the identical key and could open each other's session cookies.
+Foundry already mints a distinct secret per app.
+
 ## What the app key can do
 
 It reaches the sign-in service, which holds ZITADEL's login client. Scoped to

package/dist/auth.d.ts

@@ -251,6 +251,18 @@ export interface Auth {
     }, requestHeaders?: Headers): Promise<SignedIn<SignInError> | (PasswordChangeRequired & {
         message: string;
     })>;
+    /**
+     * `signUp` as data, run over the same server-started transaction as
+     * `signInWithPassword` -- for a caller with no browser to carry through
+     * the OIDC redirect. Unlike `signUp`, which needs an `authRequestId` a
+     * browser flow already started with `start()`, this starts and finishes
+     * its own transaction, exactly as `signInWithPassword` does. Same two
+     * checks apply: an `ok: true` with an empty `cookies` means hosted
+     * login, and the cookie name is fixed.
+     */
+    signUpWithPassword(input: {
+        next?: string;
+    } & NewUser, requestHeaders?: Headers): Promise<SignedIn<SignUpError>>;
     /** Emails a fresh verification link. Says nothing about whether the address exists. */
     resendVerification(email: string, next?: string): Promise<void>;
     /** Emails a password-reset link to {basePath}/reset?userId=&code=. Says nothing about whether the address exists. */
@@ -280,6 +292,20 @@ export interface Auth {
         invited: boolean;
         personalEmailStored: boolean;
     }>;
+    /**
+     * A company's own test user: a new person, marked in the sign-in service
+     * so nothing it does is read as a real customer. Refused for an address
+     * that already has a user, and for an entry that acts as another (stage,
+     * a laptop) -- a test user is made from production's entry.
+     */
+    createTestUser(input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        username?: string;
+    }): Promise<{
+        userId: string;
+    }>;
     handle(request: Request): Promise<Response>;
     /**
      * `refresh: false` for callers that cannot set cookies; they get a user only while the token is valid.

package/dist/auth.js

@@ -539,6 +539,11 @@ export function createAuth(input) {
         emit({ type: 'invite', email: input.email, userId: result.userId, invited: result.invited });
         return result;
     };
+    const createTestUser = async (input) => {
+        const result = await broker().createTestUser(input);
+        emit({ type: 'createTestUser', email: input.email, userId: result.userId });
+        return result;
+    };
     /**
      * An admin's reset for somebody in this app's own organisation whom
      * `requestPasswordReset` cannot otherwise get back in -- nobody at the
@@ -670,6 +675,36 @@ export function createAuth(input) {
             return { ok: false, error: code, message };
         }
     };
+    const signUpWithPassword = async ({ next, ...user }, requestHeaders) => {
+        try {
+            const flow = await serverFlow();
+            const completed = await finishOrHandoff(() => broker().signUp({ authRequestId: flow.id, ...user }), flow, safeNextPath(next, options().afterLogin), requestHeaders);
+            emit({ type: 'signUp', email: user.email });
+            return { ok: true, ...completed };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.error === 'email_taken') {
+                return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'registration_closed') {
+                return { ok: false, error: 'registration_closed', message: error.detail ?? error.error };
+            }
+            // Both carry a sentence about the name, for the form to show as it is.
+            if (error instanceof BrokerError && error.error === 'username_taken') {
+                return { ok: false, error: 'username_taken', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'username_invalid') {
+                return { ok: false, error: 'username_invalid', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'request') {
+                return { ok: false, error: 'request', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.status < 500) {
+                return { ok: false, error: 'invalid', message: error.detail ?? error.error };
+            }
+            return { ok: false, error: 'unavailable', message: 'the sign-in service did not answer' };
+        }
+    };
     const signUp = async ({ authRequestId, ...user }) => {
         try {
             const redirectTo = await broker().signUp({ authRequestId, ...user });
@@ -936,6 +971,7 @@ export function createAuth(input) {
         resetPassword,
         sendLink,
         invite,
+        createTestUser,
         handle,
         read,
         readCookie,
@@ -954,6 +990,7 @@ export function createAuth(input) {
         setNewPassword,
         setNewPasswordHeadless,
         signInWithPassword,
+        signUpWithPassword,
         signUp,
         startPasskeyRegistration,
         finishPasskeyRegistration,

package/dist/broker.d.ts

@@ -137,6 +137,15 @@ export declare class Broker {
         personalEmailStored: boolean;
     }>;
     sendLink(email: string, next: string): Promise<unknown>;
+    /** A company's own test user, marked in the sign-in service. See `Auth['createTestUser']`. */
+    createTestUser(input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        username?: string;
+    }): Promise<{
+        userId: string;
+    }>;
     sendReset(email: string, next: string): Promise<unknown>;
     sendVerification(email: string, next: string): Promise<unknown>;
     /**

package/dist/broker.js

@@ -118,6 +118,10 @@ export class Broker {
     sendLink(email, next) {
         return this.call('POST', '/link/send', { email, next });
     }
+    /** A company's own test user, marked in the sign-in service. See `Auth['createTestUser']`. */
+    createTestUser(input) {
+        return this.call('POST', '/test-users', input);
+    }
     sendReset(email, next) {
         return this.call('POST', '/reset/send', { email, next });
     }

package/dist/browser.js

@@ -1,6 +1,10 @@
 import { createNamespaceBrowserAuth } from './namespace-browser.js';
 const TOKEN = 'wtfalch.auth.token';
 const VERIFIER = 'wtfalch.auth.verifier';
+/** CSRF protection on the callback: checked before the code exchange, never persisted past it. */
+const STATE = 'wtfalch.auth.state';
+/** Replay protection on the ID token: checked against its own claim after the exchange, never persisted past it. */
+const NONCE = 'wtfalch.auth.nonce';
 const RETURN = 'wtfalch.auth.return';
 /** Set before a silent attempt leaves, so a refusal cannot become a loop. */
 const TRIED = 'wtfalch.auth.silent-tried';
@@ -44,9 +48,26 @@ async function challengeFor(verifier) {
 }
 function verifier() {
     // 32 bytes is RFC 7636's recommendation; base64url of it is 43 characters,
-    // inside the 43..128 the spec allows.
+    // inside the 43..128 the spec allows. Reused below for `state` and `nonce`
+    // too -- a random, unguessable token is exactly what each of the three is.
     return base64url(crypto.getRandomValues(new Uint8Array(32)).buffer);
 }
+/** The payload of a JWT, read without verifying its signature -- the ID token here comes straight
+ *  from the token endpoint over TLS, which OIDC Core 1.0 3.1.3.7 allows in place of a signature
+ *  check for the authorization code flow. Never used to trust a claim from anywhere else. */
+function decodeJwtPayload(jwt) {
+    try {
+        const part = jwt.split('.')[1];
+        if (!part)
+            return null;
+        const base64 = part.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+        return JSON.parse(atob(padded));
+    }
+    catch {
+        return null;
+    }
+}
 function publicSession(session) {
     const { refreshToken, ...rest } = session;
     return rest;
@@ -86,6 +107,8 @@ export function createBrowserAuth(options) {
     const key = (name) => (context ? `wtfalch.auth.browser.v1:${context}:${name}` : name);
     const tokenKey = key(TOKEN);
     const verifierKey = key(VERIFIER);
+    const stateKey = key(STATE);
+    const nonceKey = key(NONCE);
     const returnKey = key(RETURN);
     const triedKey = key(TRIED);
     let contexts = coordinators.get(store);
@@ -117,6 +140,8 @@ export function createBrowserAuth(options) {
     const authorize = async (prompt, returnTo) => {
         const generation = ++coordinator.generation;
         const proof = verifier();
+        const state = verifier();
+        const nonce = verifier();
         await mutate(async () => {
             if (!current(generation))
                 return;
@@ -127,6 +152,12 @@ export function createBrowserAuth(options) {
             if (!current(generation))
                 return;
             await store.set(verifierKey, proof);
+            if (!current(generation))
+                return;
+            await store.set(stateKey, state);
+            if (!current(generation))
+                return;
+            await store.set(nonceKey, nonce);
             if (!current(generation))
                 return;
             await store.set(returnKey, returnTo);
@@ -140,6 +171,8 @@ export function createBrowserAuth(options) {
         url.searchParams.set('scope', scope);
         url.searchParams.set('code_challenge', await challengeFor(proof));
         url.searchParams.set('code_challenge_method', 'S256');
+        url.searchParams.set('state', state);
+        url.searchParams.set('nonce', nonce);
         if (prompt)
             url.searchParams.set('prompt', prompt);
         if (!current(generation))
@@ -240,16 +273,27 @@ export function createBrowserAuth(options) {
                 if (!current(generation))
                     return null;
                 const proof = store.get(verifierKey);
+                const expectedState = store.get(stateKey);
+                const expectedNonce = store.get(nonceKey);
                 const returnTo = store.get(returnKey) ?? '/';
+                // Cleared together, unconditionally, before any check below runs --
+                // a mismatch is refused on its own terms, not merely by virtue of a
+                // transaction that cannot be replayed a second time either way.
                 await store.drop(verifierKey);
+                if (!current(generation))
+                    return null;
+                await store.drop(stateKey);
+                if (!current(generation))
+                    return null;
+                await store.drop(nonceKey);
                 if (!current(generation))
                     return null;
                 await store.drop(returnKey);
-                return { proof, returnTo };
+                return { proof, expectedState, expectedNonce, returnTo };
             });
             if (!transaction || !current(generation))
                 return cancelled();
-            const { proof, returnTo } = transaction;
+            const { proof, expectedState, expectedNonce, returnTo } = transaction;
             const issuerError = params.get('error');
             if (issuerError) {
                 if (['login_required', 'interaction_required', 'consent_required'].includes(issuerError)) {
@@ -257,6 +301,13 @@ export function createBrowserAuth(options) {
                 }
                 return { kind: 'error', error: params.get('error_description') ?? issuerError };
             }
+            // Checked before the code exchange: a callback whose `state` does not
+            // match this tab's own sign-in is refused before it ever reaches the
+            // issuer, exactly as a cross-site request forgery on this callback
+            // would need it not to be.
+            if (params.get('state') !== expectedState) {
+                return { kind: 'error', error: 'the callback state does not match this sign-in' };
+            }
             const code = params.get('code');
             if (!code)
                 return { kind: 'error', error: 'the issuer sent no code' };
@@ -293,6 +344,14 @@ export function createBrowserAuth(options) {
                     return cancelled();
                 if (!token.access_token)
                     return { kind: 'error', error: 'the issuer returned no access token' };
+                // Checked against the ID token's own claim, after the exchange: a
+                // code this flow never requested cannot be replayed into a session
+                // here even if it were otherwise accepted, because the token minted
+                // for it carries a different nonce.
+                const idTokenClaims = token.id_token ? decodeJwtPayload(token.id_token) : null;
+                if (idTokenClaims?.nonce !== expectedNonce) {
+                    return { kind: 'error', error: 'the ID token nonce does not match this sign-in' };
+                }
                 const session = {
                     accessToken: token.access_token,
                     expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
@@ -326,6 +385,8 @@ export function createBrowserAuth(options) {
             await mutate(async () => {
                 await store.drop(tokenKey);
                 await store.drop(verifierKey);
+                await store.drop(stateKey);
+                await store.drop(nonceKey);
                 await store.drop(returnKey);
                 await store.set(triedKey, '1');
             });

package/dist/config.d.ts

@@ -24,6 +24,10 @@ export type AuthEvent = {
  | {
     type: 'adminResetPassword';
     userId: string;
+} | {
+    type: 'createTestUser';
+    email: string;
+    userId: string;
 };
 /**
  * Why `accessToken` refused: no session (no cookie in cookie mode, no live
@@ -158,3 +162,14 @@ export interface ResolvedOptions {
     onAuthEvent: ((event: AuthEvent) => void) | null;
 }
 export declare function resolveOptions(options: AuthOptions): ResolvedOptions;
+/**
+ * The actual AES-256 key `cookies.ts` encrypts and decrypts with -- HKDF-SHA256
+ * over the decoded `cookieSecret`, never the secret's bytes directly. A secret an
+ * operator can read (an env var, a value pasted into a terminal) is weaker key
+ * material than a key meant to be used as one; HKDF's job is exactly this gap.
+ * No fallback to the raw key: decided as a hard cut (auth#255), so the only
+ * way a cookie sealed before this shipped keeps validating is if it already
+ * carries no more than its own session's worth of trust -- which is what every
+ * cookie here already assumes of `sessionMaxAge`/`TRANSACTION_TTL`/etc.
+ */
+export declare function deriveCookieKey(secret: Uint8Array): Promise<Uint8Array>;

package/dist/config.js

@@ -105,3 +105,29 @@ function decodeKey(secret) {
     }
     return bytes;
 }
+// Fixed, not random: every server sealing or opening a cookie must derive
+// the same AES key from the same `cookieSecret`, so there is nowhere to
+// store a per-process salt even if one were generated. `COOKIE_KEY_INFO`
+// scopes the derivation to this one use of the secret, the same way a
+// derived key's `info` is meant to -- a future second use of `cookieSecret`
+// (there is none today) would derive under a different info string and
+// never collide with this key.
+const COOKIE_KEY_SALT = new TextEncoder().encode('@wtfalch/auth cookie salt v1');
+const COOKIE_KEY_INFO = new TextEncoder().encode('@wtfalch/auth cookie v1');
+/**
+ * The actual AES-256 key `cookies.ts` encrypts and decrypts with -- HKDF-SHA256
+ * over the decoded `cookieSecret`, never the secret's bytes directly. A secret an
+ * operator can read (an env var, a value pasted into a terminal) is weaker key
+ * material than a key meant to be used as one; HKDF's job is exactly this gap.
+ * No fallback to the raw key: decided as a hard cut (auth#255), so the only
+ * way a cookie sealed before this shipped keeps validating is if it already
+ * carries no more than its own session's worth of trust -- which is what every
+ * cookie here already assumes of `sessionMaxAge`/`TRANSACTION_TTL`/etc.
+ */
+export async function deriveCookieKey(secret) {
+    const keyMaterial = await crypto.subtle.importKey('raw', secret, 'HKDF', false, [
+        'deriveBits',
+    ]);
+    const bits = await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: COOKIE_KEY_SALT, info: COOKIE_KEY_INFO }, keyMaterial, 256);
+    return new Uint8Array(bits);
+}

package/dist/cookies.d.ts

@@ -1,5 +1,7 @@
 import { type JWTPayload } from 'jose';
-import type { ResolvedOptions } from './config.js';
+import { type ResolvedOptions } from './config.js';
+/** Exported for `namespace-server.ts`, which decrypts a transaction cookie itself to read its `ns` claim before any binding is chosen. */
+export declare function cookieKeyFor(options: ResolvedOptions): Promise<Uint8Array>;
 export interface SessionPayload extends JWTPayload {
     idt: string;
     rt?: string;

package/dist/cookies.js

@@ -1,5 +1,21 @@
 import { EncryptJWT, jwtDecrypt } from 'jose';
+import { deriveCookieKey } from './config.js';
 import { AuthError } from './oidc.js';
+// `options.cookieKey` decodes once per `ResolvedOptions` (config.ts) and is
+// always the same `Uint8Array` reference after that, so keying the derived
+// key's own cache off it means every seal/open after the first reuses it
+// rather than re-running HKDF per call.
+const derivedKeyCache = new WeakMap();
+/** Exported for `namespace-server.ts`, which decrypts a transaction cookie itself to read its `ns` claim before any binding is chosen. */
+export function cookieKeyFor(options) {
+    const raw = options.cookieKey;
+    let derived = derivedKeyCache.get(raw);
+    if (!derived) {
+        derived = deriveCookieKey(raw);
+        derivedKeyCache.set(raw, derived);
+    }
+    return derived;
+}
 const SESSION = 'wtfalch_auth';
 const TRANSACTION = 'wtfalch_auth_tx';
 const LINK = 'wtfalch_auth_link';
@@ -152,17 +168,21 @@ async function seal(options, kind, payload, ttl) {
         .setAudience(await audience(options, kind))
         .setIssuedAt()
         .setExpirationTime(Math.floor(Date.now() / 1000) + ttl)
-        .encrypt(options.cookieKey);
+        .encrypt(await cookieKeyFor(options));
 }
 async function open(options, kind, value) {
     if (!value)
         return null;
     try {
-        const { payload } = await jwtDecrypt(value, options.cookieKey, {
+        const { payload } = await jwtDecrypt(value, await cookieKeyFor(options), {
             issuer: options.appUrl.origin,
             audience: await audience(options, kind),
             contentEncryptionAlgorithms: ['A256GCM'],
             keyManagementAlgorithms: ['dir'],
+            // Every cookie `seal` makes already sets `exp` (the call's own `ttl`),
+            // so requiring it here signs nobody out -- it only refuses the one
+            // thing a cookie with none could otherwise be: unbounded.
+            requiredClaims: ['exp'],
         });
         return payload;
     }

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, ty
 export type { AccessTokenReason, AccessTokenResult, AuthEvent, AuthOptions } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';
+export type { PersonTokenConfig, PersonTokenVerifier } from './person-token.js';
 export { BrokerError } from './broker.js';
 export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
 export { safeNextPath } from './redirect.js';

package/dist/names.d.ts

@@ -38,6 +38,14 @@ export interface NameRules {
     pattern: RegExp;
 }
 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.
+ */
+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. */
+export declare function reservedNames(): readonly string[];
 /** The refusal as a sentence the person can act on. */
 export declare function explain(reason: Refusal, rules?: NameRules): string;
 export declare function checkName(name: string, rules?: NameRules): Verdict;

package/dist/names.js

@@ -35,7 +35,10 @@ strictWords.addPhrase((phrase) => {
         phrase.addWhitelistedTerm(term);
     return phrase;
 });
-const strict = new RegExpMatcher({ ...strictWords.build(), ...englishRecommendedTransformers });
+const strict = new RegExpMatcher({
+    ...strictWords.build(),
+    ...englishRecommendedTransformers,
+});
 /** Only the words that are slurs wherever they appear, read with everything between the letters skipped. */
 const looseWords = new DataSet();
 for (const entry of [
@@ -84,7 +87,7 @@ const LETTERS = {
  * collapsed. Every reading, since `1` may be an `i` or an `l`; the first is
  * the one a list entry is stored under.
  */
-function flattenings(name) {
+export function flattenings(name) {
     let forms = [''];
     for (const char of name.toLowerCase()) {
         const readings = /[a-z]/.test(char) ? [char] : (LETTERS[char] ?? []);
@@ -96,7 +99,12 @@ function flattenings(name) {
     }
     return [...new Set(forms.map((form) => form.replace(/(.)\1+/g, '$1')))];
 }
-const reserved = new Set([...reservedUsernames, ...SYSTEM, ...PEOPLE].map((entry) => flattenings(entry)[0]));
+const RESERVED = [...new Set([...reservedUsernames, ...SYSTEM, ...PEOPLE])];
+const reserved = new Set(RESERVED.map((entry) => flattenings(entry)[0]));
+/** Every entry checkName holds back: the system names, the people's and the reserved-usernames list, once each. */
+export function reservedNames() {
+    return RESERVED;
+}
 /** The name in the shapes a word might hide in. */
 function shapes(name) {
     const parts = name.split(/[^A-Za-z0-9æøåÆØÅ]+/).filter(Boolean);

package/dist/namespace-server.js

@@ -1,6 +1,6 @@
 import { jwtDecrypt } from 'jose';
 import { resolveOptions } from './config.js';
-import { cookieFrom, openTransaction, transactionCookieName } from './cookies.js';
+import { cookieFrom, cookieKeyFor, openTransaction, transactionCookieName } from './cookies.js';
 import { isWebService, parseNamespaceRegistry, } from './namespaces.js';
 /** Resolve a shared callback from its authenticated transaction, never a URL
  * namespace hint. The second open checks the entire current registry binding. */
@@ -46,7 +46,7 @@ export async function resolveNamespaceCallback(input) {
             return null;
         // No identity is returned based on this hint alone. It only chooses which
         // current binding's audience to validate next, so decryption is bounded.
-        const { payload } = await jwtDecrypt(value, first.cookieKey, {
+        const { payload } = await jwtDecrypt(value, await cookieKeyFor(first), {
             issuer: input.appOrigin,
             requiredClaims: ['exp', 'iat', 'aud'],
             contentEncryptionAlgorithms: ['A256GCM'],

package/dist/namespace-session.js

@@ -1,3 +1,4 @@
+import { sleep } from '@wtfalch/utils/datetime';
 import * as client from 'openid-client';
 import { BrokerError } from './broker.js';
 import { contextDigest, digest, openHandle, openRecord, sealHandle, sealRecord, } from './cookies.js';
@@ -15,7 +16,6 @@ const LEASE_SECONDS = 60;
 const WAIT_STEP_MS = 100;
 const WAIT_STEPS = 50;
 const now = () => Math.floor(Date.now() / 1000);
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Server-side sessions for namespace mode. The cookie holds a random handle;
  * the record holds the tokens. Refreshes are serialised across replicas by a

package/dist/person-token.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Verifies a signed-in person's own `@wtfalch/auth`/ZITADEL access token,
+ * server-side, for a service that wants to accept one directly rather than
+ * only a machine credential. Two token shapes, both checked:
+ *
+ * - A JWT (three base64url segments): `jwtVerify` against a remote JWKS
+ *   built from the issuer's discovery document -- signature (RS256),
+ *   issuer, audience, expiry. `jose`'s `createRemoteJWKSet` refetches on an
+ *   unrecognised `kid` on its own, so key rotation needs nothing here
+ *   beyond the cooldown below.
+ * - Anything else: RFC 7662 introspection against the issuer's
+ *   `introspection_endpoint`, authenticating as this resource server with
+ *   `client_secret_basic` (`introspectionClientId`/`Secret`), checking the
+ *   response's `active`, `exp` and `aud`. Not attempted -- refused outright
+ *   -- when either credential is unset, the same as an opaque token would
+ *   have refused before introspection existed. This matters because some
+ *   apps mint an *opaque* access token on purpose, and without this path no
+ *   such token could ever reach a server that only checked JWTs.
+ *
+ * Neither path checks a fixed ZITADEL organisation: a caller can come from
+ * any organisation's app, so there is nothing fixed to compare against.
+ * This module only answers "is this a live token, and whose" -- membership
+ * and authorization are the caller's own concern, same as for a machine
+ * credential.
+ *
+ * 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.
+ */
+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>;
+}
+export interface PersonTokenConfig {
+    /** The issuer every token must have been minted by, e.g.
+     *  `https://auth.wtfalch.dev`. */
+    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
+     *  `urn:zitadel:iam:org:project:id:<audience>:aud`). */
+    audience: string;
+    /** This resource server's own credentials at the issuer, for RFC 7662
+     *  introspection of an opaque (non-JWT) access token --
+     *  `client_secret_basic`. Both required together; either absent disables
+     *  introspection and an opaque bearer is refused outright. */
+    introspectionClientId?: string;
+    introspectionClientSecret?: string;
+    /** Test seam; a live deployment never sets this. */
+    fetch?: typeof fetch;
+    /** jose's default 30s would keep rejecting a token signed with a freshly
+     *  rotated key for that long; a test passes 0 so it need not sleep past a
+     *  real cooldown. */
+    jwksCooldownMs?: number;
+}
+export declare function createPersonTokenVerifier(config: PersonTokenConfig): PersonTokenVerifier;