@oxy.so/contracts 1.1.1 → 1.3.0

package/dist/cjs/inference/catalogue.js

@@ -137,12 +137,13 @@ exports.inferenceDataPolicySchema = zod_1.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".
  */
 exports.availabilityScopeSchema = zod_1.z.enum([
-    'internal_alia',
+    'platform_internal',
     'public_payg',
     'enterprise',
     'byok_only',
@@ -335,7 +336,7 @@ exports.inferenceProviderSchema = zod_1.z.object({
 exports.modelDeploymentSchema = zod_1.z
     .object({
     /** See `version.ts`: exchanged with the data plane on its own. */
-    schemaVersion: zod_1.z.literal(1),
+    schemaVersion: zod_1.z.literal(2),
     deploymentId: identifiers_1.deploymentIdSchema,
     provider: identifiers_1.inferenceProviderSlugSchema,
     /** Always revision-pinned: a deployment serves specific weights. */
@@ -458,7 +459,7 @@ exports.catalogueServingProviderSummarySchema = zod_1.z
  */
 exports.modelCatalogueEntrySchema = zod_1.z.object({
     /** See `version.ts`: this is the public catalogue response shape. */
-    schemaVersion: zod_1.z.literal(2),
+    schemaVersion: zod_1.z.literal(3),
     modelId: identifiers_1.modelIdSchema,
     publisher: exports.cataloguePublisherSummarySchema,
     displayName: zod_1.z.string().min(1).max(200),

package/dist/cjs/inference/identifiers.js

@@ -19,7 +19,7 @@
  * Decided in: docs/adr/0007-canonical-request-attribution.md, docs/adr/0008-catalogue-concept-separation.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESERVED_ALIA_PUBLISHER = exports.inferenceRegionSchema = exports.deploymentIdSchema = exports.inferenceProviderSlugSchema = exports.routingProfileIdSchema = exports.routingProfileSlugSchema = exports.modelReferenceSchema = exports.modelRevisionLabelSchema = exports.modelIdSchema = exports.modelSlugSchema = exports.publisherSlugSchema = exports.sha256DigestSchema = exports.inferenceHttpsUrlSchema = exports.inferenceDateSchema = exports.inferenceTimestampSchema = exports.inferenceEnvironmentSchema = exports.idempotencyKeySchema = exports.generationIdSchema = exports.requestIdSchema = exports.oxyCredentialIdSchema = exports.oxyApplicationIdSchema = exports.delegatedUserIdSchema = exports.oxyAccountIdSchema = void 0;
+exports.RESERVED_ALIA_PUBLISHER = exports.inferenceRegionSchema = exports.deploymentIdSchema = exports.inferenceProviderSlugSchema = exports.routingProfileIdSchema = exports.routingProfileSlugSchema = exports.modelReferenceSchema = exports.modelRevisionLabelSchema = exports.modelIdSchema = exports.modelSlugSchema = exports.publisherSlugSchema = exports.PADDED_BASE64_PATTERN = exports.sha256DigestSchema = exports.inferenceHttpsUrlSchema = exports.inferenceDateSchema = exports.inferenceTimestampSchema = exports.inferenceEnvironmentSchema = exports.idempotencyKeySchema = exports.generationIdSchema = exports.requestIdSchema = exports.oxyCredentialIdSchema = exports.oxyApplicationIdSchema = exports.delegatedUserIdSchema = exports.oxyAccountIdSchema = void 0;
 const zod_1 = require("zod");
 /* -------------------------------------------------------------------------- */
 /*  Principal identifiers                                                     */
@@ -129,6 +129,8 @@ exports.inferenceHttpsUrlSchema = zod_1.z
 exports.sha256DigestSchema = zod_1.z
     .string()
     .regex(/^sha256:[a-f0-9]{64}$/, 'digest must be sha256:<64 lowercase hex>');
+/** Standard base64 in whole, padded 4-character groups. */
+exports.PADDED_BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 /* -------------------------------------------------------------------------- */
 /*  Catalogue references                                                      */
 /* -------------------------------------------------------------------------- */

package/dist/cjs/inference/providerConnection.js

@@ -114,7 +114,7 @@ const kaanaCredentialSecretBase64Schema = zod_1.z
     .string()
     .min(1)
     .max(8192)
-    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/)
+    .regex(identifiers_1.PADDED_BASE64_PATTERN)
     .refine(isVisibleASCIIProviderCredential, {
     message: 'a decoded provider credential is 1-4096 visible ASCII bytes',
 });

package/dist/cjs/inference/request.js

@@ -25,7 +25,7 @@
  * docs/adr/0017-authorized-routes-in-the-envelope.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.inferenceRequestSchema = exports.clientRequestMetadataSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
+exports.inferenceRequestSchema = exports.inferenceSpeechParametersSchema = exports.clientRequestMetadataSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
 const zod_1 = require("zod");
 const attribution_1 = require("./attribution");
 const catalogue_1 = require("./catalogue");
@@ -314,6 +314,12 @@ const modelLineOf = (reference) => {
     const at = reference.indexOf("@");
     return at === -1 ? reference : reference.slice(0, at);
 };
+/** Parameters for text-to-speech, preserved in the signed request. */
+exports.inferenceSpeechParametersSchema = zod_1.z.object({
+    voice: zod_1.z.string().min(1).max(64),
+    responseFormat: zod_1.z.enum(["mp3", "opus", "aac", "flac", "wav", "pcm"]),
+    speed: zod_1.z.number().min(0.25).max(4).optional(),
+}).strict();
 /**
  * The canonical internal request Oxy forwards to the data plane.
  *
@@ -333,6 +339,7 @@ exports.inferenceRequestSchema = zod_1.z
     stream: zod_1.z.boolean(),
     maxOutputTokens: zod_1.z.number().int().positive().safe().optional(),
     sampling: exports.samplingParametersSchema,
+    speech: exports.inferenceSpeechParametersSchema.optional(),
     tools: zod_1.z.array(exports.toolDefinitionSchema).default([]),
     toolChoice: exports.toolChoiceSchema.optional(),
     responseFormat: exports.responseFormatSchema.optional(),
@@ -375,6 +382,13 @@ exports.inferenceRequestSchema = zod_1.z
     authorizedRoutes: zod_1.z.array(routingPolicy_1.authorizedRouteSchema).min(1).optional(),
 })
     .superRefine((request, ctx) => {
+    const isSpeech = request.client.apiFormat === "audio_speech";
+    if (isSpeech && request.speech !== undefined && (request.modality !== "audio" || request.input.format !== "text" || request.stream)) {
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["speech"], message: "speech requires audio modality, text input, parameters and non-streaming output" });
+    }
+    if (!isSpeech && request.speech !== undefined) {
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["speech"], message: "speech parameters require the audio_speech API format" });
+    }
     if (request.toolChoice !== undefined && request.tools.length === 0) {
         ctx.addIssue({
             code: zod_1.z.ZodIssueCode.custom,

package/dist/cjs/inference/streamEvents.js

@@ -3,7 +3,7 @@
  * Normalized stream events — what the data plane emits and the Oxy edge
  * forwards as SSE.
  *
- * One discriminated union, seven shapes, all carrying `requestId` and a
+ * One discriminated union, eight shapes, all carrying `requestId` and a
  * monotonic `sequence`. `requestId` is on EVERY event rather than only the
  * first because a proxy that re-frames or a client that reconnects would
  * otherwise be holding events it cannot attribute; `sequence` is what makes a
@@ -22,7 +22,7 @@
  * Decided in: docs/adr/0010-public-api-compatibility.md, docs/adr/0008-catalogue-concept-separation.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.inferenceStreamEventSchema = exports.inferenceStreamDoneEventSchema = exports.inferenceFinishReasonSchema = exports.inferenceStreamErrorEventSchema = exports.inferenceStreamRouteSwitchEventSchema = exports.inferenceRouteSwitchReasonSchema = exports.inferenceRouteSwitchDetailSchema = exports.inferenceStreamUsageEventSchema = exports.inferenceStreamToolCallEventSchema = exports.inferenceStreamDeltaEventSchema = exports.inferenceStreamStartEventSchema = void 0;
+exports.inferenceStreamEventSchema = exports.inferenceStreamDoneEventSchema = exports.inferenceFinishReasonSchema = exports.inferenceStreamErrorEventSchema = exports.inferenceStreamRouteSwitchEventSchema = exports.inferenceRouteSwitchReasonSchema = exports.inferenceRouteSwitchDetailSchema = exports.inferenceStreamUsageEventSchema = exports.inferenceStreamToolCallEventSchema = exports.inferenceStreamAudioEventSchema = exports.MAX_INFERENCE_AUDIO_BYTES = exports.inferenceAudioMediaTypeSchema = exports.inferenceStreamDeltaEventSchema = exports.inferenceStreamStartEventSchema = void 0;
 const zod_1 = require("zod");
 const identifiers_1 = require("./identifiers");
 const errors_1 = require("./errors");
@@ -65,6 +65,27 @@ exports.inferenceStreamDeltaEventSchema = zod_1.z.object({
     channel: zod_1.z.enum(['output_text', 'reasoning', 'refusal']),
     text: zod_1.z.string(),
 });
+/** The encodings an audio output may carry. */
+exports.inferenceAudioMediaTypeSchema = zod_1.z.enum([
+    'audio/mpeg',
+    'audio/wav',
+    'audio/ogg',
+    'audio/aac',
+    'audio/flac',
+    'audio/pcm',
+]);
+/** The most bytes one folded audio output may hold, at the edge and in the SDK. */
+exports.MAX_INFERENCE_AUDIO_BYTES = 20 * 1024 * 1024;
+/** A bounded, independently base64-encoded chunk of one audio output. */
+exports.inferenceStreamAudioEventSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    type: zod_1.z.literal('audio'),
+    requestId: identifiers_1.requestIdSchema,
+    sequence: zod_1.z.number().int().nonnegative().safe(),
+    outputIndex: zod_1.z.number().int().nonnegative().safe(),
+    mediaType: exports.inferenceAudioMediaTypeSchema,
+    data: zod_1.z.string().min(4).max(65536).regex(identifiers_1.PADDED_BASE64_PATTERN),
+});
 /**
  * A tool call being streamed.
  *
@@ -250,6 +271,7 @@ exports.inferenceStreamDoneEventSchema = zod_1.z.object({
 exports.inferenceStreamEventSchema = zod_1.z.discriminatedUnion('type', [
     exports.inferenceStreamStartEventSchema,
     exports.inferenceStreamDeltaEventSchema,
+    exports.inferenceStreamAudioEventSchema,
     exports.inferenceStreamToolCallEventSchema,
     exports.inferenceStreamUsageEventSchema,
     exports.inferenceStreamRouteSwitchEventSchema,

package/dist/cjs/inference/version.js

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

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.themePreferenceSchema = exports.userRelationshipSchema = exports.userNameSchema = void 0;
+exports.deviceLinkedSessionsResponseSchema = exports.deviceLinkedSessionSchema = exports.currentUserResponseSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.dateOfBirthSchema = exports.themePreferenceSchema = exports.userRelationshipSchema = exports.userNameSchema = void 0;
 exports.resolveUserId = resolveUserId;
 exports.safeParseContract = safeParseContract;
 const zod_1 = require("zod");
@@ -52,6 +52,60 @@ exports.themePreferenceSchema = zod_1.z.object({
     mode: zod_1.z.enum(['light', 'dark', 'system']),
     colorPreset: zod_1.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.
+ */
+exports.dateOfBirthSchema = zod_1.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`.
  *
@@ -81,6 +135,26 @@ exports.userResponseSchema = zod_1.z
     phone: zod_1.z.string().optional(),
     address: zod_1.z.string().optional(),
     birthday: zod_1.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: exports.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: zod_1.z.boolean().optional(),
     /** Avatar file id (string) or null. */
     avatar: zod_1.z.string().nullable().optional(),
     /** Named Bloom color preset (e.g. `"blue"`) or null. */
@@ -176,6 +250,13 @@ exports.userProfileUpdateSchema = zod_1.z
     phone: zod_1.z.string().optional(),
     address: zod_1.z.string().optional(),
     birthday: zod_1.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: exports.dateOfBirthSchema.nullable().optional(),
     locations: zod_1.z.array(zod_1.z.unknown()).optional(),
     links: zod_1.z.array(zod_1.z.string()).optional(),
     linksMetadata: zod_1.z

package/dist/cjs/username.js

@@ -100,7 +100,7 @@
  * knows what is taken, and it must not pretend to.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.botUsernameSchema = exports.BOT_USERNAME_INVALID_MESSAGE = exports.BOT_USERNAME_SUFFIX = exports.usernameSchema = exports.USERNAME_PATTERN_SOURCE = exports.USERNAME_INVALID_MESSAGE = exports.USERNAME_MAX_LENGTH = exports.USERNAME_MIN_LENGTH = void 0;
+exports.botUsernameSchema = exports.BOT_USERNAME_INVALID_MESSAGE = exports.BOT_USERNAME_SUFFIX = exports.usernameSchema = exports.USERNAME_PATTERN_SOURCE = exports.NUMERIC_USERNAME_MESSAGE = exports.RESERVED_USERNAME_MESSAGE = exports.RESERVED_USERNAMES = exports.USERNAME_INVALID_MESSAGE = exports.USERNAME_MAX_LENGTH = exports.USERNAME_MIN_LENGTH = void 0;
 exports.isValidUsername = isValidUsername;
 exports.stripDisallowedUsernameCharacters = stripDisallowedUsernameCharacters;
 exports.usernameSchemaForAccountKind = usernameSchemaForAccountKind;
@@ -113,6 +113,71 @@ exports.USERNAME_MAX_LENGTH = 30;
 /** The 400 / inline-validation copy for every path that rejects a handle. */
 exports.USERNAME_INVALID_MESSAGE = 'Username must be 3-30 characters, use only letters, numbers, hyphens and underscores, ' +
     'start and end with a letter or number, and never repeat a separator';
+/**
+ * Exact-match handles nobody may newly claim, regardless of account kind.
+ *
+ * This is NOT a namespace tightening like the bot suffix — it is a list of
+ * names withheld from `users_lower_username_key` before anybody asks for
+ * them. Compared against the same normalization the unique index applies
+ * (`lower(btrim(username))`), so `Admin`, ` ADMIN ` and `admin` are the one
+ * name this list means.
+ *
+ * `oxy`, `mention`, `homiio`, `clarity`, `faircoin`, `astro` and `mercaria`
+ * are deliberately NOT here: each already has an `organization`/`project`
+ * row, so the unique index already refuses a second one, and `oxy` is the
+ * name `USERNAME_MIN_LENGTH` is pinned against in
+ * `__tests__/username.test.ts` — listing it would make
+ * `usernameSchema.safeParse('oxy')` fail and falsify that comment. A brand
+ * with no account of its own yet (measured 2026-09-18: Alia, Allo, TNP,
+ * Kaana, Bloom) has no row to protect it, so it is listed until one exists.
+ */
+exports.RESERVED_USERNAMES = new Set([
+    // Oxy product lines with no account row of their own yet.
+    'alia',
+    'allo',
+    'tnp',
+    'kaana',
+    'bloom',
+    // System / role words a signup impersonating staff or Oxy itself would reach for.
+    'admin',
+    'administrator',
+    'root',
+    'superadmin',
+    'super',
+    'superuser',
+    'support',
+    'staff',
+    'moderator',
+    'mod',
+    'security',
+    'system',
+    'official',
+    'help',
+    'noreply',
+    'anonymous',
+    'everyone',
+    'owner',
+]);
+/** The 400 / inline-validation copy for a handle on {@link RESERVED_USERNAMES}. */
+exports.RESERVED_USERNAME_MESSAGE = 'This username is reserved and cannot be registered';
+/**
+ * {@link RESERVED_USERNAMES}, minus `alia`, checked against each `-`/`_`
+ * separated SEGMENT of a candidate rather than the whole string — so
+ * `official-oxy`, `super-admin` and `team-kaana` are refused the same as the
+ * bare words, without banning every word that merely CONTAINS one as a
+ * substring (`superman`, `modern`, `grassroot`, `homeowner` all stay legal:
+ * none of them separates the reserved word from the rest with `-` or `_`).
+ *
+ * `alia` is excluded because `alia-` is the live internal-cost-centre
+ * namespace: `alia-production-chat` is a minted account and
+ * `alia-research` / `alia-voice` / `alia-evaluations` are pinned as legal
+ * slugs in `__tests__/username.test.ts` and `internalCostCenterSpecs.test.ts`.
+ * Segment-matching `alia` would refuse all four. The bare word `alia` is
+ * still refused — {@link RESERVED_USERNAMES} above catches it exactly.
+ */
+const RESERVED_USERNAME_SEGMENTS = new Set([...exports.RESERVED_USERNAMES].filter((word) => word !== 'alia'));
+/** The 400 / inline-validation copy for a handle that is only digits. */
+exports.NUMERIC_USERNAME_MESSAGE = 'Username cannot be only numbers';
 /**
  * Alphanumeric runs joined by single separators, as a SOURCE string.
  *
@@ -149,7 +214,10 @@ exports.usernameSchema = zod_1.z
     .trim()
     .min(exports.USERNAME_MIN_LENGTH, exports.USERNAME_INVALID_MESSAGE)
     .max(exports.USERNAME_MAX_LENGTH, exports.USERNAME_INVALID_MESSAGE)
-    .regex(USERNAME_PATTERN, exports.USERNAME_INVALID_MESSAGE);
+    .regex(USERNAME_PATTERN, exports.USERNAME_INVALID_MESSAGE)
+    .refine((username) => !/^[0-9]+$/.test(username), exports.NUMERIC_USERNAME_MESSAGE)
+    .refine((username) => !exports.RESERVED_USERNAMES.has(username.toLowerCase()), exports.RESERVED_USERNAME_MESSAGE)
+    .refine((username) => !username.split(/[-_]/).some((segment) => RESERVED_USERNAME_SEGMENTS.has(segment.toLowerCase())), exports.RESERVED_USERNAME_MESSAGE);
 /**
  * Whether a candidate handle is storable — the boolean form, for input surfaces
  * that show a message as somebody types rather than throwing.

package/dist/cjs/webIdentityCarrier.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webIdentityEnvelopeEstablishSchema = exports.webauthnAssertionResponseSchema = exports.webIdentityEnvelopePutSchema = exports.webIdentityEnvelopeActionSchema = exports.webIdentityEnvelopeProofFieldsSchema = exports.webIdentityEnvelopeResponseSchema = exports.webIdentityHolderSchema = exports.webIdentityEnvelopeUploadSchema = exports.webIdentityEnvelopeSchema = exports.webIdentityWrapSchema = exports.webauthnRpIdSchema = exports.webauthnCredentialIdSchema = exports.webIdentityPublicKeySchema = exports.WEB_IDENTITY_SECRET_KINDS = exports.WEB_IDENTITY_ENVELOPE_VERSION = void 0;
+/**
+ * Web identity holder contract — the sealed envelope that lets a browser hold an
+ * account's self-custody root without Oxy ever being able to use it (ADR 0024).
+ *
+ * A root is a BIP-39 phrase (12–24 words) whose seed's first 32 bytes are the
+ * secp256k1 key — exactly the Commons derivation — or, for a few imported
+ * identities, a raw private key that never had a phrase. On the web it travels as:
+ *
+ *   secret ── XChaCha20-Poly1305 under a random DEK ──▶ sealedSecret
+ *   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 secret is never uploaded. The AEAD
+ * associated data binds the secret to the root's public key and kind, and each
+ * wrap to its credential and RP ID, so a re-labelled or transplanted envelope
+ * fails to open instead of decrypting into the wrong identity.
+ *
+ * Platform-agnostic — zod only, ESM-safe (no `require()`).
+ */
+const zod_1 = require("zod");
+const identityProof_1 = require("./identityProof");
+/** The envelope scheme. A scheme change is a new literal, never a mutation. */
+exports.WEB_IDENTITY_ENVELOPE_VERSION = 2;
+/**
+ * What an envelope seals. A raw-key identity stays a raw-key identity:
+ * nothing ever derives or displays a phrase for it.
+ */
+exports.WEB_IDENTITY_SECRET_KINDS = ['mnemonic-entropy', 'raw-private-key'];
+const hex = (bytes, label) => zod_1.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.
+ */
+exports.webIdentityPublicKeySchema = zod_1.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. */
+exports.webauthnCredentialIdSchema = zod_1.z
+    .string()
+    .trim()
+    .min(16)
+    .max(1024)
+    .regex(/^[A-Za-z0-9_-]+$/, 'credentialId must be base64url');
+/** A WebAuthn RP ID: a bare registrable host name, lowercase. */
+exports.webauthnRpIdSchema = zod_1.z
+    .string()
+    .trim()
+    .min(1)
+    .max(253)
+    .regex(/^(localhost|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+)$/, 'rpId must be a lowercase host name');
+/** One passkey's wrap of the envelope's data key. */
+exports.webIdentityWrapSchema = zod_1.z.object({
+    credentialId: exports.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: zod_1.z.string().datetime(),
+    /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+    rpId: exports.webauthnRpIdSchema,
+    /**
+     * When this passkey's PRF output was shown to open the envelope. A wrap is a
+     * root HOLDER only once this is set; a login passkey never is by default.
+     */
+    verifiedAt: zod_1.z.string().datetime().optional(),
+});
+/**
+ * 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.
+ */
+exports.webIdentityEnvelopeSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(exports.WEB_IDENTITY_ENVELOPE_VERSION),
+    algorithm: zod_1.z.literal('xchacha20poly1305'),
+    publicKey: exports.webIdentityPublicKeySchema,
+    secretKind: zod_1.z.enum(exports.WEB_IDENTITY_SECRET_KINDS),
+    /** 24-byte nonce of the secret seal. */
+    secretNonce: hex(24, 'secretNonce'),
+    /**
+     * The sealed secret, tag appended: 16/20/24/28/32 bytes of BIP-39 entropy
+     * (12–24 words) or a 32-byte private key, plus 16.
+     */
+    sealedSecret: zod_1.z
+        .string()
+        .trim()
+        .regex(/^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{72}|[0-9a-fA-F]{80}|[0-9a-fA-F]{88}|[0-9a-fA-F]{96})$/, 'sealedSecret has an unsupported length'),
+    wraps: zod_1.z.array(exports.webIdentityWrapSchema).min(1).max(10),
+})
+    .refine((envelope) => envelope.secretKind === 'mnemonic-entropy' || envelope.sealedSecret.length === 96, {
+    message: 'a raw private key seals to 48 bytes',
+    path: ['sealedSecret'],
+});
+/**
+ * `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.
+ */
+exports.webIdentityEnvelopeUploadSchema = zod_1.z.object({
+    envelope: exports.webIdentityEnvelopeSchema,
+});
+/** A root holder as the status read reports it — metadata only, nothing that opens anything. */
+exports.webIdentityHolderSchema = zod_1.z.object({
+    credentialId: exports.webauthnCredentialIdSchema,
+    rpId: exports.webauthnRpIdSchema,
+    verifiedAt: zod_1.z.string().datetime().nullable(),
+    createdAt: zod_1.z.string().datetime(),
+});
+/**
+ * `GET /identity/web-envelope` — the caller's envelope and the readiness facts
+ * ADR 0024 D5 keeps separate. A client decides what to show from these fields
+ * WITHOUT decrypting anything.
+ */
+exports.webIdentityEnvelopeResponseSchema = zod_1.z.object({
+    envelope: exports.webIdentityEnvelopeSchema.nullable(),
+    /** The revision a write must name as `expectedRevision`; `0` when there is no envelope. */
+    revision: zod_1.z.number().int().nonnegative(),
+    /** Whether the account has a linked root at all (it may live only in Commons). */
+    rootLinked: zod_1.z.boolean(),
+    /** The web wraps, as metadata. */
+    holders: zod_1.z.array(exports.webIdentityHolderSchema),
+    /** When the owner confirmed the recovery material is written down, or `null`. */
+    phraseConfirmedAt: zod_1.z.string().datetime().nullable(),
+    /** When the recovery material was shown to re-derive this root, or `null`. */
+    recoveryVerifiedAt: zod_1.z.string().datetime().nullable(),
+    updatedAt: zod_1.z.string().datetime().nullable(),
+});
+/** A root proof, plus the envelope revision the write expects to replace. */
+exports.webIdentityEnvelopeProofFieldsSchema = zod_1.z.object({
+    proof: identityProof_1.identityProofSchema,
+    expectedRevision: zod_1.z.number().int().nonnegative(),
+});
+/**
+ * `POST /identity/web-envelope/phrase-confirmed`, `/recovery-verified` and
+ * `DELETE /identity/web-envelope` prove control of the root, not just a bearer.
+ */
+exports.webIdentityEnvelopeActionSchema = exports.webIdentityEnvelopeProofFieldsSchema.strict();
+/** `PUT /identity/web-envelope` body. */
+exports.webIdentityEnvelopePutSchema = exports.webIdentityEnvelopeUploadSchema.extend(exports.webIdentityEnvelopeProofFieldsSchema.shape).strict();
+/**
+ * A WebAuthn assertion by one of the account's EXISTING passkeys whose
+ * `clientDataJSON.challenge` is the proof challenge — the fresh use of the
+ * existing factor a keyless account needs before its first root is linked.
+ */
+exports.webauthnAssertionResponseSchema = zod_1.z
+    .object({
+    id: exports.webauthnCredentialIdSchema,
+    rawId: zod_1.z.string().min(1).max(2048),
+    type: zod_1.z.literal('public-key'),
+    response: zod_1.z
+        .object({
+        clientDataJSON: zod_1.z.string().min(1).max(8192),
+        authenticatorData: zod_1.z.string().min(1).max(8192),
+        signature: zod_1.z.string().min(1).max(2048),
+        userHandle: zod_1.z.string().max(2048).optional(),
+    })
+        .passthrough(),
+    clientExtensionResults: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    authenticatorAttachment: zod_1.z.string().optional(),
+})
+    .passthrough();
+/**
+ * `POST /identity/web-envelope/establish` body — an account's FIRST root, linked
+ * and stored with its envelope in ONE transaction: one root proof
+ * (`web_envelope_establish`, digest of the envelope) plus a fresh `assertion` by
+ * an existing passkey over the same challenge.
+ */
+exports.webIdentityEnvelopeEstablishSchema = exports.webIdentityEnvelopeUploadSchema
+    .extend({ proof: identityProof_1.identityProofSchema, assertion: exports.webauthnAssertionResponseSchema })
+    .strict();

package/dist/cjs/webauthn.js

@@ -14,6 +14,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = void 0;
 const zod_1 = require("zod");
+const identityProof_1 = require("./identityProof");
+const webIdentityCarrier_1 = require("./webIdentityCarrier");
 /**
  * Device-session options shared by every first-party sign-in body
  * (`deviceName`/`deviceFingerprint`). Mirrors what
@@ -59,6 +61,18 @@ exports.webauthnLoginOptionsRequestSchema = zod_1.z.object({
  */
 exports.webauthnRegisterVerifyRequestSchema = zod_1.z.object({
     username: zod_1.z.string().trim().min(1).max(60).optional(),
+    /**
+     * Sign-up only (ADR 0024 D4): the account's root, created on the holder BEFORE
+     * this request — sealed under the passkey being registered — and a root proof
+     * (`enroll_identity`) whose challenge is the registration challenge. The
+     * account, passkey, root and envelope are then created in one transaction.
+     */
+    identity: zod_1.z
+        .object({
+        envelope: webIdentityCarrier_1.webIdentityEnvelopeSchema,
+        proof: identityProof_1.identityProofSchema,
+    })
+        .optional(),
     ...deviceSessionEnvelope,
 });
 /**