@oxy.so/core 1.18.0 → 3.0.0

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

@@ -0,0 +1,113 @@
+/**
+ * `oxy.billing` — the signed-in user's subscription, wallet and payment history.
+ *
+ * Every call reads the SIGNED-IN user's data unless a `userId` is passed (the
+ * API refuses any other user's). Checkout, plan changes and cancellation live
+ * under `/billing` (Stripe) and are not wrapped here yet.
+ *
+ * The types model the JSON these routes actually return (`subscription.controller`,
+ * `payment.controller`, `wallet.routes` in `packages/api`); `Date` columns
+ * arrive as ISO-8601 strings.
+ */
+import type { OxyContext } from '../client/context';
+/** Subscription tier. */
+export type SubscriptionPlan = 'basic' | 'pro' | 'business';
+/** Lifecycle state of a subscription. */
+export type SubscriptionStatus = 'active' | 'canceled' | 'expired';
+/** Feature flags toggled by the active plan. */
+export interface SubscriptionFeatures {
+    analytics: boolean;
+    premiumBadge: boolean;
+    unlimitedFollowing: boolean;
+    higherUploadLimits: boolean;
+    promotedPosts: boolean;
+    businessTools: boolean;
+}
+/**
+ * A user's subscription. A user who never subscribed gets `{ plan: 'basic' }`,
+ * so every other field is optional.
+ */
+export interface Subscription {
+    plan: SubscriptionPlan;
+    status?: SubscriptionStatus;
+    userId?: string;
+    startDate?: string;
+    endDate?: string;
+    autoRenew?: boolean;
+    paymentMethod?: string;
+    latestInvoice?: string;
+    features?: SubscriptionFeatures;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** A payment history entry (a `deposit` or `purchase` transaction). */
+export interface Payment {
+    id: string;
+    userId: string;
+    type: string;
+    amount: number;
+    status: string;
+    description?: string;
+    itemId?: string;
+    itemType?: string;
+    /** When the payment was created. */
+    timestamp?: string;
+    completedAt?: string;
+}
+/** A user's FairCoin wallet. */
+export interface Wallet {
+    userId: string;
+    balance: number;
+    /** On-chain withdrawal address, `null` until one is set. */
+    address: string | null;
+}
+export type WalletTransactionType = 'deposit' | 'withdrawal' | 'transfer' | 'purchase';
+export type WalletTransactionStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
+/** One wallet ledger entry. */
+export interface WalletTransaction {
+    id: string;
+    userId: string | {
+        _id: string;
+        username?: string;
+    };
+    type: WalletTransactionType;
+    amount: number;
+    status: WalletTransactionStatus;
+    description?: string;
+    recipientId?: string | {
+        _id: string;
+        username?: string;
+    } | null;
+    itemId?: string;
+    itemType?: string;
+    timestamp?: string;
+    completedAt?: string;
+}
+export interface WalletPagination {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/** A page of wallet transactions. */
+export interface WalletTransactionsPage {
+    data: WalletTransaction[];
+    pagination: WalletPagination;
+}
+export declare class BillingApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /** The signed-in user's payment history. Never cached. */
+    payments(): Promise<Payment[]>;
+    /** A user's subscription (default: the signed-in user's). */
+    subscription(userId?: string): Promise<Subscription>;
+    /** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
+    wallet(userId?: string): Promise<Wallet>;
+    /** A page of a user's wallet transactions (default: the signed-in user's). Never cached. */
+    walletTransactions(options?: {
+        userId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<WalletTransactionsPage>;
+    private resolveUserId;
+}

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

@@ -0,0 +1,203 @@
+/**
+ * `oxy.civic` — the Commons "Oxy ID": the public, verifiable citizen-identity
+ * card a person shows and others scan, real-life attestation, the validator
+ * (jury) flow, personhood vouching, and verifiable credentials.
+ *
+ *  - `publicCard` fetches a user's signed card and verifies the Oxy custodial
+ *    attestation CLIENT-SIDE, so a scanner can trust the card OFFLINE (a cached
+ *    card replayed without network) instead of re-trusting the transport.
+ *  - `idPayload` / `buildAttestQrPayload` build the QRs a person shows; the
+ *    scanner parses them with `parseIdPayload` / `parseAttestPayload`
+ *    (`civic/payloads.ts`).
+ *  - `attest`, `validation.vote`, `vouch`, `credentials.issue` sign a self-issued
+ *    v2 record on the caller's own chain with the on-device key, so they are
+ *    NATIVE-ONLY — they throw on web, where there is no key.
+ *
+ * Wire shapes come from `@oxy.so/contracts`. Card verification NEVER throws on a
+ * bad or absent signature — it returns `verified: false` so the UI can render a
+ * forged/unsigned card as visibly untrusted. A transport failure still rejects.
+ */
+import type { CredentialIssueResult, CredentialListResult, CredentialStatus, CredentialVerifyResult, PersonhoodStatusResult, RealLifeAttestationResult, SignedPublicCard, ValidationRequestSummary, ValidationVerdict, ValidationVoteResult, VerifiableCredentialResponse, VouchResult } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import { type AttestQrPayload } from '../civic/payloads';
+/**
+ * A `SignedPublicCard` plus the client's verdict. `verified` is `true` ONLY when
+ * `attestation` is present and its signature over `canonicalize(card)` checks
+ * out against `attestation.publicKey`. It does NOT on its own establish that
+ * `publicKey` is Oxy's key — that anchor is the Oxy API the card came from (over
+ * TLS) and `attestation.issuer`. A `false` verdict MUST be shown as untrusted.
+ */
+export interface CivicCardResult extends SignedPublicCard {
+    verified: boolean;
+}
+/** Input for {@link CivicApi.attest} — the scanned QR's fields plus B's support signals. */
+export interface SubmitRealLifeAttestationInput {
+    /** The DID of the person being attested (A); becomes the record's `about`. */
+    subjectDid: string;
+    /** Opaque interaction id from the QR. */
+    context: string;
+    /** Single-use nonce from the QR (also the record's `rkey`). */
+    nonce: string;
+    /** Nonce expiry from the QR (epoch ms). */
+    exp: number;
+    /** Coarse co-location proof (optional). */
+    geohash?: string;
+    /** Whether B's device biometric gate fired before signing (optional). */
+    biometricOk?: boolean;
+}
+/** Result of `oxy.civic.validation.deny`. */
+export interface DenyValidationResult {
+    denied: boolean;
+}
+/** Input for {@link CivicApi.vouch} — the subject (A) the caller (B) vouches for. */
+export interface VouchForPersonInput {
+    /** A's DID (`did:web:oxy.so:u:<userId>`); becomes the vouch record's `about`. */
+    subjectDid: string;
+    /**
+     * B's chosen stake (the `stake` wire field). Omitted ⇒ the server's default;
+     * the server clamps it and echoes the recorded amount as `VouchResult.stakeAmount`.
+     */
+    stakeAmount?: number;
+    /** Whether B's device biometric gate fired before signing (optional signal). */
+    biometricOk?: boolean;
+}
+/** Result of {@link CivicApi.withdrawVouch}. */
+export interface WithdrawVouchResult {
+    withdrawn: boolean;
+}
+/** Input for `oxy.civic.credentials.issue`. */
+export interface IssueCredentialInput {
+    /** The holder's Oxy DID; becomes the record's `about`. */
+    holderDid: string;
+    /**
+     * The VC type tags. `'VerifiableCredential'` is prepended when omitted;
+     * provide at least one specific type (e.g. `'EmploymentCredential'`).
+     */
+    types: string[];
+    /** The issuer-asserted claim set about the holder (signed verbatim). */
+    claims: Record<string, unknown>;
+    /**
+     * Optional ISO-8601 expiry; absent = non-expiring. Converted to epoch ms in the
+     * signed record, so a holder cannot extend validity after the fact.
+     */
+    expiresAt?: string;
+}
+/** Result of `oxy.civic.credentials.revoke`. */
+export interface RevokeCredentialResult {
+    revoked: boolean;
+    credential: VerifiableCredentialResponse;
+}
+export declare class CivicApi {
+    private readonly ctx;
+    /** The validator (jury) flow — MEDIUM-weight peer validation. */
+    readonly validation: CivicValidationApi;
+    /** Verifiable credentials. */
+    readonly credentials: CivicCredentialsApi;
+    constructor(ctx: OxyContext);
+    /**
+     * A user's signed public Oxy ID card, with the Oxy attestation verified
+     * client-side. Public; short-TTL cached. A bad or absent signature does NOT
+     * reject — it yields `verified: false`.
+     */
+    publicCard(userId: string): Promise<CivicCardResult>;
+    /**
+     * The signed-in user's Oxy ID QR payload: `oxycommons://card?did=<did>&v=1`.
+     * Encodes ONLY the DID; a scanner resolves the signed card via `publicCard`.
+     * Throws when signed out.
+     */
+    idPayload(): string;
+    /**
+     * The real-life-attestation QR the signed-in user (A) shows to be attested by
+     * a counterparty (B):
+     * `oxycommons://attest?subject=<A.did>&ctx=<context>&nonce=<fresh>&exp=<now+10m>`.
+     * A fresh crypto-random nonce per call (single-use replay guard). Throws when
+     * signed out.
+     */
+    buildAttestQrPayload(input: {
+        context: string;
+    }): Promise<AttestQrPayload>;
+    /**
+     * Submit a real-life counterparty attestation as the SCANNER (B): sign a
+     * self-issued `real_life_attestation` record on B's own chain referencing A via
+     * `record.about`, then `POST /civic/attestations`. The server enforces nonce
+     * single-use, freshness, graph-exclusion and the per-pair cooldown, then awards
+     * A the HIGH-weight points. NATIVE-ONLY.
+     */
+    attest(input: SubmitRealLifeAttestationInput): Promise<RealLifeAttestationResult>;
+    /**
+     * Vouch that another user is a real person as the VOUCHER (B): sign a
+     * self-issued `personhood_vouch` record (`{ about, stake? }`) on B's own chain,
+     * then `POST /civic/personhood/vouch`. The server enforces voucher eligibility
+     * and graph-exclusion, stakes B, and recomputes A's personhood. One vouch per
+     * subject (`rkey: <subjectDid>`, last-writer-wins). NATIVE-ONLY.
+     */
+    vouch(input: VouchForPersonInput): Promise<VouchResult>;
+    /**
+     * Withdraw the signed-in user's active vouch for a subject. The subject is
+     * recomputed (which may demote them).
+     *
+     * @param subjectUserId - The subject's account id (NOT a DID).
+     */
+    withdrawVouch(subjectUserId: string): Promise<WithdrawVouchResult>;
+    /**
+     * A user's public personhood status snapshot (default: the signed-in user's).
+     * A zeroed `unverified` shape when none exists yet. Short-TTL cached.
+     */
+    personhood(userId?: string): Promise<PersonhoodStatusResult>;
+    /** A vouch / withdraw changes personhood reads and (via `verified`) `/users/me`. */
+    private sweepPersonhood;
+    private myUserId;
+    private myDid;
+}
+/** `oxy.civic.validation` — a randomly selected juror's duties. */
+export declare class CivicValidationApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** The signed-in user's pending jury duties. Never cached; `[]` when on no juries. */
+    inbox(): Promise<ValidationRequestSummary[]>;
+    /**
+     * Cast a SIGNED verdict as a selected juror: a self-issued `validation_verdict`
+     * record bound to `requestId` + `payloadHash` (so it cannot be replayed onto a
+     * different request or an altered payload). NATIVE-ONLY.
+     *
+     * @param payloadHash - The request's canonical payload hash (from the inbox).
+     */
+    vote(requestId: string, payloadHash: string, verdict: ValidationVerdict): Promise<ValidationVoteResult>;
+    /** Recuse from a validation request: the juror leaves the jury and it is re-tallied. */
+    deny(requestId: string): Promise<DenyValidationResult>;
+}
+/** `oxy.civic.credentials` — verifiable credentials. */
+export declare class CivicCredentialsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * Issue a verifiable credential as the ISSUER: sign a self-issued `credential`
+     * record on the caller's own chain whose `record.about` is the HOLDER's DID,
+     * then `POST /civic/credentials`. `'VerifiableCredential'` is ensured as the
+     * base type; an `expiresAt` ISO string becomes epoch ms. NATIVE-ONLY.
+     */
+    issue(input: IssueCredentialInput): Promise<CredentialIssueResult>;
+    /**
+     * A holder's credentials, newest first (default holder: the signed-in user),
+     * optionally filtered by status. Public; short-TTL cached.
+     *
+     * @param holderUserId - The holder's account id (NOT a DID).
+     */
+    list(holderUserId?: string, opts?: {
+        status?: CredentialStatus;
+    }): Promise<CredentialListResult>;
+    /**
+     * Verify a credential by its signed-record id: the server re-checks the
+     * signature against a CURRENT verification method of the issuer DID, then
+     * that it is neither revoked nor expired. A failing credential yields
+     * `valid: false`, not a throw. Short-TTL cached.
+     */
+    verify(recordId: string): Promise<CredentialVerifyResult>;
+    /**
+     * Revoke a credential the signed-in user issued.
+     *
+     * @param id - The credential's id (the projection row id, NOT the record id).
+     */
+    revoke(id: string): Promise<RevokeCredentialResult>;
+    private sweep;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * `oxy.contacts` — privacy-preserving discovery of which address-book contacts
+ * are on Oxy.
+ *
+ * Hash locally, send only digests; the server answers with the Oxy user ids
+ * and the hashes that matched. Hashing must match the server
+ * (`utils/contactHash.ts`): SHA-256, lowercase hex, over
+ * - an email: `trim().toLowerCase()`;
+ * - a phone: trim → keep one leading `+` → strip non-digits → prepend `+` if missing.
+ */
+import type { OxyContext } from '../client/context';
+/** One contact that is on Oxy. */
+export interface ContactDiscoveryMatch {
+    /** The Oxy user id. */
+    userId: string;
+    /** The request hash that matched. */
+    hashedIdentifier: string;
+    matchType: 'email' | 'phone';
+}
+export interface ContactDiscoveryResponse {
+    matches: ContactDiscoveryMatch[];
+}
+export declare class ContactsApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /**
+     * Which of these hashed contacts are on Oxy. Either list may be empty, not
+     * both; at most 200 hashes per list per call (batch larger books).
+     */
+    discover(hashedEmails: string[], hashedPhones: string[]): Promise<ContactDiscoveryResponse>;
+}

package/{src/mixins/OxyServices.deviceBoot.ts → dist/types/api/devices.d.ts}

@@ -1,33 +1,37 @@
 /**
- * Device-first token mint mixin.
+ * `oxy.devices` — this user's devices, the sessions on them, their security
+ * activity, and device sign-in.
  *
- * The client half of the zero-cookie device transport: the single network call
- * the cold boot (`sessionColdBoot`) and the unified re-mint handler (`refresh.ts`)
- * make to turn a first-party `deviceId` + `deviceSecret` into a fresh access
- * token. The response is validated against the `@oxy.so/contracts`
- * `deviceTokenMintResponseSchema`, so producer (oxy-api) and consumer cannot
- * drift — an unexpected shape throws here rather than silently corrupting the
- * persisted store.
- *
- * This method carries NO persistence or token-planting side effects of its own;
- * the cold boot / re-mint handler own persistence and `setTokens`, so the same
- * primitive can be reused from either without double-planting.
- *
- * `provisionBackgroundCredential` is the mixin's second, adjacent call: it hands
- * native background code (no JS runtime) its own non-rotating credential so that
- * code never has to mint from — and therefore never rotates — the device secret
- * JS depends on.
+ * Device sign-in is the client half of the zero-cookie device transport:
+ * {@link DevicesApi.mintToken} turns a first-party `deviceId` + `deviceSecret`
+ * into a fresh access token (the cold boot and the re-mint handler call it);
+ * {@link DevicesApi.registerBrowser}, {@link DevicesApi.requestJoinCode} and
+ * {@link DevicesApi.joinBrowser} are the browser bridge (ADR 0029 D2); and
+ * {@link DevicesApi.provisionBackgroundCredential} hands native background code
+ * its own non-rotating credential. The mint carries NO persistence or
+ * token-planting side effects: the cold boot / re-mint handler own those.
  */
-import {
-  deviceBackgroundCredentialResponseSchema,
-  deviceTokenMintResponseSchema,
-  safeParseContract,
-  type DeviceBackgroundCredentialResponse,
-  type DeviceTokenMintResponse,
-} from '@oxy.so/contracts';
-import type { OxyServicesBase } from '../OxyServices.base';
-import { extractErrorStatus } from '../utils/errorUtils';
-
+import { type DeviceBackgroundCredentialResponse, type DeviceJoinCodeRequest, type DeviceJoinCodeResponse, type DeviceJoinRequest, type DeviceJoinResponse, type DeviceRegisterResponse, type DeviceTokenMintResponse } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import type { DeviceLinkedSession, DeviceLinkedSessionLogoutResponse, SecurityActivityResponse, SecurityEventType } from '../models/interfaces';
+/** One of the signed-in user's devices (`GET /devices`). */
+export interface UserDevice {
+    id: string;
+    deviceId: string;
+    name: string;
+    deviceName: string;
+    type: string;
+    deviceType: string;
+    /** ISO-8601. */
+    lastActive: string;
+    /** ISO-8601. */
+    createdAt: string;
+    isCurrent: boolean;
+}
+/** Security information for the signed-in account (`GET /devices/security`). */
+export interface SecurityInfo {
+    recoveryEmail: string | null;
+}
 /**
  * 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.
@@ -38,34 +42,78 @@ import { extractErrorStatus } from '../utils/errorUtils';
  * must re-establish its session from the local key rather than drop/clear the
  * device credential.
  */
-export class AccountNotOnDeviceError extends Error {
-  override readonly name = 'AccountNotOnDeviceError';
-  /** HTTP status of the originating response; mirrors the ApiError shape. */
-  readonly status = 401;
-  constructor(readonly accountId: string, readonly cause?: unknown) {
-    super(
-      `account_not_on_device: ${accountId} is not a live account of this device session`,
-    );
-  }
+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);
 }
