@oxy.so/core 1.18.1 → 3.0.0

package/dist/esm/api/billing.js

@@ -0,0 +1,40 @@
+const SUBSCRIPTION_TTL = 2 * 60 * 1000;
+const WALLET_TTL = 60 * 1000;
+export class BillingApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The signed-in user's payment history. Never cached. */
+    async payments() {
+        return this.ctx.request('GET', '/payments/user', undefined, { cache: false });
+    }
+    /** A user's subscription (default: the signed-in user's). */
+    async subscription(userId) {
+        const id = this.resolveUserId(userId);
+        return this.ctx.request('GET', `/subscription/${id}`, undefined, {
+            cache: true,
+            cacheTTL: SUBSCRIPTION_TTL,
+        });
+    }
+    /** A user's wallet (default: the signed-in user's). Cached briefly: the balance moves. */
+    async wallet(userId) {
+        const id = this.resolveUserId(userId);
+        return this.ctx.request('GET', `/wallet/${id}`, undefined, { cache: true, cacheTTL: WALLET_TTL });
+    }
+    /** A page of a user's wallet transactions (default: the signed-in user's). Never cached. */
+    async walletTransactions(options = {}) {
+        const id = this.resolveUserId(options.userId);
+        const params = {};
+        if (options.limit)
+            params.limit = options.limit;
+        if (options.offset)
+            params.offset = options.offset;
+        return this.ctx.request('GET', `/wallet/transactions/${id}`, params, { cache: false });
+    }
+    resolveUserId(userId) {
+        const id = userId || this.ctx.oxy.session.userId;
+        if (!id)
+            throw new Error('User not authenticated');
+        return id;
+    }
+}

package/dist/esm/api/civic.js

