@oxy.so/contracts 1.2.0 → 1.4.0

package/dist/types/identityProof.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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 declare const IDENTITY_PROOF_VERSION: 2;
+export declare const IDENTITY_PROOF_DOMAIN: "oxy-identity-proof";
+/** The audience every API-verified identity proof names. */
+export declare const IDENTITY_PROOF_AUDIENCE: "oxy-api/identity";
+/** How long a proof challenge lives: one interactive ceremony. */
+export declare const IDENTITY_PROOF_CHALLENGE_TTL_MS: number;
+/**
+ * Everything a root proof may authorize. A challenge is minted for exactly one
+ * action and spent only by a proof for that action.
+ */
+export declare const IDENTITY_PROOF_ACTIONS: {
+    /** A keyless account's FIRST root, stored with its web envelope. */
+    readonly establish: "web_envelope_establish";
+    /** Replace the web envelope (add or remove a wrap, re-seal). */
+    readonly put: "web_envelope_put";
+    /** Record that the recovery material is written down. */
+    readonly phraseConfirmed: "web_envelope_phrase_confirmed";
+    /** Record that the recovery material re-derived the root. */
+    readonly recoveryVerified: "web_envelope_recovery_verified";
+    /** Remove the web holder. */
+    readonly delete: "web_envelope_delete";
+    /** Link a keyless account's first root without a web envelope (`POST /auth/link`). */
+    readonly link: "link_identity";
+    /** Create a personal account together with its root (passkey sign-up). */
+    readonly enroll: "enroll_identity";
+    /** Prove the root to start signed-out recovery. */
+    readonly recoverStart: "recover_account_start";
+    /** Bind the new passkey and envelope when completing signed-out recovery. */
+    readonly recoverComplete: "recover_account_complete";
+    /** Seal the root for the Commons device that joined a move (payload: move id + sealed bytes). */
+    readonly moveSeal: "identity_move_seal";
+};
+export type IdentityProofAction = (typeof IDENTITY_PROOF_ACTIONS)[keyof typeof IDENTITY_PROOF_ACTIONS];
+export declare const IDENTITY_PROOF_ACTION_VALUES: [IdentityProofAction, ...IdentityProofAction[]];
+/**
+ * The signed claims. `null` is written explicitly for a field that does not
+ * apply, so "absent" can never be confused with a value.
+ */
+export interface IdentityProofClaims {
+    action: IdentityProofAction;
+    /** The account the operation changes (`users.id`), or a namespaced subject (`username:alice`) before one exists. */
+    subject: string;
+    /** Who performs it: the signed-in personal principal, or `credential:<id>` / `anonymous` where none exists. */
+    actor: string;
+    /** The root doing the signing, lowercase uncompressed hex. */
+    rootPublicKey: string;
+    /** SHA-256 hex of `canonicalJson(payload)`, or `null` when the operation has no payload. */
+    payloadDigest: string | null;
+    /** The envelope revision the operation expects to replace, or `null`. */
+    expectedRevision: number | null;
+    audience: string;
+    /** The one-use server challenge. */
+    challenge: string;
+    /** Unix milliseconds after which the proof is refused. */
+    expiresAt: number;
+}
+/**
+ * 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 declare function canonicalJson(value: unknown): string;
+/**
+ * The exact bytes a root signs. Throws on a malformed claim rather than signing
+ * (or verifying) something ambiguous.
+ */
+export declare function buildIdentityProofMessage(claims: IdentityProofClaims): string;
+/** The proof as it travels: the signature plus the two claims the verifier cannot derive. */
+export declare const identityProofSchema: z.ZodObject<{
+    v: z.ZodLiteral<2>;
+    challenge: z.ZodString;
+    expiresAt: z.ZodNumber;
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: number;
+    signature: string;
+    v: 2;
+    challenge: string;
+}, {
+    expiresAt: number;
+    signature: string;
+    v: 2;
+    challenge: string;
+}>;
+export type IdentityProof = z.infer<typeof identityProofSchema>;
+/** `POST /identity/proof-challenge` */
+export declare const identityProofChallengeRequestSchema: z.ZodObject<{
+    action: z.ZodEnum<[IdentityProofAction, ...IdentityProofAction[]]>;
+}, "strip", z.ZodTypeAny, {
+    action: IdentityProofAction;
+}, {
+    action: IdentityProofAction;
+}>;
+export type IdentityProofChallengeRequest = z.infer<typeof identityProofChallengeRequestSchema>;
+export interface IdentityProofChallengeResponse {
+    challenge: string;
+    /** Unix milliseconds; a proof must not claim a later `expiresAt`. */
+    expiresAt: number;
+    audience: string;
+}
+export declare const identityProofChallengeResponseSchema: z.ZodType<IdentityProofChallengeResponse>;
+/**
+ * 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 declare const IDENTITY_ERROR_CODES: {
+    readonly proofInvalid: "IDENTITY_PROOF_INVALID";
+    readonly revisionConflict: "IDENTITY_ENVELOPE_REVISION_CONFLICT";
+    readonly rootAlreadyLinked: "IDENTITY_ROOT_ALREADY_LINKED";
+    readonly rootLinkedElsewhere: "IDENTITY_ROOT_LINKED_ELSEWHERE";
+    readonly noRoot: "IDENTITY_NO_ROOT";
+    readonly freshFactorRequired: "IDENTITY_FRESH_FACTOR_REQUIRED";
+    readonly lastWebHolder: "IDENTITY_LAST_WEB_HOLDER";
+    readonly enrollmentRequired: "IDENTITY_ENROLLMENT_REQUIRED";
+    readonly enrollmentInvalid: "IDENTITY_ENROLLMENT_INVALID";
+    readonly notPersonal: "IDENTITY_NOT_PERSONAL_ACCOUNT";
+    readonly recoveryFailed: "IDENTITY_RECOVERY_FAILED";
+};
+export type IdentityErrorCode = (typeof IDENTITY_ERROR_CODES)[keyof typeof IDENTITY_ERROR_CODES];
+/**
+ * `GET /identity/root-status` — non-sensitive readiness metadata any first-party
+ * surface (Accounts, the account menu) may read with a bearer to show a reminder,
+ * without the ciphertext and without opening anything (ADR 0024 D5).
+ */
+export interface IdentityRootStatus {
+    /** Whether the account has a root at all. */
+    rootLinked: boolean;
+    /** Passkeys whose wraps can open the web holder, and how many have proven it. `null`: no web holder. */
+    webHolder: {
+        passkeys: number;
+        verifiedPasskeys: number;
+    } | null;
+    /** Whether the root has recovery words (a raw-key root does not). `null` when unknown (no web holder). */
+    hasPhrase: boolean | null;
+    phraseConfirmedAt: string | null;
+    recoveryVerifiedAt: string | null;
+}
+export declare const identityRootStatusSchema: z.ZodType<IdentityRootStatus>;

