@oxy.so/contracts 1.1.1 → 1.3.0

package/dist/esm/identity.js

@@ -14,8 +14,9 @@
  *  - DID = `did:web:oxy.so:u:<userId>` — anchored on the stable account id, NOT
  *    the keypair. The keypair is a *verification method* that maps 1:1 to the
  *    existing `authMethods[]`. Custodial (password-only) users get a DID
- *    controlled solely by Oxy (`OXY_DID`); creating a Commons key upgrades them
- *    to self-sovereign (`controller = [userDid, OXY_DID]`); fully reversible.
+ *    controlled solely by Oxy (`OXY_DID`); linking a root makes them
+ *    self-sovereign (`controller = [userDid]`, ADR 0024 D9). A root is never
+ *    unlinked back into a custodial account.
  *  - Verification methods use the secp256k1 `EcdsaSecp256k1VerificationKey2019`
  *    type with `publicKeyHex` for now (a `Multikey`/`publicKeyMultibase` form may
  *    be added later — see the plan's open risks).

package/dist/esm/identityMove.js

@@ -0,0 +1,148 @@
+/**
+ * Identity move contract — give a web root to Commons (add it, or keep it only in
+ * Commons; ADR 0024 D6).
+ *
+ * The web (holding the root) shows a QR carrying only a move id; Commons scans.
+ * The relay in between must not be able to take the root, so:
+ *
+ *  1. `POST /identity/move { initiatorCommitment }` — the web publishes only
+ *     `H(initiatorKey, nonce)`, never the key.
+ *  2. `POST /identity/move/:moveId/join { responderEphemeralPublicKey }` —
+ *     Commons, having read the commitment first, joins with its own key.
+ *  3. `POST /identity/move/:moveId/reveal` — only then does the web reveal its
+ *     key and nonce; Commons checks them against the commitment it read.
+ *  4. Both screens show a 6-digit code over `(moveId, both keys, commitment)`;
+ *     the person confirms on the web that they match.
+ *  5. `POST /identity/move/:moveId/seal` — the web seals the phrase entropy under
+ *     `HKDF(ECDH(both keys), moveId)`, authorized by a one-use root proof over the
+ *     exact sealed bytes.
+ *  6. `POST /identity/move/:moveId/receipt` — Commons stores the root, reads it
+ *     back from its keychain, and signs a receipt over the move, the root, both
+ *     keys and the digest of the ciphertext it opened. The server verifies it; the
+ *     web verifies it again from what IT sealed before removing anything.
+ *
+ * Why the commitment: without it the relay sees both keys before committing to
+ * anything and can grind a substituted key until the two codes agree (~10⁶
+ * tries, seconds). With it, the relay must fix the key it shows Commons before
+ * learning Commons' key, and the key it shows the web before the web reveals.
+ *
+ * The server holds a commitment, two ephemeral public keys, an opaque ciphertext
+ * and a receipt — nothing that decrypts the ciphertext.
+ *
+ * Platform-agnostic — zod only, ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+import { canonicalJson, identityProofSchema } from './identityProof.js';
+/** 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=';
+const hex64 = (label) => z.string().trim().regex(/^[0-9a-f]{64}$/, `${label} must be 64 lowercase hex characters`);
+export const identityMoveCreateRequestSchema = z
+    .object({
+    /** `H(initiator ephemeral key, nonce)` — the key itself is revealed only after Commons joins. */
+    initiatorCommitment: hex64('initiatorCommitment'),
+})
+    .strict();
+export const identityMoveCreateResponseSchema = z.object({
+    moveId: identityMoveIdSchema,
+    expiresAt: z.string().datetime(),
+});
+export const identityMoveJoinRequestSchema = z.object({
+    responderEphemeralPublicKey: identityMoveEphemeralKeySchema,
+});
+/** After Commons joined: the committed key and its nonce. */
+export const identityMoveRevealRequestSchema = z
+    .object({
+    initiatorEphemeralPublicKey: identityMoveEphemeralKeySchema,
+    commitmentNonce: hex64('commitmentNonce'),
+})
+    .strict();
+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–32-byte phrase entropy (12–24 words), tag appended, hex. */
+    ciphertext: z
+        .string()
+        .trim()
+        .regex(/^(?:[0-9a-f]{64}|[0-9a-f]{72}|[0-9a-f]{80}|[0-9a-f]{88}|[0-9a-f]{96})$/, 'ciphertext has an unsupported length'),
+    /**
+     * Root proof (`identity_move_seal`), payload `{ moveId, nonce, ciphertext }`,
+     * over a one-use challenge from `POST /identity/proof-challenge`.
+     */
+    proof: identityProofSchema,
+})
+    .strict();
+export const identityMoveReceiptRequestSchema = z
+    .object({
+    /** Root signature over `buildMoveReceiptMessage(...)`. */
+    signature: z.string().trim().min(1).max(512),
+})
+    .strict();
+export const identityMoveStateSchema = z.object({
+    moveId: identityMoveIdSchema,
+    status: z.enum(IDENTITY_MOVE_STATUSES),
+    initiatorCommitment: z.string(),
+    initiatorCommitmentNonce: z.string().nullable(),
+    publicKey: z.string().regex(/^04[0-9a-f]{128}$/),
+    initiatorEphemeralPublicKey: identityMoveEphemeralKeySchema.nullable(),
+    responderEphemeralPublicKey: identityMoveEphemeralKeySchema.nullable(),
+    nonce: z.string().nullable(),
+    ciphertext: z.string().nullable(),
+    receiptSignature: z.string().nullable(),
+    expiresAt: z.string().datetime(),
+});
+/**
+ * The initiator's commitment input, `canonicalJson({ v, purpose, key, nonce })`,
+ * which the caller hashes with SHA-256.
+ */
+export function buildMoveCommitmentInput(initiatorEphemeralPublicKey, nonce) {
+    return canonicalJson({
+        v: 2,
+        purpose: 'oxy-identity-move-initiator-commitment',
+        initiatorEphemeralPublicKey: initiatorEphemeralPublicKey.toLowerCase(),
+        nonce: nonce.toLowerCase(),
+    });
+}
+/** The bytes both sides hash for the 6-digit code. */
+export function buildMoveSasInput(input) {
+    return canonicalJson({
+        v: 'oxy-identity-transfer-sas-v2',
+        moveId: input.moveId.toLowerCase(),
+        initiator: input.initiatorEphemeralPublicKey.toLowerCase(),
+        responder: input.responderEphemeralPublicKey.toLowerCase(),
+        commitment: input.initiatorCommitment.toLowerCase(),
+    });
+}
+/** The ciphertext digest input the receipt binds: `canonicalJson({ nonce, ciphertext })`. */
+export function buildMoveCiphertextDigestInput(sealed) {
+    return canonicalJson({ nonce: sealed.nonce.toLowerCase(), ciphertext: sealed.ciphertext.toLowerCase() });
+}
+/** The payload a seal proof digests. */
+export function buildMoveSealPayload(moveId, sealed) {
+    return { moveId: moveId.toLowerCase(), nonce: sealed.nonce.toLowerCase(), ciphertext: sealed.ciphertext.toLowerCase() };
+}
+/** The exact bytes a receipt signs. */
+export function buildMoveReceiptMessage(input) {
+    return canonicalJson({
+        v: 2,
+        domain: 'oxy-identity-move-receipt',
+        moveId: input.moveId.toLowerCase(),
+        rootPublicKey: input.rootPublicKey.toLowerCase(),
+        initiator: input.initiatorEphemeralPublicKey.toLowerCase(),
+        responder: input.responderEphemeralPublicKey.toLowerCase(),
+        ciphertextDigest: input.ciphertextDigest.toLowerCase(),
+    });
+}

