@oxy.so/core 1.18.1 → 3.0.0

package/dist/esm/api/auth.js

@@ -0,0 +1,858 @@
+import { emailSignInLinkResponseSchema, emailSignInPendingSchema, emailSignInStartResponseSchema, emailVerificationConfirmResponseSchema, emailVerificationStartResponseSchema, loginResultSchema, safeParseContract, secondFactorRequiredSchema, signInMethodsSchema, totpBackupCodesResponseSchema, totpEnrollResponseSchema, } from '@oxy.so/contracts';
+import { OxyAuthenticationError } from '../OxyServices.errors.js';
+import { logger } from '../logger/index.js';
+import { normalizeUserIdentity } from '../utils/userIdentity.js';
+// The identity key, signatures and the registration proof-of-work load on first
+// use: an app that never signs anything must not ship secp256k1.
+const loadKeyManager = async () => (await import('../crypto/internal.js')).KeyManager;
+const loadSignatureService = async () => (await import('../crypto/internal.js')).SignatureService;
+/**
+ * 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;
+}
+/** The body fields a session-ending call sends: the options, plus the device proof. */
+async function signInEnvelope(ctx, options = {}) {
+    const { device: explicit, deviceName, deviceFingerprint } = options;
+    const device = explicit === undefined ? await ctx.oxy.session.readDeviceProof() : explicit;
+    return {
+        ...(deviceName ? { deviceName } : {}),
+        ...(deviceFingerprint ? { deviceFingerprint } : {}),
+        ...(device ? { device } : {}),
+    };
+}
+/** Parse a session, planting its token. */
+function plantSession(ctx, res, path) {
+    const parsed = safeParseContract(loginResultSchema, res);
+    if (!parsed)
+        throw new Error(`${path} returned an unexpected response shape`);
+    if (parsed.accessToken)
+        ctx.oxy.session.setAccessToken(parsed.accessToken);
+    return parsed;
+}
+/** Parse a first factor's answer: the second-factor step, or a session. */
+function signInStep(ctx, res, path) {
+    const challenge = safeParseContract(secondFactorRequiredSchema, res);
+    if (challenge)
+        return challenge;
+    return plantSession(ctx, res, path);
+}
+/** `oxy.auth.email` — email sign-in (code or link) and email confirmation codes. */
+export class AuthEmailApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Send a 6-digit code to the email of a new account
+     * (`purpose: 'signup'`). The answer is the same whether or not the address
+     * already has an account; nothing is revealed about who has one.
+     */
+    async startVerification(request) {
+        const res = await this.ctx.request('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;
+    }
+    /**
+     * Confirm the code {@link AuthEmailApi.startVerification} sent. Resolves to a
+     * short-lived one-use ticket, which a sign-up passes (with the email) to
+     * {@link AuthApi.signUp}.
+     */
+    async confirmVerification(verificationId, code) {
+        const res = await this.ctx.request('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;
+    }
+    /**
+     * Send the sign-in email (a code and a link) for a username or email. The
+     * answer is the same whether or not the account exists. Keep
+     * `requestSecret` in memory only.
+     */
+    async start(identifier, options = {}) {
+        const device = options.device === undefined ? await this.ctx.oxy.session.readDeviceProof() : options.device;
+        const res = await this.ctx.request('POST', '/auth/signin/email/start', { identifier, ...(device ? { device } : {}) }, { cache: false, skipAuth: true });
+        const parsed = safeParseContract(emailSignInStartResponseSchema, res);
+        if (!parsed)
+            throw new Error('auth/signin/email/start returned an unexpected response shape');
+        return parsed;
+    }
+    /**
+     * The code from the email → a session, or the second-factor step. The code
+     * is 6 digits, or the 10-character long code (`XXXXX-XXXXX`) an account
+     * gets after too many guesses in a day — accept both in one field and pass
+     * it as typed.
+     */
+    async confirm(request) {
+        const { requestId, requestSecret, code, ...options } = request;
+        const res = await this.ctx.request('POST', '/auth/signin/email/confirm', { requestId, requestSecret, code, ...(await signInEnvelope(this.ctx, options)) }, { cache: false, skipAuth: true });
+        return signInStep(this.ctx, res, 'auth/signin/email/confirm');
+    }
+    /**
+     * Whether the email's link was opened in this browser: `{ status: 'pending' }`
+     * until it was, then a session (or the second-factor step). Poll it.
+     */
+    async collect(request) {
+        const { requestId, requestSecret, ...options } = request;
+        const res = await this.ctx.request('POST', '/auth/signin/email/collect', { requestId, requestSecret, ...(await signInEnvelope(this.ctx, options)) }, { cache: false, skipAuth: true });
+        const pending = safeParseContract(emailSignInPendingSchema, res);
+        if (pending)
+            return pending;
+        return signInStep(this.ctx, res, 'auth/signin/email/collect');
+    }
+    /**
+     * auth.oxy.so's link page: approve the request with THIS client's device
+     * proof. It approves only in the browser that asked, and never returns a
+     * session here — the app's dialog collects it.
+     */
+    async approveLink(token, device) {
+        const proof = device ?? (await this.ctx.oxy.session.readDeviceProof());
+        if (!proof)
+            throw new Error('This browser holds no Oxy device to approve the sign-in with');
+        const res = await this.ctx.request('POST', '/auth/signin/email/link', { token, device: proof }, { cache: false, skipAuth: true });
+        const parsed = safeParseContract(emailSignInLinkResponseSchema, res);
+        if (!parsed)
+            throw new Error('auth/signin/email/link returned an unexpected response shape');
+        return parsed;
+    }
+}
+/** `oxy.auth.password` — password sign-in and setting the password. */
+export class AuthPasswordApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async signIn(request) {
+        const { identifier, password, ...options } = request;
+        const res = await this.ctx.request('POST', '/auth/signin/password', { identifier, password, ...(await signInEnvelope(this.ctx, options)) }, { cache: false, skipAuth: true });
+        return signInStep(this.ctx, res, 'auth/signin/password');
+    }
+    async set(request) {
+        return this.ctx.request('PUT', '/users/me/password', request, { cache: false });
+    }
+}
+/** `oxy.auth.totp` — the account’s authenticator app. */
+export class AuthTotpApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    async enroll() {
+        const res = await this.ctx.request('POST', '/users/me/totp/enroll', undefined, { cache: false });
+        const parsed = safeParseContract(totpEnrollResponseSchema, res);
+        if (!parsed)
+            throw new Error('users/me/totp/enroll returned an unexpected response shape');
+        return parsed;
+    }
+    async confirm(code, reauth) {
+        const res = await this.ctx.request('POST', '/users/me/totp/confirm', { code, reauth }, { cache: false });
+        const parsed = safeParseContract(totpBackupCodesResponseSchema, res);
+        if (!parsed)
+            throw new Error('users/me/totp/confirm returned an unexpected response shape');
+        return parsed.backupCodes;
+    }
+    async disable(reauth) {
+        return this.ctx.request('POST', '/users/me/totp/disable', { reauth }, { cache: false });
+    }
+    async regenerateBackupCodes(reauth) {
+        const res = await this.ctx.request('POST', '/users/me/totp/backup-codes', { reauth }, { cache: false });
+        const parsed = safeParseContract(totpBackupCodesResponseSchema, res);
+        if (!parsed)
+            throw new Error('users/me/totp/backup-codes returned an unexpected response shape');
+        return parsed.backupCodes;
+    }
+}
+/** `oxy.auth.oauth` — a relying party’s OAuth authorization-code exchange. */
+export class AuthOAuthApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * 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 exchangeCode(params) {
+        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.ctx.request('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.ctx.oxy.session.setAccessToken(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,
+            },
+        };
+    }
+    /**
+     * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
+     * The response is a flat JSON document — no `{ data }` wrapper.
+     */
+    async userInfo() {
+        const res = await this.ctx.request('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 } : {}),
+        };
+    }
+}
+/**
+ * `oxy.auth.commons` — "Sign in with Oxy": a relying party hands a sign-in to
+ * Commons (QR, push, deep link, popup), and Commons approves or denies it.
+ *
+ * Relying party: {@link AuthCommonsApi.start} → {@link AuthCommonsApi.poll}
+ * (or the auth socket) → finalize with `oxy.auth.claimSession` (device sign-in)
+ * or {@link AuthCommonsApi.finalizeOAuth} (OAuth). Approver (Commons):
+ * {@link AuthCommonsApi.approvalInfo} → {@link AuthCommonsApi.approve} /
+ * {@link AuthCommonsApi.deny}. The approver signs with its PRIMARY local key;
+ * the relying party never sees the private key.
+ */
+export class AuthCommonsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * 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 AuthCommonsApi.poll} 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 `auth.claimSession`.
+     *   - with `oauth`: an `oauth_authorization` request — on `authorized`, call
+     *     {@link AuthCommonsApi.finalizeOAuth} 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 start(params) {
+        // 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 (await loadSignatureService()).generateChallenge();
+        const expiresAt = Date.now() + COMMONS_SIGN_IN_EXPIRY_MS;
+        const res = await this.ctx.request('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,
+        };
+    }
+    /**
+     * MECHANISM B (relying party) — poll a device-flow session for approval.
+     *
+     * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
+     * caller finalizes: `auth.claimSession` for a `device_sign_in` request,
+     * {@link AuthCommonsApi.finalizeOAuth} 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 AuthCommonsApi.start}.
+     */
+    async poll(sessionToken) {
+        const res = await this.ctx.request('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),
+        };
+    }
+    /**
+     * 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 `auth.commons.approvalInfo`.
+     *
+     * @param authorizeCode - The public code from {@link AuthCommonsApi.start}.
+     */
+    async deliver(authorizeCode) {
+        const res = await this.ctx.request('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 };
+    }
+    /**
+     * 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 markOpened(authorizeCode) {
+        await this.ctx.request('POST', `/auth/session/opened/${encodeURIComponent(authorizeCode)}`, undefined, 
+        // Public (no bearer) — skip the preflight, exactly like approve-info.
+        { cache: false, skipAuth: true });
+    }
+    /**
+     * MECHANISM B (relying party) — finalize an APPROVED, OAuth-bound request
+     * into a single-use OAuth authorization code.
+     *
+     * The OAuth counterpart of `auth.claimSession`: 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 (`auth.oauth.exchangeCode`) 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 `auth.claimSession`, 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 AuthCommonsApi.start}.
+     */
+    async finalizeOAuth(sessionToken) {
+        const res = await this.ctx.request('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 };
+    }
+    /**
+     * 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 approvalInfo(authorizeCode) {
+        const raw = await this.ctx.request('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,
+        };
+    }
+    /**
+     * 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 approve(params) {
+        const publicKey = await (await loadKeyManager()).getPublicKey();
+        if (!publicKey) {
+            throw new Error('No identity found on this device. Create or import an identity first.');
+        }
+        const { challenge } = await this.ctx.oxy.auth.requestChallenge(publicKey);
+        const signed = await (await loadSignatureService()).signChallenge(challenge);
+        return this.ctx.request('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 });
+    }
+    /**
+     * 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 deny(authorizeCode, reason) {
+        return this.ctx.request('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, reason ? { reason } : undefined, 
+        // Public (no auth required) — skip the bearer preflight.
+        { cache: false, skipAuth: true });
+    }
+}
+export class AuthApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.email = new AuthEmailApi(ctx);
+        this.password = new AuthPasswordApi(ctx);
+        this.totp = new AuthTotpApi(ctx);
+        this.oauth = new AuthOAuthApi(ctx);
+        this.commons = new AuthCommonsApi(ctx);
+    }
+    /**
+     * 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 registerKey(publicKey, signature, timestamp) {
+        // 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 { solveRegistrationPow } = await import('../crypto/internal.js');
+        const powNonce = await solveRegistrationPow(publicKey, timestamp);
+        const res = await this.ctx.request('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;
+    }
+    /**
+     * 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) {
+        return this.ctx.request('POST', '/auth/challenge', {
+            publicKey,
+        }, { cache: false, skipAuth: true, ...requestOptions });
+    }
+    /**
+     * 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 = {}) {
+        const res = await this.ctx.request('POST', '/auth/verify', {
+            publicKey,
+            challenge,
+            signature,
+            timestamp,
+            deviceName,
+            deviceFingerprint,
+        }, { cache: false, skipAuth: true, ...requestOptions });
+        // Plant the freshly-minted tokens, mirroring `auth.claimSession`.
+        // `/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.ctx.oxy.session.setAccessToken(res.accessToken);
+        }
+        return {
+            ...res,
+            user: normalizeUserIdentity(res.user),
+        };
+    }
+    /**
+     * Check if a public key is already registered
+     */
+    async isKeyRegistered(publicKey) {
+        return this.ctx.request('GET', `/auth/check-publickey/${encodeURIComponent(publicKey)}`, undefined, { cache: false, skipAuth: true });
+    }
+    /**
+     * 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 claimSession(sessionToken, options = {}) {
+        // The device this client holds, so an official app's claim joins it
+        // (ADR 0029 D2). `null` opts out explicitly.
+        const device = options.device === undefined ? await this.ctx.oxy.session.readDeviceProof() : options.device;
+        const res = await this.ctx.request('POST', '/auth/session/claim', {
+            sessionToken,
+            ...(options.deviceFingerprint ? { deviceFingerprint: options.deviceFingerprint } : {}),
+            ...(device ? { device } : {}),
+        }, 
+        // Body-authenticated device-flow claim (no bearer) — skip the preflight.
+        { cache: false, retry: false, skipAuth: true });
+        if (options.plantTokens !== false) {
+            this.ctx.oxy.session.setAccessToken(res.accessToken);
+        }
+        return res;
+    }
+    /**
+     * 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 = {}) {
+        // `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.
+        const KeyManager = await loadKeyManager();
+        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 (await loadSignatureService()).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 });
+    }
+    /**
+     * Check username availability
+     */
+    async checkUsername(username) {
+        // Public availability lookup (pre-session) — skip the bearer preflight.
+        return this.ctx.request('GET', `/auth/check-username/${username}`, undefined, { cache: false, skipAuth: true });
+    }
+    /**
+     * The authenticator's code (or a backup code) for a first factor's
+     * challenge → the session. Send the same device proof the first factor did
+     * (the default does).
+     */
+    async completeSecondFactor(request) {
+        const { challengeId, code, ...options } = request;
+        const res = await this.ctx.request('POST', '/auth/signin/second-factor', { challengeId, code, ...(await signInEnvelope(this.ctx, options)) }, { cache: false, skipAuth: true });
+        return plantSession(this.ctx, res, 'auth/signin/second-factor');
+    }
+    async signUp(request) {
+        const { username, email, emailTicket, ...options } = request;
+        const res = await this.ctx.request('POST', '/auth/signup', { username, email, emailTicket, ...(await signInEnvelope(this.ctx, options)) }, { cache: false, skipAuth: true });
+        return plantSession(this.ctx, res, 'auth/signup');
+    }
+    async methods() {
+        const res = await this.ctx.request('GET', '/users/me/sign-in-methods', undefined, { cache: false });
+        const parsed = safeParseContract(signInMethodsSchema, res);
+        if (!parsed)
+            throw new Error('users/me/sign-in-methods returned an unexpected response shape');
+        return parsed;
+    }
+    /**
+     * Send a confirmation code to the signed-in account's email, for a
+     * `reauth: { emailCode: { verificationId, code } }` proof of ONE change:
+     * the code works only for the `action` it was asked for, and the email
+     * names it.
+     */
+    async requestReauthCode(action) {
+        const res = await this.ctx.request('POST', '/users/me/reauth/email', { action }, { cache: false });
+        const parsed = safeParseContract(emailVerificationStartResponseSchema, res);
+        if (!parsed)
+            throw new Error('users/me/reauth/email returned an unexpected response shape');
+        return parsed;
+    }
+}