@oxy.so/core 1.18.0 → 3.0.0

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -1,965 +0,0 @@
-/**
- * Authentication Methods Mixin
- *
- * Supports password-based login (email/username) and public key challenge-response.
- */
-import type { User } from '../models/interfaces';
-import type { LoginResult, CommonsDenyReason } from '@oxy.so/contracts';
-import { type EmailVerificationConfirmResponse, type EmailVerificationStartRequest, type EmailVerificationStartResponse } from '@oxy.so/contracts';
-import type { SessionLoginResponse } from '../models/session';
-import type { OxyServicesBase } from '../OxyServices.base';
-import type { PublicApplication } from './OxyServices.connectedApps';
-export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from '../utils/commonsApproval';
-export interface ChallengeResponse {
-    challenge: string;
-    expiresAt: string;
-}
-export interface RegistrationRequest {
-    publicKey: string;
-    username: string;
-    email?: string;
-    signature: string;
-    timestamp: number;
-}
-export interface ChallengeVerifyRequest {
-    publicKey: string;
-    challenge: string;
-    signature: string;
-    timestamp: number;
-    deviceName?: string;
-    deviceFingerprint?: string;
-}
-export interface PublicKeyCheckResponse {
-    registered: boolean;
-    message: string;
-}
-/** OpenID Connect userinfo claims returned by `GET /auth/oauth/userinfo`. */
-export interface OAuthUserInfoResponse {
-    sub: string;
-    preferred_username?: string;
-    name?: string;
-    picture?: string;
-}
-/**
- * The session an OAuth authorization-code exchange yields.
- *
- * Deliberately NOT `LoginSessionResult`. That type mirrors the API's
- * `buildSessionAuthResponse`, which every FIRST-PARTY sign-in lane emits, and it
- * requires `deviceId` because those lanes always join the origin's DeviceSession.
- * `POST /auth/oauth/token` is the RFC 6749 token endpoint and serves third
- * parties, whose grant is deliberately ISOLATED: an untrusted application must be
- * able to receive a session carrying NO DeviceSession credential at all.
- *
- * Both device fields are therefore optional here, and a response omitting them is
- * a well-formed device-less grant rather than a malformed payload. What that
- * costs the session is spelled out on `exchangeOAuthCode` below.
- */
-export interface OAuthTokenExchangeResult {
-    sessionId: string;
-    /** ISO-8601 expiry of {@link accessToken}, derived from RFC 6749 `expires_in`. */
-    expiresAt: string;
-    accessToken?: string;
-    /**
-     * The DeviceSession this grant joined, when the server issued one. ABSENT for
-     * an isolated third-party grant — never assume a string.
-     */
-    deviceId?: string;
-    /**
-     * The zero-cookie mint credential for {@link deviceId}. Present only alongside
-     * it; absent for an isolated third-party grant.
-     */
-    deviceSecret?: string;
-    user: {
-        id: string;
-        username?: string;
-        avatar?: string;
-    };
-}
-/**
- * How a "Sign in with Oxy" request finalizes once the approver authorizes it.
- *
- * ONE request (`AuthSession`) serves every delivery surface — popup, push, QR,
- * deep link — so the purpose describes the FINALIZATION, never the transport:
- *
- * - `device_sign_in` — the classic device flow. The initiator exchanges its
- *   secret `sessionToken` for the first access token via `claimSessionByToken`.
- * - `oauth_authorization` — the request additionally carries an OAuth binding
- *   ({@link CommonsOAuthContext}), so it finalizes into a single-use
- *   authorization CODE via {@link OxyServicesAuthMixin.finalizeCommonsOAuth}.
- *   The caller still performs the PKCE token exchange itself.
- */
-export type CommonsSignInPurpose = 'device_sign_in' | 'oauth_authorization';
-/**
- * OAuth binding attached to a "Sign in with Oxy" request so a single
- * `AuthSession` can finalize into a standard OAuth authorization code instead of
- * a device-flow session.
- *
- * Only the minimum request binding is carried here — everything else (the app's
- * name, icon, registered redirect URIs, trust flags) is owned server-side by the
- * `Application` the `clientId` resolves to and is never client-supplied.
- *
- * The PKCE `codeVerifier` NEVER appears here: only its S256 `codeChallenge`
- * crosses the wire, exactly as in the redirect flow. The RP-owned OAuth `state`
- * also stays with the relying party, which validates it locally.
- */
-export interface CommonsOAuthContext {
-    /** Exact registered redirect URI the authorization code will be returned to. */
-    redirectUri: string;
-    /** PKCE `BASE64URL(SHA-256(codeVerifier))` (RFC 7636 §4.2); the verifier stays client-side. */
-    codeChallenge: string;
-    /** PKCE transformation method. Always `S256` — `plain` is not accepted. */
-    codeChallengeMethod: 'S256';
-    /** Space-delimited OAuth scope string; the server normalizes and validates it. */
-    scope?: string;
-    /**
-     * Optional delegated account the application will act AS (an organization or
-     * project the identity is a member of). The identity approving the request
-     * does not change; the server verifies the identity's permission to act as
-     * this account before finalizing.
-     */
-    subjectAccountId?: string;
-}
-/**
- * Handle returned by {@link OxyServicesAuthMixin.startCommonsSignIn} for a
- * relying-party app initiating a "Sign in with Oxy" flow.
- *
- * `sessionToken` is the SECRET, high-entropy device-flow credential — it stays
- * on the initiating client, is exchanged once via `claimSessionByToken` (device
- * sign-in) or {@link OxyServicesAuthMixin.finalizeCommonsOAuth} (OAuth), and is
- * NEVER placed in the QR/deep-link. `authorizeCode` is the PUBLIC handle carried
- * in `qrPayload`; the approver (Commons) resolves it via
- * {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
- */
-export interface CommonsSignInHandle {
-    /** Secret device-flow token (held by the initiator; exchanged via `claimSessionByToken`). */
-    sessionToken: string;
-    /** Public, single-use authorize code carried in the QR / deep-link. */
-    authorizeCode: string;
-    /** Ready-to-render deep-link / universal-link string (`oxycommons://approve?...`). */
-    qrPayload: string;
-    /** Server-authoritative expiry (epoch milliseconds). */
-    expiresAt: number;
-    /** Session lifecycle status as reported by the server (e.g. `'pending'`). */
-    status: string;
-}
-/**
- * Poll result for a "Sign in with Oxy" device-flow session
- * (`GET /auth/session/status`).
- *
- * The authoritative state machine stays small — `pending → authorized →
- * consumed`, plus `cancelled` / `expired` — and lives in `status`. Delivery
- * PROGRESS (`pushSentAt`, `openedAt`) is carried as timestamps beside it, never
- * as competing statuses, so a progress signal can never be mistaken for an
- * authorization.
- */
-export interface CommonsSignInStatus {
-    /** True once an approver has authorized the session. */
-    authorized: boolean;
-    /** The authorized session id (present once `authorized` for device sign-in). */
-    sessionId?: string;
-    /** The approving identity's public key (present once `authorized`). */
-    publicKey?: string;
-    /** Lifecycle status (`'pending'` | `'authorized'` | `'cancelled'` | `'expired'`). */
-    status?: string;
-    /**
-     * How this request finalizes. Unrecognized/missing values degrade to
-     * `device_sign_in` so an older API never misroutes an OAuth finalize.
-     */
-    purpose?: CommonsSignInPurpose;
-    /**
-     * ISO-8601 timestamp of when the request was pushed to a known Commons
-     * installation, or `null` when no push has been sent (including on a server
-     * that predates delivery progress). Progress only — it never implies the push
-     * was received, opened, or approved.
-     */
-    pushSentAt: string | null;
-    /**
-     * ISO-8601 timestamp of when the approval route was opened in Commons, or
-     * `null` when it has not been opened. Reported by the approver via
-     * {@link OxyServicesAuthMixin.markCommonsApprovalOpened}; it is an
-     * un-authenticated progress hint used only to advance the waiting UI, and is
-     * NEVER evidence that the request was approved.
-     */
-    openedAt: string | null;
-}
-/**
- * Outcome of asking Oxy to deliver a pending sign-in request to the identity's
- * known Commons installations (`POST /auth/session/deliver/:authorizeCode`).
- *
- * `targets: 0` is a NORMAL outcome, not a failure: it simply means no capable
- * Commons installation is registered, so push is not a usable route and the
- * caller shows the QR instead. Feed `targets` into `selectCommonsDelivery`
- * (`utils/commonsDelivery`) rather than branching on it ad hoc.
- */
-export interface CommonsDeliveryResult {
-    /** Whether the server dispatched the request to at least one installation. */
-    delivered: boolean;
-    /** How many eligible Commons installations it was dispatched to (`0` is normal). */
-    targets: number;
-}
-/**
- * The account an application will act AS once the request is approved, when the
- * request delegates to an organization/project rather than the approver's own
- * personal account. Resolved and sanitized server-side from the request's
- * `subjectAccountId`, so it is safe to display in the approval UI.
- *
- * The identity approving stays the identity: Commons renders this as a distinct
- * "will act as" line, never as a change of who is signing.
- */
-export interface CommonsApprovalSubjectAccount {
-    /** The delegated account's id. */
-    id: string;
-    /** The delegated account's handle. */
-    username: string;
-    /** Optional human-readable name; absent when the account has no real name. */
-    displayName?: string;
-}
-/**
- * Server-resolved approval context shown by the approver (Commons) before
- * authorizing — the TRUSTED identity of the requesting app, resolved from the
- * `authorizeCode` server-side (never from the QR string).
- */
-export interface CommonsApprovalInfo {
-    /** Sanitized, display-safe identity of the requesting application. */
-    application: PublicApplication | null;
-    /** OAuth scopes the application is requesting. */
-    scopes: string[];
-    /** The origin the session is bound to (the RP web origin), when applicable. */
-    boundOrigin?: string;
-    /**
-     * Server-authoritative anti-phishing flag: `true` only when this device-flow
-     * sign-in was started from a verified, registered origin of a trusted app.
-     * The approver (Commons) shows a warning when this is `false`. Always present
-     * — a missing/non-boolean server value is coerced to `false` (fail-safe to
-     * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
-     */
-    originVerified: boolean;
-    /**
-     * COARSE, display-only label of the client that STARTED the request
-     * (`"Chrome on Windows"`), resolved server-side from the requesting browser —
-     * NEVER from the QR payload. Render it verbatim as a secondary line under the
-     * origin; it is the whole descriptor the platform has (no raw User-Agent, no
-     * IP, no location is ever collected for it).
-     *
-     * `null` whenever the server has no browser context to describe: native
-     * requesters, unidentifiable User-Agents, and any API that predates the field.
-     * Omit the line entirely in that case — never substitute a guess.
-     */
-    requesterLabel: string | null;
-    /**
-     * How this request finalizes. Always present — an unrecognized or missing
-     * server value degrades to `'device_sign_in'`, the behaviour every server has
-     * always had, so an older API never makes the approver believe it is granting
-     * an OAuth authorization.
-     */
-    purpose: CommonsSignInPurpose;
-    /**
-     * The delegated account the application will act as, or `null` when the
-     * request is for the approver's own account. Always present — a missing or
-     * malformed server value degrades to `null` (fail-safe to "no delegation"),
-     * so a partial payload can never imply a broader grant than was requested.
-     */
-    subjectAccount: CommonsApprovalSubjectAccount | null;
-    /** Server-authoritative expiry (epoch ms or ISO-8601 string from the API). */
-    expiresAt: number | string;
-    /** Session lifecycle status. */
-    status: string;
-}
-/** Result of approving / denying a "Sign in with Oxy" request. */
-export interface CommonsSignInActionResult {
-    success: boolean;
-}
-/**
- * Result of finalizing an approved, OAuth-bound "Sign in with Oxy" request.
- *
- * This is an authorization CODE, not a session: the caller still performs the
- * standard PKCE token exchange (`exchangeOAuthCode`) with the `codeVerifier` it
- * has held all along. No access token, refresh token, or device secret is ever
- * produced by finalization.
- */
-export interface CommonsOAuthFinalizeResult {
-    /** Single-use OAuth authorization code. */
-    code: string;
-    /** The exact registered redirect URI the request was bound to. */
-    redirectUri: string;
-    /** Lifetime of the authorization code, in seconds. */
-    expiresIn: number;
-}
-export interface ServiceTokenResponse {
-    token: string;
-    expiresIn: number;
-    appName: string;
-}
-/**
- * One cache entry per (apiKey hash) → issued token + the secret that produced it.
- * The secret is kept around in raw Buffer form so we can perform a
- * constant-time compare against any reused credential pair — this prevents an
- * attacker who learned a victim's apiKey from receiving the victim's cached
- * service token by simply guessing the secret.
- *
- * @internal
- */
-interface ServiceTokenCacheEntry {
-    token: string;
-    /** Expiry as ms since epoch */
-    expiresAt: number;
-    /** Raw secret stored as Buffer for constant-time comparison on cache hit */
-    secretBuf: Buffer;
-    /** In-flight refresh promise (deduplicates concurrent callers) */
-    pending: Promise<string> | null;
-    /**
-     * The raw apiKey that produced this entry. Retained so a targeted, fully
-     * synchronous `invalidateServiceToken(apiKey)` can locate the entry without
-     * re-deriving the async `SHA-256(apiKey)` Map key. Never logged or returned.
-     */
-    apiKey: string;
-}
-/**
- * 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 declare class ServiceCredentialMismatchError extends Error {
-    constructor();
-}
-export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
-    new (...args: any[]): {
-        /**
-         * 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
-         */
-        _serviceTokenCache: Map<string, ServiceTokenCacheEntry>;
-        /** @internal Raw apiKey stored by configureServiceAuth() for use by getServiceToken() */
-        _serviceApiKey: string | null;
-        /** @internal Raw apiSecret stored by configureServiceAuth() for use by getServiceToken() */
-        _serviceApiSecret: string | 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
-         */
-        _hashApiKey(apiKey: string): Promise<string>;
-        /**
-         * 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: string, apiSecret: string): void;
-        /**
-         * 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)
-         */
-        getServiceToken(apiKey?: string, apiSecret?: string): Promise<string>;
-        /**
-         * 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
-         */
-        _canUseWorkloadIdentity(): Promise<boolean>;
-        /**
-         * 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
-         */
-        _getWorkloadServiceToken(): Promise<string>;
-        /**
-         * Perform the actual /auth/service-token request and cache the result.
-         * Separated so getServiceToken() can deduplicate concurrent calls.
-         * @internal
-         */
-        _doFetchServiceToken(key: string, secret: string, cacheKey: string, secretBuf: Buffer): Promise<string>;
-        /**
-         * 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?: string): void;
-        /**
-         * 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)
-         */
-        makeServiceRequest<R = any>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, userId?: string): Promise<R>;
-        /**
-         * 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
-         */
-        register(publicKey: string, signature: string, timestamp: number): Promise<{
-            message: string;
-            user: User;
-        }>;
-        /**
-         * 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.
-         */
-        requestChallenge(publicKey: string, requestOptions?: {
-            retry?: boolean;
-            timeout?: number;
-        }): Promise<ChallengeResponse>;
-        /**
-         * 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.
-         */
-        verifyChallenge(publicKey: string, challenge: string, signature: string, timestamp: number, deviceName?: string, deviceFingerprint?: string, requestOptions?: {
-            retry?: boolean;
-            timeout?: number;
-        }, options?: {
-            plantTokens?: boolean;
-        }): Promise<SessionLoginResponse>;
-        /**
-         * Check if a public key is already registered
-         */
-        checkPublicKeyRegistered(publicKey: string): Promise<PublicKeyCheckResponse>;
-        /**
-         * Get user by public key
-         */
-        getUserByPublicKey(publicKey: string): Promise<User>;
-        /**
-         * Get user by session ID
-         */
-        getUserBySession(sessionId: string): Promise<User>;
-        /**
-         * Batch get multiple user profiles by session IDs
-         */
-        getUsersBySessions(sessionIds: string[]): Promise<Array<{
-            sessionId: string;
-            user: User | null;
-        }>>;
-        /**
-         * 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`.
-         */
-        claimSessionByToken(sessionToken: string, options?: {
-            deviceFingerprint?: string;
-            plantTokens?: boolean;
-        }): Promise<{
-            accessToken: string;
-            sessionId: string;
-            deviceId: string;
-            expiresAt: string;
-            user: User;
-            deviceSecret?: string;
-        }>;
-        /**
-         * 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`).
-         */
-        signInWithSharedIdentity(opts?: {
-            deviceName?: string;
-            deviceFingerprint?: string;
-            requestOptions?: {
-                retry?: boolean;
-                timeout?: number;
-            };
-            plantTokens?: boolean;
-        }): Promise<SessionLoginResponse | null>;
-        /**
-         * 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.
-         */
-        startCommonsSignIn(params: {
-            clientId: string;
-            oauth?: CommonsOAuthContext;
-        }): Promise<CommonsSignInHandle>;
-        /**
-         * 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}.
-         */
-        pollCommonsSignIn(sessionToken: string): Promise<CommonsSignInStatus>;
-        /**
-         * 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}.
-         */
-        deliverCommonsSignIn(authorizeCode: string): Promise<CommonsDeliveryResult>;
-        /**
-         * 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.
-         */
-        markCommonsApprovalOpened(authorizeCode: string): Promise<void>;
-        /**
-         * 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}.
-         */
-        finalizeCommonsOAuth(sessionToken: string): Promise<CommonsOAuthFinalizeResult>;
-        /**
-         * 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.
-         */
-        getCommonsApprovalInfo(authorizeCode: string): Promise<CommonsApprovalInfo>;
-        /**
-         * 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.
-         */
-        approveCommonsSignIn(params: {
-            authorizeCode: string;
-            deviceName?: string;
-            deviceFingerprint?: string;
-        }): Promise<CommonsSignInActionResult>;
-        /**
-         * 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.
-         */
-        denyCommonsSignIn(authorizeCode: string, reason?: CommonsDenyReason): Promise<CommonsSignInActionResult>;
-        /**
-         * 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: string): string | null;
-        /**
-         * Get sessions by session ID
-         */
-        getSessionsBySessionId(sessionId: string): Promise<any[]>;
-        /**
-         * Logout from a specific session
-         */
-        logoutSession(sessionId: string, targetSessionId?: string): Promise<void>;
-        /**
-         * Logout from all sessions
-         */
-        logoutAllSessions(sessionId: string): Promise<void>;
-        /**
-         * Validate session
-         */
-        validateSession(sessionId: string, options?: {
-            deviceFingerprint?: string;
-            useHeaderValidation?: boolean;
-        }): Promise<{
-            valid: boolean;
-            expiresAt: string;
-            lastActivity: string;
-            user: User;
-            sessionId?: string;
-            source?: string;
-        }>;
-        /**
-         * Check username availability
-         */
-        checkUsernameAvailability(username: string): Promise<{
-            available: boolean;
-            message: string;
-        }>;
-        /**
-         * 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.
-         */
-        startEmailVerification(request: EmailVerificationStartRequest): Promise<EmailVerificationStartResponse>;
-        /**
-         * 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}.
-         */
-        confirmEmailVerification(verificationId: string, code: string): Promise<EmailVerificationConfirmResponse>;
-        /**
-         * 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.
-         */
-        webauthnRegisterOptions(request?: {
-            username?: string;
-            recoveryTicket?: string;
-        }): Promise<unknown>;
-        /**
-         * 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).
-         */
-        webauthnRegisterVerify(response: unknown, envelope?: {
-            username?: string;
-            /** Sign-up: the recovery email, confirmed with `emailTicket`. */
-            email?: string;
-            emailTicket?: string;
-            /** Recovery: the ticket {@link confirmEmailVerification} returned. */
-            recoveryTicket?: string;
-            deviceName?: string;
-            deviceFingerprint?: string;
-        }): Promise<{
-            success: true;
-            message: string;
-        } | LoginResult>;
-        /**
-         * 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`.
-         */
-        webauthnLoginOptions(username?: string): Promise<unknown>;
-        /**
-         * 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.
-         */
-        webauthnLoginVerify(response: unknown, envelope?: {
-            deviceName?: string;
-            deviceFingerprint?: string;
-        }): Promise<LoginResult>;
-        /**
-         * 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.
-         */
-        exchangeOAuthCode(params: {
-            code: string;
-            clientId: string;
-            redirectUri: string;
-            codeVerifier: string;
-        }): Promise<OAuthTokenExchangeResult>;
-        /**
-         * Fetch OpenID Connect userinfo for the current bearer (`GET /auth/oauth/userinfo`).
-         * The response is a flat JSON document — no `{ data }` wrapper.
-         */
-        getOAuthUserInfo(): Promise<OAuthUserInfoResponse>;
-        httpService: import("../HttpService").HttpService;
-        cloudURL: string;
-        config: import("../OxyServices.base").OxyConfig;
-        __resetTokensForTests(): void;
-        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
-        getBaseURL(): string;
-        getClient(): import("../HttpService").HttpService;
-        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
-        getMetrics(): {
-            totalRequests: number;
-            successfulRequests: number;
-            failedRequests: number;
-            cacheHits: number;
-            cacheMisses: number;
-            averageResponseTime: number;
-        };
-        clearCache(): void;
-        clearCacheEntry(key: string): void;
-        clearCacheByPrefix(prefix: string): number;
-        getCacheStats(): {
-            size: number;
-            hits: number;
-            misses: number;
-            hitRate: number;
-        };
-        getCloudURL(): string;
-        setTokens(accessToken: string): void;
-        clearTokens(): void;
-        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
-        _cachedUserId: string | null | undefined;
-        _cachedAccessToken: string | null;
-        getCurrentUserId(): string | null;
-        hasValidToken(): boolean;
-        getAccessToken(): string | null;
-        getAccessTokenExpiry(): number | null;
-        waitForAuth(timeoutMs?: number): Promise<boolean>;
-        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
-            maxRetries?: number;
-            retryDelay?: number;
-            authTimeoutMs?: number;
-        }): Promise<T_1>;
-        validate(): Promise<boolean>;
-        handleError(error: unknown): Error;
-        healthCheck(): Promise<{
-            status: string;
-            users?: number;
-            timestamp?: string;
-            [key: string]: any;
-        }>;
-    };
-} & T;