package/dist/esm/identityProof.js

@@ -0,0 +1,159 @@
+/**
+ * Identity proof contract — the ONE signed format for operations on a personal root.
+ *
+ * ADR 0024 D7. A proof is a signature by the root key over the canonical bytes
+ * of {@link IdentityProofClaims}. Every field the verifier cares about is IN the
+ * signed bytes, so a signature cannot be moved to another operation, account,
+ * root, payload, revision or audience, and the one-use `challenge` means it
+ * cannot be replayed either (a timestamp window is not replay protection).
+ *
+ * Both sides build the bytes with {@link buildIdentityProofMessage} and hash
+ * payloads with {@link canonicalJson}; neither writes its own JSON template, so
+ * the client and the verifier cannot drift apart.
+ *
+ * Platform-agnostic — zod only, ESM-safe (no `require()`), no hashing here (the
+ * caller hashes `canonicalJson(payload)` with SHA-256 using its platform's
+ * primitive and passes the hex digest in).
+ */
+import { z } from 'zod';
+export const IDENTITY_PROOF_VERSION = 2;
+export const IDENTITY_PROOF_DOMAIN = 'oxy-identity-proof';
+/** The audience every API-verified identity proof names. */
+export const IDENTITY_PROOF_AUDIENCE = 'oxy-api/identity';
+/** How long a proof challenge lives: one interactive ceremony. */
+export const IDENTITY_PROOF_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Everything a root proof may authorize. A challenge is minted for exactly one
+ * action and spent only by a proof for that action.
+ */
+export const IDENTITY_PROOF_ACTIONS = {
+    /** A keyless account's FIRST root, stored with its web envelope. */
+    establish: 'web_envelope_establish',
+    /** Replace the web envelope (add or remove a wrap, re-seal). */
+    put: 'web_envelope_put',
+    /** Record that the recovery material is written down. */
+    phraseConfirmed: 'web_envelope_phrase_confirmed',
+    /** Record that the recovery material re-derived the root. */
+    recoveryVerified: 'web_envelope_recovery_verified',
+    /** Remove the web holder. */
+    delete: 'web_envelope_delete',
+    /** Link a keyless account's first root without a web envelope (`POST /auth/link`). */
+    link: 'link_identity',
+    /** Create a personal account together with its root (passkey sign-up). */
+    enroll: 'enroll_identity',
+    /** Prove the root to start signed-out recovery. */
+    recoverStart: 'recover_account_start',
+    /** Bind the new passkey and envelope when completing signed-out recovery. */
+    recoverComplete: 'recover_account_complete',
+    /** Seal the root for the Commons device that joined a move (payload: move id + sealed bytes). */
+    moveSeal: 'identity_move_seal',
+};
+export const IDENTITY_PROOF_ACTION_VALUES = Object.values(IDENTITY_PROOF_ACTIONS);
+const HEX_DIGEST = /^[0-9a-f]{64}$/;
+const ROOT_KEY = /^04[0-9a-f]{128}$/;
+const CHALLENGE = /^[0-9a-f]{64}$/;
+/**
+ * Canonical JSON: object keys sorted by UTF-16 code unit, no whitespace,
+ * `undefined` members omitted, arrays in order. Numbers must be finite. This is
+ * the ONLY serializer for anything digested into a proof.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new Error('canonicalJson: non-finite number');
+            return JSON.stringify(value);
+        case 'object': {
+            if (Array.isArray(value)) {
+                return `[${value.map((entry) => (entry === undefined ? 'null' : canonicalJson(entry))).join(',')}]`;
+            }
+            const record = value;
+            const keys = Object.keys(record)
+                .filter((key) => record[key] !== undefined)
+                .sort();
+            return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+        }
+        default:
+            throw new Error(`canonicalJson: unsupported ${typeof value}`);
+    }
+}
+/**
+ * The exact bytes a root signs. Throws on a malformed claim rather than signing
+ * (or verifying) something ambiguous.
+ */
+export function buildIdentityProofMessage(claims) {
+    if (!IDENTITY_PROOF_ACTION_VALUES.includes(claims.action))
+        throw new Error('identity proof: unknown action');
+    if (!claims.subject || !claims.actor)
+        throw new Error('identity proof: subject and actor are required');
+    if (!ROOT_KEY.test(claims.rootPublicKey))
+        throw new Error('identity proof: rootPublicKey must be canonical');
+    if (claims.payloadDigest !== null && !HEX_DIGEST.test(claims.payloadDigest)) {
+        throw new Error('identity proof: payloadDigest must be a lowercase SHA-256 hex digest');
+    }
+    if (claims.expectedRevision !== null && (!Number.isSafeInteger(claims.expectedRevision) || claims.expectedRevision < 0)) {
+        throw new Error('identity proof: expectedRevision must be a non-negative integer');
+    }
+    if (!CHALLENGE.test(claims.challenge))
+        throw new Error('identity proof: challenge must be 64 lowercase hex characters');
+    if (!Number.isSafeInteger(claims.expiresAt) || claims.expiresAt <= 0)
+        throw new Error('identity proof: expiresAt must be unix milliseconds');
+    return canonicalJson({
+        v: IDENTITY_PROOF_VERSION,
+        domain: IDENTITY_PROOF_DOMAIN,
+        action: claims.action,
+        subject: claims.subject,
+        actor: claims.actor,
+        rootPublicKey: claims.rootPublicKey,
+        payloadDigest: claims.payloadDigest,
+        expectedRevision: claims.expectedRevision,
+        audience: claims.audience,
+        challenge: claims.challenge,
+        expiresAt: claims.expiresAt,
+    });
+}
+/** The proof as it travels: the signature plus the two claims the verifier cannot derive. */
+export const identityProofSchema = z.object({
+    v: z.literal(IDENTITY_PROOF_VERSION),
+    challenge: z.string().trim().regex(CHALLENGE, 'challenge must be 64 lowercase hex characters'),
+    expiresAt: z.number().int().positive(),
+    signature: z.string().trim().min(1).max(512),
+});
+/** `POST /identity/proof-challenge` */
+export const identityProofChallengeRequestSchema = z.object({
+    action: z.enum(IDENTITY_PROOF_ACTION_VALUES),
+});
+export const identityProofChallengeResponseSchema = z.object({
+    challenge: z.string().regex(CHALLENGE),
+    expiresAt: z.number().int().positive(),
+    audience: z.string().min(1),
+});
+/**
+ * Stable error codes the root routes answer with (`error.code` in the API error
+ * body). Clients map these through their localization, never the English message.
+ */
+export const IDENTITY_ERROR_CODES = {
+    proofInvalid: 'IDENTITY_PROOF_INVALID',
+    revisionConflict: 'IDENTITY_ENVELOPE_REVISION_CONFLICT',
+    rootAlreadyLinked: 'IDENTITY_ROOT_ALREADY_LINKED',
+    rootLinkedElsewhere: 'IDENTITY_ROOT_LINKED_ELSEWHERE',
+    noRoot: 'IDENTITY_NO_ROOT',
+    freshFactorRequired: 'IDENTITY_FRESH_FACTOR_REQUIRED',
+    lastWebHolder: 'IDENTITY_LAST_WEB_HOLDER',
+    enrollmentRequired: 'IDENTITY_ENROLLMENT_REQUIRED',
+    enrollmentInvalid: 'IDENTITY_ENROLLMENT_INVALID',
+    notPersonal: 'IDENTITY_NOT_PERSONAL_ACCOUNT',
+    recoveryFailed: 'IDENTITY_RECOVERY_FAILED',
+};
+export const identityRootStatusSchema = z.object({
+    rootLinked: z.boolean(),
+    webHolder: z.object({ passkeys: z.number().int().nonnegative(), verifiedPasskeys: z.number().int().nonnegative() }).nullable(),
+    hasPhrase: z.boolean().nullable(),
+    phraseConfirmedAt: z.string().datetime().nullable(),
+    recoveryVerifiedAt: z.string().datetime().nullable(),
+});

