@oxy.so/contracts 1.2.0 → 1.4.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

@@ -1,34 +1,38 @@
 /**
- * Identity move contract — take a web identity INTO Commons (a MOVE, not a copy).
+ * Identity move contract — give a web root to Commons (add it, or keep it only in
+ * Commons; ADR 0024 D6).
  *
- * Design: `docs/superpowers/specs/2026-09-15-one-identity-two-carriers-design.md` §5.
+ * 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:
  *
- * 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.
+ *  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.
  *
- * The server holds two ephemeral public keys, an opaque ciphertext, and a
- * receipt. It never holds anything that decrypts the ciphertext.
+ * 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. */
@@ -44,9 +48,13 @@ export const identityMoveEphemeralKeySchema = z
 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,
-});
+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(),
@@ -54,29 +62,87 @@ export const identityMoveCreateResponseSchema = z.object({
 export const identityMoveJoinRequestSchema = z.object({
     responderEphemeralPublicKey: identityMoveEphemeralKeySchema,
 });
-export const identityMoveSealRequestSchema = z.object({
+/** 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-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 }`. */
+    /** 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),
-    timestamp: z.number().int().positive(),
-});
+})
+    .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,
+    initiatorEphemeralPublicKey: identityMoveEphemeralKeySchema.nullable(),
     responderEphemeralPublicKey: identityMoveEphemeralKeySchema.nullable(),
     nonce: z.string().nullable(),
     ciphertext: z.string().nullable(),
     receiptSignature: z.string().nullable(),
-    receiptTimestamp: z.number().int().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,7 +10,7 @@
  * 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, dateOfBirthSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 
@@ -82,10 +82,16 @@ export {
 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';
+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, identityMoveIdSchema, identityMoveEphemeralKeySchema, identityMoveCreateRequestSchema, identityMoveCreateResponseSchema, identityMoveJoinRequestSchema, identityMoveSealRequestSchema, identityMoveReceiptRequestSchema, identityMoveStateSchema, } from './identityMove.js';
+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, 
@@ -101,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';
 /* -------------------------------------------------------------------------- */
@@ -135,7 +138,7 @@ export {
 priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
 export { 
 // The six distinct catalogue objects + the customer-safe projection.
-inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
+inferenceModalitySchema, reasoningEffortSchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
 export { 
 // Routing policy: every control, plus the refinement that rejects a policy
 // no route could ever satisfy.
@@ -152,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, inferenceReasoningSchema, 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

@@ -40,6 +40,15 @@ export const inferenceModalitySchema = z.enum([
     'video',
     'embedding',
 ]);
+/**
+ * How hard a reasoning model is asked to think before it answers.
+ *
+ * A closed, provider-neutral vocabulary: Kaana translates each value into the
+ * serving provider's own control. A model advertises the subset it accepts in
+ * `modelCapabilitiesSchema.reasoningEfforts`, and Oxy refuses a request for an
+ * effort the resolved model does not advertise rather than dropping it.
+ */
+export const reasoningEffortSchema = z.enum(['low', 'medium', 'high']);
 /**
  * What a model can do, in the terms a caller has to decide against before
  * sending a request: can it call tools, does it accept images, will it honour a
@@ -54,6 +63,13 @@ export const modelCapabilitiesSchema = z
     structuredOutput: z.boolean(),
     jsonMode: z.boolean(),
     reasoning: z.boolean(),
+    /**
+     * The reasoning efforts a request may name for this model, in the order
+     * low → high. Empty means the model takes no effort control at all (it may
+     * still reason: `reasoning` answers that). Added in contract set 3.1.0;
+     * absent on the wire from an older producer, it parses as `[]`.
+     */
+    reasoningEfforts: z.array(reasoningEffortSchema).default([]),
     streaming: z.boolean(),
     promptCaching: z.boolean(),
     maxContextTokens: z.number().int().positive().safe(),
@@ -469,6 +485,12 @@ export const modelCatalogueEntrySchema = z.object({
     provenance: modelProvenanceSchema,
     knowledgeCutoff: inferenceDateSchema.optional(),
     releasedOn: inferenceDateSchema.optional(),
+    /**
+     * When the upstream provider first published this model, as that provider
+     * reports it. Present only when a provider reported it; never an Oxy or Kaana
+     * observation time. Lets a picker order models newest first.
+     */
+    releasedAt: inferenceTimestampSchema.optional(),
     regions: z.array(inferenceRegionSchema).default([]),
     servingProviders: z.array(catalogueServingProviderSummarySchema).default([]),
     dataPolicy: inferenceDataPolicySchema,

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

@@ -25,7 +25,7 @@
  */
 import { z } from "zod";
 import { inferenceAttributionSchema } from "./attribution.js";
-import { inferenceModalitySchema } from "./catalogue.js";
+import { inferenceModalitySchema, reasoningEffortSchema } from "./catalogue.js";
 import { idempotencyKeySchema, inferenceTimestampSchema } from "./identifiers.js";
 import { authorizedRouteSchema, routingPolicyReferenceSchema, routingTargetSchema, } from "./routingPolicy.js";
 /* -------------------------------------------------------------------------- */
@@ -260,6 +260,16 @@ export const responseFormatSchema = z.discriminatedUnion("type", [
     })
         .strict(),
 ]);
+/**
+ * The caller's reasoning control. Strict, like every leaf: a provider-specific
+ * knob (`budget_tokens`, `summary`) is refused rather than silently dropped.
+ *
+ * Oxy forwards it only after checking the resolved model advertises the effort
+ * in its catalogue `reasoningEfforts`; Kaana translates it per provider.
+ */
+export const inferenceReasoningSchema = z
+    .object({ effort: reasoningEffortSchema })
+    .strict();
 /* -------------------------------------------------------------------------- */
 /*  Client metadata                                                           */
 /* -------------------------------------------------------------------------- */
@@ -311,6 +321,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 +346,9 @@ export const inferenceRequestSchema = z
     stream: z.boolean(),
     maxOutputTokens: z.number().int().positive().safe().optional(),
     sampling: samplingParametersSchema,
+    /** Absent means the route's own default reasoning behaviour. */
+    reasoning: inferenceReasoningSchema.optional(),
+    speech: inferenceSpeechParametersSchema.optional(),
     tools: z.array(toolDefinitionSchema).default([]),
     toolChoice: toolChoiceSchema.optional(),
     responseFormat: responseFormatSchema.optional(),
@@ -372,6 +391,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,