@oxy.so/core 1.0.0

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

@@ -0,0 +1,169 @@
+/**
+ * Connected Apps (OAuth consent) Methods Mixin
+ *
+ * The user-facing OAuth-consent surface: resolving the PUBLIC identity of a
+ * requesting application (for consent/authorize/device-flow screens), and
+ * viewing/revoking the THIRD-PARTY applications the current user has authorized.
+ *
+ * This is deliberately separate from account ownership (`OxyServices.accounts.ts`):
+ * an account owns and manages its own applications, whereas this mixin is about a
+ * user granting/revoking another party's app access to their own data. None of
+ * these methods touch the account graph.
+ *
+ * Reference connected apps by their application `_id` (`applicationId`), NOT a
+ * credential/client id, so a grant — and its revocation — survive credential
+ * rotation.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { ApplicationType } from './OxyServices.accounts';
+/**
+ * Sanitized, PUBLIC application identity returned by the API when resolving a
+ * cross-app/OAuth client to a registered application.
+ *
+ * This shape carries NO sensitive or membership fields — it is safe to display
+ * unauthenticated in consent/authorize screens and device-flow approval UIs. The
+ * API resolves a `client_id` (OAuth credential public key) to the owning
+ * application and projects only the fields below. `id` is the application's
+ * `_id` as a string.
+ */
+export interface PublicApplication {
+    /** The application's Mongo `_id` as a string. */
+    id: string;
+    /** Human-readable application name shown to the user. */
+    name: string;
+    /** Optional short description of what the application does. */
+    description?: string;
+    /** Optional icon URL for the application. */
+    icon?: string;
+    /** Optional public website/homepage URL for the application. */
+    websiteUrl?: string;
+    /** Optional public privacy-policy URL, rendered as a legal link on the consent screen. */
+    privacyPolicyUrl?: string;
+    /** Optional public terms-of-service URL, rendered as a legal link on the consent screen. */
+    termsUrl?: string;
+    /** Application classification (set by Oxy platform staff). */
+    type: ApplicationType;
+    /** Whether the application is an officially endorsed Oxy application. */
+    isOfficial: boolean;
+    /** Whether the application is an internal Oxy ecosystem application. */
+    isInternal: boolean;
+    /** OAuth scopes the application is configured to request. */
+    scopes: string[];
+    /** Optional display name of the developer/owner organisation. */
+    developerName?: string;
+}
+/**
+ * A connected (OAuth-authorized) application from the current user's point of
+ * view: an application the user has granted access to via the consent flow.
+ *
+ * Returned by `GET /auth/grants` and rendered in the user-facing "Connected
+ * apps" management surface. Keyed by `applicationId` (the application's Mongo
+ * `_id`) rather than a credential/client id, so the grant — and a subsequent
+ * {@link OxyServicesConnectedAppsMixin.revokeAppGrant} — survive credential
+ * rotation. This is a display shape: it carries the application's name/logo and
+ * the granted scopes, never any membership or credential material.
+ */
+export interface ConnectedApp {
+    /** The connected application's Mongo `_id`. Use this to revoke the grant. */
+    applicationId: string;
+    /** Human-readable application name shown to the user. */
+    name: string;
+    /** Optional logo URL for the application. */
+    logoUrl?: string;
+    /** OAuth scopes the user has granted to the application. */
+    scopes: string[];
+    /** ISO timestamp of when the user first authorized the application. */
+    firstGrantedAt: string;
+    /** ISO timestamp of when the grant was last exercised. */
+    lastUsedAt: string;
+}
+export declare function OxyServicesConnectedAppsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Resolve an OAuth client identifier to the owning application's PUBLIC
+         * identity. No authentication required — the API returns only sanitized,
+         * display-safe metadata ({@link PublicApplication}). Use this to render the
+         * requesting application's name/icon in consent, authorize, and device-flow
+         * approval UIs before any session exists.
+         *
+         * @param clientId - The OAuth `client_id` (an active credential's public
+         *   key). URL-encoded before being placed in the path.
+         */
+        getPublicApplication(clientId: string): Promise<PublicApplication>;
+        /**
+         * List the OAuth-authorized applications the current user has connected —
+         * the third-party apps the user granted access to via the consent flow.
+         * Each entry is a {@link ConnectedApp} carrying the application's display
+         * identity, the granted scopes, and when the grant was first made and last
+         * exercised. Requires an authenticated session.
+         *
+         * Backed by `GET /auth/grants`. The response is briefly cached
+         * (identity-scoped); {@link revokeAppGrant} busts that cache so a revoke is
+         * reflected on the next read.
+         */
+        listConnectedApps(): Promise<ConnectedApp[]>;
+        /**
+         * Revoke the current user's grant for a connected application, identified by
+         * its application `_id` (a {@link ConnectedApp.applicationId}, NOT a
+         * credential/client id — keyed by application so the revocation survives
+         * credential rotation). After this the application can no longer act on the
+         * user's behalf until it is re-authorized.
+         *
+         * Backed by `DELETE /auth/grants/:applicationId`. On success the cached
+         * connected-apps list (`GET:/auth/grants`) is invalidated so the next
+         * {@link listConnectedApps} read reflects the removal.
+         *
+         * @param applicationId - The connected application's Mongo `_id`.
+         */
+        revokeAppGrant(applicationId: string): Promise<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;
+        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;
+        getAccessTokenExpiry(): number | 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.contacts.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Contact Discovery Mixin
+ *
+ * Privacy-preserving discovery of which address-book contacts are on Oxy.
+ *
+ * The client hashes emails and phones locally before calling the API.
+ * The server responds with only Oxy user IDs and the hashes that matched,
+ * so the consumer can map each match back to the local contact that
+ * produced it.
+ *
+ * Hashing rules (must match the server `utils/contactHash.ts` exactly):
+ *   - SHA-256, hex-encoded, lowercase
+ *   - Email: `value.trim().toLowerCase()` then digest
+ *   - Phone: trim → keep a single leading "+" → strip non-digits → prepend "+"
+ *     if missing → digest
+ *
+ * Mobile clients can compute these digests with `expo-crypto`'s
+ * `digestStringAsync(SHA256, value, { encoding: HEX })`. Web clients should
+ * use `SubtleCrypto.digest('SHA-256', ...)`.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/** A single match returned by `POST /contacts/discover`. */
+export interface ContactDiscoveryMatch {
+    /** Oxy user ID (MongoDB ObjectId hex string). */
+    userId: string;
+    /** The hashed identifier from the request that matched this user. */
+    hashedIdentifier: string;
+    /** Whether the match came from the email index or phone index. */
+    matchType: 'email' | 'phone';
+}
+/** Response shape of `POST /contacts/discover`. */
+export interface ContactDiscoveryResponse {
+    matches: ContactDiscoveryMatch[];
+}
+export declare function OxyServicesContactsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Discover which of the caller's contacts are on Oxy.
+         *
+         * @param hashedEmails - SHA-256 hex digests of normalized emails.
+         * @param hashedPhones - SHA-256 hex digests of normalized phone numbers.
+         * @returns Matches mapping each hashed identifier to the Oxy user ID it
+         *   resolved to. Empty arrays are valid for either parameter, but at
+         *   least one must be non-empty.
+         *
+         * The server enforces a 200-hash cap per channel per request — callers
+         * should batch larger address books client-side.
+         */
+        discoverContacts(hashedEmails: string[], hashedPhones: string[]): Promise<ContactDiscoveryResponse>;
+        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;
+        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;
+        getAccessTokenExpiry(): number | 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.deviceBoot.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Device-first token mint mixin.
+ *
+ * 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.
+ */
+import { type DeviceBackgroundCredentialResponse, type DeviceTokenMintResponse } from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * The server's `401 account_not_on_device` for a PINNED mint: the requested
+ * `accountId` is not (or is no longer) a live account of this device session.
+ *
+ * Distinguished from every other mint 401 because the remedy is different: the
+ * device secret is FINE — it is the identity binding that went stale (the
+ * account was signed out on this device, or revoked). An identity-bound caller
+ * must re-establish its session from the local key rather than drop/clear the
+ * device credential.
+ */
+export declare class AccountNotOnDeviceError extends Error {
+    readonly accountId: string;
+    readonly cause?: unknown | undefined;
+    readonly name = "AccountNotOnDeviceError";
+    /** HTTP status of the originating response; mirrors the ApiError shape. */
+    readonly status = 401;
+    constructor(accountId: string, cause?: unknown | undefined);
+}
+export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * 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}.
+         */
+        mintFromDeviceSecret(deviceId: string, deviceSecret: string, options?: {
+            accountId?: string;
+        }): Promise<DeviceTokenMintResponse>;
+        /**
+         * 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. The status is read off the RAW rejection because
+         * `handleError` only preserves it for errors carrying `HttpService`'s
+         * annotations.
+         * @throws if the response does not match {@link deviceBackgroundCredentialResponseSchema}.
+         */
+        provisionBackgroundCredential(): Promise<DeviceBackgroundCredentialResponse | null>;
+        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;
+        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;
+        getAccessTokenExpiry(): number | 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.deviceTransfer.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Device-to-device Identity Transfer Mixin (b3 Feature 2 — "add a device")
+ *
+ * Clones an existing device's secp256k1 identity onto a fresh device over a
+ * short-lived, unauthenticated relay, WITHOUT the server ever holding a
+ * decryption key. Both devices end up holding the SAME private key.
+ *
+ * The two devices agree on a symmetric key via an ephemeral secp256k1 ECDH
+ * handshake (Phase-0 crypto): `deriveSharedSecret` → `hkdfSha256` → a per-pairing
+ * transfer key, used with `encryptAead`/`decryptAead` (XChaCha20-Poly1305) to
+ * seal `{ privateKey, publicKey }`. The relay carries only ephemeral public keys
+ * plus opaque ciphertext — a passive/at-rest-compromised backend cannot decrypt.
+ *
+ * Roles:
+ *  - NEW device (no identity): {@link initDeviceTransfer} (generate ephemeral
+ *    pair, register the pairing, render `pairingId` as a QR) then
+ *    {@link subscribeDeviceTransfer} (await approval over the `/device-pair`
+ *    socket with a poll fallback, decrypt, and import the key).
+ *  - OLD device (has identity): {@link getDeviceTransferInfo} (resolve the
+ *    scanned `pairingId` server-side — the QR is NOT self-contained) then
+ *    {@link approveDeviceTransfer} (biometric-gate in the UI, seal the key
+ *    material, and post it with a fresh signature over the CURRENT identity key).
+ *
+ * SECURITY: E2E against a passive relay only. Explicitly NOT hardened against an
+ * actively-malicious backend MITM'ing the ephemeral keys (same trust boundary as
+ * the existing QR sign-in; SAS compare deferred per owner decision). Approve
+ * requires BOTH a bearer token AND a fresh identity-key signature.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import type { DeviceTransferInfoResponse, DeviceTransferApproveResponse, DeviceTransferDenyResponse } from '@oxy.so/contracts';
+/** Result of {@link OxyServicesDeviceTransferMixin.initDeviceTransfer}. */
+export interface InitDeviceTransferResult {
+    /** 128-bit single-use handle to render in the QR (also the HKDF salt). */
+    pairingId: string;
+    /** ISO-8601 expiry (3 minutes). */
+    expiresAt: string;
+    /** The new device's ephemeral public key registered with the relay. */
+    newEphemeralPublicKey: string;
+}
+/** Terminal outcome delivered to {@link subscribeDeviceTransfer}'s callback. */
+export type DeviceTransferOutcome = {
+    status: 'approved';
+    publicKey: string;
+} | {
+    status: 'denied';
+} | {
+    status: 'expired';
+};
+export declare function OxyServicesDeviceTransferMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * NEW device — begin an "add a device" transfer. Generates a single-use
+         * ephemeral secp256k1 pair, registers the pairing, and returns the
+         * `pairingId` to render as a QR. The ephemeral private key is held in memory
+         * (keyed by `pairingId`) for the subsequent {@link subscribeDeviceTransfer}.
+         *
+         * @param label - Optional human-readable label for this new device.
+         */
+        initDeviceTransfer(label?: string): Promise<InitDeviceTransferResult>;
+        /**
+         * Resolve a pairing server-side (the QR carries only `pairingId`). The OLD
+         * device calls this after scanning to read the new device's ephemeral public
+         * key + label; the NEW device polls it to fetch the sealed material once
+         * approved. Public — no auth required.
+         */
+        getDeviceTransferInfo(pairingId: string): Promise<DeviceTransferInfoResponse>;
+        /**
+         * OLD device — approve a scanned transfer. Reads the new device's ephemeral
+         * public key, derives the shared transfer key, AEAD-seals
+         * `{ privateKey, publicKey }`, and posts it PLUS a fresh signature over
+         * `{ action:'approve_device_transfer', pairingId, timestamp }` made with the
+         * CURRENT identity key (dual-proof alongside the bearer token).
+         *
+         * NATIVE-ONLY: requires a stored identity (throws otherwise). The UI must
+         * biometric-gate before calling this — a key clone leaves the device.
+         */
+        approveDeviceTransfer(pairingId: string): Promise<DeviceTransferApproveResponse>;
+        /**
+         * OLD device — deny (cancel) a scanned transfer so the waiting new device
+         * stops. Public — no auth required.
+         */
+        denyDeviceTransfer(pairingId: string): Promise<DeviceTransferDenyResponse>;
+        /**
+         * NEW device — await approval for a pairing started with
+         * {@link initDeviceTransfer}, then decrypt and import the transferred
+         * identity key. Primary path is an instant `device_pair_update` push over the
+         * `/device-pair` socket; a poll backstops a socket that can't connect.
+         *
+         * On `approved`: re-derives the shared transfer key from the old device's
+         * ephemeral public key, decrypts `{ privateKey, publicKey }`, imports it via
+         * `KeyManager.importKeyPair(privateKey, { overwrite: false })`, and invokes
+         * `onOutcome({ status:'approved', publicKey })`. The caller then runs the
+         * NORMAL challenge/verify sign-in — this method does not mint a session.
+         *
+         * @returns An unsubscribe function; call it to stop waiting (also called
+         *   automatically once the transfer settles).
+         */
+        subscribeDeviceTransfer(pairingId: string, onOutcome: (outcome: DeviceTransferOutcome) => void): () => 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;
+        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;
+        getAccessTokenExpiry(): number | 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;