@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/mixins/OxyServices.auth.js

@@ -1,1400 +0,0 @@
-import { emailVerificationConfirmResponseSchema, emailVerificationStartResponseSchema, loginResultSchema, safeParseContract, } from '@oxy.so/contracts';
-export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from '../utils/commonsApproval.js';
-import { OxyAuthenticationError } from '../OxyServices.errors.js';
-import { KeyManager } from '../crypto/keyManager.js';
-import { solveRegistrationPow } from '../crypto/registrationPow.js';
-import { SignatureService } from '../crypto/signatureService.js';
-import { loadNodeCrypto } from '@oxy.so/protocol';
-import { logger } from '../logger/index.js';
-import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
-/**
- * Default lifetime of a "Sign in with Oxy" device-flow session / authorize code.
- * Matches the authorize-code TTL the server enforces (5 minutes). The server's
- * returned `expiresAt` is authoritative; this is only the client-proposed value.
- */
-const COMMONS_SIGN_IN_EXPIRY_MS = 5 * 60 * 1000;
-/**
- * Fallback access-token lifetime used only if the token endpoint ever omits the
- * RFC 6749 `expires_in` member. Matches the server's current 15-minute access
- * token; the server's value always wins when present.
- */
-const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
-/**
- * @internal Narrow an untrusted `requesterLabel` from the approve-info response.
- *
- * Returns the trimmed label only when the server sent a real, non-empty string;
- * everything else — absent (an API that predates the field), `null` (a native
- * requester the server could not describe), or a non-string — degrades to
- * `null`, so the approval UI drops the line instead of rendering a blank or a
- * coerced value under the app it is about to authorize.
- */
-function parseCommonsRequesterLabel(value) {
-    if (typeof value !== 'string') {
-        return null;
-    }
-    const label = value.trim();
-    return label.length > 0 ? label : null;
-}
-/**
- * @internal Narrow an untrusted `subjectAccount` from the approve-info response.
- *
- * Returns `null` unless the value is an object carrying a non-empty string `id`
- * AND `username` — the two fields the approval UI needs to name the delegated
- * account. A half-populated object is rejected whole rather than rendered with
- * blanks, and `displayName` is only carried through when it is a string.
- */
-function parseCommonsSubjectAccount(value) {
-    if (value === null || typeof value !== 'object') {
-        return null;
-    }
-    const raw = value;
-    const { id, username, displayName } = raw;
-    if (typeof id !== 'string' || !id || typeof username !== 'string' || !username) {
-        return null;
-    }
-    return {
-        id,
-        username,
-        ...(typeof displayName === 'string' ? { displayName } : {}),
-    };
-}
-/**
- * @internal Narrow an untrusted delivery-progress timestamp from the status
- * response.
- *
- * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
- * and `null` for everything else — absent (an older API that has no delivery
- * progress at all), empty, non-string, or unparseable. Progress is advisory, so
- * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
- * to the waiting UI is not.
- */
-function parseCommonsProgressTimestamp(value) {
-    if (typeof value !== 'string' || !value) {
-        return null;
-    }
-    return Number.isFinite(Date.parse(value)) ? value : null;
-}
-/**
- * Sentinel error raised when getServiceToken() is called with a known apiKey
- * but a non-matching secret. Indicates either credential drift in the caller
- * or a cross-tenant cache lookup attempt. Surface as a 401-equivalent.
- */
-export class ServiceCredentialMismatchError extends Error {
-    constructor() {
-        super('Service credential mismatch: provided secret does not match the secret stored for this apiKey');
-        this.name = 'ServiceCredentialMismatchError';
-    }
-}
-export function OxyServicesAuthMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-            /**
-             * Per-credential token cache.
-             *
-             * Keyed by SHA-256(apiKey). Each entry carries:
-             *   - the issued service JWT
-             *   - its expiry timestamp
-             *   - the secret that produced it (Buffer for constant-time compare)
-             *   - an optional in-flight promise to deduplicate concurrent refreshes
-             *
-             * The previous implementation kept ONE token/exp pair per OxyServices
-             * instance. That meant calling `getServiceToken(keyA, secretA)` populated
-             * the cache, and a subsequent `getServiceToken(keyB, secretB)` (different
-             * tenant) would receive tenant A's token. This is fixed by routing every
-             * lookup through the Map.
-             *
-             * @internal
-             */
-            this._serviceTokenCache = new Map();
-            /** @internal Raw apiKey stored by configureServiceAuth() for use by getServiceToken() */
-            this._serviceApiKey = null;
-            /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
-            this._serviceApiSecret = null;
-        }
-        /**
-         * Hash an apiKey into a stable Map cache key. Uses Node's SHA-256 — service
-         * tokens are only ever issued by a Node host (the SDK on web/RN never has
-         * the apiSecret in the first place), so we can rely on Node crypto here.
-         *
-         * @internal
-         */
-        async _hashApiKey(apiKey) {
-            const nodeCrypto = await loadNodeCrypto();
-            return nodeCrypto.createHash('sha256').update(apiKey).digest('hex');
-        }
-        /**
-         * Configure service credentials for internal service-to-service communication.
-         * Call this once at startup so that getServiceToken() and makeServiceRequest()
-         * can automatically obtain and refresh tokens.
-         *
-         * Calling this with credentials that differ from a previously-configured pair
-         * is allowed — each `(apiKey, apiSecret)` pair is cached independently, so
-         * legitimate multi-tenant hosts that need to switch credentials cannot leak
-         * one tenant's token to another tenant on the same instance.
-         *
-         * @param apiKey - Application credential public key (oxy_dk_*)
-         * @param apiSecret - Application credential secret
-         */
-        configureServiceAuth(apiKey, apiSecret) {
-            this._serviceApiKey = apiKey;
-            this._serviceApiSecret = apiSecret;
-        }
-        /**
-         * Get a service token for internal service-to-service communication.
-         * Tokens are short-lived (1h) and automatically cached/refreshed per
-         * `(apiKey, apiSecret)` pair.
-         *
-         * Concurrent callers for the same credential pair share a single in-flight
-         * request to avoid hammering `/auth/service-token` when the cache is empty
-         * or expired.
-         *
-         * **Security guarantee:** if the cache already holds a token for this
-         * apiKey but the supplied apiSecret does not constant-time match the
-         * secret that originally produced that token, this method throws
-         * `ServiceCredentialMismatchError` instead of returning the cached token.
-         * This prevents an attacker who learned a peer's apiKey from extracting
-         * their service token by polling with a wrong secret.
-         *
-         * @param apiKey - Application credential public key (optional if configureServiceAuth was called)
-         * @param apiSecret - Application credential secret (optional if configureServiceAuth was called)
-         */
-        async getServiceToken(apiKey, apiSecret) {
-            const key = apiKey || this._serviceApiKey;
-            const secret = apiSecret || this._serviceApiSecret;
-            if (!key || !secret) {
-                /**
-                 * No credential configured — so prove what this process IS instead
-                 * (ADR 0026).
-                 *
-                 * This is what lets an official service drop its api key and secret
-                 * WITHOUT a code change: remove the two environment variables, and the
-                 * next token comes from the workload path. It is deliberately the
-                 * fallback rather than the preference, so a deployment that still has a
-                 * credential keeps using it and the migration is one service at a time.
-                 *
-                 * A process with no credential AND no attestation still gets the
-                 * original error: "nothing to authenticate with" is the truth there, and
-                 * a local checkout must not be told to go looking for a container
-                 * credentials endpoint that is not there.
-                 */
-                if (await this._canUseWorkloadIdentity()) {
-                    return this._getWorkloadServiceToken();
-                }
-                throw new Error('Service credentials not provided. Call configureServiceAuth() or pass apiKey and apiSecret.');
-            }
-            const cacheKey = await this._hashApiKey(key);
-            const now = Date.now();
-            const providedSecretBuf = Buffer.from(secret, 'utf8');
-            let entry = this._serviceTokenCache.get(cacheKey);
-            // Verify the secret on every cache hit, regardless of token freshness.
-            // Constant-time compare prevents timing oracles on the stored secret.
-            if (entry) {
-                const nodeCrypto = await loadNodeCrypto();
-                const storedSecretBuf = entry.secretBuf;
-                const lengthMatch = storedSecretBuf.length === providedSecretBuf.length;
-                // Always run timingSafeEqual on equal-length inputs to keep timing flat.
-                // When lengths differ, run against a zero-padded copy of the same length
-                // to avoid an early-return timing signal.
-                const compareBuf = lengthMatch
-                    ? providedSecretBuf
-                    : Buffer.alloc(storedSecretBuf.length);
-                const compareResult = nodeCrypto.timingSafeEqual(storedSecretBuf, compareBuf);
-                if (!lengthMatch || !compareResult) {
-                    logger.warn('[oxy.auth] Service token cache hit with mismatched secret', {
-                        component: 'auth',
-                        method: 'getServiceToken',
-                    });
-                    throw new ServiceCredentialMismatchError();
-                }
-                // Return cached token if still valid (with 60s buffer for clock drift)
-                if (entry.token && entry.expiresAt > now + 60000) {
-                    return entry.token;
-                }
-                // If a fetch is already in-flight for this credential, share its result
-                if (entry.pending) {
-                    return entry.pending;
-                }
-            }
-            else {
-                // First time seeing this apiKey on this instance — seed an empty entry
-                // so concurrent callers serialize on the same promise.
-                entry = {
-                    token: '',
-                    expiresAt: 0,
-                    secretBuf: providedSecretBuf,
-                    pending: null,
-                    apiKey: key,
-                };
-                this._serviceTokenCache.set(cacheKey, entry);
-            }
-            const pending = this._doFetchServiceToken(key, secret, cacheKey, providedSecretBuf);
-            entry.pending = pending;
-            try {
-                return await pending;
-            }
-            catch (error) {
-                // Do not retain unauthenticated cache entries. If the initial
-                // /auth/service-token request fails (for example, wrong apiSecret),
-                // leaving the pre-seeded empty entry would cause later calls with the
-                // real secret for the same apiKey to fail locally as a credential
-                // mismatch without ever contacting the server. Keep previously-issued
-                // stale tokens on refresh failures, but remove never-authenticated
-                // entries.
-                const failed = this._serviceTokenCache.get(cacheKey);
-                if (failed?.pending === pending && !failed.token) {
-                    this._serviceTokenCache.delete(cacheKey);
-                }
-                throw error;
-            }
-            finally {
-                // Clear the in-flight slot; the entry itself (with fresh token / expiry)
-                // is updated inside _doFetchServiceToken before we land here.
-                const settled = this._serviceTokenCache.get(cacheKey);
-                if (settled?.pending === pending) {
-                    settled.pending = null;
-                }
-            }
-        }
-        /**
-         * Whether this process can prove what it is (ADR 0026).
-         *
-         * `#workload-identity` (package.json `imports`) selects a client
-         * implementation for native and browser bundlers, and the signer only for
-         * Node hosts. The runtime Node guard avoids calling attestation on clients;
-         * the module boundary keeps node:crypto out of their bundle graphs (a guard
-         * alone cannot). It is a package import, not a self-reference to an export
-         * subpath: a self-reference only resolves where `@oxy.so/core` is reachable
-         * through `node_modules`, which bundlers inside this workspace are not.
-         *
-         * @internal
-         */
-        async _canUseWorkloadIdentity() {
-            if (typeof process === 'undefined' || !process.versions?.node)
-                return false;
-            try {
-                const { canAttestWorkloadIdentity } = await import('#workload-identity');
-                return canAttestWorkloadIdentity();
-            }
-            catch {
-                // A bundler that dropped the server subpath, or a runtime without it.
-                // "We cannot attest here" is the correct reading, and the caller falls
-                // back to the credential error it would have thrown anyway.
-                return false;
-            }
-        }
-        /**
-         * A service token obtained by attestation, cached like a credential's.
-         *
-         * The cache key is a constant, not a credential hash: a process has exactly
-         * one identity, so there is nothing to key on and nothing to keep separate.
-         * The secret-comparison guard the credential path applies has nothing to
-         * compare here, which is the point — there is no secret.
-         *
-         * @internal
-         */
-        async _getWorkloadServiceToken() {
-            const cacheKey = 'workload-identity';
-            const entry = this._serviceTokenCache.get(cacheKey);
-            const now = Date.now();
-            if (entry?.token && entry.expiresAt > now + 60000)
-                return entry.token;
-            if (entry?.pending)
-                return entry.pending;
-            const { requestWorkloadServiceToken } = await import('#workload-identity');
-            const seeded = entry ?? {
-                token: '',
-                expiresAt: 0,
-                secretBuf: Buffer.alloc(0),
-                pending: null,
-                apiKey: cacheKey,
-            };
-            this._serviceTokenCache.set(cacheKey, seeded);
-            const pending = (async () => {
-                const granted = await requestWorkloadServiceToken({ baseUrl: this.getBaseURL() });
-                const current = this._serviceTokenCache.get(cacheKey);
-                if (current) {
-                    current.token = granted.token;
-                    current.expiresAt = Date.now() + granted.expiresIn * 1000;
-                }
-                return granted.token;
-            })();
-            seeded.pending = pending;
-            try {
-                return await pending;
-            }
-            catch (error) {
-                // Never keep an entry that never held a token: the next caller must try
-                // again rather than inherit a failure.
-                const failed = this._serviceTokenCache.get(cacheKey);
-                if (failed?.pending === pending && !failed.token)
-                    this._serviceTokenCache.delete(cacheKey);
-                throw error;
-            }
-            finally {
-                const settled = this._serviceTokenCache.get(cacheKey);
-                if (settled?.pending === pending)
-                    settled.pending = null;
-            }
-        }
-        /**
-         * Perform the actual /auth/service-token request and cache the result.
-         * Separated so getServiceToken() can deduplicate concurrent calls.
-         * @internal
-         */
-        async _doFetchServiceToken(key, secret, cacheKey, secretBuf) {
-            const response = await this.makeRequest('POST', '/auth/service-token', { apiKey: key, apiSecret: secret }, { cache: false, retry: false, skipAuth: true });
-            const expiresAt = Date.now() + response.expiresIn * 1000;
-            // Update the entry in-place so any caller that already grabbed a reference
-            // (via `_serviceTokenCache.get(...)`) sees the fresh state.
-            const entry = this._serviceTokenCache.get(cacheKey);
-            if (entry) {
-                entry.token = response.token;
-                entry.expiresAt = expiresAt;
-                entry.secretBuf = secretBuf;
-            }
-            else {
-                this._serviceTokenCache.set(cacheKey, {
-                    token: response.token,
-                    expiresAt,
-                    secretBuf,
-                    pending: null,
-                    apiKey: key,
-                });
-            }
-            return response.token;
-        }
-        /**
-         * Invalidate cached service token(s), forcing the next `getServiceToken()`
-         * call to mint a fresh token from `/auth/service-token`.
-         *
-         * `getServiceToken()` only refreshes on expiry (with a 60s clock-drift
-         * buffer), so a credential that is revoked or rotated mid-run — surfaced as
-         * a 401 on a downstream service request — cannot otherwise be recovered
-         * within the same process: the still-unexpired cached token keeps being
-         * returned. Call this after such a 401 to clear the stale entry; the very
-         * next `getServiceToken()` for that credential re-mints.
-         *
-         * Fully synchronous and deterministic: the call completes before it
-         * returns, so a `getServiceToken()` issued immediately afterwards is
-         * guaranteed to see the cleared cache and mint anew.
-         *
-         * @param apiKey - When provided, clears only the cache entry for that
-         *   specific apiKey. When omitted, clears the entry for the credential set
-         *   via `configureServiceAuth()`; if neither is available (no key to
-         *   target), clears the entire cache. Passing no argument is the common
-         *   case for hosts that configured a single service credential at startup.
-         *
-         * The cache Map is keyed by an asynchronously-computed `SHA-256(apiKey)`
-         * that cannot be reproduced synchronously, so a targeted clear scans the
-         * entries and removes the one whose stored raw `apiKey` matches — keeping
-         * this method synchronous. The fully-untargeted call (no argument and no
-         * configured key) clears every entry, which is safe because each credential
-         * pair is independently re-minted on its next request.
-         */
-        invalidateServiceToken(apiKey) {
-            const targetKey = apiKey ?? this._serviceApiKey;
-            // No specific credential to target — clear everything. The next
-            // getServiceToken() for any credential re-mints from scratch.
-            if (!targetKey) {
-                this._serviceTokenCache.clear();
-                return;
-            }
-            for (const [cacheKey, entry] of this._serviceTokenCache) {
-                if (entry.apiKey === targetKey) {
-                    this._serviceTokenCache.delete(cacheKey);
-                    return;
-                }
-            }
-        }
-        /**
-         * Make an authenticated request on behalf of a user using a service token.
-         * Automatically obtains/refreshes the service token.
-         *
-         * @param method - HTTP method
-         * @param url - API endpoint URL
-         * @param data - Request body or query params
-         * @param userId - Optional user ID to act on behalf of (sent as X-Oxy-User-Id)
-         */
-        async makeServiceRequest(method, url, data, userId) {
-            const token = await this.getServiceToken();
-            const headers = {
-                Authorization: `Bearer ${token}`,
-            };
-            if (userId) {
-                headers['X-Oxy-User-Id'] = userId;
-            }
-            return this.makeRequest(method, url, data, { headers, cache: false });
-        }
-        /**
-         * Register a new identity with public key authentication
-         * Identity is purely cryptographic - username and profile data are optional
-         *
-         * @param publicKey - The user's ECDSA public key (hex)
-         * @param signature - Signature of the registration request
-         * @param timestamp - Timestamp when the signature was created
-         */
-        async register(publicKey, signature, timestamp) {
-            try {
-                // Advisory for now (server soft-enforces — see
-                // `SessionController.register`), but solved unconditionally so every
-                // client is already sending it once the server starts requiring it.
-                const powNonce = await solveRegistrationPow(publicKey, timestamp);
-                const res = await this.makeRequest('POST', '/auth/register', {
-                    publicKey,
-                    signature,
-                    timestamp,
-                    powNonce,
-                }, { cache: false, skipAuth: true });
-                if (!res || (typeof res === 'object' && Object.keys(res).length === 0)) {
-                    throw new OxyAuthenticationError('Registration failed', 'REGISTER_FAILED', 400);
-                }
-                return res;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Request an authentication challenge
-         * The client must sign this challenge with their private key
-         *
-         * @param publicKey - The user's public key
-         * @param requestOptions - Optional per-call transport overrides (`retry`,
-         *   `timeout`). Interactive callers omit it (defaults keep retries); the
-         *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
-         *   network cannot multiply boot latency via the inner retry loop.
-         */
-        async requestChallenge(publicKey, requestOptions) {
-            try {
-                return await this.makeRequest('POST', '/auth/challenge', {
-                    publicKey,
-                }, { cache: false, skipAuth: true, ...requestOptions });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Verify a signed challenge and create a session
-         *
-         * @param publicKey - The user's public key
-         * @param challenge - The challenge string from requestChallenge
-         * @param signature - Signature of the auth message
-         * @param timestamp - Timestamp when the signature was created
-         * @param deviceName - Optional device name
-         * @param deviceFingerprint - Optional device fingerprint
-         * @param requestOptions - Optional per-call transport overrides (`retry`,
-         *   `timeout`). Interactive callers omit it (defaults keep retries); the
-         *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
-         *   network cannot multiply boot latency via the inner retry loop.
-         * @param options.plantTokens - Install the returned bearer on this client
-         *   (default `true`). A caller that must decide LATER whether the session is
-         *   still wanted (the account dialog, whose user may have cancelled while the
-         *   request was in flight) passes `false` and plants it itself.
-         */
-        async verifyChallenge(publicKey, challenge, signature, timestamp, deviceName, deviceFingerprint, requestOptions, options = {}) {
-            try {
-                const res = await this.makeRequest('POST', '/auth/verify', {
-                    publicKey,
-                    challenge,
-                    signature,
-                    timestamp,
-                    deviceName,
-                    deviceFingerprint,
-                }, { cache: false, skipAuth: true, ...requestOptions });
-                // Plant the freshly-minted tokens, mirroring `claimSessionByToken`.
-                // `/auth/verify` returns the first access token (and refresh token) in
-                // its body, so installing it here means callers get an authenticated
-                // client without a second round-trip. Refresh stays in the httpOnly
-                // cookie slot set by the API.
-                if (res?.accessToken && options.plantTokens !== false) {
-                    this.setTokens(res.accessToken);
-                }
-                return {
-                    ...res,
-                    user: normalizeUserIdentity(res.user),
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Check if a public key is already registered
-         */
-        async checkPublicKeyRegistered(publicKey) {
-            try {
-                return await this.makeRequest('GET', `/auth/check-publickey/${encodeURIComponent(publicKey)}`, undefined, { cache: false, skipAuth: true });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Get user by public key
-         */
-        async getUserByPublicKey(publicKey) {
-            try {
-                const user = await this.makeRequest('GET', `/auth/user/${encodeURIComponent(publicKey)}`, undefined, {
-                    cache: true,
-                    cacheTTL: 2 * 60 * 1000,
-                    // Public lookup by public key (pre-session) — skip the bearer preflight.
-                    skipAuth: true,
-                });
-                return normalizeUserIdentity(user);
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Get user by session ID
-         */
-        async getUserBySession(sessionId) {
-            try {
-                const user = await this.makeRequest('GET', `/session/user/${sessionId}`, undefined, {
-                    cache: true,
-                    cacheTTL: 2 * 60 * 1000,
-                });
-                return normalizeUserIdentity(user);
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Batch get multiple user profiles by session IDs
-         */
-        async getUsersBySessions(sessionIds) {
-            try {
-                if (!Array.isArray(sessionIds) || sessionIds.length === 0) {
-                    return [];
-                }
-                const uniqueSessionIds = Array.from(new Set(sessionIds)).sort();
-                const users = await this.makeRequest('POST', '/session/users/batch', { sessionIds: uniqueSessionIds }, {
-                    cache: true,
-                    cacheTTL: 2 * 60 * 1000,
-                    deduplicate: true,
-                });
-                return users.map((entry) => ({
-                    ...entry,
-                    user: normalizeUserIdentityOrNull(entry.user),
-                }));
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Exchange a device-flow sessionToken for the first access token.
-         *
-         * The originating client holds a 128-bit `sessionToken` that nobody
-         * else has seen — it was generated client-side, sent once on
-         * `POST /auth/session/create`, and is never echoed back. After
-         * another authenticated device approves the session via
-         * `POST /auth/session/authorize/{sessionToken}` (bearer-authed) and
-         * the auth socket / poll loop notifies this client, the client
-         * exchanges its `sessionToken` here for the first access token,
-         * refresh token, sessionId, and the authorized user.
-         *
-         * This call requires no Authorization header — the high-entropy
-         * `sessionToken` IS the credential (RFC 8628 §3.4). The exchange is
-         * single-use; replay attempts are rejected with 401.
-         *
-         * @param sessionToken - The same sessionToken the SDK passed to
-         *   `POST /auth/session/create` at the start of the flow.
-         * @param options.deviceFingerprint - Optional fingerprint of the
-         *   originating client device.
-         * @param options.plantTokens - Install the claimed bearer on this client
-         *   (default `true`). Pass `false` to install it yourself once you know the
-         *   session is still wanted — see `verifyChallenge`.
-         */
-        async claimSessionByToken(sessionToken, options = {}) {
-            try {
-                const res = await this.makeRequest('POST', '/auth/session/claim', {
-                    sessionToken,
-                    ...(options.deviceFingerprint ? { deviceFingerprint: options.deviceFingerprint } : {}),
-                }, 
-                // Body-authenticated device-flow claim (no bearer) — skip the preflight.
-                { cache: false, retry: false, skipAuth: true });
-                if (options.plantTokens !== false) {
-                    this.setTokens(res.accessToken);
-                }
-                return res;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =======================================================================
-        // "Sign in with Oxy" — handoff (Workstream C)
-        //
-        // Two mechanisms share the same challenge/verify + device-flow primitives:
-        //   A. Same-device shared-keychain SSO (`signInWithSharedIdentity`): a
-        //      sibling native app silently mints its own session from the shared
-        //      identity key. No user interaction.
-        //   B. QR / app-to-app / popup / push handoff: a relying party
-        //      (`startCommonsSignIn` + `pollCommonsSignIn`, finalized with either
-        //      `claimSessionByToken` or `finalizeCommonsOAuth`) and the approver /
-        //      Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn` /
-        //      `denyCommonsSignIn`). The approver signs with its PRIMARY local key;
-        //      the RP never sees the private key.
-        //
-        //      ONE request serves every delivery surface. The delivery surface is
-        //      not part of the model: only the request's purpose is, and it is fixed
-        //      at creation by whether an OAuth binding was attached.
-        // =======================================================================
-        /**
-         * MECHANISM A — same-device shared-keychain SSO.
-         *
-         * Native-only. If this device holds a shared identity (the cross-app
-         * `group.so.oxy.shared` keychain key), prove control of it and mint a
-         * session: `requestChallenge(sharedPublicKey)` → `signChallengeWithSharedKey`
-         * → `verifyChallenge` (which plants the tokens). Returns `null` on web or
-         * when no shared identity is present — never throws for the absent-identity
-         * case, so a cold-boot caller can fall through to the next step.
-         *
-         * The cold-boot wiring that CALLS this lives in `OxyContext`
-         * (`@oxy.so/services`); this method just performs the exchange.
-         *
-         * @param opts.requestOptions - Optional per-call transport overrides
-         *   (`retry`, `timeout`) forwarded to BOTH the `requestChallenge` and
-         *   `verifyChallenge` round-trips. Interactive flows omit it (defaults keep
-         *   retries); the cold-boot `shared-key-signin` step passes `{ retry: false }`
-         *   so this network step cannot multiply boot latency via the inner retry
-         *   loop. The token-refresh scheduler / 401 lane still retry later.
-         * @param opts.plantTokens - Forwarded to `verifyChallenge` (default `true`).
-         */
-        async signInWithSharedIdentity(opts = {}) {
-            try {
-                // `hasSharedIdentity()` already returns false on web (the shared
-                // keychain is native-only), so this short-circuits the web case without
-                // a wasted challenge round-trip.
-                if (!(await KeyManager.hasSharedIdentity())) {
-                    return null;
-                }
-                const sharedPublicKey = await KeyManager.getSharedPublicKey();
-                if (!sharedPublicKey) {
-                    return null;
-                }
-                const { challenge } = await this.requestChallenge(sharedPublicKey, opts.requestOptions);
-                const signed = await SignatureService.signChallengeWithSharedKey(challenge);
-                // `signed.challenge` carries the SIGNATURE (mirrors `signChallenge`).
-                return await this.verifyChallenge(signed.publicKey, challenge, signed.challenge, signed.timestamp, opts.deviceName, opts.deviceFingerprint, opts.requestOptions, { plantTokens: opts.plantTokens });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (relying party) — begin a "Sign in with Oxy" handoff.
-         *
-         * Generates a secret device-flow `sessionToken` client-side (it never
-         * appears in the QR), registers it with `POST /auth/session/create`, and
-         * returns the server-issued public `authorizeCode` + ready-to-render
-         * `qrPayload`. Render the QR (web) / open the deep-link (same-device); the
-         * approver resolves the code and authorizes. Then poll with
-         * {@link pollCommonsSignIn} and finalize.
-         *
-         * ONE request serves every delivery surface, and how it finalizes is decided
-         * here by whether an OAuth binding is attached:
-         *   - no `oauth` (the default): a `device_sign_in` request — on `authorized`,
-         *     exchange the `sessionToken` via the existing `claimSessionByToken`.
-         *   - with `oauth`: an `oauth_authorization` request — on `authorized`, call
-         *     {@link finalizeCommonsOAuth} with the same `sessionToken` to mint the
-         *     single-use authorization code, then exchange it with PKCE.
-         *
-         * @param params.clientId - The RP's registered OAuth client id
-         *   (ApplicationCredential publicKey); required so the server can resolve the
-         *   requesting application's identity.
-         * @param params.oauth - Optional OAuth binding ({@link CommonsOAuthContext}).
-         *   Carries only the redirect URI, the PKCE S256 challenge, the requested
-         *   scope, and an optional delegated `subjectAccountId` — never the PKCE
-         *   verifier, the OAuth `state`, or any token.
-         */
-        async startCommonsSignIn(params) {
-            try {
-                // High-entropy opaque secret token (256-bit hex). Generated client-side
-                // and held only here; the server stores it but never returns it in the
-                // QR. Reuses the platform-safe random generator.
-                const sessionToken = await SignatureService.generateChallenge();
-                const expiresAt = Date.now() + COMMONS_SIGN_IN_EXPIRY_MS;
-                const res = await this.makeRequest('POST', '/auth/session/create', {
-                    sessionToken,
-                    expiresAt,
-                    clientId: params.clientId,
-                    // Omitted entirely when absent so the device-sign-in body stays
-                    // exactly what it has always been (the server reads presence, not a
-                    // null, to decide the request's purpose).
-                    ...(params.oauth ? { oauth: params.oauth } : {}),
-                }, 
-                // Public/pre-session (no bearer): skip the preflight so a stale
-                // near-expiry token cannot re-enter refreshAccessToken while the
-                // refresh handler is already in flight (self-await hang).
-                { cache: false, skipAuth: true });
-                return {
-                    sessionToken,
-                    authorizeCode: res.authorizeCode,
-                    qrPayload: res.qrPayload,
-                    expiresAt: res.expiresAt ?? expiresAt,
-                    status: res.status,
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (relying party) — poll a device-flow session for approval.
-         *
-         * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
-         * caller finalizes: `claimSessionByToken` for a `device_sign_in` request,
-         * {@link finalizeCommonsOAuth} for an `oauth_authorization` one.
-         *
-         * Every field is narrowed fail-safe. `authorized` counts only as a literal
-         * `true`, the identifiers only as non-empty strings, and the delivery
-         * progress timestamps degrade to `null` when absent or unparseable — so a
-         * partial or older-API payload can advance the waiting UI at most, never
-         * make it believe a request was approved.
-         *
-         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
-         */
-        async pollCommonsSignIn(sessionToken) {
-            try {
-                const res = await this.makeRequest('GET', `/auth/session/status/${encodeURIComponent(sessionToken)}`, undefined, 
-                // Public/pre-session (no bearer): a preflight here is wrong per se and,
-                // if ever reached while a refresh is pending, would re-enter
-                // refreshAccessToken and await the very promise it runs inside.
-                { cache: false, retry: false, skipAuth: true });
-                if (res === null || typeof res !== 'object') {
-                    throw new Error('auth/session/status returned an unexpected response shape');
-                }
-                const { authorized, sessionId, publicKey, status, purpose, pushSentAt, openedAt } = res;
-                return {
-                    authorized: authorized === true,
-                    ...(typeof sessionId === 'string' && sessionId ? { sessionId } : {}),
-                    ...(typeof publicKey === 'string' && publicKey ? { publicKey } : {}),
-                    ...(typeof status === 'string' && status ? { status } : {}),
-                    purpose: purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
-                    pushSentAt: parseCommonsProgressTimestamp(pushSentAt),
-                    openedAt: parseCommonsProgressTimestamp(openedAt),
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (relying party) — ask Oxy to DELIVER a pending sign-in request
-         * to the identity's known Commons installations.
-         *
-         * This is the automatic half of "one intention, one primary action": rather
-         * than offering the user a menu of transports, the caller asks for delivery
-         * and lets the answer pick the route. Pass the returned `targets` to
-         * `selectCommonsDelivery` (`utils/commonsDelivery`) — `targets: 0` means no
-         * capable Commons installation is registered, which is a NORMAL outcome that
-         * resolves to the QR route, not an error to surface.
-         *
-         * **Requires a bearer.** Delivery is only allowed when Oxy already knows the
-         * intended identity from a trusted authenticated context — a request that
-         * merely carries a username or email typed into an unauthenticated browser
-         * must never be able to ring somebody's phone.
-         *
-         * The push it sends carries only `{ type, approvalUrl }` where the URL holds
-         * the public `authorizeCode` — no display data, no secrets. Commons resolves
-         * everything it shows from `getCommonsApprovalInfo`.
-         *
-         * @param authorizeCode - The public code from {@link startCommonsSignIn}.
-         */
-        async deliverCommonsSignIn(authorizeCode) {
-            try {
-                const res = await this.makeRequest('POST', `/auth/session/deliver/${encodeURIComponent(authorizeCode)}`, undefined, 
-                // Bearer REQUIRED (unlike its public siblings): the identity to
-                // deliver to comes from the authenticated caller, never the code.
-                { cache: false });
-                if (res === null || typeof res !== 'object') {
-                    throw new Error('auth/session/deliver returned an unexpected response shape');
-                }
-                const { delivered, targets } = res;
-                // Both fields drive the route choice, so a partial payload is rejected
-                // outright rather than defaulted into a route the server never chose.
-                if (typeof delivered !== 'boolean' ||
-                    typeof targets !== 'number' ||
-                    !Number.isInteger(targets) ||
-                    targets < 0) {
-                    throw new Error('auth/session/deliver returned an incomplete delivery result');
-                }
-                return { delivered, targets };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (approver / Commons) — report that the approval route was
-         * OPENED, so the waiting relying party can show "Opened in Commons".
-         *
-         * Progress only. It is idempotent, applies to a `pending` request alone, and
-         * records a timestamp (`openedAt`) — it never approves, authorizes, or
-         * advances the authorization state machine. Public, like the other approver
-         * handles: the approver has only the public `authorizeCode` at this point
-         * and has not yet signed anything.
-         *
-         * Best-effort by nature — a failure here costs the user only a progress
-         * line, so callers are free to ignore a rejection and continue to the
-         * approval screen.
-         *
-         * @param authorizeCode - The public code scanned from the QR / deep-link / push.
-         */
-        async markCommonsApprovalOpened(authorizeCode) {
-            try {
-                await this.makeRequest('POST', `/auth/session/opened/${encodeURIComponent(authorizeCode)}`, undefined, 
-                // Public (no bearer) — skip the preflight, exactly like approve-info.
-                { cache: false, skipAuth: true });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (relying party) — finalize an APPROVED, OAuth-bound request
-         * into a single-use OAuth authorization code.
-         *
-         * The OAuth counterpart of `claimSessionByToken`: same secret credential,
-         * same single-use semantics, different output. Call it once the request the
-         * RP started with an `oauth` binding reports `authorized`; the server
-         * atomically mints exactly ONE `AuthCode` bound to the redirect URI, PKCE
-         * challenge, scopes, approving identity, and any delegated subject account
-         * the request was created with. A second call cannot mint another code.
-         *
-         * The result is an authorization CODE, never a token — the caller completes
-         * the flow with the ordinary PKCE exchange (`exchangeOAuthCode`) using the
-         * `codeVerifier` it never sent anywhere. Nothing here is exposed to the
-         * popup: the code travels back through the registered callback, and the
-         * main window owns the verifier.
-         *
-         * Like `claimSessionByToken`, this needs no Authorization header — the
-         * high-entropy SECRET `sessionToken` IS the credential. Never pass the
-         * public `authorizeCode` here; it is the approver's handle, not the
-         * initiator's. Every server-side failure (wrong/expired/already-finalized
-         * request, non-OAuth purpose, missing permission for the delegated account)
-         * surfaces as one generic error, so nothing about the request's state can be
-         * probed from outside.
-         *
-         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
-         */
-        async finalizeCommonsOAuth(sessionToken) {
-            try {
-                const res = await this.makeRequest('POST', `/auth/session/finalize/${encodeURIComponent(sessionToken)}`, undefined, 
-                // Body-authenticated by the path's secret token (no bearer) — skip the
-                // preflight, exactly like the device-flow claim.
-                { cache: false, skipAuth: true });
-                if (res === null || typeof res !== 'object') {
-                    throw new Error('auth/session/finalize returned an unexpected response shape');
-                }
-                const { code, redirectUri, expiresIn } = res;
-                // All three fields are load-bearing for the exchange that follows, so a
-                // partial payload is rejected outright rather than returned half-parsed.
-                if (typeof code !== 'string' ||
-                    !code ||
-                    typeof redirectUri !== 'string' ||
-                    !redirectUri ||
-                    typeof expiresIn !== 'number' ||
-                    !Number.isFinite(expiresIn)) {
-                    throw new Error('auth/session/finalize returned an incomplete authorization code');
-                }
-                return { code, redirectUri, expiresIn };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (approver / Commons) — resolve the TRUSTED identity of a
-         * sign-in request from its public `authorizeCode`.
-         *
-         * The returned `application` and `subjectAccount` are resolved server-side
-         * and are the only safe things to display in the approval UI — NEVER trust
-         * the app/name/origin strings carried in the QR payload. Public (no auth
-         * required).
-         *
-         * @param authorizeCode - The public code scanned from the QR / deep-link.
-         */
-        async getCommonsApprovalInfo(authorizeCode) {
-            try {
-                const raw = await this.makeRequest('GET', `/auth/session/approve-info/${encodeURIComponent(authorizeCode)}`, undefined, 
-                // Public (no auth required) — skip the bearer preflight (avoids the
-                // pre-session self-await class).
-                { cache: false, skipAuth: true });
-                return {
-                    application: raw.application,
-                    scopes: raw.scopes,
-                    boundOrigin: raw.boundOrigin,
-                    // Fail-safe: only a literal boolean `true` counts as verified. A
-                    // missing or non-boolean value (older server, malformed response)
-                    // coerces to `false` so a stale server can never imply trust.
-                    originVerified: raw.originVerified === true,
-                    // Same discipline: a missing/blank/non-string label degrades to null
-                    // (an older API, or a native requester with no browser to describe),
-                    // and the approver simply omits the "where from" line.
-                    requesterLabel: parseCommonsRequesterLabel(raw.requesterLabel),
-                    // Same discipline: only the literal OAuth purpose opts into OAuth
-                    // finalization. Anything else — including a server that predates this
-                    // field — is the plain device sign-in it has always been.
-                    purpose: raw.purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
-                    // A missing/partial delegated account degrades to "no delegation"
-                    // rather than a half-rendered "will act as" line.
-                    subjectAccount: parseCommonsSubjectAccount(raw.subjectAccount),
-                    expiresAt: raw.expiresAt,
-                    status: raw.status,
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (approver / Commons) — approve a sign-in request by signing a
-         * fresh challenge with the PRIMARY local identity key.
-         *
-         * Commons holds the user's identity as its primary key (not the shared
-         * key), so this uses `signChallenge`. The signed-but-cookieless authorize
-         * endpoint resolves the user from the verified signer — the RP that started
-         * the flow then claims its session. Native-only (requires a local identity).
-         *
-         * @param params.authorizeCode - The public code being approved.
-         * @param params.deviceName - Optional human-readable device label.
-         * @param params.deviceFingerprint - Optional device fingerprint.
-         */
-        async approveCommonsSignIn(params) {
-            try {
-                const publicKey = await KeyManager.getPublicKey();
-                if (!publicKey) {
-                    throw new Error('No identity found on this device. Create or import an identity first.');
-                }
-                const { challenge } = await this.requestChallenge(publicKey);
-                const signed = await SignatureService.signChallenge(challenge);
-                return await this.makeRequest('POST', `/auth/session/authorize-signed/${encodeURIComponent(params.authorizeCode)}`, {
-                    // `signed.challenge` carries the SIGNATURE; `challenge` is the
-                    // original server-issued challenge string.
-                    publicKey: signed.publicKey,
-                    challenge,
-                    signature: signed.challenge,
-                    timestamp: signed.timestamp,
-                    ...(params.deviceName ? { deviceName: params.deviceName } : {}),
-                    ...(params.deviceFingerprint ? { deviceFingerprint: params.deviceFingerprint } : {}),
-                }, 
-                // Key-signed, cookieless (no bearer) — skip the preflight.
-                { cache: false, skipAuth: true });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * MECHANISM B (approver / Commons) — deny a sign-in request, cancelling the
-         * device-flow session so the RP stops waiting.
-         *
-         * @param authorizeCode - The public code being denied.
-         * @param reason - Optional closed-set reason ({@link CommonsDenyReason}).
-         *   Pass `'not_me'` ONLY when the user actually reported the request as one
-         *   they did not start — the server records it as a suspicious denial rather
-         *   than an ordinary cancel. Omitting it sends the exact body this endpoint
-         *   has always received.
-         */
-        async denyCommonsSignIn(authorizeCode, reason) {
-            try {
-                return await this.makeRequest('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, reason ? { reason } : undefined, 
-                // Public (no auth required) — skip the bearer preflight.
-                { cache: false, skipAuth: true });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Internal: decode (without verifying) the `sessionId` claim from a
-         * server-signed access token. The server already verified the signature;
-         * the client only reads the claim to drive multi-session state.
-         *
-         * @internal
-         */
-        _decodeSessionIdFromAccessToken(token) {
-            if (!token || typeof token !== 'string') {
-                return null;
-            }
-            const segments = token.split('.');
-            if (segments.length !== 3) {
-                return null;
-            }
-            const payloadSegment = segments[1];
-            if (!payloadSegment) {
-                return null;
-            }
-            try {
-                const base64 = payloadSegment.replace(/-/g, '+').replace(/_/g, '/');
-                const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
-                if (typeof atob !== 'function') {
-                    return null;
-                }
-                const json = decodeURIComponent(atob(padded)
-                    .split('')
-                    .map((char) => `%${`00${char.charCodeAt(0).toString(16)}`.slice(-2)}`)
-                    .join(''));
-                const parsed = JSON.parse(json);
-                if (parsed === null || typeof parsed !== 'object') {
-                    return null;
-                }
-                const claims = parsed;
-                return typeof claims.sessionId === 'string' ? claims.sessionId : null;
-            }
-            catch {
-                return null;
-            }
-        }
-        /**
-         * Get sessions by session ID
-         */
-        async getSessionsBySessionId(sessionId) {
-            try {
-                return await this.makeRequest('GET', `/session/sessions/${sessionId}`, undefined, {
-                    cache: false,
-                });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Logout from a specific session
-         */
-        async logoutSession(sessionId, targetSessionId) {
-            try {
-                const url = targetSessionId
-                    ? `/session/logout/${sessionId}/${targetSessionId}`
-                    : `/session/logout/${sessionId}`;
-                await this.makeRequest('POST', url, undefined, { cache: false });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Logout from all sessions
-         */
-        async logoutAllSessions(sessionId) {
-            try {
-                await this.makeRequest('POST', `/session/logout-all/${sessionId}`, undefined, { cache: false });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Validate session
-         */
-        async validateSession(sessionId, options = {}) {
-            try {
-                const urlParams = {};
-                if (options.deviceFingerprint)
-                    urlParams.deviceFingerprint = options.deviceFingerprint;
-                if (options.useHeaderValidation)
-                    urlParams.useHeaderValidation = 'true';
-                const validation = await this.makeRequest('GET', `/session/validate/${sessionId}`, urlParams, { cache: false });
-                return {
-                    ...validation,
-                    user: normalizeUserIdentity(validation.user),
-                };
-            }
-            catch (error) {
-                // Session is invalid — clear any cached user data for this session (#196)
-                this.clearCacheEntry(`GET:/session/user/${sessionId}`);
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Check username availability
-         */
-        async checkUsernameAvailability(username) {
-            try {
-                // Public availability lookup (pre-session) — skip the bearer preflight.
-                return await this.makeRequest('GET', `/auth/check-username/${username}`, undefined, { cache: false, skipAuth: true });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Send a 6-digit code to an email (ADR 0029 D3): the recovery email of a
-         * new passkey account (`purpose: 'signup'`), or — named by username or
-         * email — the recovery email of an account being recovered
-         * (`purpose: 'recovery'`). The answer is the same whether or not an
-         * account exists; nothing is revealed about who has one.
-         */
-        async startEmailVerification(request) {
-            try {
-                const res = await this.makeRequest('POST', '/auth/email/verify/start', request, {
-                    cache: false,
-                    skipAuth: true,
-                });
-                const parsed = safeParseContract(emailVerificationStartResponseSchema, res);
-                if (!parsed)
-                    throw new Error('auth/email/verify/start returned an unexpected response shape');
-                return parsed;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Confirm the code {@link startEmailVerification} sent. Resolves to a
-         * short-lived one-use ticket: a sign-up passes it (with the email) to
-         * {@link webauthnRegisterVerify}; a recovery passes it as `recoveryTicket`
-         * to {@link webauthnRegisterOptions} and {@link webauthnRegisterVerify}.
-         */
-        async confirmEmailVerification(verificationId, code) {
-            try {
-                const res = await this.makeRequest('POST', '/auth/email/verify/confirm', { verificationId, code }, { cache: false, skipAuth: true });
-                const parsed = safeParseContract(emailVerificationConfirmResponseSchema, res);
-                if (!parsed)
-                    throw new Error('auth/email/verify/confirm returned an unexpected response shape');
-                return parsed;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Begin a WebAuthn / passkey REGISTRATION ceremony. Requests the
-         * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
-         * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
-         *
-         * With a bearer token planted this adds a passkey to the signed-in account.
-         * Without one, `username` is a prospective sign-up's handle, and
-         * `recoveryTicket` a recovery's new passkey for the account it names. The
-         * returned options are OPAQUE — Oxy does not own their shape (the browser /
-         * `@simplewebauthn` does), so they pass through as `unknown` for the caller
-         * to hand straight to the ceremony.
-         */
-        async webauthnRegisterOptions(request = {}) {
-            const signedOut = request.username !== undefined || request.recoveryTicket !== undefined;
-            try {
-                return await this.makeRequest('POST', '/auth/webauthn/register/options', {
-                    ...(request.username !== undefined ? { username: request.username } : {}),
-                    ...(request.recoveryTicket !== undefined ? { recoveryTicket: request.recoveryTicket } : {}),
-                }, { cache: false, ...(signedOut ? { skipAuth: true } : {}) });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Finish a WebAuthn / passkey REGISTRATION ceremony. Forwards the opaque
-         * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
-         * (desired `username` for signup + the device-session naming fields).
-         *
-         * Server branches, disambiguated by the response shape:
-         *  - **Sign-up** (no bearer; `username`, `email`, `emailTicket`) and
-         *    **recovery** (no bearer; `recoveryTicket`): the account is created, or
-         *    gains the passkey, and a session is minted — the response carries
-         *    `sessionId`, is the SAME {@link LoginResult} contract as
-         *    `POST /auth/verify`, and its access token is planted here.
-         *  - **Link** (bearer present): the passkey is attached to the signed-in
-         *    account and the server returns `{ success, message }` with no session,
-         *    which is returned verbatim (no token planting).
-         */
-        async webauthnRegisterVerify(response, envelope = {}) {
-            try {
-                const res = await this.makeRequest('POST', '/auth/webauthn/register/verify', { response, ...envelope }, {
-                    cache: false,
-                    ...(envelope.username !== undefined || envelope.recoveryTicket !== undefined ? { skipAuth: true } : {}),
-                });
-                if (res && typeof res === 'object') {
-                    const record = res;
-                    // Signup branch: mints a session (LoginSessionResult, carries
-                    // `sessionId`). Parse against the login contract and plant the token.
-                    if ('sessionId' in record) {
-                        const parsed = safeParseContract(loginResultSchema, record);
-                        if (!parsed) {
-                            throw new Error('auth/webauthn/register/verify returned an unexpected response shape');
-                        }
-                        if (parsed.accessToken) {
-                            this.setTokens(parsed.accessToken);
-                        }
-                        return parsed;
-                    }
-                    // Link branch: passkey attached to the signed-in account, no session.
-                    if (record.success === true && typeof record.message === 'string') {
-                        return { success: true, message: record.message };
-                    }
-                }
-                throw new Error('auth/webauthn/register/verify returned an unexpected response shape');
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Begin a WebAuthn / passkey AUTHENTICATION ceremony. Requests the
-         * `PublicKeyCredentialRequestOptions` the browser's `navigator.credentials
-         * .get()` (or `@simplewebauthn/browser`'s `startAuthentication`) needs.
-         *
-         * When `username` is present the server scopes `allowCredentials` to that
-         * user's passkeys (username-first); when omitted it returns an empty
-         * allow-list for the usernameless / discoverable-credential flow. The
-         * returned options are OPAQUE and pass through as `unknown`.
-         */
-        async webauthnLoginOptions(username) {
-            try {
-                return await this.makeRequest('POST', '/auth/webauthn/login/options', { ...(username !== undefined ? { username } : {}) }, 
-                // Pre-session login ceremony — skip the bearer preflight.
-                { cache: false, skipAuth: true });
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Finish a WebAuthn / passkey AUTHENTICATION ceremony. Forwards the opaque
-         * browser `AuthenticationResponseJSON` (`response`) alongside the
-         * device-session envelope. Resolves to the SAME {@link LoginResult} contract
-         * as `POST /auth/verify`; the access token is planted immediately, and the
-         * response's `deviceId` + `deviceSecret` are the zero-cookie restore
-         * credential.
-         */
-        async webauthnLoginVerify(response, envelope = {}) {
-            try {
-                const res = await this.makeRequest('POST', '/auth/webauthn/login/verify', { response, ...envelope }, 
-                // Pre-session login ceremony — skip the bearer preflight.
-                { cache: false, skipAuth: true });
-                const parsed = safeParseContract(loginResultSchema, res);
-                if (!parsed) {
-                    throw new Error('auth/webauthn/login/verify returned an unexpected response shape');
-                }
-                if (parsed.accessToken) {
-                    this.setTokens(parsed.accessToken);
-                }
-                return parsed;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Exchange an OAuth authorization code (returned to the RP redirect URI
-         * after sign-in at auth.oxy.so) for a device-first session.
-         * Public first-party clients use PKCE (`codeVerifier`); the access token is
-         * planted immediately on success.
-         *
-         * Speaks the standard RFC 6749 §4.1.3 token request — a form-urlencoded
-         * body with snake_case parameters and `grant_type=authorization_code` — and
-         * reads the flat §5.1 response. The camelCase JSON request and `{ data }`
-         * response this method used before were an Oxy invention no OAuth library
-         * could interoperate with; the endpoint no longer accepts them. The method's
-         * OWN signature is unchanged, so callers are unaffected.
-         *
-         * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
-         * outcome, not an error. A third-party grant is meant to be isolated from the
-         * browser's shared DeviceSession, so the token endpoint must be free to return
-         * no device credential at all — the guard that used to require the pair made
-         * that omission unshippable, since it turned every third-party sign-in through
-         * the SDK into a silent `exchange-failed`.
-         *
-         * The cost is real and deliberate: a DEVICE-LESS session cannot use the
-         * zero-cookie mint lane (`POST /session/device/token`), because that lane's
-         * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
-         * access token itself — nothing persists a restore credential, the cold boot's
-         * `device-secret-mint` step reports `no-secret` and skips, and the refresh
-         * scheduler has nothing to re-mint from. When the token expires the session
-         * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
-         * out, so the app can run the OAuth flow again. It never degrades into a
-         * session that looks alive and cannot refresh.
-         */
-        async exchangeOAuthCode(params) {
-            try {
-                const form = new URLSearchParams({
-                    grant_type: 'authorization_code',
-                    code: params.code,
-                    redirect_uri: params.redirectUri,
-                    client_id: params.clientId,
-                    code_verifier: params.codeVerifier,
-                });
-                const res = await this.makeRequest('POST', '/auth/oauth/token', form, { cache: false, skipAuth: true });
-                if (!res || typeof res !== 'object') {
-                    throw new Error('auth/oauth/token returned an unexpected response shape');
-                }
-                // RFC 6749 §5.1: every member sits at the TOP LEVEL of the document.
-                const record = res;
-                const accessToken = typeof record.access_token === 'string' ? record.access_token : undefined;
-                const sessionId = typeof record.session_id === 'string' ? record.session_id : undefined;
-                const deviceId = typeof record.deviceId === 'string' ? record.deviceId : undefined;
-                const deviceSecret = typeof record.deviceSecret === 'string' ? record.deviceSecret : undefined;
-                const userRaw = record.user;
-                // The device pair is NOT part of this guard — see the note above. What is
-                // still mandatory is what identifies the session at all.
-                if (!sessionId || !userRaw || typeof userRaw !== 'object') {
-                    throw new Error('auth/oauth/token returned an incomplete session payload');
-                }
-                const userObj = userRaw;
-                const userId = typeof userObj.id === 'string' ? userObj.id : undefined;
-                if (!userId) {
-                    throw new Error('auth/oauth/token returned a session without user.id');
-                }
-                const expiresInSec = typeof record.expires_in === 'number' ? record.expires_in : DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
-                const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
-                if (accessToken) {
-                    this.setTokens(accessToken);
-                }
-                if (!deviceId || !deviceSecret) {
-                    logger.debug('auth/oauth/token returned no device credential — this session lives only as long as its access token', { component: 'oxy.auth', method: 'exchangeOAuthCode' });
-                }
-                return {
-                    sessionId,
-                    expiresAt,
-                    accessToken,
-                    // Omitted rather than set to `undefined` when the server sent no device
-                    // credential, so a device-less grant serializes as the absence it is.
-                    ...(deviceId ? { deviceId } : {}),
-                    ...(deviceSecret ? { deviceSecret } : {}),
-                    user: {
-                        id: userId,
-                        username: typeof userObj.username === 'string' ? userObj.username : undefined,
-                        avatar: typeof userObj.avatar === 'string' ? userObj.avatar : undefined,
-                    },
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
-         * The response is a flat JSON document — no `{ data }` wrapper.
-         */
-        async getOAuthUserInfo() {
-            try {
-                const res = await this.makeRequest('GET', '/auth/oauth/userinfo', undefined, { cache: false });
-                if (!res || typeof res !== 'object') {
-                    throw new Error('auth/oauth/userinfo returned an unexpected response shape');
-                }
-                const record = res;
-                const sub = typeof record.sub === 'string' ? record.sub : undefined;
-                if (!sub) {
-                    throw new Error('auth/oauth/userinfo returned a response without sub');
-                }
-                return {
-                    sub,
-                    ...(typeof record.preferred_username === 'string'
-                        ? { preferred_username: record.preferred_username }
-                        : {}),
-                    ...(typeof record.name === 'string' ? { name: record.name } : {}),
-                    ...(typeof record.picture === 'string' ? { picture: record.picture } : {}),
-                };
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-    };
-}