@@ -0,0 +1,250 @@
+import { verifyPublicCardAttestation } from '../civic/payloads.js';
+import { buildUserDid, signOwnChainRecord } from './identity.js';
+/** Short-TTL read cache for public civic reads. */
+const SHORT_TTL = 60 * 1000;
+/**
+ * Validity window of a real-life-attestation QR, matching the server's
+ * `REAL_LIFE_NONCE_MAX_AGE_MS` ceiling. The server is authoritative on
+ * freshness; this is the client-issued `exp`.
+ */
+const ATTEST_QR_TTL_MS = 10 * 60 * 1000;
+/** AtProto-style collections of the civic records. */
+const ATTEST_COLLECTION = 'app.oxy.attestation';
+const VALIDATION_COLLECTION = 'app.oxy.validation';
+const VOUCH_COLLECTION = 'app.oxy.vouch';
+/**
+ * Each credential is its own chain entry, so its `rkey` MUST be unique (a fresh
+ * nonce), unlike the one-per-subject vouch keyed on the subject DID.
+ */
+const CREDENTIAL_COLLECTION = 'app.oxy.credential';
+/**
+ * The W3C base VC type that MUST be present in every credential's `types`;
+ * prepended when the caller omits it (the server rejects a record lacking it).
+ */
+const CREDENTIAL_BASE_TYPE = 'VerifiableCredential';
+/** Every credential read (holder list + by-record verify) starts with this. */
+const CREDENTIAL_CACHE_PREFIX = 'GET:/civic/credentials/';
+/** Every personhood-status read starts with this. */
+const PERSONHOOD_CACHE_PREFIX = 'GET:/civic/personhood/';
+/**
+ * `GET /users/me`: a subject crossing the personhood threshold flips their
+ * mirrored `User.verified`, so a vouch / withdraw sweeps it.
+ */
+const USERS_ME_CACHE_PREFIX = 'GET:/users/me';
+export class CivicApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.validation = new CivicValidationApi(ctx);
+        this.credentials = new CivicCredentialsApi(ctx);
+    }
+    /**
+     * 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`.
+     */
+    async publicCard(userId) {
+        const signed = await this.ctx.request('GET', `/civic/${encodeURIComponent(userId)}/card`, undefined, {
+            cache: true,
+            cacheTTL: SHORT_TTL,
+        });
+        const verified = await verifyPublicCardAttestation(signed.card, signed.attestation);
+        return { card: signed.card, attestation: signed.attestation, verified };
+    }
+    /**
+     * 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() {
+        return `oxycommons://card?did=${this.myDid('build an Oxy ID payload')}&v=1`;
+    }
+    /**
+     * 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.
+     */
+    async buildAttestQrPayload(input) {
+        const subject = this.myDid('build an attestation QR');
+        const { SignatureService } = await import('../crypto/internal.js');
+        const nonce = await SignatureService.generateChallenge();
+        const exp = Date.now() + ATTEST_QR_TTL_MS;
+        const payload = `oxycommons://attest?subject=${subject}` +
+            `&ctx=${encodeURIComponent(input.context)}` +
+            `&nonce=${nonce}&exp=${exp}`;
+        return { payload, nonce, exp };
+    }
+    /**
+     * 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.
+     */
+    async attest(input) {
+        const envelope = await signOwnChainRecord(this.ctx, 'real_life_attestation', {
+            about: input.subjectDid,
+            context: input.context,
+            nonce: input.nonce,
+            exp: input.exp,
+            ...(input.geohash !== undefined ? { geohash: input.geohash } : {}),
+            ...(input.biometricOk !== undefined ? { biometricOk: input.biometricOk } : {}),
+        }, { collection: ATTEST_COLLECTION, rkey: input.nonce });
+        return this.ctx.request('POST', '/civic/attestations', envelope, { cache: false });
+    }
+    /**
+     * 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.
+     */
+    async vouch(input) {
+        const envelope = await signOwnChainRecord(this.ctx, 'personhood_vouch', {
+            about: input.subjectDid,
+            ...(input.stakeAmount !== undefined ? { stake: input.stakeAmount } : {}),
+            ...(input.biometricOk !== undefined ? { biometricOk: input.biometricOk } : {}),
+        }, { collection: VOUCH_COLLECTION, rkey: input.subjectDid });
+        const result = await this.ctx.request('POST', '/civic/personhood/vouch', envelope, { cache: false });
+        this.sweepPersonhood();
+        return result;
+    }
+    /**
+     * 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).
+     */
+    async withdrawVouch(subjectUserId) {
+        const result = await this.ctx.request('DELETE', `/civic/personhood/vouch/${encodeURIComponent(subjectUserId)}`, undefined, { cache: false });
+        this.sweepPersonhood();
+        return result;
+    }
+    /**
+     * A user's public personhood status snapshot (default: the signed-in user's).
+     * A zeroed `unverified` shape when none exists yet. Short-TTL cached.
+     */
+    async personhood(userId) {
+        const id = userId ?? this.myUserId('resolve personhood status');
+        return this.ctx.request('GET', `/civic/personhood/${encodeURIComponent(id)}`, undefined, {
+            cache: true,
+            cacheTTL: SHORT_TTL,
+        });
+    }
+    /** A vouch / withdraw changes personhood reads and (via `verified`) `/users/me`. */
+    sweepPersonhood() {
+        this.ctx.http.invalidateCache({ prefixes: [PERSONHOOD_CACHE_PREFIX, USERS_ME_CACHE_PREFIX] });
+    }
+    myUserId(action) {
+        const userId = this.ctx.oxy.session.userId;
+        if (!userId) {
+            throw new Error(`No authenticated user — cannot ${action}.`);
+        }
+        return userId;
+    }
+    myDid(action) {
+        return buildUserDid(this.myUserId(action));
+    }
+}
+/** `oxy.civic.validation` — a randomly selected juror's duties. */
+export class CivicValidationApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The signed-in user's pending jury duties. Never cached; `[]` when on no juries. */
+    async inbox() {
+        const res = await this.ctx.request('GET', '/civic/validations/inbox', undefined, {
+            cache: false,
+        });
+        return res.requests ?? [];
+    }
+    /**
+     * 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).
+     */
+    async vote(requestId, payloadHash, verdict) {
+        const envelope = await signOwnChainRecord(this.ctx, 'validation_verdict', { requestId, payloadHash, verdict }, { collection: VALIDATION_COLLECTION, rkey: requestId });
+        return this.ctx.request('POST', `/civic/validations/${encodeURIComponent(requestId)}/vote`, envelope, { cache: false });
+    }
+    /** Recuse from a validation request: the juror leaves the jury and it is re-tallied. */
+    async deny(requestId) {
+        return this.ctx.request('POST', `/civic/validations/${encodeURIComponent(requestId)}/deny`, undefined, { cache: false });
+    }
+}
+/** `oxy.civic.credentials` — verifiable credentials. */
+export class CivicCredentialsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * 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.
+     */
+    async issue(input) {
+        const types = input.types.includes(CREDENTIAL_BASE_TYPE) ? input.types : [CREDENTIAL_BASE_TYPE, ...input.types];
+        let expiresAtMs;
+        if (input.expiresAt !== undefined) {
+            const parsed = Date.parse(input.expiresAt);
+            if (Number.isNaN(parsed)) {
+                throw new Error('Invalid expiresAt — must be an ISO 8601 date string.');
+            }
+            expiresAtMs = parsed;
+        }
+        const record = {
+            about: input.holderDid,
+            types,
+            claims: input.claims,
+            ...(expiresAtMs !== undefined ? { expiresAt: expiresAtMs } : {}),
+        };
+        // A fresh crypto-random rkey: every credential is its own chain entry.
+        const { SignatureService } = await import('../crypto/internal.js');
+        const rkey = await SignatureService.generateChallenge();
+        const envelope = await signOwnChainRecord(this.ctx, 'credential', record, { collection: CREDENTIAL_COLLECTION, rkey });
+        const result = await this.ctx.request('POST', '/civic/credentials', envelope, { cache: false });
+        this.sweep();
+        return result;
+    }
+    /**
+     * 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).
+     */
+    async list(holderUserId, opts = {}) {
+        const holder = holderUserId ?? this.ctx.oxy.session.userId;
+        if (!holder) {
+            throw new Error('No authenticated user — cannot list credentials.');
+        }
+        const base = `/civic/credentials/${encodeURIComponent(holder)}`;
+        const url = opts.status ? `${base}?status=${encodeURIComponent(opts.status)}` : base;
+        return this.ctx.request('GET', url, undefined, { cache: true, cacheTTL: SHORT_TTL });
+    }
+    /**
+     * 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.
+     */
+    async verify(recordId) {
+        return this.ctx.request('GET', `/civic/credentials/by-record/${encodeURIComponent(recordId)}/verify`, undefined, { cache: true, cacheTTL: SHORT_TTL });
+    }
+    /**
+     * Revoke a credential the signed-in user issued.
+     *
+     * @param id - The credential's id (the projection row id, NOT the record id).
+     */
+    async revoke(id) {
+        const result = await this.ctx.request('POST', `/civic/credentials/${encodeURIComponent(id)}/revoke`, undefined, { cache: false });
+        this.sweep();
+        return result;
+    }
+    sweep() {
+        this.ctx.http.invalidateCache({ prefixes: [CREDENTIAL_CACHE_PREFIX] });
+    }
+}

