@oxyhq/contracts 0.16.0 → 0.18.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

@@ -169,16 +169,27 @@ export type DeviceSessionSync = z.infer<typeof deviceSessionSyncSchema>;
  * 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

package/dist/types/index.d.ts

@@ -11,8 +11,8 @@
  */
 export { ORGANIZATION_CATEGORIES, organizationCategorySchema, createAccountRequestSchema, } from './accountGraph';
 export type { OrganizationCategory, CreateAccountRequest, } from './accountGraph';
-export { userNameSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, resolveUserId, safeParseContract, } from './userResponse';
-export type { UserNameResponse, UserResponse, UserProfileUpdate, CurrentUserResponseContract, DeviceLinkedSessionResponse, DeviceLinkedSessionsResponseContract, } from './userResponse';
+export { userNameSchema, userRelationshipSchema, themePreferenceSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, resolveUserId, safeParseContract, } from './userResponse';
+export type { UserNameResponse, UserRelationship, ThemePreference, UserResponse, UserProfileUpdate, CurrentUserResponseContract, DeviceLinkedSessionResponse, DeviceLinkedSessionsResponseContract, } from './userResponse';
 export { applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus';
 export type { ApplicationTypeContract, PublicApplicationResponse, SessionStatusResponse, } from './sessionStatus';
 export { recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations';
@@ -39,3 +39,7 @@ export { updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha2
 export type { UpdatePlatform, UpdateStatus, UpdateAssetStatus, AssetInitItem, AssetInitRequest, AssetUploadTicket, AssetInitResponse, AssetCompleteRequest, AssetCompleteResultItem, AssetCompleteResponse, UpdateAssetRef, CreateUpdateRequest, Update, CreateUpdateResponse, RollbackToEmbeddedEntry, Channel, ChannelListResponse, UpdateListResponse, RollbackRequest, RollbackToEmbeddedRequest, PromoteRequest, UpdateRolloutPatch, } from './updates';
 export { webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, } from './webauthn';
 export type { WebauthnRegisterOptionsRequest, WebauthnLoginOptionsRequest, WebauthnRegisterVerifyRequest, WebauthnLoginVerifyRequest, } from './webauthn';
+export { devicePairingStatusSchema, deviceTransferInitRequestSchema, deviceTransferInitResponseSchema, deviceTransferInfoResponseSchema, deviceTransferApproveRequestSchema, deviceTransferApproveResponseSchema, deviceTransferDenyResponseSchema, } from './devicePairing';
+export type { DevicePairingStatus, DeviceTransferInitRequest, DeviceTransferInitResponse, DeviceTransferInfoResponse, DeviceTransferApproveRequest, DeviceTransferApproveResponse, DeviceTransferDenyResponse, } from './devicePairing';
+export { transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency';
+export type { TransparencyCheckpointSignature, TransparencyAnchor, TransparencyCheckpoint, TransparencyInclusionProof, TransparencyCheckpointList, } from './transparency';

package/dist/types/keyRecovery.d.ts

@@ -61,17 +61,17 @@ export declare const encryptedBackupEnvelopeSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version: number;
     nonce: string;
+    ciphertext: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
-    ciphertext: string;
     publicKeyHint: string;
     createdAt: string;
 }, {
     version: number;
     nonce: string;
+    ciphertext: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
-    ciphertext: string;
     publicKeyHint: string;
     createdAt: string;
 }>;
@@ -100,18 +100,18 @@ export declare const backupUploadRequestSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     version: number;
     nonce: string;
+    ciphertext: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
-    ciphertext: string;
     publicKeyHint: string;
     createdAt: string;
     lookupId: string;
 }, {
     version: number;
     nonce: string;
+    ciphertext: string;
     algorithm: "xchacha20poly1305";
     kdfInfo: string;
-    ciphertext: string;
     publicKeyHint: string;
     createdAt: string;
     lookupId: string;

package/dist/types/keyRotation.d.ts

@@ -72,17 +72,17 @@ export declare const rotateKeyCompleteRequestSchema: z.ZodObject<{
     signOutEverywhere: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     signature: string;
+    timestamp: number;
     challenge: string;
     newPublicKey: string;
     newKeyProof: string;
-    timestamp: number;
     signOutEverywhere?: boolean | undefined;
 }, {
     signature: string;
+    timestamp: number;
     challenge: string;
     newPublicKey: string;
     newKeyProof: string;
-    timestamp: number;
     signOutEverywhere?: boolean | undefined;
 }>;
 export type RotateKeyCompleteRequest = z.infer<typeof rotateKeyCompleteRequestSchema>;

package/dist/types/sessionStatus.d.ts

@@ -68,7 +68,7 @@ export declare const publicApplicationSchema: z.ZodObject<{
     scopes: z.ZodArray<z.ZodString, "many">;
     developerName: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    type: "first_party" | "third_party" | "internal" | "system";
+    type: "system" | "first_party" | "third_party" | "internal";
     name: string;
     id: string;
     isOfficial: boolean;
@@ -81,7 +81,7 @@ export declare const publicApplicationSchema: z.ZodObject<{
     termsUrl?: string | undefined;
     developerName?: string | undefined;
 }, {
-    type: "first_party" | "third_party" | "internal" | "system";
+    type: "system" | "first_party" | "third_party" | "internal";
     name: string;
     id: string;
     isOfficial: boolean;
@@ -113,6 +113,14 @@ export type PublicApplicationResponse = z.infer<typeof publicApplicationSchema>;
  * current producer and are never `null`, but stay `.optional()` so the contract
  * tolerates leaner shapes from other producers of this same payload without a
  * coordinated bump.
+ *
+ * `pushSentAt` / `openedAt` are DELIVERY PROGRESS, not authorization state: they
+ * let a waiting surface render "Check Commons on your phone" → "Opened in
+ * Commons" without inventing competing statuses. `status` remains the only
+ * authority on whether the request is pending, authorized, cancelled or expired.
+ * Both are `.nullable().optional()` for the same reason as `sessionId` — the
+ * producer always emits the key with `null` until that step happens, and an
+ * older API that omits them entirely must degrade, not fail the parse.
  */
 export declare const sessionStatusSchema: z.ZodObject<{
     status: z.ZodString;
@@ -132,7 +140,7 @@ export declare const sessionStatusSchema: z.ZodObject<{
         scopes: z.ZodArray<z.ZodString, "many">;
         developerName: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        type: "first_party" | "third_party" | "internal" | "system";
+        type: "system" | "first_party" | "third_party" | "internal";
         name: string;
         id: string;
         isOfficial: boolean;
@@ -145,7 +153,7 @@ export declare const sessionStatusSchema: z.ZodObject<{
         termsUrl?: string | undefined;
         developerName?: string | undefined;
     }, {
-        type: "first_party" | "third_party" | "internal" | "system";
+        type: "system" | "first_party" | "third_party" | "internal";
         name: string;
         id: string;
         isOfficial: boolean;
@@ -162,6 +170,13 @@ export declare const sessionStatusSchema: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     publicKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     userId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /**
+     * What approving this request does. Legacy rows read as `device_sign_in`.
+     * OAuth-bound sessions finalize into an authorization code (no `sessionId`).
+     */
+    purpose: z.ZodOptional<z.ZodEnum<["device_sign_in", "oauth_authorization"]>>;
+    pushSentAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    openedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     status: string;
     publicKey?: string | null | undefined;
@@ -171,7 +186,7 @@ export declare const sessionStatusSchema: z.ZodObject<{
     authorized?: boolean | undefined;
     sessionToken?: string | undefined;
     application?: {
-        type: "first_party" | "third_party" | "internal" | "system";
+        type: "system" | "first_party" | "third_party" | "internal";
         name: string;
         id: string;
         isOfficial: boolean;
@@ -184,6 +199,9 @@ export declare const sessionStatusSchema: z.ZodObject<{
         termsUrl?: string | undefined;
         developerName?: string | undefined;
     } | null | undefined;
+    purpose?: "device_sign_in" | "oauth_authorization" | undefined;
+    pushSentAt?: string | null | undefined;
+    openedAt?: string | null | undefined;
 }, {
     status: string;
     publicKey?: string | null | undefined;
@@ -193,7 +211,7 @@ export declare const sessionStatusSchema: z.ZodObject<{
     authorized?: boolean | undefined;
     sessionToken?: string | undefined;
     application?: {
-        type: "first_party" | "third_party" | "internal" | "system";
+        type: "system" | "first_party" | "third_party" | "internal";
         name: string;
         id: string;
         isOfficial: boolean;
@@ -206,5 +224,8 @@ export declare const sessionStatusSchema: z.ZodObject<{
         termsUrl?: string | undefined;
         developerName?: string | undefined;
     } | null | undefined;
+    purpose?: "device_sign_in" | "oauth_authorization" | undefined;
+    pushSentAt?: string | null | undefined;
+    openedAt?: string | null | undefined;
 }>;
 export type SessionStatusResponse = z.infer<typeof sessionStatusSchema>;