@oxy.so/contracts 1.0.0

package/dist/esm/civic.js

@@ -0,0 +1,160 @@
+/**
+ * Civic / Commons API contracts (Fase 1 — DNI + crypto-owned reputation).
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the public "DNI" card a Commons
+ * user shows (and others scan): the user's DID, display identity, trust tier,
+ * personhood status, verified domains, and credential badges — sealed with an
+ * Oxy custodial attestation so a scanner can verify it OFFLINE against the Oxy
+ * public key (the same `ES256K-DER-SHA256` scheme as the signed data export).
+ *
+ * The QR encodes ONLY the DID (`oxydni://card?did=…`) — never trust data — so a
+ * card cannot be spoofed by crafting a QR; the scanner resolves the signed card
+ * server-side and verifies the Oxy signature. The attestation is computed over
+ * the canonical-JSON of the `card` object, so a consumer re-canonicalizes the
+ * card it received and verifies `attestation.signature` against
+ * `attestation.publicKey` (which MUST be a current verification method of the
+ * Oxy DID).
+ *
+ * Explicit-`interface` exports (PublicCard, SignedPublicCard) follow the same
+ * node-resolution rationale as `UserNameResponse` / the identity contracts: a
+ * nested `z.infer<>` can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"`, so the load-bearing shapes are declared as literal
+ * interfaces and the runtime schemas are annotated `z.ZodType<Interface>`.
+ *
+ * The `attestation` reuses the export-bundle `ExportAttestation` shape from
+ * `./identity` (mirrored, not duplicated): `{ issuer, publicKey, alg, signature,
+ * signedAt }`. It is `null` ONLY when the Oxy signing key is unconfigured (dev).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+import { exportAttestationSchema } from './identity.js';
+export const publicCardSchema = z.object({
+    did: z.string(),
+    userId: z.string(),
+    name: z.string(),
+    username: z.string().optional(),
+    avatarUrl: z.string().optional(),
+    trustTier: z.enum(['restricted', 'new', 'trusted', 'high_trust', 'verified']),
+    personhoodStatus: z.enum(['unverified', 'pending', 'verified']),
+    verifiedDomains: z.array(z.string()),
+    credentialBadges: z.array(z.string()),
+    issuedAt: z.number(),
+});
+export const signedPublicCardSchema = z.object({
+    card: publicCardSchema,
+    attestation: exportAttestationSchema.nullable(),
+});
+export const realLifeAttestationRecordSchema = z.object({
+    about: z.string(),
+    context: z.string(),
+    nonce: z.string(),
+    exp: z.number(),
+    geohash: z.string().optional(),
+    biometricOk: z.boolean().optional(),
+});
+export const realLifeAttestationResultSchema = z.object({
+    accepted: z.literal(true),
+    recordId: z.string(),
+    subjectUserId: z.string(),
+    attestorUserId: z.string(),
+    points: z.number(),
+});
+export const validationVerdictRecordSchema = z.object({
+    requestId: z.string(),
+    payloadHash: z.string(),
+    verdict: z.enum(['valid', 'invalid', 'abstain']),
+});
+/** Request body for opening a validation request (`POST /civic/validations`). */
+export const validationOpenRequestSchema = z.object({
+    subjectUserId: z.string(),
+    actionType: z.string().min(1),
+    sourceActionId: z.string().min(1),
+    payload: z.record(z.unknown()),
+    highValue: z.boolean().optional(),
+});
+export const validationOpenResultSchema = z.object({
+    requestId: z.string(),
+    selectedValidatorCount: z.number(),
+    expiresAt: z.string(),
+});
+export const validationRequestSummarySchema = z.object({
+    id: z.string(),
+    subjectUserId: z.string(),
+    actionType: z.string(),
+    payload: z.record(z.unknown()),
+    payloadHash: z.string(),
+    status: z.enum(['pending', 'quorum_met', 'validated', 'rejected', 'expired']),
+    highValue: z.boolean(),
+    expiresAt: z.string(),
+});
+export const validationVoteResultSchema = z.object({
+    recorded: z.literal(true),
+    requestId: z.string(),
+    verdict: z.enum(['valid', 'invalid', 'abstain']),
+    status: z.enum(['pending', 'quorum_met', 'validated', 'rejected', 'expired']),
+});
+export const personhoodVouchRecordSchema = z.object({
+    about: z.string(),
+    context: z.string().optional(),
+    stake: z.number().optional(),
+});
+export const personhoodBreakdownSchema = z.object({
+    vouchSignal: z.number(),
+    realLifeSignal: z.number(),
+    biometricSignal: z.number(),
+    evidence: z.number(),
+    sybilPenalty: z.number(),
+    seed: z.boolean(),
+});
+export const personhoodStatusResultSchema = z.object({
+    userId: z.string(),
+    score: z.number(),
+    isRealPerson: z.boolean(),
+    vouchCount: z.number(),
+    realLifeCount: z.number(),
+    biometricBound: z.boolean(),
+    sybilPenalty: z.number(),
+    breakdown: personhoodBreakdownSchema.nullable(),
+    updatedAt: z.string().nullable(),
+});
+export const vouchResultSchema = z.object({
+    accepted: z.literal(true),
+    recordId: z.string(),
+    subjectUserId: z.string(),
+    voucherUserId: z.string(),
+    stakeAmount: z.number(),
+    points: z.number(),
+});
+export const credentialRecordSchema = z.object({
+    about: z.string(),
+    types: z.array(z.string().min(1)).min(1),
+    claims: z.record(z.unknown()),
+    expiresAt: z.number().optional(),
+});
+export const verifiableCredentialResponseSchema = z.object({
+    id: z.string(),
+    recordId: z.string(),
+    holderUserId: z.string(),
+    holderDid: z.string(),
+    issuerUserId: z.string().optional(),
+    issuerDid: z.string(),
+    types: z.array(z.string()),
+    claims: z.record(z.unknown()),
+    status: z.enum(['active', 'revoked', 'expired']),
+    issuedAt: z.number(),
+    expiresAt: z.number().optional(),
+    revokedAt: z.number().optional(),
+});
+export const credentialIssueResultSchema = z.object({
+    accepted: z.literal(true),
+    credential: verifiableCredentialResponseSchema,
+});
+export const credentialListResultSchema = z.object({
+    credentials: z.array(verifiableCredentialResponseSchema),
+});
+export const credentialVerifyResultSchema = z.object({
+    valid: z.boolean(),
+    reason: z.string().optional(),
+    credential: verifiableCredentialResponseSchema.nullable(),
+});