-
-/**
- * Structural (never `instanceof`) read of a normalized mint error: the thrown
- * value may be a plain ApiError-shaped object or come from another realm.
- */
-function isAccountNotOnDevice(error: unknown): boolean {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  const { status, message } = error as { status?: unknown; message?: unknown };
-  if (status !== 401) {
-    return false;
-  }
-  return typeof message === 'string' && message.includes('account_not_on_device');
-}
-
-export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
+export declare class DevicesApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * Get all devices for the current user
+     * @returns Array of user devices
+     */
+    list(): Promise<UserDevice[]>;
+    /**
+     * Remove a device
+     * @param deviceId - The device ID to remove
+     */
+    remove(deviceId: string): Promise<void>;
+    /**
+     * Get device sessions for a given session ID
+     * Note: Not cached by default to ensure fresh data
+     * @param sessionId - The session ID
+     * @returns Array of device sessions
+     */
+    sessions(sessionId: string): Promise<DeviceLinkedSession[]>;
+    /**
+     * Logout all device sessions
+     * @param sessionId - The session ID
+     * @param deviceId - Optional device ID to target
+     * @param excludeCurrent - Whether to exclude the current session
+     * @returns Logout result
+     */
+    logoutAll(sessionId: string, deviceId?: string, excludeCurrent?: boolean): Promise<DeviceLinkedSessionLogoutResponse>;
+    /**
+     * Update device name
+     * @param sessionId - The session ID
+     * @param deviceName - New device name
+     * @returns Updated device object
+     */
+    rename(sessionId: string, deviceName: string): Promise<{
+        success: boolean;
+        message: string;
+        deviceName: string;
+    }>;
+    /**
+     * Get security information
+     * @returns Security information object
+     */
+    securityInfo(): Promise<SecurityInfo>;
+    /**
+     * Get user's security activity with pagination
+     * @param limit - Number of results (default: 50, max: 100)
+     * @param offset - Pagination offset (default: 0)
+     * @param eventType - Optional filter by event type
+     * @returns Security activity response with pagination
+     */
+    securityActivity(limit?: number, offset?: number, eventType?: SecurityEventType): Promise<SecurityActivityResponse>;
+    /**
+     * Log private key exported event
+     * @param deviceId - Optional device ID for tracking
+     * @returns Promise that resolves when event is logged
+     */
+    logPrivateKeyExported(deviceId?: string): Promise<void>;
+    /**
+     * Log backup created event
+     * @param deviceId - Optional device ID for tracking
+     * @returns Promise that resolves when event is logged
+     */
+    logBackupCreated(deviceId?: string): Promise<void>;
     /**
      * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
      * `POST /session/device/token` — NO bearer, NO cookies: possession of the
@@ -100,36 +148,32 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * @throws {AccountNotOnDeviceError} when a pinned mint's account is not on the device.
      * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
      */
