@oxy.so/core 1.18.1 → 3.0.0

package/dist/types/api/auth.d.ts

@@ -0,0 +1,766 @@
+/**
+ * `oxy.auth` — signing in, signing up, and the account's credentials.
+ *
+ * - Key sign-in: {@link AuthApi.requestChallenge} → sign → {@link AuthApi.verifyChallenge}.
+ * - Email: `auth.email` — a 6-digit code and a one-use link; also the code that
+ *   confirms an email for sign-up.
+ * - Password and authenticator: `auth.password`, `auth.totp`; a first factor on
+ *   an account with an authenticator answers the second-factor step, finished
+ *   with {@link AuthApi.completeSecondFactor}.
+ * - OAuth (a relying party's PKCE code exchange): `auth.oauth`.
+ * - "Sign in with Oxy" handoff to Commons (QR, push, deep link): `auth.commons`.
+ *
+ * Every call that can end in a session attaches THIS client's device proof
+ * (`oxy.session.readDeviceProof()`, ADR 0029 D2) unless the caller passes
+ * `device` itself (`null` opts out), and a session result plants its access
+ * token on `oxy.session`.
+ */
+import type { User } from '../models/interfaces';
+import type { CommonsDenyReason, DeviceProof, LoginResult } from '@oxy.so/contracts';
+import { type EmailSignInPending, type EmailSignInStartResponse, type EmailVerificationConfirmResponse, type EmailVerificationStartRequest, type EmailVerificationStartResponse, type ReauthAction, type ReauthProof, type SignInMethods, type SignInStepResult, type TotpEnrollResponse } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import type { SessionLoginResponse } from '../models/session';
+import type { PublicApplication } from './apps';
+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 `auth.oauth.exchangeCode` 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 `auth.claimSession`.
+ * - `oauth_authorization` — the request additionally carries an OAuth binding
+ *   ({@link CommonsOAuthContext}), so it finalizes into a single-use
+ *   authorization CODE via {@link AuthCommonsApi.finalizeOAuth}.
+ *   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 AuthCommonsApi.start} 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 `auth.claimSession` (device
+ * sign-in) or {@link AuthCommonsApi.finalizeOAuth} (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 AuthCommonsApi.approvalInfo}.
+ */
+export interface CommonsSignInHandle {
+    /** Secret device-flow token (held by the initiator; exchanged via `auth.claimSession`). */
+    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 AuthCommonsApi.markOpened}; 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 AuthCommonsApi.approvalInfo}.
+     */
+    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 (`auth.oauth.exchangeCode`) 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;
+}
+/** The device-session fields a sign-in may carry. */
+export interface SignInDeviceOptions {
+    deviceName?: string;
+    deviceFingerprint?: string;
+    /** The device the session joins; defaults to the one this client holds. `null` opts out. */
+    device?: DeviceProof | null;
+}
+/** The session a device-flow claim yields. */
+export interface ClaimedSession {
+    accessToken: string;
+    sessionId: string;
+    deviceId: string;
+    expiresAt: string;
+    user: User;
+    deviceSecret?: string;
+}
+/** `oxy.auth.email` — email sign-in (code or link) and email confirmation codes. */
+export declare class AuthEmailApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * 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.
+     */
+    startVerification(request: EmailVerificationStartRequest): Promise<EmailVerificationStartResponse>;
+    /**
+     * 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}.
+     */
+    confirmVerification(verificationId: string, code: string): Promise<EmailVerificationConfirmResponse>;
+    /**
+     * 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.
+     */
+    start(identifier: string, options?: {
+        device?: DeviceProof | null;
+    }): Promise<EmailSignInStartResponse>;
+    /**
+     * 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.
+     */
+    confirm(request: {
+        requestId: string;
+        requestSecret: string;
+        code: string;
+    } & SignInDeviceOptions): Promise<SignInStepResult>;
+    /**
+     * 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.
+     */
+    collect(request: {
+        requestId: string;
+        requestSecret: string;
+    } & SignInDeviceOptions): Promise<SignInStepResult | EmailSignInPending>;
+    /**
+     * 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.
+     */
+    approveLink(token: string, device?: DeviceProof): Promise<{
+        approved: true;
+    }>;
+}
+/** `oxy.auth.password` — password sign-in and setting the password. */
+export declare class AuthPasswordApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    signIn(request: {
+        identifier: string;
+        password: string;
+    } & SignInDeviceOptions): Promise<SignInStepResult>;
+    set(request: {
+        newPassword: string;
+        reauth: ReauthProof;
+        revokeOtherSessions?: boolean;
+    }): Promise<{
+        success: true;
+    }>;
+}
+/** `oxy.auth.totp` — the account’s authenticator app. */
+export declare class AuthTotpApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    enroll(): Promise<TotpEnrollResponse>;
+    confirm(code: string, reauth: ReauthProof): Promise<string[]>;
+    disable(reauth: ReauthProof): Promise<{
+        success: true;
+    }>;
+    regenerateBackupCodes(reauth: ReauthProof): Promise<string[]>;
+}
+/** `oxy.auth.oauth` — a relying party’s OAuth authorization-code exchange. */
+export declare class AuthOAuthApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * 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.
+     */
+    exchangeCode(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.
+     */
+    userInfo(): Promise<OAuthUserInfoResponse>;
+}
+/**
+ * `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 declare class AuthCommonsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * 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.
+     */
+    start(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: `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}.
+     */
+    poll(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 `auth.commons.approvalInfo`.
+     *
+     * @param authorizeCode - The public code from {@link AuthCommonsApi.start}.
+     */
+    deliver(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.
+     */
+    markOpened(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 `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}.
+     */
+    finalizeOAuth(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.
+     */
+    approvalInfo(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.
+     */
+    approve(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.
+     */
+    deny(authorizeCode: string, reason?: CommonsDenyReason): Promise<CommonsSignInActionResult>;
+}
+export declare class AuthApi {
+    private readonly ctx;
+    /** Email sign-in and email confirmation codes. */
+    readonly email: AuthEmailApi;
+    /** Password sign-in and setting the password. */
+    readonly password: AuthPasswordApi;
+    /** The account's authenticator app. */
+    readonly totp: AuthTotpApi;
+    /** OAuth authorization-code exchange. */
+    readonly oauth: AuthOAuthApi;
+    /** "Sign in with Oxy" handoff to Commons. */
+    readonly commons: AuthCommonsApi;
+    constructor(ctx: OxyContext);
+    /**
+     * 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
+     */
+    registerKey(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
+     */
+    isKeyRegistered(publicKey: string): Promise<PublicKeyCheckResponse>;
+    /**
+     * 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`.
+     */
+    claimSession(sessionToken: string, options?: {
+        deviceFingerprint?: string;
+        plantTokens?: boolean;
+        device?: DeviceProof | null;
+    }): Promise<ClaimedSession>;
+    /**
+     * 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>;
+    /**
+     * Check username availability
+     */
+    checkUsername(username: string): Promise<{
+        available: boolean;
+        message: string;
+    }>;
+    /**
+     * 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).
+     */
+    completeSecondFactor(request: {
+        challengeId: string;
+        code: string;
+    } & SignInDeviceOptions): Promise<LoginResult>;
+    signUp(request: {
+        username: string;
+        email: string;
+        emailTicket: string;
+    } & SignInDeviceOptions): Promise<LoginResult>;
+    methods(): Promise<SignInMethods>;
+    /**
+     * 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.
+     */
+    requestReauthCode(action: ReauthAction): Promise<EmailVerificationStartResponse>;
+}