package/dist/esm/commonsSignIn.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical contract for the "Sign in with Oxy" approval handoff.
+ *
+ * SINGLE SOURCE OF TRUTH for the closed set of reasons an approver may attach
+ * when it DENIES a pending request via
+ * `POST /auth/session/deny/:authorizeCode`.
+ *
+ * That endpoint is UNAUTHENTICATED — the public `authorizeCode` is the only
+ * credential — so a free-form string from it is never stored: it would be an
+ * unauthenticated write of arbitrary text onto a record other surfaces read.
+ * The set is therefore deliberately tiny, and closed:
+ *
+ *  - `'declined'` the approver rejected a request they recognised ("Not now").
+ *  - `'not_me'`   the approver did not start the request ("This wasn't me").
+ *                 The ONE value that records the denial as suspicious rather
+ *                 than an ordinary cancel, so a UI may only offer it where the
+ *                 user genuinely said so.
+ *
+ * Why this lives in `@oxy.so/contracts` rather than in either consumer: the same
+ * closed set is enforced in three places — the request schema of the API route,
+ * the `enum` of the persisted `AuthSession.deniedReason` field, and the client
+ * SDK's `denyCommonsSignIn` parameter. Two hand-maintained copies of a wire
+ * contract drift the moment a value is added on one side only, and the failure
+ * lands at runtime, in an auth path, as a generic validation error. One
+ * declaration makes that impossible.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * The closed set, as a value — consumed directly where a runtime list is
+ * required (e.g. the Mongoose `enum` of `AuthSession.deniedReason`, which is
+ * the storage-level guarantee that an unauthenticated caller can never write
+ * free-form text into the field).
+ */
+export const COMMONS_DENY_REASONS = ['declined', 'not_me'];
+/**
+ * The same set as a zod enum — the edge validator. Anything outside it
+ * (including free-form text) is rejected with 400 before any handler runs.
+ */
+export const commonsDenyReasonSchema = z.enum(COMMONS_DENY_REASONS);
+/**
+ * Android notification channel id the identity-approval push is sent on.
+ *
+ * A wire contract for the same reason the deny set is: Android 8+ DROPS a
+ * notification whose channel id the app has not created, silently and with no
+ * client-side error. The API attaches this id when it sends, and the vault
+ * creates the channel with it before registering a push token — two hand-typed
+ * copies of that string would fail as "the notification never arrived", which
+ * is the single hardest push symptom to diagnose.
+ *
+ * The channel's user-visible NAME and description are deliberately NOT here:
+ * those are localized app copy, and the vault owns them.
+ */
+export const IDENTITY_APPROVAL_PUSH_CHANNEL = 'auth-approval';

