@oxyhq/core 3.10.0 → 3.11.0

package/dist/types/HttpService.d.ts

@@ -25,6 +25,7 @@ export interface RequestOptions {
     timeout?: number;
     signal?: AbortSignal;
     headers?: Record<string, string>;
+    responseType?: 'blob';
 }
 interface RequestConfig extends RequestOptions {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -183,6 +184,8 @@ export declare class HttpService {
      * Build full URL with query params
      */
     private buildURL;
+    private getCredentialsMode;
+    private shouldSendCredentials;
     /**
      * Fetch CSRF token from server (with deduplication)
      * Required for state-changing requests (POST, PUT, PATCH, DELETE)

package/dist/types/OxyServices.d.ts

@@ -122,7 +122,7 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     waitForIframeAuth(iframe: HTMLIFrameElement, timeout: number, expectedOrigin: string): Promise<SessionLoginResponse | null>;
     signInWithRedirect(options?: RedirectAuthOptions): void;
     signUpWithRedirect(options?: RedirectAuthOptions): void;
-    exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+    exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
     generateSsoState(): string;
     auth(options?: {
         debug?: boolean;
@@ -153,7 +153,7 @@ export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
 /**
  * Export the default Oxy API URL (for documentation)
  */
-export declare const OXY_API_URL: any;
+export declare const OXY_API_URL: string;
 /**
  * Pre-configured client instance for easy import
  * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL

package/dist/types/crypto/canonicalJson.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical JSON (RFC 8785 / JCS-style) serialization.
+ *
+ * `canonicalize(value)` produces a deterministic string for any JSON-compatible
+ * value so that a client which SIGNS a record and a server which VERIFIES it
+ * agree byte-for-byte on the signing input — regardless of the order in which
+ * object keys happen to be written, how the value was deserialized, or which
+ * runtime built it.
+ *
+ * This is the load-bearing primitive for the self-sovereign identity layer's
+ * signed records (`SignatureService.signRecord` + the API's record-verify path):
+ * both sides import THIS function from `@oxyhq/core`, so cross-implementation
+ * number/string formatting differences cannot cause a verify mismatch.
+ *
+ * Rules (the JSON Canonicalization Scheme subset we need):
+ *  - Objects: keys are sorted (ascending, by UTF-16 code unit — the default
+ *    `Array.prototype.sort` order) and serialized recursively. Properties whose
+ *    value is `undefined`, a function, or a symbol are OMITTED (matching
+ *    `JSON.stringify` object semantics).
+ *  - Arrays: element order is PRESERVED; `undefined`/function/symbol elements
+ *    serialize to `null` (matching `JSON.stringify` array semantics).
+ *  - `null`, booleans, strings, and finite numbers serialize via the standard
+ *    JSON representation.
+ *  - Values exposing a `toJSON()` method (e.g. `Date`) are replaced by its
+ *    result first, then serialized — so a `Date` and its ISO-string equivalent
+ *    canonicalize identically (the wire always carries the string form).
+ *  - Non-finite numbers (`NaN`, `Infinity`) and `bigint` are not part of the
+ *    JSON data model and throw, rather than silently producing `null`.
+ *
+ * Platform-agnostic — zero dependencies, no `require()`, no react/react-native/
+ * expo. Safe in the dual CJS + ESM build.
+ */
+/**
+ * Produce the canonical JSON string for `value`.
+ *
+ * Deterministic: two structurally-equal values yield identical strings even if
+ * their object keys were written in different orders. Use this — never an
+ * ad-hoc `JSON.stringify` of a hand-sorted object — as the signing input for
+ * signed records, so client signing and server verification cannot drift.
+ *
+ * @throws if `value` (or any nested member used as the top-level/primitive)
+ *   contains a non-finite number or a `bigint`, which have no JSON form.
+ */
+export declare function canonicalize(value: unknown): string;

package/dist/types/crypto/keyManager.d.ts

@@ -186,6 +186,13 @@ export declare class KeyManager {
      * @internal
      */
     private static _persistIdentityAtomic;
+    /**
+     * Restore the backup slot to a previously-snapshotted state. Best-effort so
+     * the original persistence error remains the one surfaced to the caller.
+     *
+     * @internal
+     */
+    private static _rollbackBackup;
     /**
      * Restore the primary slot to a previously-snapshotted (privA, pubA) pair,
      * or delete it entirely if there was no prior identity. Best-effort: every

package/dist/types/crypto/signatureService.d.ts

@@ -4,6 +4,23 @@
  * Handles signing and verification of messages using ECDSA secp256k1.
  * Used for authenticating requests and proving identity ownership.
  */
+import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+/**
+ * The signing-input portion of a {@link SignedRecordEnvelope}: every field
+ * EXCEPT the `publicKey` and `signature`. Both the client (when signing) and
+ * the server (when verifying) canonicalize exactly these fields, so they agree
+ * on the bytes that the signature covers.
+ */
+export type SignedRecordSigningFields = Pick<SignedRecordEnvelope, 'version' | 'type' | 'subject' | 'issuer' | 'record' | 'issuedAt'>;
+/**
+ * Compute the canonical signing input for a signed-record envelope.
+ *
+ * This is the single definition of "what the signature covers": the canonical
+ * JSON of `{version, type, subject, issuer, record, issuedAt}`. `@oxyhq/core`
+ * (client signing) and `@oxyhq/api` (server verification) both call this, so a
+ * record signed by a client and verified by the server cannot drift.
+ */
+export declare function signedRecordSigningInput(fields: SignedRecordSigningFields): string;
 export interface SignedMessage {
     message: string;
     signature: string;
@@ -63,6 +80,22 @@ export declare class SignatureService {
      * Used for challenge-response authentication
      */
     static signChallenge(challenge: string): Promise<AuthChallenge>;
+    /**
+     * Create a signed authentication challenge response using the SHARED identity
+     * key (the cross-app `group.so.oxy.shared` keychain key), not the primary
+     * device key.
+     *
+     * Mirrors {@link signChallenge} exactly — same message format
+     * (`auth:${publicKey}:${challenge}:${timestamp}`) so the server verification
+     * path is unchanged — but sources the shared public/private key from
+     * `KeyManager` and signs with `signWithKey`. Used by "Sign in with Oxy"
+     * same-device shared-keychain SSO (Mechanism A): a sibling native app proves
+     * control of the shared identity to mint its own session.
+     *
+     * Throws if no shared identity exists (native-only; the shared keychain is
+     * unavailable on web).
+     */
+    static signChallengeWithSharedKey(challenge: string): Promise<AuthChallenge>;
     /**
      * Verify a challenge response
      */
@@ -86,5 +119,33 @@ export declare class SignatureService {
         publicKey: string;
         timestamp: number;
     }>;
+    /**
+     * Build a signed-record envelope for a self-issued identity/profile record.
+     *
+     * The envelope is self-issued: `issuer` equals `subject` (the signer's DID).
+     * The signature covers the canonical JSON of every field EXCEPT `publicKey`
+     * and `signature` (see {@link signedRecordSigningInput}); `alg` is
+     * `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of the canonical bytes,
+     * DER-encoded), the same scheme this service uses everywhere else.
+     *
+     * Requires a stored identity (native secure storage); throws if none exists.
+     *
+     * @param type - The record category (`'identity'` or `'profile'`).
+     * @param subject - The subject DID the record is about (also the issuer).
+     * @param record - The arbitrary record payload to attest to.
+     */
+    static signRecord(type: SignedRecordEnvelope['type'], subject: string, record: Record<string, unknown>): Promise<SignedRecordEnvelope>;
+    /**
+     * Verify a signed-record envelope: recompute the canonical signing input from
+     * the envelope's own fields and check the signature against the envelope's
+     * `publicKey`.
+     *
+     * Note: this confirms the signature is internally consistent with the
+     * embedded `publicKey`. It does NOT establish that `publicKey` is an
+     * authorized verification method for `subject` — that authorization check is
+     * the server's responsibility (it asserts the key is a current verification
+     * method on the subject's DID).
+     */
+    static verifyRecord(envelope: SignedRecordEnvelope): Promise<boolean>;
 }
 export default SignatureService;

package/dist/types/index.d.ts

@@ -30,6 +30,7 @@ export type { SilentAuthOptions } from './mixins/OxyServices.silent';
 export type { RedirectAuthOptions } from './mixins/OxyServices.redirect';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
+export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
@@ -41,6 +42,8 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export type { Application, PublicApplication, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export type { Workspace, WorkspaceMember, WorkspaceRole, WorkspaceType, WorkspaceStatus, WorkspaceMemberStatus, CreateWorkspaceInput, UpdateWorkspaceInput, InviteWorkspaceMemberInput, UpdateWorkspaceMemberInput, TransferWorkspaceOwnershipInput, WorkspaceSuccessResult, } from './mixins/OxyServices.workspaces';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';
+export { buildUserDid } from './mixins/OxyServices.identity';
+export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, } from './mixins/OxyServices.identity';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
@@ -48,8 +51,9 @@ export type { ClientSession, StorageKeys, MinimalUserData, SessionLoginResponse,
 export type { RefreshAllResponse, RefreshAllAccount, RefreshAllAccountUser, RefreshCookieResponse, } from './models/interfaces';
 export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/keyManager';
 export type { KeyPair } from './crypto/keyManager';
-export { SignatureService } from './crypto/signatureService';
-export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
+export { SignatureService, signedRecordSigningInput } from './crypto/signatureService';
+export type { SignedMessage, AuthChallenge, SignedRecordSigningFields } from './crypto/signatureService';
+export { canonicalize } from './crypto/canonicalJson';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
 export type { RecoveryPhraseResult } from './crypto/recoveryPhrase';
 export { DeviceManager } from './utils/deviceManager';
@@ -80,7 +84,7 @@ export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, mergeAccountsFromRefreshAll, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
-export { autoDetectAuthWebUrl, registrableApex, MULTIPART_TLDS } from './utils/fapiAutoDetect';
+export { autoDetectAuthWebUrl, registrableApex } from './utils/fapiAutoDetect';
 export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl';
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';

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

@@ -1,5 +1,9 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
+interface FileDownloadUrlOptions {
+    /** Omit bearer access tokens from generated URLs, even when authenticated. */
+    omitToken?: boolean;
+}
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -32,7 +36,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          *
          * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
          */
-        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string;
+        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number, options?: FileDownloadUrlOptions): string;
         /**
          * Get file download URL asynchronously (returns signed URL directly from CDN)
          */
@@ -168,3 +172,4 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         }>;
     };
 } & T;
+export {};

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

@@ -6,6 +6,7 @@
 import type { User, RefreshAllResponse, RefreshCookieResponse } from '../models/interfaces';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
+import type { PublicApplication } from './OxyServices.applications';
 export interface ChallengeResponse {
     challenge: string;
     expiresAt: string;
@@ -48,6 +49,60 @@ export interface PublicKeyCheckResponse {
     registered: boolean;
     message: 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
+ * 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`). */
+export interface CommonsSignInStatus {
+    /** True once an approver has authorized the session. */
+    authorized: boolean;
+    /** The authorized session id (present once `authorized`). */
+    sessionId?: string;
+    /** The approving identity's public key (present once `authorized`). */
+    publicKey?: string;
+    /** Lifecycle status (`'pending'` | `'authorized'` | `'cancelled'` | `'expired'`). */
+    status?: 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;
+    /** 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 expiry (epoch milliseconds). */
+    expiresAt: number;
+    /** Session lifecycle status. */
+    status: string;
+}
+/** Result of approving / denying a "Sign in with Oxy" request. */
+export interface CommonsSignInActionResult {
+    success: boolean;
+}
 export interface ServiceTokenResponse {
     token: string;
     expiresIn: number;
@@ -275,6 +330,87 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             expiresAt: string;
             user: User;
         }>;
+        /**
+         * 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`
+         * (`@oxyhq/services`); this method just performs the exchange.
+         */
+        signInWithSharedIdentity(opts?: {
+            deviceName?: string;
+            deviceFingerprint?: string;
+        }): 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, on `authorized`, exchange the
+         * `sessionToken` via the existing `claimSessionByToken`.
+         *
+         * @param params.clientId - The RP's registered OAuth client id
+         *   (ApplicationCredential publicKey); required so the server can resolve the
+         *   requesting application's identity.
+         */
+        startCommonsSignIn(params: {
+            clientId: string;
+        }): 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.
+         *
+         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+         */
+        pollCommonsSignIn(sessionToken: string): Promise<CommonsSignInStatus>;
+        /**
+         * 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).
+         *
+         * @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.
+         */
+        denyCommonsSignIn(authorizeCode: string): Promise<CommonsSignInActionResult>;
         /**
          * Refresh every device-local refresh-cookie slot in a single round trip
          * (Google-style multi-account rebuild).

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

@@ -0,0 +1,249 @@
+/**
+ * Identity Methods Mixin (self-sovereign identity layer)
+ *
+ * Provides typed access to Oxy's AtProto/Bluesky-flavoured identity &
+ * portability layer:
+ *  - DID resolution (`did:web:oxy.so:u:<userId>`, derived on demand by the API).
+ *  - The auth-method ↔ DID verification-method mapping and its reversibility
+ *    (link/unlink an identity key, link a password) via the existing
+ *    `/auth/link` surface.
+ *  - Signed records: clients sign an envelope with their own cryptographic key
+ *    (`SignatureService.signRecord` + the shared `canonicalize`) and publish it;
+ *    anyone can fetch and verify it.
+ *  - The signed data-export ("credible exit") bundle.
+ *  - Verified-domain badges (prove ownership of `nate.com`).
+ *
+ * Wire shapes come from `@oxyhq/contracts` (`DidDocument`,
+ * `SignedRecordEnvelope`, `AuthMethodsResponse`, `VerifiedDomain`,
+ * `DomainVerificationInstructions`, `ExportBundle`) — the single source of truth
+ * the API validates its output against, so producer and consumer cannot drift.
+ *
+ * Identity signing is NATIVE-ONLY: the private key lives in native secure
+ * storage, so `linkIdentityKey`, `signRecord`, and `publishRecord` require an
+ * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
+ * always `null`).
+ */
+import type { AuthMethodsResponse, DidDocument, DomainVerificationInstructions, ExportBundle, SignedRecordEnvelope, VerifiedDomain } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+/** Record categories a client may sign and publish. */
+export type IdentityRecordType = SignedRecordEnvelope['type'];
+/** Auth-method types that can be unlinked via {@link OxyServicesIdentityMixin}. */
+export type UnlinkableAuthMethodType = 'identity' | 'password' | 'google' | 'apple' | 'github';
+/**
+ * Result of a link/unlink auth-method mutation (`POST /auth/link`,
+ * `DELETE /auth/link/:type`).
+ */
+export interface LinkAuthMethodResult {
+    success: boolean;
+    message: string;
+}
+/**
+ * Result of publishing a signed record (`POST /identity/records`). Echoes the
+ * stored envelope plus the server's verification verdict.
+ */
+export interface PublishRecordResult {
+    envelope: SignedRecordEnvelope;
+    verified: boolean;
+}
+/**
+ * Result of verifying a stored record (`GET /identity/records/:userId/:type/verify`).
+ * `verified` is the server's verdict; `reason` is present when it is `false`.
+ */
+export interface VerifyRecordResult {
+    verified: boolean;
+    reason?: string;
+}
+/** Result of a successful domain verification (`POST /identity/domains/:domain/verify`). */
+export interface VerifyDomainResult {
+    verified: boolean;
+    domain: VerifiedDomain;
+}
+/** Result of removing a verified domain (`DELETE /identity/domains/:domain`). */
+export interface RemoveDomainResult {
+    success: boolean;
+}
+/**
+ * Derive a user's Oxy DID from their stable account id.
+ * `did:web:oxy.so:u:<userId>`.
+ */
+export declare function buildUserDid(userId: string): string;
+export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Resolve the W3C DID document for any user. The API derives it on demand
+         * from the account's `authMethods` + `publicKey` — there is no stored
+         * document. Public (no auth required); short-TTL cached.
+         *
+         * @param userId - The account's Mongo `_id`. URL-encoded into the path.
+         */
+        resolveDid(userId: string): Promise<DidDocument>;
+        /**
+         * The current user's DID (`did:web:oxy.so:u:<userId>`), derived locally from
+         * the access token's user id. Throws if no user is authenticated.
+         */
+        getMyDid(): string;
+        /** Resolve the current user's DID document. Requires an authenticated session. */
+        getMyDidDocument(): Promise<DidDocument>;
+        /**
+         * List the current user's linked authentication methods plus their DID.
+         * Each `identity` method carries a `verificationMethodId` linking it to its
+         * DID verification-method fragment.
+         */
+        listAuthMethods(): Promise<AuthMethodsResponse>;
+        /**
+         * Link the on-device cryptographic identity to the current account,
+         * upgrading it from custodial to self-sovereign. Signs a proof of private
+         * key ownership and posts it to `POST /auth/link`.
+         *
+         * NATIVE-ONLY: requires a stored identity (throws if `KeyManager` has no key
+         * or no user is authenticated). The signed payload is
+         * `JSON.stringify({ action: 'link_identity', userId, timestamp })` — the
+         * exact bytes the server reconstructs and verifies.
+         */
+        linkIdentityKey(): Promise<LinkAuthMethodResult>;
+        /**
+         * Link password authentication to the current account. Adds a `password`
+         * auth method (does not remove existing methods).
+         *
+         * @param email - The email to associate with password auth.
+         * @param password - The new password (server enforces strength rules).
+         */
+        linkPassword(email: string, password: string): Promise<LinkAuthMethodResult>;
+        /**
+         * Unlink an authentication method from the current account. The server
+         * refuses to remove the last remaining method (the account would become
+         * inaccessible). Unlinking `identity` downgrades the account to custodial.
+         *
+         * @param type - The auth-method type to remove.
+         */
+        unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult>;
+        /**
+         * Sign a record with the on-device identity key, WITHOUT publishing it.
+         * The subject is the current user's DID. NATIVE-ONLY (requires a stored
+         * key). Use {@link publishRecord} to sign and store in one step.
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        signRecord(type: IdentityRecordType, record: Record<string, unknown>): Promise<SignedRecordEnvelope>;
+        /**
+         * Sign a record and publish it to the append-only record store
+         * (`POST /identity/records`). NATIVE-ONLY (requires a stored key).
+         *
+         * @param type - The record category.
+         * @param record - The arbitrary record payload to attest to.
+         */
+        publishRecord(type: IdentityRecordType, record: Record<string, unknown>): Promise<PublishRecordResult>;
+        /**
+         * Fetch a user's most recent signed record of a given type. Public (no auth
+         * required); short-TTL cached.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to fetch.
+         */
+        getRecord(userId: string, type: IdentityRecordType): Promise<SignedRecordEnvelope>;
+        /**
+         * Ask the server to verify a user's stored record: it recomputes the
+         * canonical signing input, checks the signature, and asserts the signing key
+         * is a current verification method on the subject's DID.
+         *
+         * @param userId - The subject account's Mongo `_id`.
+         * @param type - The record category to verify.
+         */
+        verifyRecord(userId: string, type: IdentityRecordType): Promise<VerifyRecordResult>;
+        /**
+         * Download the current user's signed, open-format data-export bundle
+         * (`GET /users/me/export`) — the "credible exit" snapshot. Always carries an
+         * Oxy provenance `attestation`; carries an optional client `proof` when the
+         * account holds its own key.
+         */
+        exportMyData(): Promise<ExportBundle>;
+        /**
+         * Start verifying ownership of a domain. Returns the instructions: publish
+         * EITHER the DNS-TXT record OR the `/.well-known/oxy-domain` file, then call
+         * {@link verifyDomain}.
+         *
+         * @param domain - The domain to claim (e.g. `nate.com`).
+         */
+        requestDomainVerification(domain: string): Promise<DomainVerificationInstructions>;
+        /**
+         * Complete domain verification: the server checks the DNS-TXT record or
+         * well-known file and, on success, attaches the domain to the account
+         * (surfaced in the DID's `alsoKnownAs` and the user's `verifiedDomains`).
+         *
+         * @param domain - The domain previously requested via
+         *   {@link requestDomainVerification}.
+         */
+        verifyDomain(domain: string): Promise<VerifyDomainResult>;
+        /** List the current user's verified domains. */
+        listDomains(): Promise<VerifiedDomain[]>;
+        /**
+         * Remove a verified domain from the current account.
+         * @param domain - The verified domain to remove.
+         */
+        removeDomain(domain: string): Promise<RemoveDomainResult>;
+        /**
+         * Bust the cached reads that an identity mutation invalidates: the current
+         * user (`/users/me*`), the linked auth-methods list, the verified-domains
+         * list, and the user's derived DID document (which embeds auth methods +
+         * verified domains, so it goes stale on link/unlink/domain changes).
+         *
+         * Internal helper (leading underscore); not part of the supported public
+         * surface. Public rather than `private` because mixins compose into an
+         * exported anonymous class, where TypeScript cannot represent a private
+         * member in the emitted declaration file (TS4094).
+         */
+        _invalidateIdentityCaches(userId: string | null): void;
+        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;
+        getSessionBaseUrl(): 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;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | 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;

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

@@ -53,9 +53,12 @@ export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Ba
          * @param code - The opaque single-use code delivered in the SSO return
          *   fragment (see {@link parseSsoReturnFragment}). The central store burns
          *   it atomically on exchange.
+         * @param state - The state value returned alongside the code. In browsers,
+         *   when an SSO bounce state is still stored for the current origin, this
+         *   must match before any token-committing exchange is attempted.
          * @returns The resolved {@link SessionLoginResponse}.
          */
-        exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+        exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;