-    async mintFromDeviceSecret(
-      deviceId: string,
-      deviceSecret: string,
-      options?: { accountId?: string },
-    ): Promise<DeviceTokenMintResponse> {
-      const accountId = options?.accountId;
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/session/device/token',
-          { deviceId, deviceSecret, ...(accountId ? { accountId } : {}) },
-          // `bypassQueue`: this mint is the control-plane call the auth lane
-          // depends on — it must run even when every RequestQueue slot is parked
-          // awaiting it, or the whole client deadlocks. See RequestOptions.bypassQueue.
-          { cache: false, skipAuth: true, retry: false, bypassQueue: true },
-        );
-        const parsed = safeParseContract(deviceTokenMintResponseSchema, res);
-        if (!parsed) {
-          throw new Error('session/device/token returned an unexpected response shape');
-        }
-        return parsed;
-      } catch (error) {
-        const normalized = this.handleError(error);
-        if (accountId && isAccountNotOnDevice(normalized)) {
-          throw new AccountNotOnDeviceError(accountId, normalized);
-        }
-        throw normalized;
-      }
-    }
-
+    mintToken(deviceId: string, deviceSecret: string, options?: {
+        accountId?: string;
+    }): Promise<DeviceTokenMintResponse>;
+    /**
+     * `POST /session/device/register` — auth.oxy.so only. A new, empty browser
+     * device with a server-chosen id and auth.oxy.so's holder credential. No
+     * bearer: this runs before anyone is signed in.
+     *
+     * @throws if the response does not match {@link deviceRegisterResponseSchema}.
+     */
+    registerBrowser(): Promise<DeviceRegisterResponse>;
+    /**
+     * `POST /session/device/join-code` — auth.oxy.so only (the bridge page).
+     * Proves the device with its holder secret and returns a one-use, ~60 s
+     * code for an OFFICIAL app, bound to its exact registered redirect URI and
+     * its PKCE S256 challenge. A rejected secret surfaces as a 401 whose message
+     * carries `invalid_device_secret`.
+     */
+    requestJoinCode(request: DeviceJoinCodeRequest): Promise<DeviceJoinCodeResponse>;
+    /**
+     * `POST /session/device/join` — the app's own origin. Redeems the bridge's
+     * code with the PKCE verifier this app holds, and returns this app's own
+     * holder credential for the browser's device. Persist it, then mint through
+     * {@link DevicesApi.mintToken} like any other holder.
+     */
+    joinBrowser(request: DeviceJoinRequest): Promise<DeviceJoinResponse>;
     /**
      * Provision a NON-rotating background credential for the caller's account on
      * this device — the credential native background code (an Android widget
@@ -179,32 +223,8 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
      * @returns the provisioned credential, or `null` when the endpoint is absent
      * (404). The API deploy leads the SDK release, so a client on a newer SDK
      * than the server degrades to "no background session" quietly instead of
-     * surfacing an error. The status is read off the RAW rejection because
-     * `handleError` only preserves it for errors carrying `HttpService`'s
-     * annotations.
+     * surfacing an error.
      * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
      */
-    async provisionBackgroundCredential(): Promise<DeviceBackgroundCredentialResponse | null> {
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/session/device/background-credential',
-          undefined,
-          { cache: false },
-        );
-        const parsed = safeParseContract(deviceBackgroundCredentialResponseSchema, res);
-        if (!parsed) {
-          throw new Error(
-            'session/device/background-credential returned an unexpected response shape',
-          );
-        }
-        return parsed;
-      } catch (error) {
-        if (extractErrorStatus(error) === 404) {
-          return null;
-        }
-        throw this.handleError(error);
-      }
-    }
-  };
+    provisionBackgroundCredential(): Promise<DeviceBackgroundCredentialResponse | null>;
 }