package/dist/esm/deviceBoot.js

@@ -0,0 +1,47 @@
+/**
+ * First-party login result contract.
+ *
+ * SINGLE SOURCE OF TRUTH for the first-party login result (the session arm). The
+ * API validates its OUTPUT against this schema; every consumer (`@oxy.so/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
+ * removed in the zero-cookie cutover — nothing here carries a refresh token or a
+ * boot fragment.
+ *
+ * Nested-object response shapes are declared as explicit `interface`s with the
+ * runtime schema annotated `z.ZodType<Interface>` — the same rationale as
+ * `identity.ts` / `userResponse.ts`: a `z.infer<>` of a nested object schema can
+ * degrade to `{}` under a consumer's `moduleResolution: "node"` (node10), so the
+ * load-bearing shapes are pinned by literal interfaces. Flat request/response
+ * shapes (no nested-object hazard) are inferred via `z.infer<>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+const securityAlertSchema = z.object({
+    message: z.string(),
+    anomalies: z.array(z.object({
+        type: z.string(),
+        reason: z.string(),
+        details: z.string().optional(),
+    })),
+});
+const loginSessionResultSchema = z.object({
+    sessionId: z.string(),
+    deviceId: z.string(),
+    expiresAt: z.string(),
+    accessToken: z.string().optional(),
+    deviceSecret: z.string().optional(),
+    securityAlert: securityAlertSchema.optional(),
+    user: z.object({
+        id: z.string(),
+        username: z.string().optional(),
+        avatar: z.string().optional(),
+    }),
+});
+export const loginResultSchema = loginSessionResultSchema;

package/dist/esm/deviceDirectory.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { accountKindSchema } from './accountGraph.js';
+import { activeTokenSchema, deviceSessionStateSchema } from './deviceSession.js';
+import { userNameSchema } from './userResponse.js';
+/**
+ * The canonical device directory — the ONE server-authoritative read model an
+ * account switcher renders (issue #937, ADR 0002).
+ *
+ * It replaces the client-side union of `DeviceSessionState.accounts[]` with a
+ * separately fetched `AccountNode[]` graph. That union cannot be correct on a
+ * device holding more than one person: the client only ever holds ONE caller's
+ * account graph, so it cannot enumerate what the OTHER principals may act as.
+ * Switchability is an authorization question, so the server answers it.
+ *
+ * The directory is deterministic and revision-bound: two reads at the same
+ * `revision` describe the same device state, and `revision` only advances on a
+ * real mutation (an idempotent activation advances nothing — ADR 0002).
+ */
+/**
+ * How a principal reaches an account.
+ *
+ * Mirrors `AccountRelationship` in `@oxy.so/core`'s account graph rather than
+ * inventing a second vocabulary for the same fact:
+ *  - `self`   — the principal's own personal account (`principal.userId === accountId`)
+ *  - `owner`  — the principal owns this account
+ *  - `member` — the principal holds a membership granting `account:act_as`
+ */
+export const deviceContextRelationshipSchema = z.enum(['self', 'owner', 'member']);
+/**
+ * Sanitized display metadata for a principal or an account context.
+ *
+ * Deliberately NOT `userResponseSchema`: a switcher needs a handle, a name, an
+ * avatar and the accent the row is drawn in, and the directory is read by every
+ * app on the device — so it carries the minimum that renders a row and nothing
+ * that would make it a general profile feed. `name.displayName` stays OPTIONAL;
+ * consumers fall back to the handle (`getNormalizedUserHandle`), never to a
+ * synthesized name.
+ *
+ * `color` is here and `email` is not, and the line between them is what the
+ * field is FOR rather than how sensitive it looks. An accent is a property of
+ * drawing the row — without it every non-active row falls back to the ambient
+ * theme accent and a device holding two people renders them identically
+ * (issue #961). An address is somebody's contact detail, and the `@handle` the
+ * secondary line already shows fills the same slot, so putting one in a payload
+ * every installed app reads would widen the profile for no rendering gain.
+ */
+export const deviceDirectoryProfileSchema = z.object({
+    id: z.string().min(1),
+    username: z.string(),
+    name: userNameSchema.optional(),
+    avatar: z.string().nullable().optional(),
+    /**
+     * Named Bloom color preset (e.g. `"blue"`), or null when the account has
+     * none. Same shape as `userResponseSchema.color` — one spelling of one fact,
+     * so a consumer that themes a row from either source reads the same values.
+     */
+    color: z.string().nullable().optional(),
+});
+/**
+ * One `principal acting as account` pair — the globally switchable unit.
+ *
+ * `id` is the identifier `POST /session/device/activate` takes. It names the
+ * PAIR, not the account: the same `accountId` legitimately appears under two
+ * principals on a shared device, and those are different sessions, permissions,
+ * audit actors and revocation paths.
+ *
+ * `onDevice` is `false` for a context the principal may act as but has never
+ * activated here — it exists as a row so it has a stable id to activate, and
+ * its delegated session is minted on first activation rather than eagerly for
+ * every organization the principal belongs to.
+ *
+ * `available` is `principalLive && (personal || live account:act_as)`, and the
+ * principal clause is not decoration: a principal whose own personal session
+ * has died makes EVERY context of theirs unavailable, including delegated ones
+ * whose sessions are perfectly alive. Activation verifies the principal's
+ * personal session (ADR 0002 step 3), so a client that models availability as
+ * "delegated context has a live session ⇒ activatable" will be refused by the
+ * server and the context healed away.
+ *
+ * A managed account whose membership was revoked is returned with
+ * `available: false` rather than silently omitted, so the UI can explain a row
+ * disappearing instead of just dropping it.
+ *
+ * (An earlier version of this comment described `available` as the
+ * `account:act_as` verdict alone. It was written before the server existed and
+ * was weaker than the code that shipped — the kind of wrong statement nothing
+ * recomputes, so it is spelled out here in full.)
+ */
+export const deviceAccountContextSchema = z.object({
+    id: z.string().min(1),
+    accountId: z.string().min(1),
+    kind: accountKindSchema,
+    relationship: deviceContextRelationshipSchema,
+    account: deviceDirectoryProfileSchema,
+    onDevice: z.boolean(),
+    available: z.boolean(),
+    active: z.boolean(),
+    lastUsedAt: z.number().nullable(),
+});
+/**
+ * A human who authenticated onto this device.
+ *
+ * Never an organization, project, channel or bot — those are subjects a
+ * principal acts as, and they appear only in `contexts`. `authuser` is the
+ * Google-style signed-in-human slot and belongs HERE, not to an account: adding
+ * an organization must never consume one.
+ */
+export const devicePrincipalSchema = z.object({
+    id: z.string().min(1),
+    userId: z.string().min(1),
+    authuser: z.number().int().nonnegative(),
+    user: deviceDirectoryProfileSchema,
+    contexts: z.array(deviceAccountContextSchema),
+});
+/**
+ * Response of `GET /session/device/directory`.
+ *
+ * `activeContextId` is the authority for what every official app in
+ * `sessionMode: 'account'` renders. It is null when the device has no active
+ * context — a real state (every context removed, or an active context healed
+ * away), not an error.
+ */
+export const deviceDirectorySchema = z.object({
+    deviceId: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    activeContextId: z.string().nullable(),
+    principals: z.array(devicePrincipalSchema),
+    updatedAt: z.number(),
+});
+/**
+ * Request body of `POST /session/device/activate`.
+ *
+ * `contextId`, never `accountId`: an account id cannot name a context on a
+ * device where two people can both reach the same organization, and resolving
+ * that ambiguity server-side would mean guessing inside an authorization path.
+ */
+export const deviceActivateRequestSchema = z.object({
+    contextId: z.string().min(1),
+});
+/**
+ * Response of `POST /session/device/activate`.
+ *
+ * Carries the post-transition directory AND the bearer for the newly active
+ * context, because the client's ordering invariant is
+ * `commit token → reset caches → publish snapshot → notify` (ADR 0002). Handing
+ * the directory back without the token would force a second round trip in the
+ * middle of that sequence, which is exactly where a component would render the
+ * new subject while still holding the previous subject's bearer.
+ *
+ * `activeToken` is null when the activation legitimately produced no bearer for
+ * THIS caller — an identity-pinned client, or a caller whose application is not
+ * entitled to a token for the new context. It is never an error signal.
+ */
+export const deviceActivateResponseSchema = z.object({
+    directory: deviceDirectorySchema,
+    activeToken: activeTokenSchema.nullable(),
+});
+/**
+ * Response of the CONTEXT-aware removals — `POST /session/device/signout` with
+ * `{ contextId }` (one `principal → account` pair) or `{ principalId }` (one
+ * person and every context they reach, and nobody else's).
+ *
+ * It carries BOTH halves because a removal elects a replacement active context,
+ * so both the directory and the flat compatibility projection move in the same
+ * transition — and a client that learned only one of them would render one
+ * half of a device that no longer exists.
+ *
+ * This is deliberately NOT {@link deviceSessionSyncSchema} and must never be
+ * merged into it. A zod object strips unknown keys, so `{directory, state,
+ * activeToken}` parses cleanly as `{state, activeToken}` — silently dropping the
+ * directory. One schema covering both shapes would therefore make "the server
+ * stopped sending the directory" and "this endpoint never sends one"
+ * indistinguishable at the parse, on the exact path that decides which identity
+ * the app is running as. Two schemas fail closed instead: `directory` is
+ * required here, so a directory-less payload is refused outright.
+ *
+ * `activeToken` is null on the same terms as everywhere else — an identity-
+ * pinned caller, or one not entitled to a bearer for the newly-elected context —
+ * and null is also the honest answer when the removal left the device with no
+ * active context at all.
+ */
+export const deviceDirectorySyncSchema = z.object({
+    directory: deviceDirectorySchema,
+    state: deviceSessionStateSchema,
+    activeToken: activeTokenSchema.nullable(),
+});