package/dist/types/identityRecovery.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 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';
+/** A recovery attempt lives this long between steps. */
+export declare const IDENTITY_RECOVERY_TTL_MS: number;
+export interface IdentityRecoveryChallengeResponse {
+    /** 32 bytes, lowercase hex. */
+    challenge: string;
+    /** Unix milliseconds. */
+    expiresAt: number;
+}
+export declare const identityRecoveryChallengeResponseSchema: z.ZodType<IdentityRecoveryChallengeResponse>;
+export declare const identityRecoveryStartRequestSchema: z.ZodObject<{
+    publicKey: z.ZodString;
+    /** `recover_account_start`, subject `root:<publicKey>`, actor `anonymous`. */
+    proof: z.ZodObject<{
+        v: z.ZodLiteral<2>;
+        challenge: z.ZodString;
+        expiresAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    }, {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    publicKey: string;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+}, {
+    publicKey: string;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+}>;
+export type IdentityRecoveryStartRequest = z.infer<typeof identityRecoveryStartRequestSchema>;
+export interface IdentityRecoveryStartResponse {
+    /** Opaque, one-use; presented once to `complete`. */
+    ticket: string;
+    accountId: string;
+    username: string | null;
+    /** `PublicKeyCredentialCreationOptionsJSON` for the account's new passkey. */
+    registrationOptions: Record<string, unknown>;
+    /** Unix milliseconds. */
+    expiresAt: number;
+}
+export declare const identityRecoveryCompleteRequestSchema: z.ZodObject<{
+    ticket: z.ZodString;
+    /** The browser `RegistrationResponseJSON`, verified by the API's WebAuthn library. */
+    response: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    /** The root sealed under the new passkey — exactly one wrap, for that credential. */
+    envelope: z.ZodEffects<z.ZodObject<{
+        version: z.ZodLiteral<2>;
+        algorithm: z.ZodLiteral<"xchacha20poly1305">;
+        publicKey: z.ZodString;
+        secretKind: z.ZodEnum<["mnemonic-entropy", "raw-private-key"]>;
+        secretNonce: z.ZodString;
+        sealedSecret: z.ZodString;
+        wraps: z.ZodArray<z.ZodObject<{
+            credentialId: z.ZodString;
+            nonce: z.ZodString;
+            wrappedKey: z.ZodString;
+            createdAt: z.ZodString;
+            rpId: z.ZodString;
+            verifiedAt: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }>, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }>;
+    /** `recover_account_complete`, subject = account id, actor `credential:<id>`, challenge = registration challenge (hex). */
+    proof: z.ZodObject<{
+        v: z.ZodLiteral<2>;
+        challenge: z.ZodString;
+        expiresAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    }, {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    }>;
+    deviceName: z.ZodOptional<z.ZodString>;
+    deviceFingerprint: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+    envelope: {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    };
+    response: Record<string, unknown>;
+    ticket: string;
+    deviceName?: string | undefined;
+    deviceFingerprint?: string | undefined;
+}, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+    envelope: {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    };
+    response: Record<string, unknown>;
+    ticket: string;
+    deviceName?: string | undefined;
+    deviceFingerprint?: string | undefined;
+}>;
+export type IdentityRecoveryCompleteRequest = z.infer<typeof identityRecoveryCompleteRequestSchema>;

