@oxyhq/core 12.10.6 → 12.11.1

package/dist/types/HttpService.d.ts

@@ -89,7 +89,15 @@ export declare class HttpService {
     private logger;
     private config;
     private tokenRefreshPromise;
-    private tokenRefreshCooldownUntil;
+    /**
+     * Epoch ms of the last FAILED refresh (0 = none since the last success). The
+     * post-failure cooldown is measured from here; its length depends on whether
+     * the current token is still valid ({@link TOKEN_REFRESH_COOLDOWN_MS}) or
+     * already expired ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}), so an expired
+     * token recovers promptly the instant it crosses `exp` — without storing a
+     * fixed deadline that could not shrink once the token expired mid-cooldown.
+     */
+    private lastRefreshFailureAt;
     private authRefreshHandler;
     private accessTokenProvider;
     private deviceSecretMintInFlight;
@@ -224,6 +232,15 @@ export declare class HttpService {
      */
     private getAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
+    /**
+     * Whether the CURRENT stored access token is already past its `exp`. Drives
+     * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):
+     * a still-valid (near-expiry) token can wait out the full cooldown, but an
+     * expired one must re-mint promptly. Returns `false` for an absent or
+     * opaque/no-`exp` token — no proof it is expired, so keep the conservative
+     * (longer) cooldown and avoid an unnecessary retry loop.
+     */
+    private isAccessTokenExpired;
     /**
      * PROCESS-WIDE single-flight for the rotating device-secret mint
      * (`POST /session/device/token`).

package/dist/types/boot/sessionColdBoot.d.ts

@@ -15,14 +15,34 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
+ *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
+ *      re-mint from THIS device's primary identity key.
  *   4. Signed out.
  *
+ * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
+ *   - `account` (default) — the device's ACTIVE account owns the session. Every
+ *     Oxy app but the identity vault boots this way; behaviour is unchanged.
+ *   - `identity` — the owner of the local PRIMARY identity key owns the session,
+ *     permanently, regardless of which account the device is switched to. Each
+ *     step above is bound to the persisted identity pin, and the shared-keychain
+ *     lane is replaced by the primary-key one (the shared slot is a CROSS-APP
+ *     slot that may hold a different identity).
+ *
  * ESM-safe (no `require()`); no react/react-native/expo imports.
  */
 import { type ColdBootOutcome } from '../utils/coldBoot';
+import { type IdentityBinding } from '../session/identitySession';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
+/**
+ * Who owns the session this boot resolves.
+ *
+ * - `account` — the device's active account (every ordinary Oxy app).
+ * - `identity` — the owner of the device's primary identity key (the identity
+ *   vault). Requires {@link RunSessionColdBootOptions.identity}.
+ */
+export type SessionMode = 'account' | 'identity';
 /** The winning session shape a cold-boot step reports. */
 export interface DeviceBootSession {
     sessionId: string;
@@ -71,6 +91,23 @@ export interface RunSessionColdBootOptions {
      * so a flaky probe can never falsely skip a real sign-in.
      */
     isOffline?: () => boolean;
+    /**
+     * Who owns the resolved session. Defaults to `'account'` — the device's active
+     * account — which is the behaviour every ordinary Oxy app has today and which
+     * this option leaves byte-for-byte unchanged.
+     *
+     * `'identity'` binds the boot to the owner of this device's PRIMARY identity
+     * key and REQUIRES {@link identity}. When it is missing the boot refuses to
+     * run any lane (an identity-bound client silently falling back to the device's
+     * active account is precisely the bug this mode exists to prevent) and
+     * resolves signed out.
+     */
+    sessionMode?: SessionMode;
+    /**
+     * The identity binding (pin store + key/signature access) used by
+     * `sessionMode: 'identity'`. Ignored in `'account'` mode.
+     */
+    identity?: IdentityBinding;
 }
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as

package/dist/types/index.d.ts

@@ -23,8 +23,11 @@ export type { LinkedHttpClient } from './OxyServices.base';
 export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
 export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth';
 export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval';
+export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery';
+export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRoute, } from './utils/commonsDelivery';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
-export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
+export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsDenyReason, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
+export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export type { InitDeviceTransferResult, DeviceTransferOutcome, } from './mixins/OxyServices.deviceTransfer';
@@ -93,7 +96,7 @@ export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { isOxyRpOrigin } from './utils/webauthnOrigin';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins';
 export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';
@@ -107,13 +110,18 @@ export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountId
 export { projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
 export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
-export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
+export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
+export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './session/identityPin';
+export type { IdentityPin, IdentityPinStore } from './session/identityPin';
+export { resolveIdentityPin, establishIdentitySession, } from './session/identitySession';
+export type { IdentityBinding, IdentityRequestOptions, EstablishedIdentitySession, } from './session/identitySession';
+export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome } from './session/refresh';
 export { runSessionColdBoot } from './boot/sessionColdBoot';
-export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
+export type { RunSessionColdBootOptions, SessionMode, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

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

@@ -32,12 +32,57 @@ export interface PublicKeyCheckResponse {
     registered: boolean;
     message: 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`, and is
+ * 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}.
@@ -54,16 +99,77 @@ export interface CommonsSignInHandle {
     /** 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`). */
+/**
+ * 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`). */
+    /** 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
@@ -85,6 +191,32 @@ export interface CommonsApprovalInfo {
      * "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. */
@@ -94,6 +226,33 @@ export interface CommonsApprovalInfo {
 export interface CommonsSignInActionResult {
     success: boolean;
 }
+/**
+ * Why the approver denied a "Sign in with Oxy" request. A CLOSED set — the deny
+ * endpoint is unauthenticated, so it accepts no free-form text:
+ *
+ *  - `'declined'` the approver rejected a request they recognised ("Not now").
+ *  - `'not_me'`   the approver did not start the request ("This wasn't me").
+ *                 The only value that records the denial as suspicious rather
+ *                 than an ordinary cancel, so a UI may only offer it where the
+ *                 user genuinely said so.
+ */
+export type CommonsDenyReason = 'declined' | 'not_me';
+/**
+ * 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;
@@ -372,33 +531,120 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * 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, on `authorized`, exchange the
-         * `sessionToken` via the existing `claimSessionByToken`.
+         * {@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 exchanges the secret `sessionToken` via the existing
-         * `claimSessionByToken` to mint the first access token.
+         * 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` is resolved server-side and is the only safe
-         * thing to display in the approval UI — NEVER trust the app/name/origin
-         * strings carried in the QR payload. Public (no auth required).
+         * 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.
          */
@@ -426,8 +672,13 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * 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): Promise<CommonsSignInActionResult>;
+        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;

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

@@ -15,6 +15,24 @@
  */
 import { type DeviceTokenMintResponse, type DeviceHubTicketIssueResponse, type DeviceHubTicketRedeemResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * The server's `401 account_not_on_device` for a PINNED mint: the requested
+ * `accountId` is not (or is no longer) a live account of this device session.
+ *
+ * Distinguished from every other mint 401 because the remedy is different: the
+ * device secret is FINE — it is the identity binding that went stale (the
+ * account was signed out on this device, or revoked). An identity-bound caller
+ * must re-establish its session from the local key rather than drop/clear the
+ * device credential.
+ */
+export declare class AccountNotOnDeviceError extends Error {
+    readonly accountId: string;
+    readonly cause?: unknown | undefined;
+    readonly name = "AccountNotOnDeviceError";
+    /** HTTP status of the originating response; mirrors the ApiError shape. */
+    readonly status = 401;
+    constructor(accountId: string, cause?: unknown | undefined);
+}
 export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -38,9 +56,21 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * boot's worst-case time-to-route. A transient failure surfaces once and the
          * scheduler/401 path retries it later.
          *
+         * `options.accountId` PINS the mint to one account of the device instead of
+         * whichever account is currently active. It exists for identity-bound
+         * clients (Commons), whose authenticated user is fixed by a local
+         * cryptographic key and must never follow an account switch made by another
+         * app on the same device. The server never mutates `activeAccountId` for a
+         * pinned mint — the returned `state` still reports the device's true active
+         * account — and rejects a non-member/dead account with
+         * `401 account_not_on_device`, surfaced here as {@link AccountNotOnDeviceError}.
+         *
+         * @throws {AccountNotOnDeviceError} when a pinned mint's account is not on the device.
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
-        mintFromDeviceSecret(deviceId: string, deviceSecret: string): Promise<DeviceTokenMintResponse>;
+        mintFromDeviceSecret(deviceId: string, deviceSecret: string, options?: {
+            accountId?: string;
+        }): Promise<DeviceTokenMintResponse>;
         /** Mint a one-time hub sync ticket (bearer required). */
         issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse>;
         /** Redeem a hub sync ticket for a fresh device secret (public). */