package/dist/esm/identityRecovery.js

@@ -0,0 +1,48 @@
+/**
+ * Signed-out recovery contract (ADR 0024 D5) — get an EXISTING account back from
+ * its root alone, with no passkey, session or email.
+ *
+ *  1. `POST /identity/recovery/challenge` → a one-use challenge. It says nothing
+ *     about any account.
+ *  2. The holder derives the root locally from recovery material (12/24 words or a
+ *     raw key) and signs `recover_account_start` over that challenge:
+ *     `POST /identity/recovery/start { publicKey, proof }`. Only a valid proof
+ *     learns which account the root belongs to; the response carries passkey
+ *     registration options for THAT account and a short-lived ticket.
+ *  3. The holder creates the passkey, seals the root under it (PRF), and signs
+ *     `recover_account_complete` over the registration challenge and the envelope
+ *     digest: `POST /identity/recovery/complete`. The passkey, the envelope and a
+ *     session are created in one transaction.
+ *
+ * The recovery material and the root never leave the holder. Platform-agnostic —
+ * zod only, ESM-safe.
+ */
+import { z } from 'zod';
+import { identityProofSchema } from './identityProof.js';
+import { webIdentityEnvelopeSchema, webIdentityPublicKeySchema } from './webIdentityCarrier.js';
+/** A recovery attempt lives this long between steps. */
+export const IDENTITY_RECOVERY_TTL_MS = 5 * 60 * 1000;
+export const identityRecoveryChallengeResponseSchema = z.object({
+    challenge: z.string().regex(/^[0-9a-f]{64}$/),
+    expiresAt: z.number().int().positive(),
+});
+export const identityRecoveryStartRequestSchema = z
+    .object({
+    publicKey: webIdentityPublicKeySchema,
+    /** `recover_account_start`, subject `root:<publicKey>`, actor `anonymous`. */
+    proof: identityProofSchema,
+})
+    .strict();
+export const identityRecoveryCompleteRequestSchema = z
+    .object({
+    ticket: z.string().regex(/^[0-9a-f]{64}$/),
+    /** The browser `RegistrationResponseJSON`, verified by the API's WebAuthn library. */
+    response: z.record(z.string(), z.unknown()),
+    /** The root sealed under the new passkey — exactly one wrap, for that credential. */
+    envelope: webIdentityEnvelopeSchema,
+    /** `recover_account_complete`, subject = account id, actor `credential:<id>`, challenge = registration challenge (hex). */
+    proof: identityProofSchema,
+    deviceName: z.string().trim().max(100).optional(),
+    deviceFingerprint: z.string().trim().max(512).optional(),
+})
+    .strict();