package/dist/types/index.d.ts

@@ -11,7 +11,7 @@
  */
 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';
 export type { AccountKind, AccountCategoryId, AccountCategoryKind, ChildAccountKind, CreateAccountRequest, } from './accountGraph';
-export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, } from './username';
+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';
 export { userNameSchema, userRelationshipSchema, themePreferenceSchema, dateOfBirthSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, resolveUserId, safeParseContract, } from './userResponse';
 export type { UserNameResponse, UserRelationship, ThemePreference, UserResponse, UserProfileUpdate, CurrentUserResponseContract, DeviceLinkedSessionResponse, DeviceLinkedSessionsResponseContract, } from './userResponse';
 export { applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus';
@@ -51,16 +51,18 @@ export { rotateKeyChallengeResponseSchema, rotateKeyCompleteRequestSchema, rotat
 export type { RotateKeyChallengeResponse, RotateKeyCompleteRequest, RotateKeyCompleteResponse, } from './keyRotation';
 export { backupLookupIdSchema, encryptedBackupEnvelopeSchema, backupUploadRequestSchema, backupStatusResponseSchema, } from './keyRecovery';
 export type { EncryptedBackupEnvelope, BackupUploadRequest, BackupStatusResponse, } from './keyRecovery';
-export { WEB_IDENTITY_ENVELOPE_VERSION, webIdentityPublicKeySchema, webauthnCredentialIdSchema, webIdentityWrapSchema, webIdentityEnvelopeSchema, webIdentityEnvelopeUploadSchema, webIdentityEnvelopeResponseSchema, webIdentityEnvelopeProofSchema, webIdentityEnvelopePutSchema, webIdentityEnvelopeEstablishSchema, } from './webIdentityCarrier';
-export { IDENTITY_MOVE_TTL_MS, IDENTITY_MOVE_STATUSES, IDENTITY_MOVE_QR_PREFIX, identityMoveIdSchema, identityMoveEphemeralKeySchema, identityMoveCreateRequestSchema, identityMoveCreateResponseSchema, identityMoveJoinRequestSchema, identityMoveSealRequestSchema, identityMoveReceiptRequestSchema, identityMoveStateSchema, } from './identityMove';
-export type { IdentityMoveStatus, IdentityMoveCreateRequest, IdentityMoveCreateResponse, IdentityMoveJoinRequest, IdentityMoveSealRequest, IdentityMoveReceiptRequest, IdentityMoveState, } from './identityMove';
-export type { WebIdentityWrap, WebIdentityEnvelope, WebIdentityEnvelopeUpload, WebIdentityEnvelopeResponse, WebIdentityEnvelopeProof, WebIdentityEnvelopePut, WebIdentityEnvelopeEstablish, } from './webIdentityCarrier';
+export { WEB_IDENTITY_ENVELOPE_VERSION, WEB_IDENTITY_SECRET_KINDS, webIdentityPublicKeySchema, webauthnCredentialIdSchema, webauthnRpIdSchema, webIdentityWrapSchema, webIdentityEnvelopeSchema, webIdentityEnvelopeUploadSchema, webIdentityHolderSchema, webIdentityEnvelopeResponseSchema, webIdentityEnvelopeProofFieldsSchema, webIdentityEnvelopeActionSchema, webIdentityEnvelopePutSchema, webauthnAssertionResponseSchema, webIdentityEnvelopeEstablishSchema, } from './webIdentityCarrier';
+export { 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';
+export { IDENTITY_RECOVERY_TTL_MS, identityRecoveryChallengeResponseSchema, identityRecoveryStartRequestSchema, identityRecoveryCompleteRequestSchema, } from './identityRecovery';
+export type { IdentityRecoveryChallengeResponse, IdentityRecoveryStartRequest, IdentityRecoveryStartResponse, IdentityRecoveryCompleteRequest, } from './identityRecovery';
+export type { IdentityProofAction, IdentityErrorCode, IdentityProofClaims, IdentityProof, IdentityProofChallengeRequest, IdentityProofChallengeResponse, IdentityRootStatus, } from './identityProof';
+export { 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';
+export type { IdentityMoveStatus, IdentityMoveCreateRequest, IdentityMoveCreateResponse, IdentityMoveJoinRequest, IdentityMoveSealRequest, IdentityMoveReceiptRequest, IdentityMoveRevealRequest, IdentityMoveState, } from './identityMove';
+export type { WebIdentityWrap, WebIdentityEnvelope, WebIdentitySecretKind, WebIdentityHolder, WebIdentityEnvelopeAction, WebauthnAssertionResponse, WebIdentityEnvelopeUpload, WebIdentityEnvelopeResponse, WebIdentityEnvelopePut, WebIdentityEnvelopeEstablish, } from './webIdentityCarrier';
 export { updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, assetInitItemSchema, assetInitRequestSchema, assetUploadTicketSchema, assetInitResponseSchema, assetCompleteRequestSchema, assetCompleteResultItemSchema, assetCompleteResponseSchema, updateAssetRefSchema, createUpdateRequestSchema, updateSchema, createUpdateResponseSchema, rollbackToEmbeddedEntrySchema, channelSchema, channelListResponseSchema, updateListResponseSchema, rollbackRequestSchema, rollbackToEmbeddedRequestSchema, promoteRequestSchema, updateRolloutPatchSchema, } from './updates';
 export type { UpdatePlatform, UpdateStatus, UpdateAssetStatus, AssetInitItem, AssetInitRequest, AssetUploadTicket, AssetInitResponse, AssetCompleteRequest, AssetCompleteResultItem, AssetCompleteResponse, UpdateAssetRef, CreateUpdateRequest, Update, CreateUpdateResponse, RollbackToEmbeddedEntry, Channel, ChannelListResponse, UpdateListResponse, RollbackRequest, RollbackToEmbeddedRequest, PromoteRequest, UpdateRolloutPatch, } from './updates';
 export { webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, } from './webauthn';
 export type { WebauthnRegisterOptionsRequest, WebauthnLoginOptionsRequest, WebauthnRegisterVerifyRequest, WebauthnLoginVerifyRequest, } from './webauthn';
-export { devicePairingStatusSchema, deviceTransferInitRequestSchema, deviceTransferInitResponseSchema, deviceTransferInfoResponseSchema, deviceTransferApproveRequestSchema, deviceTransferApproveResponseSchema, deviceTransferDenyResponseSchema, } from './devicePairing';
-export type { DevicePairingStatus, DeviceTransferInitRequest, DeviceTransferInitResponse, DeviceTransferInfoResponse, DeviceTransferApproveRequest, DeviceTransferApproveResponse, DeviceTransferDenyResponse, } from './devicePairing';
 export { transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency';
 export type { TransparencyCheckpointSignature, TransparencyAnchor, TransparencyCheckpoint, TransparencyInclusionProof, TransparencyCheckpointList, } from './transparency';
 export { INFERENCE_CONTRACT_VERSION, } from './inference/version';
@@ -76,18 +78,18 @@ export { embeddingVectorSchema, embeddingUsageSchema, embeddingSuccessSchema, em
 export type { EmbeddingVector, EmbeddingUsage, EmbeddingSuccess, EmbeddingFailure, EmbeddingResponse, } from './inference/embeddings';
 export { priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion';
 export type { PriceVersionStatus, PriceVersion, PriceSnapshot } from './inference/priceVersion';
-export { inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue';
-export type { InferenceModality, ModelCapabilities, ModelLicense, ModelProvenance, InferenceDataPolicy, AvailabilityScope, CommercialPermission, ModelDeprecation, ModelEvaluationResult, ModelSafetyMetadata, ModelPublisher, CatalogueModel, ModelRevision, InferenceProvider, ModelDeployment, RoutingProfileCandidate, RoutingProfile, CataloguePublisherSummary, CatalogueServingProviderSummary, ModelCatalogueEntry, } from './inference/catalogue';
+export { inferenceModalitySchema, reasoningEffortSchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue';
+export type { InferenceModality, ReasoningEffort, ModelCapabilities, ModelLicense, ModelProvenance, InferenceDataPolicy, AvailabilityScope, CommercialPermission, ModelDeprecation, ModelEvaluationResult, ModelSafetyMetadata, ModelPublisher, CatalogueModel, ModelRevision, InferenceProvider, ModelDeployment, RoutingProfileCandidate, RoutingProfile, CataloguePublisherSummary, CatalogueServingProviderSummary, ModelCatalogueEntry, } from './inference/catalogue';
 export { routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, authorizedRouteSchema, } from './inference/routingPolicy';
 export type { RoutingTarget, RoutingPolicyScope, RoutingFallbackPolicy, RoutingPolicy, RoutingPolicyReference, AuthorizedRoute, } from './inference/routingPolicy';
 export { aliaReleaseArtifactSchema, aliaReleaseSignatureSchema, aliaModelReleaseManifestSchema, } from './inference/aliaModelRelease';
 export type { AliaReleaseArtifact, AliaReleaseSignature, AliaModelReleaseManifest, } from './inference/aliaModelRelease';
 export { modelDistributionMethodSchema, modelSystemicRiskTierSchema, trainingComputeFlopsSchema, SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS, modelDownstreamDocumentationSchema, modelGpaiDocumentationSchema, modelLineDeclarationSchema, modelReleaseIngestionRequestSchema, modelReleaseIngestionResultSchema, modelDocumentationSchema, } from './inference/modelDocumentation';
 export type { ModelDistributionMethod, ModelSystemicRiskTier, ModelDownstreamDocumentation, ModelGpaiDocumentation, ModelLineDeclaration, ModelReleaseIngestionRequest, ModelReleaseIngestionResult, ModelDocumentation, } from './inference/modelDocumentation';
-export { inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request';
-export type { InferenceContentSource, InferenceContentPart, InferenceToolCall, InferenceMessageRole, InferenceMessage, InferenceInput, SamplingParameters, ToolDefinition, ToolChoice, ResponseFormat, ClientRequestMetadata, InferenceRequest, } from './inference/request';
-export { inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents';
-export type { InferenceStreamStartEvent, InferenceStreamDeltaEvent, InferenceStreamToolCallEvent, InferenceStreamUsageEvent, InferenceRouteSwitchDetail, InferenceRouteSwitchReason, InferenceStreamRouteSwitchEvent, InferenceStreamErrorEvent, InferenceFinishReason, InferenceStreamDoneEvent, InferenceStreamEvent, } from './inference/streamEvents';
+export { inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, inferenceReasoningSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request';
+export type { InferenceContentSource, InferenceContentPart, InferenceToolCall, InferenceMessageRole, InferenceMessage, InferenceInput, SamplingParameters, InferenceReasoning, ToolDefinition, ToolChoice, ResponseFormat, ClientRequestMetadata, InferenceRequest, InferenceSpeechParameters, } from './inference/request';
+export { inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceAudioMediaTypeSchema, MAX_INFERENCE_AUDIO_BYTES, inferenceStreamAudioEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents';
+export type { InferenceStreamStartEvent, InferenceStreamDeltaEvent, InferenceAudioMediaType, InferenceStreamAudioEvent, InferenceStreamToolCallEvent, InferenceStreamUsageEvent, InferenceRouteSwitchDetail, InferenceRouteSwitchReason, InferenceStreamRouteSwitchEvent, InferenceStreamErrorEvent, InferenceFinishReason, InferenceStreamDoneEvent, InferenceStreamEvent, } from './inference/streamEvents';
 export { usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage';
 export type { UsageReservationRequest, UsageReservationStatus, UsageReservation, InferenceRequestOutcome, NormalizedUsageReport, UsageReceipt, UsageRefundSubject, UsageRefundReason, UsageRefund, } from './inference/usage';
 export { providerConnectionScopeSchema, kaanaCredentialHandleSchema, kaanaCredentialOperationIdSchema, kaanaCredentialOperationActionSchema, kaanaCredentialIdentitySchema, kaanaCredentialCreateMutationSchema, kaanaCredentialRotateMutationSchema, kaanaCredentialRevokeMutationSchema, kaanaCredentialMutationSchema, kaanaCredentialCreateOutcomeRequestSchema, kaanaCredentialRotateOutcomeRequestSchema, kaanaCredentialRevokeOutcomeRequestSchema, kaanaCredentialOutcomeRequestSchema, kaanaCredentialAppliedOutcomeSchema, kaanaCredentialConflictOutcomeSchema, kaanaCredentialOutcomeSchema, kaanaCredentialValidationTaskSchema, kaanaCredentialValidationOutcomeStateSchema, kaanaCredentialValidationFailureCodeSchema, kaanaCredentialValidationOutcomeSchema, providerCredentialValidationOperationSchema, providerCredentialValidationDeploymentSchema, providerCredentialCustodyStateSchema, providerConnectionValidationSchema, providerConnectionStatusSchema, providerConnectionSchema, } from './inference/providerConnection';

package/dist/types/inference/catalogue.d.ts

@@ -29,6 +29,15 @@
 import { z } from 'zod';
 /** The modalities a model can consume or produce. */
 export declare const inferenceModalitySchema: z.ZodEnum<["text", "image", "audio", "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 declare const reasoningEffortSchema: z.ZodEnum<["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
@@ -42,6 +51,13 @@ export declare const modelCapabilitiesSchema: z.ZodObject<{
     structuredOutput: z.ZodBoolean;
     jsonMode: z.ZodBoolean;
     reasoning: z.ZodBoolean;
+    /**
+     * 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.ZodDefault<z.ZodArray<z.ZodEnum<["low", "medium", "high"]>, "many">>;
     streaming: z.ZodBoolean;
     promptCaching: z.ZodBoolean;
     maxContextTokens: z.ZodNumber;
@@ -54,6 +70,7 @@ export declare const modelCapabilitiesSchema: z.ZodObject<{
     structuredOutput: boolean;
     jsonMode: boolean;
     reasoning: boolean;
+    reasoningEfforts: ("low" | "medium" | "high")[];
     streaming: boolean;
     promptCaching: boolean;
     maxContextTokens: number;
@@ -70,6 +87,7 @@ export declare const modelCapabilitiesSchema: z.ZodObject<{
     promptCaching: boolean;
     maxContextTokens: number;
     maxOutputTokens: number;
+    reasoningEfforts?: ("low" | "medium" | "high")[] | undefined;
 }>;
 /**
  * License terms, including the two questions that decide whether Oxy may serve
@@ -289,6 +307,13 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         structuredOutput: z.ZodBoolean;
         jsonMode: z.ZodBoolean;
         reasoning: z.ZodBoolean;
+        /**
+         * 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.ZodDefault<z.ZodArray<z.ZodEnum<["low", "medium", "high"]>, "many">>;
         streaming: z.ZodBoolean;
         promptCaching: z.ZodBoolean;
         maxContextTokens: z.ZodNumber;
@@ -301,6 +326,7 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         structuredOutput: boolean;
         jsonMode: boolean;
         reasoning: boolean;
+        reasoningEfforts: ("low" | "medium" | "high")[];
         streaming: boolean;
         promptCaching: boolean;
         maxContextTokens: number;
@@ -317,6 +343,7 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         promptCaching: boolean;
         maxContextTokens: number;
         maxOutputTokens: number;
+        reasoningEfforts?: ("low" | "medium" | "high")[] | undefined;
     }>;
     license: z.ZodObject<{
         /** SPDX identifier where one exists, otherwise the publisher's own name. */
@@ -395,6 +422,7 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         structuredOutput: boolean;
         jsonMode: boolean;
         reasoning: boolean;
+        reasoningEfforts: ("low" | "medium" | "high")[];
         streaming: boolean;
         promptCaching: boolean;
         maxContextTokens: number;
@@ -441,6 +469,7 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         promptCaching: boolean;
         maxContextTokens: number;
         maxOutputTokens: number;
+        reasoningEfforts?: ("low" | "medium" | "high")[] | undefined;
     };
     schemaVersion: 1;
     slug: string;
@@ -479,6 +508,7 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         structuredOutput: boolean;
         jsonMode: boolean;
         reasoning: boolean;
+        reasoningEfforts: ("low" | "medium" | "high")[];
         streaming: boolean;
         promptCaching: boolean;
         maxContextTokens: number;
@@ -525,6 +555,7 @@ export declare const catalogueModelSchema: z.ZodEffects<z.ZodObject<{
         promptCaching: boolean;
         maxContextTokens: number;
         maxOutputTokens: number;
+        reasoningEfforts?: ("low" | "medium" | "high")[] | undefined;
     };
     schemaVersion: 1;
     slug: string;
@@ -1127,6 +1158,13 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         structuredOutput: z.ZodBoolean;
         jsonMode: z.ZodBoolean;
         reasoning: z.ZodBoolean;
+        /**
+         * 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.ZodDefault<z.ZodArray<z.ZodEnum<["low", "medium", "high"]>, "many">>;
         streaming: z.ZodBoolean;
         promptCaching: z.ZodBoolean;
         maxContextTokens: z.ZodNumber;
@@ -1139,6 +1177,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         structuredOutput: boolean;
         jsonMode: boolean;
         reasoning: boolean;
+        reasoningEfforts: ("low" | "medium" | "high")[];
         streaming: boolean;
         promptCaching: boolean;
         maxContextTokens: number;
@@ -1155,6 +1194,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         promptCaching: boolean;
         maxContextTokens: number;
         maxOutputTokens: number;
+        reasoningEfforts?: ("low" | "medium" | "high")[] | undefined;
     }>;
     license: z.ZodObject<{
         /** SPDX identifier where one exists, otherwise the publisher's own name. */
@@ -1195,6 +1235,12 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
     }>;
     knowledgeCutoff: z.ZodOptional<z.ZodString>;
     releasedOn: z.ZodOptional<z.ZodString>;
+    /**
+     * 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: z.ZodOptional<z.ZodString>;
     regions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     servingProviders: z.ZodDefault<z.ZodArray<z.ZodObject<{
         slug: z.ZodString;
@@ -1418,6 +1464,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         structuredOutput: boolean;
         jsonMode: boolean;
         reasoning: boolean;
+        reasoningEfforts: ("low" | "medium" | "high")[];
         streaming: boolean;
         promptCaching: boolean;
         maxContextTokens: number;
@@ -1483,6 +1530,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
     description?: string | undefined;
     knowledgeCutoff?: string | undefined;
     releasedOn?: string | undefined;
+    releasedAt?: string | undefined;
     modelCardUrl?: string | undefined;
     safety?: {
         contentFilteringDefault: "strict" | "none" | "provider_default";
@@ -1516,6 +1564,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         promptCaching: boolean;
         maxContextTokens: number;
         maxOutputTokens: number;
+        reasoningEfforts?: ("low" | "medium" | "high")[] | undefined;
     };
     schemaVersion: 3;
     modelId: string;
@@ -1556,6 +1605,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
     description?: string | undefined;
     knowledgeCutoff?: string | undefined;
     releasedOn?: string | undefined;
+    releasedAt?: string | undefined;
     modelCardUrl?: string | undefined;
     evaluations?: {
         score: string;
@@ -1598,6 +1648,7 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
     } | undefined;
 }>;
 export type InferenceModality = z.infer<typeof inferenceModalitySchema>;
+export type ReasoningEffort = z.infer<typeof reasoningEffortSchema>;
 export type ModelCapabilities = z.infer<typeof modelCapabilitiesSchema>;
 export type ModelLicense = z.infer<typeof modelLicenseSchema>;
 export type ModelProvenance = z.infer<typeof modelProvenanceSchema>;