@oxyhq/contracts 0.17.0 → 0.18.0

package/dist/cjs/devicePairing.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceTransferDenyResponseSchema = exports.deviceTransferApproveResponseSchema = exports.deviceTransferApproveRequestSchema = exports.deviceTransferInfoResponseSchema = exports.deviceTransferInitResponseSchema = exports.deviceTransferInitRequestSchema = exports.devicePairingStatusSchema = void 0;
+const zod_1 = require("zod");
+/* -------------------------------------------------------------------------- */
+/*  Shared field validators                                                   */
+/* -------------------------------------------------------------------------- */
+/** Lowercase/uppercase hex string (no `0x` prefix). */
+const hexString = zod_1.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
+ * `@oxyhq/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.
+ */
+exports.devicePairingStatusSchema = zod_1.z.enum([
+    'pending',
+    'approved',
+    'denied',
+    'expired',
+]);
+/* -------------------------------------------------------------------------- */
+/*  POST /identity/device-transfer/init                                       */
+/* -------------------------------------------------------------------------- */
+/** Request body for `POST /identity/device-transfer/init` (public). */
+exports.deviceTransferInitRequestSchema = zod_1.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: zod_1.z.string().trim().min(1).max(120).optional(),
+});
+exports.deviceTransferInitResponseSchema = zod_1.z.object({
+    pairingId: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+});
+exports.deviceTransferInfoResponseSchema = zod_1.z.object({
+    pairingId: zod_1.z.string(),
+    newDeviceEphemeralPublicKey: zod_1.z.string(),
+    newDeviceLabel: zod_1.z.string().nullable(),
+    status: exports.devicePairingStatusSchema,
+    expiresAt: zod_1.z.string(),
+    oldDeviceEphemeralPublicKey: zod_1.z.string().nullable(),
+    ciphertext: zod_1.z.string().nullable(),
+    nonce: zod_1.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.
+ */
+exports.deviceTransferApproveRequestSchema = zod_1.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: zod_1.z.number().int().positive(),
+});
+exports.deviceTransferApproveResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    pairingId: zod_1.z.string(),
+    status: exports.devicePairingStatusSchema,
+});
+exports.deviceTransferDenyResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    pairingId: zod_1.z.string(),
+    status: exports.devicePairingStatusSchema,
+});

package/dist/cjs/deviceSession.js

@@ -32,10 +32,19 @@ exports.deviceSessionSyncSchema = zod_1.z.object({
  * 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.
  */
 exports.deviceTokenMintRequestSchema = zod_1.z.object({
     deviceId: zod_1.z.string().min(1),
     deviceSecret: zod_1.z.string().min(1),
+    accountId: zod_1.z.string().min(1).optional(),
 });
 /**
  * Wire shape of a successful `POST /session/device/token`: the freshly-minted

package/dist/cjs/index.js

@@ -13,7 +13,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validationOpenResultSchema = exports.validationOpenRequestSchema = exports.validationVerdictRecordSchema = exports.realLifeAttestationResultSchema = exports.realLifeAttestationRecordSchema = exports.signedPublicCardSchema = exports.publicCardSchema = exports.logPageResponseSchema = exports.chainHeadResponseSchema = exports.oxySignedRecordTypeSchema = exports.exportBundleSchema = exports.exportAttestationSchema = exports.authMethodsResponseSchema = exports.authMethodEntrySchema = exports.domainVerificationInstructionsSchema = exports.domainVerificationRequestSchema = exports.verifiedDomainSchema = exports.signedRecordEnvelopeSchema = exports.didDocumentSchema = exports.didServiceSchema = exports.verificationMethodSchema = exports.appAffinityEventsIngestSchema = exports.appAffinityEventSchema = exports.appAffinityEventTypeSchema = exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = exports.sessionStatusSchema = exports.publicApplicationSchema = exports.applicationTypeSchema = exports.safeParseContract = exports.resolveUserId = exports.deviceLinkedSessionsResponseSchema = exports.deviceLinkedSessionSchema = exports.currentUserResponseSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.themePreferenceSchema = exports.userRelationshipSchema = exports.userNameSchema = exports.createAccountRequestSchema = exports.organizationCategorySchema = exports.ORGANIZATION_CATEGORIES = void 0;
 exports.assetCompleteResponseSchema = exports.assetCompleteResultItemSchema = exports.assetCompleteRequestSchema = exports.assetInitResponseSchema = exports.assetUploadTicketSchema = exports.assetInitRequestSchema = exports.assetInitItemSchema = exports.rolloutPercentSchema = exports.runtimeVersionSchema = exports.channelNameSchema = exports.sha256HexSchema = exports.updateAssetStatusSchema = exports.updateStatusSchema = exports.updatePlatformSchema = exports.backupStatusResponseSchema = exports.backupUploadRequestSchema = exports.encryptedBackupEnvelopeSchema = exports.backupLookupIdSchema = exports.rotateKeyCompleteResponseSchema = exports.rotateKeyCompleteRequestSchema = exports.rotateKeyChallengeResponseSchema = exports.loginResultSchema = exports.sessionAccountsChangedEventSchema = exports.sessionAccountsChangedReasonSchema = exports.SESSION_ACCOUNTS_CHANGED_EVENT = exports.deviceHubTicketRedeemResponseSchema = exports.deviceHubTicketRedeemRequestSchema = exports.deviceHubTicketIssueResponseSchema = exports.deviceHubTicketIssueRequestSchema = exports.deviceTokenMintResponseSchema = exports.deviceTokenMintRequestSchema = exports.deviceSessionSyncSchema = exports.activeTokenSchema = exports.deviceSessionStateSchema = exports.sessionAccountSchema = exports.linkPreviewResponseSchema = exports.linkPreviewBatchResponseSchema = exports.linkPreviewBatchRequestSchema = exports.linkPreviewSchema = exports.credentialVerifyResultSchema = exports.credentialListResultSchema = exports.credentialIssueResultSchema = exports.verifiableCredentialResponseSchema = exports.credentialRecordSchema = exports.vouchResultSchema = exports.personhoodStatusResultSchema = exports.personhoodBreakdownSchema = exports.personhoodVouchRecordSchema = exports.validationVoteResultSchema = exports.validationRequestSummarySchema = void 0;
-exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = exports.updateRolloutPatchSchema = exports.promoteRequestSchema = exports.rollbackToEmbeddedRequestSchema = exports.rollbackRequestSchema = exports.updateListResponseSchema = exports.channelListResponseSchema = exports.channelSchema = exports.rollbackToEmbeddedEntrySchema = exports.createUpdateResponseSchema = exports.updateSchema = exports.createUpdateRequestSchema = exports.updateAssetRefSchema = void 0;
+exports.transparencyCheckpointListSchema = exports.transparencyInclusionProofSchema = exports.transparencyCheckpointSchema = exports.transparencyAnchorSchema = exports.transparencyCheckpointSignatureSchema = exports.deviceTransferDenyResponseSchema = exports.deviceTransferApproveResponseSchema = exports.deviceTransferApproveRequestSchema = exports.deviceTransferInfoResponseSchema = exports.deviceTransferInitResponseSchema = exports.deviceTransferInitRequestSchema = exports.devicePairingStatusSchema = exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = exports.updateRolloutPatchSchema = exports.promoteRequestSchema = exports.rollbackToEmbeddedRequestSchema = exports.rollbackRequestSchema = exports.updateListResponseSchema = exports.channelListResponseSchema = exports.channelSchema = exports.rollbackToEmbeddedEntrySchema = exports.createUpdateResponseSchema = exports.updateSchema = exports.createUpdateRequestSchema = exports.updateAssetRefSchema = void 0;
 var accountGraph_1 = require("./accountGraph");
 Object.defineProperty(exports, "ORGANIZATION_CATEGORIES", { enumerable: true, get: function () { return accountGraph_1.ORGANIZATION_CATEGORIES; } });
 Object.defineProperty(exports, "organizationCategorySchema", { enumerable: true, get: function () { return accountGraph_1.organizationCategorySchema; } });
@@ -164,3 +164,19 @@ Object.defineProperty(exports, "webauthnRegisterOptionsRequestSchema", { enumera
 Object.defineProperty(exports, "webauthnLoginOptionsRequestSchema", { enumerable: true, get: function () { return webauthn_1.webauthnLoginOptionsRequestSchema; } });
 Object.defineProperty(exports, "webauthnRegisterVerifyRequestSchema", { enumerable: true, get: function () { return webauthn_1.webauthnRegisterVerifyRequestSchema; } });
 Object.defineProperty(exports, "webauthnLoginVerifyRequestSchema", { enumerable: true, get: function () { return webauthn_1.webauthnLoginVerifyRequestSchema; } });
+var devicePairing_1 = require("./devicePairing");
+// Schemas
+Object.defineProperty(exports, "devicePairingStatusSchema", { enumerable: true, get: function () { return devicePairing_1.devicePairingStatusSchema; } });
+Object.defineProperty(exports, "deviceTransferInitRequestSchema", { enumerable: true, get: function () { return devicePairing_1.deviceTransferInitRequestSchema; } });
+Object.defineProperty(exports, "deviceTransferInitResponseSchema", { enumerable: true, get: function () { return devicePairing_1.deviceTransferInitResponseSchema; } });
+Object.defineProperty(exports, "deviceTransferInfoResponseSchema", { enumerable: true, get: function () { return devicePairing_1.deviceTransferInfoResponseSchema; } });
+Object.defineProperty(exports, "deviceTransferApproveRequestSchema", { enumerable: true, get: function () { return devicePairing_1.deviceTransferApproveRequestSchema; } });
+Object.defineProperty(exports, "deviceTransferApproveResponseSchema", { enumerable: true, get: function () { return devicePairing_1.deviceTransferApproveResponseSchema; } });
+Object.defineProperty(exports, "deviceTransferDenyResponseSchema", { enumerable: true, get: function () { return devicePairing_1.deviceTransferDenyResponseSchema; } });
+var transparency_1 = require("./transparency");
+// Schemas — transparency log (checkpoints + inclusion proofs)
+Object.defineProperty(exports, "transparencyCheckpointSignatureSchema", { enumerable: true, get: function () { return transparency_1.transparencyCheckpointSignatureSchema; } });
+Object.defineProperty(exports, "transparencyAnchorSchema", { enumerable: true, get: function () { return transparency_1.transparencyAnchorSchema; } });
+Object.defineProperty(exports, "transparencyCheckpointSchema", { enumerable: true, get: function () { return transparency_1.transparencyCheckpointSchema; } });
+Object.defineProperty(exports, "transparencyInclusionProofSchema", { enumerable: true, get: function () { return transparency_1.transparencyInclusionProofSchema; } });
+Object.defineProperty(exports, "transparencyCheckpointListSchema", { enumerable: true, get: function () { return transparency_1.transparencyCheckpointListSchema; } });

package/dist/cjs/sessionStatus.js

@@ -93,6 +93,14 @@ exports.publicApplicationSchema = zod_1.z.object({
  * 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.
  */
 exports.sessionStatusSchema = zod_1.z.object({
     status: zod_1.z.string(),
@@ -103,4 +111,11 @@ exports.sessionStatusSchema = zod_1.z.object({
     sessionId: zod_1.z.string().nullable().optional(),
     publicKey: zod_1.z.string().nullable().optional(),
     userId: zod_1.z.string().nullable().optional(),
+    /**
+     * What approving this request does. Legacy rows read as `device_sign_in`.
+     * OAuth-bound sessions finalize into an authorization code (no `sessionId`).
+     */
+    purpose: zod_1.z.enum(['device_sign_in', 'oauth_authorization']).optional(),
+    pushSentAt: zod_1.z.string().nullable().optional(),
+    openedAt: zod_1.z.string().nullable().optional(),
 });

package/dist/cjs/transparency.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transparencyCheckpointListSchema = exports.transparencyInclusionProofSchema = exports.transparencyCheckpointSchema = exports.transparencyAnchorSchema = exports.transparencyCheckpointSignatureSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Transparency log — the public wire contract of the checkpoint surface.
+ *
+ * A checkpoint is the operator's signed commitment to EVERY subject's chain head
+ * at a point in time: "at `periodEnd` I committed to `root` over `treeSize`
+ * subjects, and the previous checkpoint hashed to `prevCheckpointHash`". Anyone
+ * can then ask for an inclusion proof of their own head and verify it against
+ * that root without trusting the server — which is what closes the one gap a
+ * per-subject hash chain cannot close on its own (the server serving two
+ * different histories, or quietly dropping a record).
+ *
+ * The Merkle math, the leaf/checkpoint signing bytes, and the proof verifier all
+ * live in `@oxyhq/protocol` (`src/transparency/`); this module only fixes the
+ * SHAPES that cross the wire, so a client and the API cannot drift on them.
+ *
+ * Digest fields are pinned to 64-char LOWERCASE hex on purpose: the digests are
+ * compared as strings against locally recomputed hashes, so accepting an
+ * upper-case or truncated variant would turn a real mismatch into a confusing
+ * verification failure at a distance.
+ */
+/** A SHA-256 digest in the exact form the protocol emits: 64 lowercase hex chars. */
+const hexDigestSchema = zod_1.z.string().regex(/^[0-9a-f]{64}$/, 'Expected a 64-char lowercase hex digest');
+/**
+ * One signer's endorsement of a checkpoint's signed fields.
+ *
+ * The operator and every independent witness produce this same shape over the
+ * SAME bytes, so the array on a checkpoint can grow without coordination.
+ */
+exports.transparencyCheckpointSignatureSchema = zod_1.z.object({
+    /** Uncompressed hex public key of the signer. */
+    publicKey: zod_1.z.string().min(1),
+    alg: zod_1.z.literal('ES256K-DER-SHA256'),
+    /** DER-encoded hex secp256k1 signature over the checkpoint signing input. */
+    signature: zod_1.z.string().min(1),
+});
+/** Where a checkpoint root was published on a public chain. */
+exports.transparencyAnchorSchema = zod_1.z.object({
+    /** Chain/network identifier, e.g. `faircoin-main`. */
+    network: zod_1.z.string().min(1),
+    txid: zod_1.z.string().min(1),
+    confirmations: zod_1.z.number().int().nonnegative(),
+    /** When the anchoring transaction was broadcast (ms epoch). */
+    anchoredAt: zod_1.z.number().int().positive(),
+});
+/**
+ * A published checkpoint.
+ *
+ * `signatures` is non-empty by contract: an unsigned root commits nobody and
+ * must never be served as a checkpoint. `anchors` may be empty — a checkpoint is
+ * published immediately and anchored asynchronously, so "not yet anchored" is a
+ * normal, temporary state rather than an error.
+ */
+exports.transparencyCheckpointSchema = zod_1.z.object({
+    index: zod_1.z.number().int().nonnegative(),
+    /** End of the committed period (ms epoch). */
+    periodEnd: zod_1.z.number().int().positive(),
+    /** Number of subjects (leaves) committed. */
+    treeSize: zod_1.z.number().int().nonnegative(),
+    root: hexDigestSchema,
+    /** Hash of the previous checkpoint; `null` only at genesis. */
+    prevCheckpointHash: hexDigestSchema.nullable(),
+    signatures: zod_1.z.array(exports.transparencyCheckpointSignatureSchema).min(1),
+    anchors: zod_1.z.array(exports.transparencyAnchorSchema),
+});
+/**
+ * An inclusion proof for one subject against one checkpoint.
+ *
+ * Carries the leaf PREIMAGE (`subjectDid`, `seq`, `headRecordId`) as well as the
+ * `leaf` digest so the verifier re-derives the leaf itself rather than trusting
+ * the server's hash, then walks `proof` up to the checkpoint's `root`.
+ */
+exports.transparencyInclusionProofSchema = zod_1.z.object({
+    checkpoint: exports.transparencyCheckpointSchema,
+    subjectDid: zod_1.z.string().min(1),
+    seq: zod_1.z.number().int().nonnegative(),
+    headRecordId: hexDigestSchema,
+    leaf: hexDigestSchema,
+    leafIndex: zod_1.z.number().int().nonnegative(),
+    /** Audit path, leaf-adjacent sibling first; empty for a single-leaf tree. */
+    proof: zod_1.z.array(hexDigestSchema),
+});
+/** A page of the checkpoint chain, oldest first, for walking `prevCheckpointHash`. */
+exports.transparencyCheckpointListSchema = zod_1.z.object({
+    checkpoints: zod_1.z.array(exports.transparencyCheckpointSchema),
+});