@oxy.so/contracts 1.1.0 → 1.2.0

package/dist/esm/identityMove.js

@@ -0,0 +1,82 @@
+/**
+ * Identity move contract — take a web identity INTO Commons (a MOVE, not a copy).
+ *
+ * Design: `docs/superpowers/specs/2026-09-15-one-identity-two-carriers-design.md` §5.
+ *
+ * Flow (the web — the OLD carrier — shows the QR; Commons — the NEW carrier —
+ * scans it):
+ *  1. `id.oxy.so` generates an ephemeral secp256k1 pair and calls
+ *     `POST /identity/move { initiatorEphemeralPublicKey }` (bearer) →
+ *     `{ moveId, expiresAt }`. The QR carries `moveId` only.
+ *  2. Commons scans, generates its own ephemeral pair, and calls
+ *     `POST /identity/move/:moveId/join { responderEphemeralPublicKey }` (no
+ *     bearer — Commons has no identity yet).
+ *  3. Both sides derive the same 6-digit SAS from the move id and BOTH ephemeral
+ *     keys and show it. The person confirms on the web that they match. A relay
+ *     that substituted either key produces two different codes.
+ *  4. The web seals the BIP-39 entropy under
+ *     `HKDF(ECDH(initiatorEph, responderEph), moveId, 'oxy-identity-move-v1')` and
+ *     calls `POST /identity/move/:moveId/seal` (bearer + identity-key proof).
+ *  5. Commons decrypts, imports the identity, and posts a RECEIPT: a signature by
+ *     the identity key over `{ action:'identity_move_received', moveId, timestamp }`
+ *     (`POST /identity/move/:moveId/receipt`). The server checks it against the
+ *     account's key; the WEB verifies it again locally before destroying its copy,
+ *     so not even the server can fake a completed move.
+ *
+ * The server holds two ephemeral public keys, an opaque ciphertext, and a
+ * receipt. It never holds anything that decrypts the ciphertext.
+ *
+ * Platform-agnostic — zod only, ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+/** A move lives this long: one interactive handoff. */
+export const IDENTITY_MOVE_TTL_MS = 5 * 60 * 1000;
+/** 128-bit move id, lowercase hex. */
+export const identityMoveIdSchema = z
+    .string()
+    .trim()
+    .regex(/^[0-9a-f]{32}$/, 'moveId must be 32 lowercase hex characters');
+/** An ephemeral secp256k1 public key, uncompressed lowercase hex. */
+export const identityMoveEphemeralKeySchema = z
+    .string()
+    .trim()
+    .regex(/^04[0-9a-f]{128}$/, 'ephemeral public key must be uncompressed, lowercase hex');
+export const IDENTITY_MOVE_STATUSES = ['pending', 'joined', 'sealed', 'completed', 'cancelled', 'expired'];
+/** The QR payload Commons scans. Carries the move id only. */
+export const IDENTITY_MOVE_QR_PREFIX = 'oxycommons://move?id=';
+export const identityMoveCreateRequestSchema = z.object({
+    initiatorEphemeralPublicKey: identityMoveEphemeralKeySchema,
+});
+export const identityMoveCreateResponseSchema = z.object({
+    moveId: identityMoveIdSchema,
+    expiresAt: z.string().datetime(),
+});
+export const identityMoveJoinRequestSchema = z.object({
+    responderEphemeralPublicKey: identityMoveEphemeralKeySchema,
+});
+export const identityMoveSealRequestSchema = z.object({
+    /** 24-byte XChaCha20-Poly1305 nonce, hex. */
+    nonce: z.string().trim().regex(/^[0-9a-f]{48}$/, 'nonce must be 48 lowercase hex characters'),
+    /** The 16-byte entropy, tag appended (32 bytes), hex. */
+    ciphertext: z.string().trim().regex(/^[0-9a-f]{64}$/, 'ciphertext must be 64 lowercase hex characters'),
+    /** Identity-key proof over `{ action:'identity_move_seal', moveId, timestamp }`. */
+    signature: z.string().trim().min(1).max(512),
+    timestamp: z.number().int().positive(),
+});
+export const identityMoveReceiptRequestSchema = z.object({
+    /** Identity-key signature over `{ action:'identity_move_received', moveId, timestamp }`. */
+    signature: z.string().trim().min(1).max(512),
+    timestamp: z.number().int().positive(),
+});
+export const identityMoveStateSchema = z.object({
+    moveId: identityMoveIdSchema,
+    status: z.enum(IDENTITY_MOVE_STATUSES),
+    publicKey: z.string().regex(/^04[0-9a-f]{128}$/),
+    initiatorEphemeralPublicKey: identityMoveEphemeralKeySchema,
+    responderEphemeralPublicKey: identityMoveEphemeralKeySchema.nullable(),
+    nonce: z.string().nullable(),
+    ciphertext: z.string().nullable(),
+    receiptSignature: z.string().nullable(),
+    receiptTimestamp: z.number().int().nullable(),
+    expiresAt: z.string().datetime(),
+});