package/dist/esm/api/contacts.js

@@ -0,0 +1,12 @@
+export class ContactsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * 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).
+     */
+    async discover(hashedEmails, hashedPhones) {
+        return this.ctx.request('POST', '/contacts/discover', { hashedEmails, hashedPhones }, { cache: false });
+    }
+}

package/dist/esm/api/devices.js

@@ -0,0 +1,346 @@
+/**
+ * `oxy.devices` — this user's devices, the sessions on them, their security
+ * activity, and device sign-in.
+ *
+ * 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, deviceJoinCodeResponseSchema, deviceJoinResponseSchema, deviceRegisterResponseSchema, deviceTokenMintResponseSchema, safeParseContract, } from '@oxy.so/contracts';
+import { logger } from '../logger/index.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
+/**
+ * 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 class AccountNotOnDeviceError extends Error {
+    constructor(accountId, cause) {
+        super(`account_not_on_device: ${accountId} is not a live account of this device session`);
+        this.accountId = accountId;
+        this.cause = cause;
+        this.name = 'AccountNotOnDeviceError';
+        /** HTTP status of the originating response; mirrors the ApiError shape. */
+        this.status = 401;
+    }
+}
+/**
+ * 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) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const { status, message } = error;
+    if (status !== 401) {
+        return false;
+    }
+    return typeof message === 'string' && message.includes('account_not_on_device');
+}
+/**
+ * The bridge calls share their transport rules with the mint: no bearer
+ * (`skipAuth`, so a 401 surfaces directly), one attempt, and never parked
+ * behind the request queue.
+ */
+async function bridgeRequest(ctx, url, body, schema) {
+    const res = await ctx.request('POST', url, body, {
+        cache: false,
+        skipAuth: true,
+        retry: false,
+        bypassQueue: true,
+    });
+    const parsed = safeParseContract(schema, res);
+    if (!parsed) {
+        throw new Error(`${url.slice(1)} returned an unexpected response shape`);
+    }
+    return parsed;
+}
+export class DevicesApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Get all devices for the current user
+     * @returns Array of user devices
+     */
+    async list() {
+        return this.ctx.request('GET', '/devices', undefined, {
+            cache: false, // Don't cache device list - always get fresh data
+        });
+    }
+    /**
+     * Remove a device
+     * @param deviceId - The device ID to remove
+     */
+    async remove(deviceId) {
+        await this.ctx.request('DELETE', `/devices/${deviceId}`, undefined, { cache: false });
+    }
+    /**
+     * 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
+     */
+    async sessions(sessionId) {
+        // Cache disabled by default to ensure fresh session data
+        return this.ctx.request('GET', `/session/device/sessions/${sessionId}`, undefined, {
+            cache: false, // Don't cache sessions - always get fresh data
+            deduplicate: true, // Deduplicate concurrent requests for same sessionId
+        });
+    }
+    /**
+     * 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
+     */
+    async logoutAll(sessionId, deviceId, excludeCurrent) {
+        const urlParams = {};
+        if (deviceId)
+            urlParams.deviceId = deviceId;
+        if (excludeCurrent)
+            urlParams.excludeCurrent = 'true';
+        return this.ctx.request('POST', `/session/device/logout-all/${sessionId}`, urlParams, { cache: false });
+    }
+    /**
+     * Update device name
+     * @param sessionId - The session ID
+     * @param deviceName - New device name
+     * @returns Updated device object
+     */
+    async rename(sessionId, deviceName) {
+        return this.ctx.request('PUT', `/session/device/name/${sessionId}`, { deviceName }, { cache: false });
+    }
+    /**
+     * Get security information
+     * @returns Security information object
+     */
+    async securityInfo() {
+        return this.ctx.request('GET', '/devices/security', undefined, {
+            cache: false,
+        });
+    }
+    /**
+     * 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
+     */
+    async securityActivity(limit, offset, eventType) {
+        const params = {};
+        if (limit !== undefined)
+            params.limit = limit;
+        if (offset !== undefined)
+            params.offset = offset;
+        if (eventType)
+            params.eventType = eventType;
+        // The API responds with the standard paginated envelope:
+        //   { data: SecurityActivity[], pagination: { total, limit, offset, hasMore } }
+        // SecurityActivityResponse is the flattened shape consumers expect.
+        const raw = await this.ctx.request('GET', '/security/activity', params, { cache: false });
+        const requestedLimit = typeof params.limit === 'number' ? params.limit : 0;
+        const requestedOffset = typeof params.offset === 'number' ? params.offset : 0;
+        return {
+            data: raw.data ?? [],
+            total: raw.pagination?.total ?? raw.data?.length ?? 0,
+            limit: raw.pagination?.limit ?? requestedLimit,
+            offset: raw.pagination?.offset ?? requestedOffset,
+            hasMore: raw.pagination?.hasMore ?? false,
+        };
+    }
+    /**
+     * Log private key exported event
+     * @param deviceId - Optional device ID for tracking
+     * @returns Promise that resolves when event is logged
+     */
+    async logPrivateKeyExported(deviceId) {
+        try {
+            await this.ctx.request('POST', '/security/activity/private-key-exported', { deviceId }, { cache: false });
+        }
+        catch (error) {
+            // Don't throw - logging failures shouldn't break user flow, but surface
+            // for monitoring via the shared logger sink.
+            logger.warn('[OxyServices] Failed to log private key exported event', { component: 'oxy.devices' }, error);
+        }
+    }
+    /**
+     * Log backup created event
+     * @param deviceId - Optional device ID for tracking
+     * @returns Promise that resolves when event is logged
+     */
+    async logBackupCreated(deviceId) {
+        try {
+            await this.ctx.request('POST', '/security/activity/backup-created', { deviceId }, { cache: false });
+        }
+        catch (error) {
+            // Don't throw - logging failures shouldn't break user flow, but surface
+            // for monitoring via the shared logger sink.
+            logger.warn('[OxyServices] Failed to log backup created event', { component: 'oxy.devices' }, error);
+        }
+    }
+    /**
+     * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
+     * `POST /session/device/token` — NO bearer, NO cookies: possession of the
+     * secret IS the device-ownership proof. Returns a fresh short access token
+     * for the device's active account plus `nextDeviceSecret` (on mint, the same
+     * proven secret echoed back — rotation happens on sign-in, not mint) and
+     * the projected device-session `state`.
+     *
+     * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
+     * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-
+     * mint handler read the 401 body (`invalid_device_secret` vs
+     * `no_active_session`) to decide whether to drop the secret and fall back or
+     * resolve signed-out.
+     *
+     * `retry: false`: the mint is a single logical attempt. The proactive
+     * token-refresh scheduler and the reactive 401 lane already own backoff and
+     * re-arm, so `HttpService`'s inner retry loop here would only multiply the
+     * mint's latency on a slow/black-hole network (3 retries × 5s timeout ≈ 20s
+     * per lane) with no correctness benefit — it is the dominant term in the cold
+     * 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}.
+     */
+    async mintToken(deviceId, deviceSecret, options) {
+        const accountId = options?.accountId;
+        try {
+            const res = await this.ctx.request('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) {
+            if (accountId && isAccountNotOnDevice(error)) {
+                throw new AccountNotOnDeviceError(accountId, error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * `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}.
+     */
+    async registerBrowser() {
+        return bridgeRequest(this.ctx, '/session/device/register', {}, deviceRegisterResponseSchema);
+    }
+    /**
+     * `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`.
+     */
+    async requestJoinCode(request) {
+        return bridgeRequest(this.ctx, '/session/device/join-code', request, deviceJoinCodeResponseSchema);
+    }
+    /**
+     * `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.
+     */
+    async joinBrowser(request) {
+        return bridgeRequest(this.ctx, '/session/device/join', request, deviceJoinResponseSchema);
+    }
+    /**
+     * Provision a NON-rotating background credential for the caller's account on
+     * this device — the credential native background code (an Android widget
+     * worker, which runs with no JS runtime) presents to mint its own access
+     * tokens without any JS involvement.
+     *
+     * It exists precisely so background code never touches the device secret:
+     * `POST /session/device/token` ROTATES that secret on every mint (the
+     * presented one stays valid only for a short grace), so a worker minting
+     * from it would become a second writer of the value JS depends on and could
+     * silently sign the user out. The background credential is a separate,
+     * non-rotating value minted server-side, so the two lanes never contend.
+     *
+     * Bearer required and NO body: the server derives both the `deviceId` and
+     * the account from the validated bearer. This is the only way a background
+     * credential comes into existence, so background code can EXTEND a session
+     * the user established in-app but can never bootstrap one from nothing.
+     *
+     * Unlike the mint above this is NOT a control-plane call — it runs while a
+     * session is already live — so it takes the normal authenticated path: no
+     * `skipAuth` (a 401 should go through the ordinary re-mint lane) and no
+     * `bypassQueue` (nothing in the auth lane is parked awaiting it).
+     *
+     * There is deliberately no JS counterpart that MINTS from the returned
+     * credential: the native side owns that call, and a symmetric-looking JS
+     * method would be dead code plus a second implementation of the failure
+     * rules. The asymmetry is the design.
+     *
+     * **Call this from NATIVE only.** There is no background worker on web to
+     * consume the credential, and handing a browser origin a long-lived
+     * non-rotating secret to persist is strictly weaker than the rotating device
+     * secret it already holds. The 404 degrade below is also native-shaped: a
+     * browser attaches `Origin`, which a server predating this route answers
+     * `403 BAD_ORIGIN` from its router-wide same-site guard rather than 404, so
+     * the quiet degrade would not fire there. A native client sends no `Origin`
+     * and gets the 404. Gate the caller by platform; do not widen the degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
+     *
+     * That paragraph is LOAD-BEARING, not belt-and-braces: the route sits above
+     * oxy-api's router-wide origin guard (deliberately, so a native client with
+     * no `Origin` is not rejected). oxy-api additionally refuses callers that
+     * carry browser context signals (`Origin` or `Sec-Fetch-Site`) with
+     * `403 browser_not_allowed` — native HTTP clients send neither. Gate the
+     * caller by platform on the client as well; do not widen the 404 degrade to
+     * 403, which would also swallow a genuine origin misconfiguration.
+     *
+     * @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.
+     * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
+     */
+    async provisionBackgroundCredential() {
+        try {
+            const res = await this.ctx.request('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 error;
+        }
+    }
+}