@oxy.so/contracts 1.0.0

package/dist/types/devicePairing.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Device-to-device identity transfer contracts (b3 Feature 2 — "add a device").
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the short-lived, unauthenticated
+ * relay that carries E2E-encrypted key material from an existing (old) device to
+ * a fresh (new) device so both end up holding the SAME secp256k1 private key
+ * (key cloning). The relay is E2E-encrypted via an ephemeral secp256k1 ECDH
+ * handshake: the server stores only the two ephemeral public keys plus an opaque
+ * AEAD ciphertext + nonce and NEVER holds a decryption key.
+ *
+ * Flow:
+ *  1. New device (no identity) generates an ephemeral pair and calls
+ *     `POST /identity/device-transfer/init { newEphPub, newDeviceLabel? }` →
+ *     `{ pairingId, expiresAt }`. The QR carries ONLY `pairingId` (not
+ *     self-contained — mirrors the QR sign-in `approve-info` resolution).
+ *  2. Old device (has identity) scans, resolves the request via
+ *     `GET /identity/device-transfer/:pairingId` (returns `newEphPub` + label),
+ *     derives `transferKey = HKDF(ECDH(oldEphPriv, newEphPub), pairingId,
+ *     'oxy-device-transfer-v1')`, AEAD-encrypts `{ privateKey, publicKey }`, and
+ *     calls `POST /identity/device-transfer/:pairingId/approve` with the
+ *     ciphertext PLUS a fresh signature over
+ *     `{ action:'approve_device_transfer', pairingId, timestamp }` made with the
+ *     CURRENT identity key (dual-proof: a bearer alone cannot exfiltrate the key).
+ *  3. New device (socket push or poll fallback) re-derives the same
+ *     `transferKey` from `ECDH(newEphPriv, oldEphPub)`, decrypts, and imports the
+ *     private key, then completes a NORMAL challenge/verify sign-in.
+ *
+ * The load-bearing response shapes are declared as explicit `interface`s (same
+ * `moduleResolution: node` rationale as `UserNameResponse` / the identity/civic
+ * contracts: a nested `z.infer<>` can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"`), with the runtime schemas annotated
+ * `z.ZodType<Interface>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+/**
+ * Pairing lifecycle:
+ *  - `pending`  — created by the new device, awaiting the old device's approval.
+ *  - `approved` — the old device sealed and posted the encrypted key material.
+ *  - `denied`   — the old device explicitly cancelled the transfer.
+ *  - `expired`  — the 3-minute TTL elapsed before approval.
+ */
+export declare const devicePairingStatusSchema: z.ZodEnum<["pending", "approved", "denied", "expired"]>;
+export type DevicePairingStatus = z.infer<typeof devicePairingStatusSchema>;
+/** Request body for `POST /identity/device-transfer/init` (public). */
+export declare const deviceTransferInitRequestSchema: z.ZodObject<{
+    /** The new device's ephemeral secp256k1 public key (single-use). */
+    newEphPub: z.ZodString;
+    /** Optional human-readable label for the new device (e.g. "iPhone 15"). */
+    newDeviceLabel: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    newEphPub: string;
+    newDeviceLabel?: string | undefined;
+}, {
+    newEphPub: string;
+    newDeviceLabel?: string | undefined;
+}>;
+export type DeviceTransferInitRequest = z.infer<typeof deviceTransferInitRequestSchema>;
+export interface DeviceTransferInitResponse {
+    /** 128-bit single-use handle carried in the QR. Also the HKDF salt. */
+    pairingId: string;
+    /** ISO-8601 expiry (3 minutes from creation). */
+    expiresAt: string;
+}
+export declare const deviceTransferInitResponseSchema: z.ZodType<DeviceTransferInitResponse>;
+export interface DeviceTransferInfoResponse {
+    pairingId: string;
+    /** The new device's ephemeral public key (so the old device can ECDH). */
+    newDeviceEphemeralPublicKey: string;
+    /** Optional new-device label supplied at init. */
+    newDeviceLabel: string | null;
+    status: DevicePairingStatus;
+    /** ISO-8601 expiry. */
+    expiresAt: string;
+    /**
+     * The old device's ephemeral public key — present ONLY once `status` is
+     * `approved` (so the new device can re-derive the shared secret).
+     */
+    oldDeviceEphemeralPublicKey: string | null;
+    /** AEAD ciphertext (hex) — present ONLY once `status` is `approved`. */
+    ciphertext: string | null;
+    /** AEAD nonce (hex) — present ONLY once `status` is `approved`. */
+    nonce: string | null;
+}
+export declare const deviceTransferInfoResponseSchema: z.ZodType<DeviceTransferInfoResponse>;
+/**
+ * Request body for `POST /identity/device-transfer/:pairingId/approve`
+ * (bearer-authenticated AND signature-proven). The `signature` covers
+ * `JSON.stringify({ action:'approve_device_transfer', pairingId, timestamp })`
+ * made with the caller's CURRENT identity key — dual-proof so a bearer token
+ * alone can never exfiltrate the private key.
+ */
+export declare const deviceTransferApproveRequestSchema: z.ZodObject<{
+    /** The old device's ephemeral secp256k1 public key (single-use). */
+    oldEphPub: z.ZodString;
+    /** AEAD ciphertext of `{ privateKey, publicKey }`, hex. */
+    ciphertext: z.ZodString;
+    /** AEAD nonce, hex (24 bytes). */
+    nonce: z.ZodString;
+    /** ECDSA (DER, hex) signature proving control of the CURRENT identity key. */
+    signature: z.ZodString;
+    /** Signing timestamp (ms since epoch) — freshness-checked server-side. */
+    timestamp: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    nonce: string;
+    ciphertext: string;
+    oldEphPub: string;
+    timestamp: number;
+}, {
+    signature: string;
+    nonce: string;
+    ciphertext: string;
+    oldEphPub: string;
+    timestamp: number;
+}>;
+export type DeviceTransferApproveRequest = z.infer<typeof deviceTransferApproveRequestSchema>;
+export interface DeviceTransferApproveResponse {
+    success: boolean;
+    pairingId: string;
+    status: DevicePairingStatus;
+}
+export declare const deviceTransferApproveResponseSchema: z.ZodType<DeviceTransferApproveResponse>;
+export interface DeviceTransferDenyResponse {
+    success: boolean;
+    pairingId: string;
+    status: DevicePairingStatus;
+}
+export declare const deviceTransferDenyResponseSchema: z.ZodType<DeviceTransferDenyResponse>;

package/dist/types/deviceSession.d.ts

@@ -0,0 +1,411 @@
+import { z } from 'zod';
+export declare const sessionAccountSchema: z.ZodObject<{
+    accountId: z.ZodString;
+    sessionId: z.ZodString;
+    authuser: z.ZodNumber;
+    operatedByUserId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    accountId: string;
+    sessionId: string;
+    authuser: number;
+    operatedByUserId?: string | undefined;
+}, {
+    accountId: string;
+    sessionId: string;
+    authuser: number;
+    operatedByUserId?: string | undefined;
+}>;
+export declare const deviceSessionStateSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    accounts: z.ZodArray<z.ZodObject<{
+        accountId: z.ZodString;
+        sessionId: z.ZodString;
+        authuser: z.ZodNumber;
+        operatedByUserId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        accountId: string;
+        sessionId: string;
+        authuser: number;
+        operatedByUserId?: string | undefined;
+    }, {
+        accountId: string;
+        sessionId: string;
+        authuser: number;
+        operatedByUserId?: string | undefined;
+    }>, "many">;
+    activeAccountId: z.ZodNullable<z.ZodString>;
+    revision: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: number;
+    deviceId: string;
+    accounts: {
+        accountId: string;
+        sessionId: string;
+        authuser: number;
+        operatedByUserId?: string | undefined;
+    }[];
+    activeAccountId: string | null;
+    revision: number;
+}, {
+    updatedAt: number;
+    deviceId: string;
+    accounts: {
+        accountId: string;
+        sessionId: string;
+        authuser: number;
+        operatedByUserId?: string | undefined;
+    }[];
+    activeAccountId: string | null;
+    revision: number;
+}>;
+export declare const activeTokenSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    accessToken: string;
+}, {
+    expiresAt: string;
+    accessToken: string;
+}>;
+export declare const deviceSessionSyncSchema: z.ZodObject<{
+    state: z.ZodObject<{
+        deviceId: z.ZodString;
+        accounts: z.ZodArray<z.ZodObject<{
+            accountId: z.ZodString;
+            sessionId: z.ZodString;
+            authuser: z.ZodNumber;
+            operatedByUserId: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }, {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }>, "many">;
+        activeAccountId: z.ZodNullable<z.ZodString>;
+        revision: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    }, {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    }>;
+    activeToken: z.ZodNullable<z.ZodObject<{
+        accessToken: z.ZodString;
+        expiresAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        expiresAt: string;
+        accessToken: string;
+    }, {
+        expiresAt: string;
+        accessToken: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    state: {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    };
+    activeToken: {
+        expiresAt: string;
+        accessToken: string;
+    } | null;
+}, {
+    state: {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    };
+    activeToken: {
+        expiresAt: string;
+        accessToken: string;
+    } | null;
+}>;
+export type SessionAccount = z.infer<typeof sessionAccountSchema>;
+export type DeviceSessionState = z.infer<typeof deviceSessionStateSchema>;
+export type ActiveToken = z.infer<typeof activeTokenSchema>;
+export type DeviceSessionSync = z.infer<typeof deviceSessionSyncSchema>;
+/**
+ * Request body for `POST /session/device/token` — the client presents the
+ * `deviceId` it stored first-party plus the opaque `deviceSecret`. NO bearer:
+ * possession of the secret IS the proof of device ownership. The server matches
+ * `sha256(deviceSecret)` against the device's stored `secretHash` (constant-time)
+ * and mints a short access token for the device's active account.
+ *
+ * `accountId` pins the mint to ONE account of that device instead of whichever
+ * account is currently active. It exists for identity-bound clients (Commons),
+ * whose authenticated user is determined by a local cryptographic key and must
+ * never follow an account switch made by another app on the same device. The
+ * account must already be a member of the device session; the mint NEVER
+ * mutates `activeAccountId`, so pinning is read-only with respect to the device
+ * state every other app observes.
+ */
+export declare const deviceTokenMintRequestSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+    accountId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+    accountId?: string | undefined;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+    accountId?: string | undefined;
+}>;
+/**
+ * Wire shape of a successful `POST /session/device/token`: the freshly-minted
+ * short access token for the active account, its expiry, the device secret the
+ * client must persist (`nextDeviceSecret` — on mint this echoes the presented
+ * secret unchanged so concurrent refreshes from multiple origins do not race),
+ * and the projected device-session state. Sign-in rotates the secret via
+ * `issueDeviceSecret`; mint does not.
+ */
+export declare const deviceTokenMintResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodString;
+    nextDeviceSecret: z.ZodString;
+    state: z.ZodObject<{
+        deviceId: z.ZodString;
+        accounts: z.ZodArray<z.ZodObject<{
+            accountId: z.ZodString;
+            sessionId: z.ZodString;
+            authuser: z.ZodNumber;
+            operatedByUserId: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }, {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }>, "many">;
+        activeAccountId: z.ZodNullable<z.ZodString>;
+        revision: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    }, {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    accessToken: string;
+    state: {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    };
+    nextDeviceSecret: string;
+}, {
+    expiresAt: string;
+    accessToken: string;
+    state: {
+        updatedAt: number;
+        deviceId: string;
+        accounts: {
+            accountId: string;
+            sessionId: string;
+            authuser: number;
+            operatedByUserId?: string | undefined;
+        }[];
+        activeAccountId: string | null;
+        revision: number;
+    };
+    nextDeviceSecret: string;
+}>;
+export type DeviceTokenMintRequest = z.infer<typeof deviceTokenMintRequestSchema>;
+export type DeviceTokenMintResponse = z.infer<typeof deviceTokenMintResponseSchema>;
+/**
+ * Name of the token-free Socket.IO event emitted to room `user:<userId>` on
+ * every DeviceSession mutation that changes what is signed in for that user.
+ *
+ * This is a pure SIGNAL — it carries NO access token, NO deviceSecret and NO
+ * account bodies. A client that receives it re-fetches its authenticated
+ * session/account state (`GET /session/device/state`, `GET /accounts`). Unlike
+ * `session_state` (scoped to `device:<deviceId>`, i.e. a single origin), this
+ * reaches ALL of a user's connected sockets across their devices/origins so
+ * every Oxy app reflects an add / switch / signout instantly.
+ */
+export declare const SESSION_ACCOUNTS_CHANGED_EVENT = "session_accounts_changed";
+/**
+ * Why the signed-in set changed:
+ *  - `login`   — a brand-new session was minted for the user (QR / cross-app authorize)
+ *  - `add`     — an account was registered onto a device set
+ *  - `switch`  — the active account on a device changed
+ *  - `signout` — one or all accounts were signed out of a device
+ *  - `revoke`  — a dead/revoked account was healed out of a device set
+ */
+export declare const sessionAccountsChangedReasonSchema: z.ZodEnum<["login", "add", "switch", "signout", "revoke"]>;
+/**
+ * Payload of {@link SESSION_ACCOUNTS_CHANGED_EVENT}. `revision` is the mutated
+ * DeviceSession revision for device-scoped reasons (`add`/`switch`/`signout`/
+ * `revoke`); for `login` (no device mutation at emit time) it is `0`. The
+ * payload is deliberately minimal and secret-free — the client refetches.
+ */
+export declare const sessionAccountsChangedEventSchema: z.ZodObject<{
+    userId: z.ZodString;
+    revision: z.ZodNumber;
+    reason: z.ZodEnum<["login", "add", "switch", "signout", "revoke"]>;
+}, "strip", z.ZodTypeAny, {
+    reason: "login" | "add" | "switch" | "signout" | "revoke";
+    revision: number;
+    userId: string;
+}, {
+    reason: "login" | "add" | "switch" | "signout" | "revoke";
+    revision: number;
+    userId: string;
+}>;
+export type SessionAccountsChangedReason = z.infer<typeof sessionAccountsChangedReasonSchema>;
+export type SessionAccountsChangedEvent = z.infer<typeof sessionAccountsChangedEventSchema>;
+/**
+ * Response from `POST /session/device/background-credential` — provisioned by
+ * the SDK WHILE THE APP IS RUNNING (bearer required, `deviceId` and account
+ * derived server-side from it) and consumed afterwards only by native
+ * background code, which has no JS runtime to mint a token for itself.
+ *
+ * Deliberately a SEPARATE credential from the rotating `deviceSecret`: that one
+ * rotates on every mint, so background code presenting it would become a second
+ * writer of a value the JS runtime depends on, and background code killed
+ * mid-rotation would silently sign the user out on the next cold start. Against
+ * this credential background code is the sole writer, and it can never rotate
+ * anything JS reads.
+ *
+ * The raw `secret` is returned exactly once, at provision time — never stored
+ * retrievably, never logged, never re-read. A caller that loses it provisions
+ * a new one.
+ *
+ * `expiresAt` is an unvalidated string, like every other expiry in this file:
+ * no consumer on the JS path interprets it (native background code parses it
+ * itself), and a `.datetime()` here alone would leave one strict field beside
+ * two lax ones. If expiry is ever validated it goes on all three at once, with
+ * the API's serializers checked against it — the producer is the same server.
+ */
+export declare const deviceBackgroundCredentialResponseSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    secret: z.ZodString;
+    accountId: z.ZodString;
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    accountId: string;
+    expiresAt: string;
+    deviceId: string;
+    secret: string;
+}, {
+    accountId: string;
+    expiresAt: string;
+    deviceId: string;
+    secret: string;
+}>;
+/**
+ * Request body for `POST /session/device/background-token` — presented by
+ * native background code with NO bearer and NO cookies: possession of the
+ * background `secret` IS the proof, as it is for the device-secret mint.
+ *
+ * Unlike that mint this one NEVER rotates the presented secret (hence no
+ * `next…` field to persist in the response), so background code interrupted
+ * anywhere between request and response leaves the credential intact and
+ * usable on its next run.
+ */
+export declare const deviceBackgroundTokenRequestSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    secret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    secret: string;
+}, {
+    deviceId: string;
+    secret: string;
+}>;
+/**
+ * Wire shape of a successful `POST /session/device/background-token`: the short
+ * access token, its expiry, and the account the token belongs to — the last so
+ * a caller can key cached data per account and drop data belonging to a
+ * foreign one.
+ *
+ * Carries NO device state — no account list, no `activeAccountId`, no
+ * `revision`, unlike {@link deviceTokenMintResponseSchema} — deliberately, to
+ * cap what a compromised credential record yields.
+ */
+export declare const deviceBackgroundTokenResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresAt: z.ZodString;
+    accountId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    accountId: string;
+    expiresAt: string;
+    accessToken: string;
+}, {
+    accountId: string;
+    expiresAt: string;
+    accessToken: string;
+}>;
+export type DeviceBackgroundCredentialResponse = z.infer<typeof deviceBackgroundCredentialResponseSchema>;
+export type DeviceBackgroundTokenRequest = z.infer<typeof deviceBackgroundTokenRequestSchema>;
+export type DeviceBackgroundTokenResponse = z.infer<typeof deviceBackgroundTokenResponseSchema>;