package/dist/esm/devicePairing.js

@@ -0,0 +1,135 @@
+/**
+ * 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';
+/* -------------------------------------------------------------------------- */
+/*  Shared field validators                                                   */
+/* -------------------------------------------------------------------------- */
+/** Lowercase/uppercase hex string (no `0x` prefix). */
+const hexString = z
+    .string()
+    .trim()
+    .regex(/^[0-9a-fA-F]+$/, 'must be a hex string');
+/**
+ * A secp256k1 public key, hex-encoded — compressed (`02`/`03` + 32 bytes = 66
+ * chars) or uncompressed (`04` + 64 bytes = 130 chars). The exact curve-point
+ * validity is re-checked server-side; this only bounds the shape/length.
+ */
+const publicKeyHex = hexString.min(66).max(130);
+/** DER-encoded ECDSA signature, hex (variable length, ~140–144 chars). */
+const signatureHex = hexString.min(2).max(256);
+/**
+ * The 24-byte XChaCha20-Poly1305 nonce, hex (exactly 48 chars). Matches
+ * `@oxy.so/core` `AEAD_NONCE_LENGTH` (24 bytes).
+ */
+const nonceHex = hexString.length(48);
+/**
+ * The AEAD ciphertext (Poly1305 tag appended), hex. The plaintext is the small
+ * JSON `{ privateKey, publicKey }` (~200 bytes), so the ciphertext stays well
+ * under the cap; the bound blunts relay-abuse via oversized blobs.
+ */
+const ciphertextHex = hexString.min(2).max(8192);
+/* -------------------------------------------------------------------------- */
+/*  Status                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const devicePairingStatusSchema = z.enum([
+    'pending',
+    'approved',
+    'denied',
+    'expired',
+]);
+/* -------------------------------------------------------------------------- */
+/*  POST /identity/device-transfer/init                                       */
+/* -------------------------------------------------------------------------- */
+/** Request body for `POST /identity/device-transfer/init` (public). */
+export const deviceTransferInitRequestSchema = z.object({
+    /** The new device's ephemeral secp256k1 public key (single-use). */
+    newEphPub: publicKeyHex,
+    /** Optional human-readable label for the new device (e.g. "iPhone 15"). */
+    newDeviceLabel: z.string().trim().min(1).max(120).optional(),
+});
+export const deviceTransferInitResponseSchema = z.object({
+    pairingId: z.string(),
+    expiresAt: z.string(),
+});
+export const deviceTransferInfoResponseSchema = z.object({
+    pairingId: z.string(),
+    newDeviceEphemeralPublicKey: z.string(),
+    newDeviceLabel: z.string().nullable(),
+    status: devicePairingStatusSchema,
+    expiresAt: z.string(),
+    oldDeviceEphemeralPublicKey: z.string().nullable(),
+    ciphertext: z.string().nullable(),
+    nonce: z.string().nullable(),
+});
+/* -------------------------------------------------------------------------- */
+/*  POST /identity/device-transfer/:pairingId/approve                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const deviceTransferApproveRequestSchema = z.object({
+    /** The old device's ephemeral secp256k1 public key (single-use). */
+    oldEphPub: publicKeyHex,
+    /** AEAD ciphertext of `{ privateKey, publicKey }`, hex. */
+    ciphertext: ciphertextHex,
+    /** AEAD nonce, hex (24 bytes). */
+    nonce: nonceHex,
+    /** ECDSA (DER, hex) signature proving control of the CURRENT identity key. */
+    signature: signatureHex,
+    /** Signing timestamp (ms since epoch) — freshness-checked server-side. */
+    timestamp: z.number().int().positive(),
+});
+export const deviceTransferApproveResponseSchema = z.object({
+    success: z.boolean(),
+    pairingId: z.string(),
+    status: devicePairingStatusSchema,
+});
+export const deviceTransferDenyResponseSchema = z.object({
+    success: z.boolean(),
+    pairingId: z.string(),
+    status: devicePairingStatusSchema,
+});