@oxyhq/contracts 0.15.0 → 0.17.0

package/dist/cjs/index.js

@@ -11,9 +11,9 @@
  * expo, no `require()` in the ESM build.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validationVoteResultSchema = exports.validationRequestSummarySchema = 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.userNameSchema = exports.createAccountRequestSchema = exports.organizationCategorySchema = exports.ORGANIZATION_CATEGORIES = void 0;
-exports.rollbackRequestSchema = exports.updateListResponseSchema = exports.channelListResponseSchema = exports.channelSchema = exports.rollbackToEmbeddedEntrySchema = exports.createUpdateResponseSchema = exports.updateSchema = exports.createUpdateRequestSchema = exports.updateAssetRefSchema = 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.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 = void 0;
-exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = exports.updateRolloutPatchSchema = exports.promoteRequestSchema = exports.rollbackToEmbeddedRequestSchema = void 0;
+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;
 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; } });
@@ -21,6 +21,8 @@ Object.defineProperty(exports, "createAccountRequestSchema", { enumerable: true,
 var userResponse_1 = require("./userResponse");
 // Schemas
 Object.defineProperty(exports, "userNameSchema", { enumerable: true, get: function () { return userResponse_1.userNameSchema; } });
+Object.defineProperty(exports, "userRelationshipSchema", { enumerable: true, get: function () { return userResponse_1.userRelationshipSchema; } });
+Object.defineProperty(exports, "themePreferenceSchema", { enumerable: true, get: function () { return userResponse_1.themePreferenceSchema; } });
 Object.defineProperty(exports, "userResponseSchema", { enumerable: true, get: function () { return userResponse_1.userResponseSchema; } });
 Object.defineProperty(exports, "userProfileUpdateSchema", { enumerable: true, get: function () { return userResponse_1.userProfileUpdateSchema; } });
 Object.defineProperty(exports, "currentUserResponseSchema", { enumerable: true, get: function () { return userResponse_1.currentUserResponseSchema; } });
@@ -113,6 +115,17 @@ Object.defineProperty(exports, "sessionAccountsChangedEventSchema", { enumerable
 var deviceBoot_1 = require("./deviceBoot");
 // Schemas
 Object.defineProperty(exports, "loginResultSchema", { enumerable: true, get: function () { return deviceBoot_1.loginResultSchema; } });
+var keyRotation_1 = require("./keyRotation");
+// Schemas
+Object.defineProperty(exports, "rotateKeyChallengeResponseSchema", { enumerable: true, get: function () { return keyRotation_1.rotateKeyChallengeResponseSchema; } });
+Object.defineProperty(exports, "rotateKeyCompleteRequestSchema", { enumerable: true, get: function () { return keyRotation_1.rotateKeyCompleteRequestSchema; } });
+Object.defineProperty(exports, "rotateKeyCompleteResponseSchema", { enumerable: true, get: function () { return keyRotation_1.rotateKeyCompleteResponseSchema; } });
+var keyRecovery_1 = require("./keyRecovery");
+// Schemas — encrypted off-device identity backup (b3 Feature 1)
+Object.defineProperty(exports, "backupLookupIdSchema", { enumerable: true, get: function () { return keyRecovery_1.backupLookupIdSchema; } });
+Object.defineProperty(exports, "encryptedBackupEnvelopeSchema", { enumerable: true, get: function () { return keyRecovery_1.encryptedBackupEnvelopeSchema; } });
+Object.defineProperty(exports, "backupUploadRequestSchema", { enumerable: true, get: function () { return keyRecovery_1.backupUploadRequestSchema; } });
+Object.defineProperty(exports, "backupStatusResponseSchema", { enumerable: true, get: function () { return keyRecovery_1.backupStatusResponseSchema; } });
 var updates_1 = require("./updates");
 // Shared primitives
 Object.defineProperty(exports, "updatePlatformSchema", { enumerable: true, get: function () { return updates_1.updatePlatformSchema; } });

package/dist/cjs/keyRecovery.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backupStatusResponseSchema = exports.backupUploadRequestSchema = exports.encryptedBackupEnvelopeSchema = exports.backupLookupIdSchema = void 0;
+/**
+ * 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()`).
+ */
+const zod_1 = require("zod");
+/** 256-bit backup locator (32 bytes), lowercase/uppercase hex. */
+exports.backupLookupIdSchema = zod_1.z
+    .string()
+    .trim()
+    .regex(/^[0-9a-fA-F]{64}$/, 'lookupId must be 64 hex characters');
+/**
+ * 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.
+ */
+exports.encryptedBackupEnvelopeSchema = zod_1.z.object({
+    version: zod_1.z.number().int().positive(),
+    algorithm: zod_1.z.literal('xchacha20poly1305'),
+    kdfInfo: zod_1.z.string().min(1),
+    nonce: zod_1.z.string().trim().min(1),
+    ciphertext: zod_1.z.string().trim().min(1),
+    publicKeyHint: zod_1.z.string().trim().min(1),
+    createdAt: zod_1.z.string().trim().min(1),
+});
+/**
+ * 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.
+ */
+exports.backupUploadRequestSchema = exports.encryptedBackupEnvelopeSchema.extend({
+    /**
+     * 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: exports.backupLookupIdSchema,
+});
+/**
+ * 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.
+ */
+exports.backupStatusResponseSchema = zod_1.z.object({
+    exists: zod_1.z.boolean(),
+    publicKeyHint: zod_1.z.string().optional(),
+    createdAt: zod_1.z.string().optional(),
+});

package/dist/cjs/keyRotation.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rotateKeyCompleteResponseSchema = exports.rotateKeyCompleteRequestSchema = exports.rotateKeyChallengeResponseSchema = void 0;
+/**
+ * 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()`).
+ */
+const zod_1 = require("zod");
+/**
+ * Response of `POST /auth/rotate/challenge`: the single-use `rotate_key`
+ * challenge the client must sign with its CURRENT key, plus its expiry.
+ */
+exports.rotateKeyChallengeResponseSchema = zod_1.z.object({
+    challenge: zod_1.z.string(),
+    /** ISO-8601 expiry timestamp. */
+    expiresAt: zod_1.z.string(),
+});
+/**
+ * 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.
+ */
+exports.rotateKeyCompleteRequestSchema = zod_1.z.object({
+    newPublicKey: zod_1.z.string().trim().min(1),
+    challenge: zod_1.z.string().trim().min(1),
+    signature: zod_1.z.string().trim().min(1),
+    /** Proof-of-possession: the NEW key signs the rotate_key_new payload. */
+    newKeyProof: zod_1.z.string().trim().min(1),
+    timestamp: zod_1.z.number(),
+    /**
+     * 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: zod_1.z.boolean().optional(),
+});
+/** Response of `POST /auth/rotate/complete`: the account's new (rotated) public key. */
+exports.rotateKeyCompleteResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    publicKey: zod_1.z.string(),
+    message: zod_1.z.string(),
+});

package/dist/cjs/userResponse.js

@@ -30,7 +30,7 @@
  * `require()`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deviceLinkedSessionsResponseSchema = exports.deviceLinkedSessionSchema = exports.currentUserResponseSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
+exports.deviceLinkedSessionsResponseSchema = exports.deviceLinkedSessionSchema = exports.currentUserResponseSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.themePreferenceSchema = exports.userRelationshipSchema = exports.userNameSchema = void 0;
 exports.resolveUserId = resolveUserId;
 exports.safeParseContract = safeParseContract;
 const zod_1 = require("zod");
@@ -44,6 +44,14 @@ exports.userNameSchema = zod_1.z
     displayName: zod_1.z.string().optional(),
 })
     .passthrough();
+exports.userRelationshipSchema = zod_1.z.object({
+    isFollowing: zod_1.z.boolean(),
+    followsYou: zod_1.z.boolean(),
+});
+exports.themePreferenceSchema = zod_1.z.object({
+    mode: zod_1.z.enum(['light', 'dark', 'system']),
+    colorPreset: zod_1.z.string(),
+});
 /**
  * The canonical user object emitted by `formatUserResponse`.
  *
@@ -102,6 +110,19 @@ exports.userResponseSchema = zod_1.z
      * Absent on personal, project, and bot accounts.
      */
     organizationCategory: accountGraph_1.organizationCategorySchema.optional(),
+    /**
+     * The authenticated viewer's relationship to this profile. Present ONLY
+     * on single-profile fetches (`GET /profiles/username/:username`,
+     * `GET /users/:userId`) when the request is authenticated; OMITTED for
+     * anonymous requests and for the bulk `POST /users/by-ids` fan-out.
+     */
+    relationship: exports.userRelationshipSchema.optional(),
+    /**
+     * Portable theme preference. Rides the self/session payload (cold boot),
+     * so it is present on the current-user DTO (`GET /users/me`,
+     * `GET /session/user/:sessionId`) and absent until the user sets it.
+     */
+    themePreference: exports.themePreferenceSchema.optional(),
 })
     .passthrough();
 exports.userProfileUpdateSchema = zod_1.z
@@ -142,6 +163,11 @@ exports.userProfileUpdateSchema = zod_1.z
     notificationPreferences: zod_1.z.record(zod_1.z.unknown()).optional(),
     userPreferences: zod_1.z.record(zod_1.z.unknown()).optional(),
     privacySettings: zod_1.z.record(zod_1.z.unknown()).optional(),
+    /**
+     * Portable theme preference. Written through the same `PUT /users/me`
+     * settings-update path as `languages`/`userPreferences`.
+     */
+    themePreference: exports.themePreferenceSchema.optional(),
 })
     .passthrough();
 /**