package/dist/esm/index.js

@@ -10,10 +10,10 @@
  * expo, no `require()` in the ESM build.
  */
 export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph.js';
-export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, } from './username.js';
+export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_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,18 @@ 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, WEB_IDENTITY_SECRET_KINDS, webIdentityPublicKeySchema, webauthnCredentialIdSchema, webauthnRpIdSchema, webIdentityWrapSchema, webIdentityEnvelopeSchema, webIdentityEnvelopeUploadSchema, webIdentityHolderSchema, webIdentityEnvelopeResponseSchema, webIdentityEnvelopeProofFieldsSchema, webIdentityEnvelopeActionSchema, webIdentityEnvelopePutSchema, webauthnAssertionResponseSchema, webIdentityEnvelopeEstablishSchema, } from './webIdentityCarrier.js';
+export { 
+// Identity proofs (ADR 0024 D7) — the one signed format for root operations
+IDENTITY_PROOF_VERSION, IDENTITY_PROOF_DOMAIN, IDENTITY_PROOF_AUDIENCE, IDENTITY_PROOF_CHALLENGE_TTL_MS, IDENTITY_PROOF_ACTIONS, IDENTITY_PROOF_ACTION_VALUES, IDENTITY_ERROR_CODES, canonicalJson, buildIdentityProofMessage, identityProofSchema, identityProofChallengeRequestSchema, identityProofChallengeResponseSchema, identityRootStatusSchema, } from './identityProof.js';
+export { 
+// Signed-out recovery (ADR 0024 D5)
+IDENTITY_RECOVERY_TTL_MS, identityRecoveryChallengeResponseSchema, identityRecoveryStartRequestSchema, identityRecoveryCompleteRequestSchema, } from './identityRecovery.js';
+export { 
+// Schemas — moving a web identity into Commons
+IDENTITY_MOVE_TTL_MS, IDENTITY_MOVE_STATUSES, IDENTITY_MOVE_QR_PREFIX, identityMoveRevealRequestSchema, buildMoveCommitmentInput, buildMoveSasInput, buildMoveSealPayload, buildMoveCiphertextDigestInput, buildMoveReceiptMessage, identityMoveIdSchema, identityMoveEphemeralKeySchema, identityMoveCreateRequestSchema, identityMoveCreateResponseSchema, identityMoveJoinRequestSchema, identityMoveSealRequestSchema, identityMoveReceiptRequestSchema, identityMoveStateSchema, } from './identityMove.js';
+export { 
 // Shared primitives
 updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, 
 // Assets: init + complete
@@ -95,9 +107,6 @@ export {
 // Schemas
 webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, } from './webauthn.js';
 export { 
-// Schemas
-devicePairingStatusSchema, deviceTransferInitRequestSchema, deviceTransferInitResponseSchema, deviceTransferInfoResponseSchema, deviceTransferApproveRequestSchema, deviceTransferApproveResponseSchema, deviceTransferDenyResponseSchema, } from './devicePairing.js';
-export { 
 // Schemas — transparency log (checkpoints + inclusion proofs)
 transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency.js';
 /* -------------------------------------------------------------------------- */
@@ -146,10 +155,10 @@ export {
 modelDistributionMethodSchema, modelSystemicRiskTierSchema, trainingComputeFlopsSchema, SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS, modelDownstreamDocumentationSchema, modelGpaiDocumentationSchema, modelLineDeclarationSchema, modelReleaseIngestionRequestSchema, modelReleaseIngestionResultSchema, modelDocumentationSchema, } from './inference/modelDocumentation.js';
 export { 
 // The normalized Oxy→data-plane request envelope.
-inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request.js';
+inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request.js';
 export { 
 // Normalized SSE events.
-inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents.js';
+inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceAudioMediaTypeSchema, MAX_INFERENCE_AUDIO_BYTES, inferenceStreamAudioEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents.js';
 export { 
 // Reserve → settle → refund.
 usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage.js';

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/identifiers.js

@@ -126,6 +126,8 @@ export const inferenceHttpsUrlSchema = z
 export const sha256DigestSchema = z
     .string()
     .regex(/^sha256:[a-f0-9]{64}$/, 'digest must be sha256:<64 lowercase hex>');
+/** Standard base64 in whole, padded 4-character groups. */
+export const PADDED_BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 /* -------------------------------------------------------------------------- */
 /*  Catalogue references                                                      */
 /* -------------------------------------------------------------------------- */

package/dist/esm/inference/providerConnection.js

@@ -24,7 +24,7 @@
  * Decided in: issue #972 workstream 10.
  */
 import { z } from 'zod';
-import { deploymentIdSchema, inferenceEnvironmentSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, oxyAccountIdSchema, oxyApplicationIdSchema, } from './identifiers.js';
+import { deploymentIdSchema, inferenceEnvironmentSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, oxyAccountIdSchema, oxyApplicationIdSchema, PADDED_BASE64_PATTERN, } from './identifiers.js';
 /**
  * How widely a connection applies.
  *
@@ -111,7 +111,7 @@ const kaanaCredentialSecretBase64Schema = z
     .string()
     .min(1)
     .max(8192)
-    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/)
+    .regex(PADDED_BASE64_PATTERN)
     .refine(isVisibleASCIIProviderCredential, {
     message: 'a decoded provider credential is 1-4096 visible ASCII bytes',
 });

package/dist/esm/inference/request.js

@@ -311,6 +311,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. */
+export const inferenceSpeechParametersSchema = z.object({
+    voice: z.string().min(1).max(64),
+    responseFormat: z.enum(["mp3", "opus", "aac", "flac", "wav", "pcm"]),
+    speed: z.number().min(0.25).max(4).optional(),
+}).strict();
 /**
  * The canonical internal request Oxy forwards to the data plane.
  *
@@ -330,6 +336,7 @@ export const inferenceRequestSchema = z
     stream: z.boolean(),
     maxOutputTokens: z.number().int().positive().safe().optional(),
     sampling: samplingParametersSchema,
+    speech: inferenceSpeechParametersSchema.optional(),
     tools: z.array(toolDefinitionSchema).default([]),
     toolChoice: toolChoiceSchema.optional(),
     responseFormat: responseFormatSchema.optional(),
@@ -372,6 +379,13 @@ export const inferenceRequestSchema = z
     authorizedRoutes: z.array(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: 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: 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: z.ZodIssueCode.custom,

package/dist/esm/inference/streamEvents.js

@@ -2,7 +2,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
@@ -21,7 +21,7 @@
  * Decided in: docs/adr/0010-public-api-compatibility.md, docs/adr/0008-catalogue-concept-separation.md.
  */
 import { z } from 'zod';
-import { deploymentIdSchema, generationIdSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
+import { deploymentIdSchema, generationIdSchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelIdSchema, modelReferenceSchema, PADDED_BASE64_PATTERN, requestIdSchema, } from './identifiers.js';
 import { inferenceErrorSchema } from './errors.js';
 import { usageQuantitySchema, usageSourceSchema } from './money.js';
 /**
@@ -62,6 +62,27 @@ export const inferenceStreamDeltaEventSchema = z.object({
     channel: z.enum(['output_text', 'reasoning', 'refusal']),
     text: z.string(),
 });
+/** The encodings an audio output may carry. */
+export const inferenceAudioMediaTypeSchema = 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. */
+export const MAX_INFERENCE_AUDIO_BYTES = 20 * 1024 * 1024;
+/** A bounded, independently base64-encoded chunk of one audio output. */
+export const inferenceStreamAudioEventSchema = z.object({
+    schemaVersion: z.literal(1),
+    type: z.literal('audio'),
+    requestId: requestIdSchema,
+    sequence: z.number().int().nonnegative().safe(),
+    outputIndex: z.number().int().nonnegative().safe(),
+    mediaType: inferenceAudioMediaTypeSchema,
+    data: z.string().min(4).max(65536).regex(PADDED_BASE64_PATTERN),
+});
 /**
  * A tool call being streamed.
  *
@@ -247,6 +268,7 @@ export const inferenceStreamDoneEventSchema = z.object({
 export const inferenceStreamEventSchema = z.discriminatedUnion('type', [
     inferenceStreamStartEventSchema,
     inferenceStreamDeltaEventSchema,
+    inferenceStreamAudioEventSchema,
     inferenceStreamToolCallEventSchema,
     inferenceStreamUsageEventSchema,
     inferenceStreamRouteSwitchEventSchema,

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';