@oxyhq/contracts 0.14.2 → 0.16.0

package/dist/types/deviceBoot.d.ts

@@ -1,10 +1,11 @@
 /**
  * First-party login result contract.
  *
- * SINGLE SOURCE OF TRUTH for the first-party password login result (2FA arm vs.
- * session arm). The API validates its OUTPUT against this schema; every consumer
- * (`@oxyhq/core`'s auth mixin) validates its INPUT against the same definition,
- * so producer and consumers cannot drift.
+ * SINGLE SOURCE OF TRUTH for the first-party login result (the session arm). The
+ * API validates its OUTPUT against this schema; every consumer (`@oxyhq/core`'s
+ * auth mixin) validates its INPUT against the same definition, so producer and
+ * consumers cannot drift. Sign-in is passkey (WebAuthn) or Commons handoff —
+ * password and 2FA were removed, so the only outcome is a completed session.
  *
  * The device transport is `deviceId` + `deviceSecret` + `POST /session/device/token`
  * (see `deviceSession.ts`). The legacy cookie/bootstrap/refresh-family lanes were
@@ -39,18 +40,9 @@ export interface SecurityAlert {
     anomalies: SecurityAlertAnomaly[];
 }
 /**
- * `POST /auth/login` when the account has 2FA enabled: a short-lived login
- * token to be presented at the 2FA challenge, and no session yet.
- */
-export interface LoginTwoFactorRequired {
-    twoFactorRequired: true;
-    loginToken: string;
-}
-/**
- * `POST /auth/login` when authentication completed in one step. Matches the
- * API's `SessionAuthResponse` EXACTLY (`buildSessionAuthResponse`). `user` is the
- * truncated session-user shape the login endpoint emits (NOT the full
- * `userResponseSchema`).
+ * A successful sign-in. Matches the API's `SessionAuthResponse` EXACTLY
+ * (`buildSessionAuthResponse`). `user` is the truncated session-user shape the
+ * sign-in endpoints emit (NOT the full `userResponseSchema`).
  */
 export interface LoginSessionResult {
     sessionId: string;
@@ -77,6 +69,6 @@ export interface LoginSessionResult {
         avatar?: string;
     };
 }
-/** The discriminated outcome of `POST /auth/login`. */
-export type LoginResult = LoginTwoFactorRequired | LoginSessionResult;
+/** The outcome of a successful sign-in — always a completed session. */
+export type LoginResult = LoginSessionResult;
 export declare const loginResultSchema: z.ZodType<LoginResult>;

package/dist/types/identity.d.ts