package/dist/esm/index.js

@@ -13,7 +13,7 @@ export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKind
 export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, } from './username.js';
 export { 
 // Schemas
-userNameSchema, userRelationshipSchema, themePreferenceSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 
+userNameSchema, userRelationshipSchema, themePreferenceSchema, dateOfBirthSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 
 // Helpers
 resolveUserId, safeParseContract, } from './userResponse.js';
 export { 
@@ -81,6 +81,12 @@ export {
 // Schemas — encrypted off-device identity backup (b3 Feature 1)
 backupLookupIdSchema, encryptedBackupEnvelopeSchema, backupUploadRequestSchema, backupStatusResponseSchema, } from './keyRecovery.js';
 export { 
+// Schemas — web identity carrier (one identity, two carriers)
+WEB_IDENTITY_ENVELOPE_VERSION, webIdentityPublicKeySchema, webauthnCredentialIdSchema, webIdentityWrapSchema, webIdentityEnvelopeSchema, webIdentityEnvelopeUploadSchema, webIdentityEnvelopeResponseSchema, webIdentityEnvelopeProofSchema, webIdentityEnvelopePutSchema, webIdentityEnvelopeEstablishSchema, } from './webIdentityCarrier.js';
+export { 
+// Schemas — moving a web identity into Commons
+IDENTITY_MOVE_TTL_MS, IDENTITY_MOVE_STATUSES, IDENTITY_MOVE_QR_PREFIX, identityMoveIdSchema, identityMoveEphemeralKeySchema, identityMoveCreateRequestSchema, identityMoveCreateResponseSchema, identityMoveJoinRequestSchema, identityMoveSealRequestSchema, identityMoveReceiptRequestSchema, identityMoveStateSchema, } from './identityMove.js';
+export { 
 // Shared primitives
 updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, 
 // Assets: init + complete

package/dist/esm/inference/catalogue.js

@@ -134,12 +134,13 @@ export const inferenceDataPolicySchema = z
     }
 });
 /**
- * Who a route may be served to. Availability inside Alia never implies
- * permission to resell the same provider/model publicly, which is why this is
- * an explicit scope on the route rather than a boolean derived from "it works".
+ * Who a route may be served to. Availability to an official Oxy product never
+ * implies permission to resell the same provider/model publicly, which is why
+ * this is an explicit scope on the route rather than a boolean derived from
+ * "it works".
  */
 export const availabilityScopeSchema = z.enum([
-    'internal_alia',
+    'platform_internal',
     'public_payg',
     'enterprise',
     'byok_only',
@@ -332,7 +333,7 @@ export const inferenceProviderSchema = z.object({
 export const modelDeploymentSchema = z
     .object({
     /** See `version.ts`: exchanged with the data plane on its own. */
-    schemaVersion: z.literal(1),
+    schemaVersion: z.literal(2),
     deploymentId: deploymentIdSchema,
     provider: inferenceProviderSlugSchema,
     /** Always revision-pinned: a deployment serves specific weights. */
@@ -455,7 +456,7 @@ export const catalogueServingProviderSummarySchema = z
  */
 export const modelCatalogueEntrySchema = z.object({
     /** See `version.ts`: this is the public catalogue response shape. */
-    schemaVersion: z.literal(2),
+    schemaVersion: z.literal(3),
     modelId: modelIdSchema,
     publisher: cataloguePublisherSummarySchema,
     displayName: z.string().min(1).max(200),

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '2.0.0';
+export const INFERENCE_CONTRACT_VERSION = '3.0.0';

package/dist/esm/userResponse.js

@@ -47,6 +47,60 @@ export const themePreferenceSchema = z.object({
     mode: z.enum(['light', 'dark', 'system']),
     colorPreset: z.string(),
 });
+/**
+ * The earliest calendar year `dateOfBirthSchema` accepts.
+ *
+ * Not a real biological bound — it exists to catch an obviously-transposed
+ * year (`1027` for `2027`, a stray OCR/typo digit) with a clear message
+ * instead of the value quietly becoming a 150-year-old account. 1900 is
+ * generous enough that no living person's real birthdate is rejected by it.
+ */
+const MIN_BIRTH_YEAR = 1900;
+/**
+ * `true` when `year`/`month`/`day` name a date that actually exists on the
+ * Gregorian calendar — the check `z.string().regex(...)` alone cannot make,
+ * since the regex only constrains digit COUNT and would pass `2024-02-30`.
+ */
+function isRealCalendarDate(year, month, day) {
+    const isLeapYear = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const daysInMonth = [31, isLeapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth[month - 1];
+}
+/**
+ * A date of birth, `YYYY-MM-DD`, the sole structured representation this
+ * platform stores going forward (`users.date_of_birth` — see
+ * `packages/api/src/db/schema/users.ts`). `birthday` (below) stays as the
+ * legacy free-text field for backward compatibility with existing readers;
+ * this schema is what both the write path (`user.service.ts`) and the read
+ * path (nothing — a date of birth is owner-only, never echoed to another
+ * viewer) validate against.
+ *
+ * Three checks, in order, because a regex alone would accept a string-shaped
+ * lie:
+ *  1. Exactly `YYYY-MM-DD` — the wire format, nothing looser.
+ *  2. A real Gregorian date — rejects `2024-02-30`, a date the regex cannot see
+ *     is impossible.
+ *  3. Bounded to a plausible human lifetime — not before {@link MIN_BIRTH_YEAR}
+ *     and not after today (comparing the zero-padded ISO strings directly is
+ *     a valid, simpler stand-in for a numeric comparison here, since two
+ *     `YYYY-MM-DD` strings of equal length sort exactly the way their dates
+ *     do). "Today" is UTC — see `computeIsAdult` in `user.service.ts` for why
+ *     a date with no timezone of its own is evaluated in UTC rather than any
+ *     particular caller's local zone.
+ */
+export const dateOfBirthSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'dateOfBirth must be an ISO 8601 calendar date (YYYY-MM-DD)')
+    .refine((value) => {
+    const [year, month, day] = value.split('-').map(Number);
+    return isRealCalendarDate(year, month, day);
+}, { message: 'dateOfBirth is not a real calendar date' })
+    .refine((value) => Number(value.slice(0, 4)) >= MIN_BIRTH_YEAR, {
+    message: `dateOfBirth must not be before ${MIN_BIRTH_YEAR}`,
+})
+    .refine((value) => value <= new Date().toISOString().slice(0, 10), {
+    message: 'dateOfBirth must not be in the future',
+});
 /**
  * The canonical user object emitted by `formatUserResponse`.
  *
@@ -76,6 +130,26 @@ export const userResponseSchema = z
     phone: z.string().optional(),
     address: z.string().optional(),
     birthday: z.string().optional(),
+    /**
+     * Structured date of birth, `YYYY-MM-DD`. Present only on the
+     * account's OWN profile response (`GET /users/me`, `PUT /users/me`
+     * with `includePrivateFields`) — never on another account's profile,
+     * the same visibility `phone`/`address`/`birthday` already have. See
+     * {@link dateOfBirthSchema}.
+     */
+    dateOfBirth: dateOfBirthSchema.optional(),
+    /**
+     * Derived, non-PII signal: whether the account holder is at least 18
+     * (see `computeIsAdult` in `user.service.ts` for the exact threshold
+     * and the UTC-"today" choice). Computed fresh on every read — age
+     * changes daily, so this is never stored. `undefined` when
+     * `dateOfBirth` is unset ("unknown"), distinct from `false` ("known,
+     * not yet 18"). Rides the same owner-only visibility as
+     * `dateOfBirth`; a future pass may widen this specific field to
+     * other viewers without exposing the birthdate itself, but that is
+     * not decided here.
+     */
+    isAdult: z.boolean().optional(),
     /** Avatar file id (string) or null. */
     avatar: z.string().nullable().optional(),
     /** Named Bloom color preset (e.g. `"blue"`) or null. */
@@ -171,6 +245,13 @@ export const userProfileUpdateSchema = z
     phone: z.string().optional(),
     address: z.string().optional(),
     birthday: z.string().optional(),
+    /**
+     * Structured date of birth. `null` (or `''`, at the service layer)
+     * clears it. Independently settable from `birthday` — see
+     * `user.service.ts`'s `updateUserProfile` for why the two legacy and
+     * structured fields are not kept in sync with each other.
+     */
+    dateOfBirth: dateOfBirthSchema.nullable().optional(),
     locations: z.array(z.unknown()).optional(),
     links: z.array(z.string()).optional(),
     linksMetadata: z

package/dist/esm/webIdentityCarrier.js

@@ -0,0 +1,119 @@
+/**
+ * Web identity carrier contract — "one identity, two carriers".
+ *
+ * SINGLE SOURCE OF TRUTH for the sealed envelope that lets a browser carry an
+ * account's self-custody identity without Oxy ever holding it
+ * (`docs/superpowers/specs/2026-09-15-one-identity-two-carriers-design.md`).
+ *
+ * The identity is a BIP-39 mnemonic whose seed's first 32 bytes are the
+ * secp256k1 key — exactly the Commons derivation — so a web identity and a
+ * Commons identity are the same thing. On the web it travels as:
+ *
+ *   entropy (16 bytes) ── XChaCha20-Poly1305 under a random DEK ──▶ sealedEntropy
+ *   DEK ── XChaCha20-Poly1305 under KEK_i ──▶ wraps[i]
+ *   KEK_i = HKDF(PRF output of passkey i)
+ *
+ * The server stores the envelope and can open NONE of it: the PRF output never
+ * leaves the user's authenticator, and the mnemonic is never uploaded. The AEAD
+ * associated data binds every ciphertext to the identity's public key (and each
+ * wrap to its credential), so a re-labelled or transplanted envelope fails to
+ * open instead of decrypting into the wrong identity.
+ *
+ * Every hex field is lowercase-or-uppercase hex. Platform-agnostic — zod only,
+ * ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+/** The only envelope version. A scheme change is a new literal, never a mutation. */
+export const WEB_IDENTITY_ENVELOPE_VERSION = 1;
+const hex = (bytes, label) => z
+    .string()
+    .trim()
+    .regex(new RegExp(`^[0-9a-fA-F]{${bytes * 2}}$`), `${label} must be ${bytes * 2} hex characters`);
+/**
+ * The identity's secp256k1 public key in Oxy's canonical form: uncompressed SEC1
+ * (`04` + 64 bytes), lowercase hex — what `KeyManager.derivePublicKey` produces
+ * and `users.public_key` stores.
+ */
+export const webIdentityPublicKeySchema = z
+    .string()
+    .trim()
+    .regex(/^04[0-9a-f]{128}$/, 'publicKey must be an uncompressed, lowercase secp256k1 key (130 hex characters)');
+/** A WebAuthn credential id, base64url as the browser reports it. */
+export const webauthnCredentialIdSchema = z
+    .string()
+    .trim()
+    .min(16)
+    .max(1024)
+    .regex(/^[A-Za-z0-9_-]+$/, 'credentialId must be base64url');
+/** One passkey's wrap of the envelope's data key. */
+export const webIdentityWrapSchema = z.object({
+    credentialId: webauthnCredentialIdSchema,
+    /** 24-byte XChaCha20-Poly1305 nonce. */
+    nonce: hex(24, 'nonce'),
+    /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+    wrappedKey: hex(48, 'wrappedKey'),
+    createdAt: z.string().datetime(),
+});
+/**
+ * The sealed identity as it is stored (server copy and local copy alike).
+ *
+ * `wraps` holds one entry per passkey able to open it; at least one, and a
+ * bounded number so an envelope cannot grow without limit.
+ */
+export const webIdentityEnvelopeSchema = z.object({
+    version: z.literal(WEB_IDENTITY_ENVELOPE_VERSION),
+    algorithm: z.literal('xchacha20poly1305'),
+    publicKey: webIdentityPublicKeySchema,
+    /** 24-byte nonce of the entropy seal. */
+    entropyNonce: hex(24, 'entropyNonce'),
+    /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
+    sealedEntropy: hex(32, 'sealedEntropy'),
+    wraps: z.array(webIdentityWrapSchema).min(1).max(10),
+});
+/**
+ * `PUT /identity/web-envelope` — store or replace the caller's envelope.
+ *
+ * Refused unless `envelope.publicKey` is the identity key already linked to the
+ * account: an envelope can only ever carry the account's own identity.
+ */
+export const webIdentityEnvelopeUploadSchema = z.object({
+    envelope: webIdentityEnvelopeSchema,
+});
+/** `GET /identity/web-envelope` — the caller's envelope and its recovery-phrase state. */
+export const webIdentityEnvelopeResponseSchema = z.object({
+    envelope: webIdentityEnvelopeSchema.nullable(),
+    /**
+     * When the owner confirmed they wrote the recovery phrase down, or `null`.
+     * Until then the identity must not be unlocked on a second device, nor used
+     * for any operation that needs the key (design decision D2).
+     */
+    phraseConfirmedAt: z.string().datetime().nullable(),
+    updatedAt: z.string().datetime().nullable(),
+});
+/**
+ * `POST /identity/web-envelope/phrase-confirmed` and
+ * `DELETE /identity/web-envelope` both prove control of the identity key, not
+ * just a bearer: a stolen session must not be able to mark a phrase as saved or
+ * destroy the web copy of someone's identity.
+ *
+ * The signed message is `JSON.stringify({ action, userId, timestamp })` — the
+ * same scheme as `link_identity`.
+ */
+export const webIdentityEnvelopeProofSchema = z.object({
+    signature: z.string().trim().min(1).max(512),
+    timestamp: z.number().int().positive(),
+});
+/** `PUT /identity/web-envelope` body: the envelope plus a `web_envelope_put` identity-key proof. */
+export const webIdentityEnvelopePutSchema = webIdentityEnvelopeUploadSchema.extend(webIdentityEnvelopeProofSchema.shape);
+/**
+ * `POST /identity/web-envelope/establish` body — create an account's FIRST
+ * identity on the web: link the key and store its envelope in ONE transaction.
+ *
+ * Linking and storing as two calls would let a failure (or a closed tab) in
+ * between leave the account bound to a key that nothing carries — an identity
+ * lost at birth. `link` is a `link_identity` proof and the outer proof a
+ * `web_envelope_put` proof, both signed by the envelope's own key.
+ */
+export const webIdentityEnvelopeEstablishSchema = webIdentityEnvelopePutSchema.extend({
+    link: webIdentityEnvelopeProofSchema,
+});