@@ -275,15 +275,15 @@ export declare const domainVerificationInstructionsSchema: z.ZodObject<{
 export type DomainVerificationInstructions = z.infer<typeof domainVerificationInstructionsSchema>;
 /**
  * One linked authentication method. Mirrors a `User.authMethods[]` entry.
- * `verificationMethodId` is present for `identity` methods (a key) and absent
- * for `password`/social methods, linking the auth method to its DID
- * verification-method fragment. For `webauthn` methods `credentialId` identifies
- * the specific passkey (one entry per registered credential) and `name` is its
- * user-facing label; a passkey is NOT a DID verification method, so it carries
- * no `verificationMethodId` (a passkey-only account stays custodial).
+ * `verificationMethodId` is present for `identity` methods (a key), linking the
+ * auth method to its DID verification-method fragment. For `webauthn` methods
+ * `credentialId` identifies the specific passkey (one entry per registered
+ * credential) and `name` is its user-facing label; a passkey is NOT a DID
+ * verification method, so it carries no `verificationMethodId` (a passkey-only
+ * account stays custodial).
  */
 export interface AuthMethodEntry {
-    type: 'identity' | 'password' | 'google' | 'apple' | 'github' | 'webauthn';
+    type: 'identity' | 'webauthn';
     linkedAt: string | Date;
     verificationMethodId?: string;
     credentialId?: string;

package/dist/types/index.d.ts

@@ -30,7 +30,11 @@ export type { LinkPreviewStatus, LinkPreview, LinkPreviewBatchRequest, LinkPrevi
 export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceHubTicketIssueRequestSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemRequestSchema, deviceHubTicketRedeemResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession';
 export type { SessionAccount, DeviceSessionState, ActiveToken, DeviceSessionSync, DeviceTokenMintRequest, DeviceTokenMintResponse, DeviceHubTicketIssueRequest, DeviceHubTicketIssueResponse, DeviceHubTicketRedeemRequest, DeviceHubTicketRedeemResponse, SessionAccountsChangedReason, SessionAccountsChangedEvent, } from './deviceSession';
 export { loginResultSchema, } from './deviceBoot';
-export type { LoginTwoFactorRequired, LoginSessionResult, LoginResult, SecurityAlert, SecurityAlertAnomaly, } from './deviceBoot';
+export type { LoginSessionResult, LoginResult, SecurityAlert, SecurityAlertAnomaly, } from './deviceBoot';
+export { rotateKeyChallengeResponseSchema, rotateKeyCompleteRequestSchema, rotateKeyCompleteResponseSchema, } from './keyRotation';
+export type { RotateKeyChallengeResponse, RotateKeyCompleteRequest, RotateKeyCompleteResponse, } from './keyRotation';
+export { backupLookupIdSchema, encryptedBackupEnvelopeSchema, backupUploadRequestSchema, backupStatusResponseSchema, } from './keyRecovery';
+export type { EncryptedBackupEnvelope, BackupUploadRequest, BackupStatusResponse, } from './keyRecovery';
 export { updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, assetInitItemSchema, assetInitRequestSchema, assetUploadTicketSchema, assetInitResponseSchema, assetCompleteRequestSchema, assetCompleteResultItemSchema, assetCompleteResponseSchema, updateAssetRefSchema, createUpdateRequestSchema, updateSchema, createUpdateResponseSchema, rollbackToEmbeddedEntrySchema, channelSchema, channelListResponseSchema, updateListResponseSchema, rollbackRequestSchema, rollbackToEmbeddedRequestSchema, promoteRequestSchema, updateRolloutPatchSchema, } from './updates';
 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';

package/dist/types/keyRecovery.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Encrypted off-device identity backup contract (b3 Feature 1).
+ *
+ * SINGLE SOURCE OF TRUTH for the "encrypted identity backup" flow, where a
+ * client stores an encrypted copy of its self-custody identity key off-device so
+ * a lost/wiped device can be recovered from the recovery phrase ALONE — without
+ * the platform ever seeing the phrase, the derived encryption key, or the
+ * plaintext private key.
+ *
+ * Zero-knowledge design (mirrors the zero-cookie `DeviceSession.secretHash`
+ * pattern): the client derives, from the FULL 64-byte BIP-39 seed, both an
+ * encryption key (`backupKey`) and a locator (`lookupId`) via HKDF with
+ * domain-separated `info` labels. It uploads ONLY the XChaCha20-Poly1305
+ * ciphertext plus the raw `lookupId`; the server stores the ciphertext and
+ * `sha256(lookupId)` (never the raw `lookupId`). Restoration re-derives both
+ * from the phrase, fetches the envelope by `lookupId`, and decrypts locally.
+ *
+ * The server can neither locate a backup (it lacks the seed to compute the
+ * lookup id) nor decrypt one (it lacks the seed to compute the backup key) — a
+ * DB dump yields only opaque ciphertext keyed by an un-invertible hash.
+ *
+ * The producer (`@oxyhq/api`) validates its request/response against these
+ * schemas; the consumer (`@oxyhq/core` identity-backup mixin) validates its
+ * input against the same definitions, so the wire shape cannot drift.
+ *
+ * All shapes here are FLAT (no nested objects), so `z.infer<>` is safe under a
+ * consumer's node10 `moduleResolution`. Platform-agnostic — zod only, ESM-safe
+ * (no `require()`).
+ */
+import { z } from 'zod';
+/** 256-bit backup locator (32 bytes), lowercase/uppercase hex. */
+export declare const backupLookupIdSchema: z.ZodString;
+/**
+ * The stored, self-describing encrypted backup as it lives at rest and travels
+ * on the public restore endpoint. Contains NO secret and NO locator: the
+ * `lookupId` is uploaded separately (see {@link backupUploadRequestSchema}) and
+ * only its hash is ever persisted.
+ *
+ * - `version`       — envelope/KDF version, so a future scheme migration is
+ *   distinguishable at rest.
+ * - `algorithm`     — the AEAD used. Pinned literal so a mismatched decryptor
+ *   fails loudly rather than silently.
+ * - `kdfInfo`       — the HKDF `info` label used to derive the encryption key
+ *   (domain-separation tag; documents exactly which context produced the key).
+ * - `nonce`         — the 24-byte XChaCha20-Poly1305 nonce, hex.
+ * - `ciphertext`    — the encrypted `{privateKey, publicKey, createdAt}` payload
+ *   with the appended Poly1305 tag, hex.
+ * - `publicKeyHint` — a short, non-sensitive prefix of the backed-up identity's
+ *   public key, so the owner can recognise WHICH identity a backup belongs to
+ *   without exposing the full key. Bound into the AEAD associated data.
+ * - `createdAt`     — ISO-8601 creation timestamp.
+ */
+export declare const encryptedBackupEnvelopeSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    algorithm: z.ZodLiteral<"xchacha20poly1305">;
+    kdfInfo: z.ZodString;
+    nonce: z.ZodString;
+    ciphertext: z.ZodString;
+    publicKeyHint: z.ZodString;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    nonce: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    ciphertext: string;
+    publicKeyHint: string;
+    createdAt: string;
+}, {
+    version: number;
+    nonce: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    ciphertext: string;
+    publicKeyHint: string;
+    createdAt: string;
+}>;
+export type EncryptedBackupEnvelope = z.infer<typeof encryptedBackupEnvelopeSchema>;
+/**
+ * Request body of `POST /identity/backup` — the envelope PLUS the raw
+ * `lookupId`. The server sha256-hashes `lookupId` before storing it (it never
+ * persists the raw value), and upserts by the authenticated user id so a
+ * re-upload REPLACES the prior backup rather than accumulating duplicates.
+ */
+export declare const backupUploadRequestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    algorithm: z.ZodLiteral<"xchacha20poly1305">;
+    kdfInfo: z.ZodString;
+    nonce: z.ZodString;
+    ciphertext: z.ZodString;
+    publicKeyHint: z.ZodString;
+    createdAt: z.ZodString;
+} & {
+    /**
+     * The raw 256-bit backup locator (hex), derived client-side from the seed
+     * with a domain-separated HKDF `info`. The server stores ONLY its sha256; a
+     * DB dump therefore cannot recompute a locator to enumerate backups.
+     */
+    lookupId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    nonce: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    ciphertext: string;
+    publicKeyHint: string;
+    createdAt: string;
+    lookupId: string;
+}, {
+    version: number;
+    nonce: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    ciphertext: string;
+    publicKeyHint: string;
+    createdAt: string;
+    lookupId: string;
+}>;
+export type BackupUploadRequest = z.infer<typeof backupUploadRequestSchema>;
+/**
+ * Response of `GET /identity/backup/status` (and the write/delete acks): whether
+ * the authenticated user has a stored backup, plus the non-sensitive hint +
+ * timestamp when one exists. Carries no ciphertext and no locator.
+ */
+export declare const backupStatusResponseSchema: z.ZodObject<{
+    exists: z.ZodBoolean;
+    publicKeyHint: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    exists: boolean;
+    publicKeyHint?: string | undefined;
+    createdAt?: string | undefined;
+}, {
+    exists: boolean;
+    publicKeyHint?: string | undefined;
+    createdAt?: string | undefined;
+}>;
+export type BackupStatusResponse = z.infer<typeof backupStatusResponseSchema>;

package/dist/types/keyRotation.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Key-rotation contract (b3 Feature 3 — key rotation + last-credential replacement).
+ *
+ * SINGLE SOURCE OF TRUTH for the atomic key-rotation flow:
+ *  - `POST /auth/rotate/challenge` — mint a single-use `rotate_key` challenge.
+ *  - `POST /auth/rotate/complete`  — prove control of the CURRENT (old) key and
+ *    atomically swap in the new one.
+ *
+ * Rotation is an atomic REPLACE of the single identity key, never a
+ * remove-then-add, so it never passes through a zero-auth-method state and is
+ * independent of the unlink guards. Because the client proves possession of the
+ * current key (from SecureStore OR a recovery-phrase re-derivation), the LAST
+ * remaining credential can be replaced — the server only cares that the
+ * signature validates against the current `publicKey`.
+ *
+ * The API validates its output against these schemas; `@oxyhq/core`'s identity
+ * mixin validates its input against the same definitions, so producer and
+ * consumer cannot drift.
+ *
+ * All shapes here are FLAT (no nested objects), so `z.infer<>` is safe under a
+ * consumer's node10 `moduleResolution` — no interface-pinning needed.
+ *
+ * Platform-agnostic — zod only, ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Response of `POST /auth/rotate/challenge`: the single-use `rotate_key`
+ * challenge the client must sign with its CURRENT key, plus its expiry.
+ */
+export declare const rotateKeyChallengeResponseSchema: z.ZodObject<{
+    challenge: z.ZodString;
+    /** ISO-8601 expiry timestamp. */
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    challenge: string;
+}, {
+    expiresAt: string;
+    challenge: string;
+}>;
+export type RotateKeyChallengeResponse = z.infer<typeof rotateKeyChallengeResponseSchema>;
+/**
+ * Request body of `POST /auth/rotate/complete`.
+ *
+ * Two proofs are required:
+ *  - `signature` — the CURRENT (old) key signs
+ *    `JSON.stringify({ action: 'rotate_key', userId, oldPublicKey, newPublicKey,
+ *    challenge, timestamp })` (proves control of the key being replaced).
+ *  - `newKeyProof` — the NEW key signs
+ *    `JSON.stringify({ action: 'rotate_key_new', userId, newPublicKey, challenge,
+ *    timestamp })` (proof-of-possession of the key being rotated IN; prevents an
+ *    attacker rotating their account to a re-encoding of someone else's key they
+ *    do not control).
+ *
+ * The request carries ONLY `newPublicKey` — `oldPublicKey` and `userId` are
+ * derived server-side from the authenticated user document (never
+ * client-supplied), so a caller cannot prove control of key X while rotating
+ * key Y.
+ */
+export declare const rotateKeyCompleteRequestSchema: z.ZodObject<{
+    newPublicKey: z.ZodString;
+    challenge: z.ZodString;
+    signature: z.ZodString;
+    /** Proof-of-possession: the NEW key signs the rotate_key_new payload. */
+    newKeyProof: z.ZodString;
+    timestamp: z.ZodNumber;
+    /**
+     * When true, all OTHER active sessions for the account are revoked after a
+     * successful rotation (the rotating device stays signed in). Use it when the
+     * old key is presumed compromised.
+     */
+    signOutEverywhere: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    challenge: string;
+    newPublicKey: string;
+    newKeyProof: string;
+    timestamp: number;
+    signOutEverywhere?: boolean | undefined;
+}, {
+    signature: string;
+    challenge: string;
+    newPublicKey: string;
+    newKeyProof: string;
+    timestamp: number;
+    signOutEverywhere?: boolean | undefined;
+}>;
+export type RotateKeyCompleteRequest = z.infer<typeof rotateKeyCompleteRequestSchema>;
+/** Response of `POST /auth/rotate/complete`: the account's new (rotated) public key. */
+export declare const rotateKeyCompleteResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    publicKey: z.ZodString;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    publicKey: string;
+    success: boolean;
+}, {
+    message: string;
+    publicKey: string;
+    success: boolean;
+}>;
+export type RotateKeyCompleteResponse = z.infer<typeof rotateKeyCompleteResponseSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -78,7 +78,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
-    "@types/node": "^20.19.9",
+    "@types/node": "^20.19.43",
     "release-it": "^19.0.6",
     "typescript": "^5.9.2"
   }