@oxy.so/contracts 1.0.0

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

@@ -0,0 +1,102 @@
+/**
+ * Version rule for the Oxy↔data-plane inference contracts.
+ *
+ * Oxy is the control plane; the inference data plane is a separate service.
+ * They are deployed independently, in different repositories, possibly in
+ * different languages.
+ * Every shape they exchange therefore carries its version IN THE PARSED DATA,
+ * never as a comment or an out-of-band assumption, so a producer running ahead
+ * of a consumer fails loudly at the parse instead of being silently reinterpreted.
+ *
+ * The rule, enforced by `src/__tests__/inference.compatibility.test.ts`:
+ *
+ *  - A schema carries `schemaVersion: z.literal(<n>)` **if and only if** it can
+ *    appear on the wire as a whole message — a request envelope, a stream event,
+ *    a catalogue descriptor, a ledger record, an error body.
+ *  - A schema that only ever appears EMBEDDED inside such a message (the
+ *    attribution block, one message part, one usage quantity, a data-retention
+ *    policy) carries no version of its own: it inherits the version of the
+ *    envelope it rides in. Versioning it separately would create two versions
+ *    that can disagree about one byte stream.
+ *  - A shape that is BOTH — `inferenceErrorSchema` is returned as an HTTP body
+ *    and also rides inside the stream's error event — keeps its own version.
+ *    The envelope's version then governs the envelope and the payload's governs
+ *    the payload, which is two versions of two things rather than two versions
+ *    of one.
+ *  - Every exported object schema in `src/inference/` must fall into exactly one
+ *    of those groups. The compatibility test holds both lists as exact
+ *    equalities, so a new shape that is in neither fails the build rather than
+ *    quietly shipping unversioned.
+ *
+ * A shape's own version is bumped when its meaning changes in a way a consumer
+ * pinned to the previous version would misread — a field removed, a field's
+ * units changed, a closed enum's member given a new meaning. Adding an OPTIONAL
+ * field is additive and does not bump it, because a consumer on the previous
+ * version parses the message correctly and simply does not read the new field.
+ *
+ * ## Which shapes reject an unknown field
+ *
+ * That last rule is why the shapes EXCHANGED WITH THE DATA PLANE are not
+ * `.strict()` at their top level — the request envelope, the four usage records,
+ * the stream events, the error body, the catalogue descriptors, the price
+ * version. The split is a decision rather than an omission: `.strict()` and
+ * "adding an optional field is additive" cannot both hold on one shape, because
+ * a producer one minor version ahead would have its whole message REFUSED
+ * rather than its new field ignored. For a usage report that means a request
+ * already served upstream can never be settled and Oxy absorbs its cost, which
+ * is a worse failure than the one strictness would have caught.
+ *
+ * Their LEAVES are strict, and that is where the protection lives: a stripped
+ * field is the worse outcome exactly where it would be a leak or a second
+ * source of truth, because it disappears at this parse and survives in the
+ * producer, which is where somebody eventually reads it. So
+ * `clientRequestMetadataSchema` (no IP, ever), `moneySchema` (no convenience
+ * float beside the exact decimal), `providerErrorPassthroughSchema` (no
+ * upstream request or headers beside the message), `usageQuantitySchema` and
+ * `unitPriceSchema` all refuse an unknown field, while the envelope carrying
+ * them tolerates an additive one.
+ *
+ * A shape Oxy does NOT exchange with the data plane is strict at its top level
+ * too, since nothing there can run ahead of this package:
+ * `providerConnectionSchema`, where an unknown field is how a BYOK credential
+ * escapes, and the billing and entitlement records, where one is a second
+ * number beside an exact amount.
+ *
+ * A SIGNED document is strict at its top level for a third reason, and there it
+ * is forced rather than chosen. `aliaModelReleaseManifestSchema` carries
+ * signatures over its own canonical bytes, so a field stripped at this parse is a
+ * field missing from the bytes a verifier re-canonicalizes: a tolerant parse
+ * would report an invalid SIGNATURE where the truth is that this build does not
+ * understand the DOCUMENT. Its producer can run ahead of this package — Alia's
+ * release tooling is deployed independently — so the usual argument applies here
+ * and is outweighed, because the refusal costs an operator one retry after Oxy
+ * takes the newer contract, while the tolerant parse costs a misdiagnosis of a
+ * cryptographic failure.
+ *
+ * Decided in: docs/adr/0006-oxy-kaana-boundary.md,
+ * docs/adr/0010-public-api-compatibility.md,
+ * docs/adr/0017-authorized-routes-in-the-envelope.md.
+ */
+/**
+ * Version of the contract SET as a whole — the value the control plane and the
+ * data plane exchange in a startup/health handshake to establish that they were built against
+ * compatible definitions before a single inference request is served.
+ *
+ * MAJOR is bumped when any individual shape's `schemaVersion` increments (at
+ * least one message is now read differently by the two sides); MINOR when a
+ * shape or an optional field is added, when a CLOSED ENUM gains a member, or
+ * when a refinement changes which bytes parse; PATCH for documentation-only
+ * changes that leave every parsed byte identical.
+ *
+ * The last two are MINOR rather than PATCH because both produce the same
+ * failure: a producer on the newer set emits something the older set refuses,
+ * with no `schemaVersion` difference to explain it. A new enum member and a
+ * loosened refinement are exactly what the handshake exists to surface — a
+ * skew the per-message version cannot express.
+ *
+ * This constant is deliberately NOT embedded in the request envelope. Pinning a
+ * request to the version of the whole set would make an unrelated additive
+ * change to, say, the catalogue reject every in-flight inference request; the
+ * per-shape `schemaVersion` is what a message is validated against.
+ */
+export declare const INFERENCE_CONTRACT_VERSION = "2.0.0";

package/dist/types/keyRecovery.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Encrypted off-device identity backup contract (b3 Feature 1).
+ *
+ * SINGLE SOURCE OF TRUTH for the "encrypted identity backup" flow, where a
+ * client stores an encrypted copy of its self-custody identity key off-device so
+ * a lost/wiped device can be recovered from the recovery phrase ALONE — without
+ * the platform ever seeing the phrase, the derived encryption key, or the
+ * plaintext private key.
+ *
+ * Zero-knowledge design (mirrors the zero-cookie `DeviceSession.secretHash`
+ * pattern): the client derives, from the FULL 64-byte BIP-39 seed, both an
+ * encryption key (`backupKey`) and a locator (`lookupId`) via HKDF with
+ * domain-separated `info` labels. It uploads ONLY the XChaCha20-Poly1305
+ * ciphertext plus the raw `lookupId`; the server stores the ciphertext and
+ * `sha256(lookupId)` (never the raw `lookupId`). Restoration re-derives both
+ * from the phrase, fetches the envelope by `lookupId`, and decrypts locally.
+ *
+ * The server can neither locate a backup (it lacks the seed to compute the
+ * lookup id) nor decrypt one (it lacks the seed to compute the backup key) — a
+ * DB dump yields only opaque ciphertext keyed by an un-invertible hash.
+ *
+ * The producer (`@oxy.so/api`) validates its request/response against these
+ * schemas; the consumer (`@oxy.so/core` identity-backup mixin) validates its
+ * input against the same definitions, so the wire shape cannot drift.
+ *
+ * All shapes here are FLAT (no nested objects), so `z.infer<>` is safe under a
+ * consumer's node10 `moduleResolution`. Platform-agnostic — zod only, ESM-safe
+ * (no `require()`).
+ */
+import { z } from 'zod';
+/** 256-bit backup locator (32 bytes), lowercase/uppercase hex. */
+export declare const backupLookupIdSchema: z.ZodString;
+/**
+ * The stored, self-describing encrypted backup as it lives at rest and travels
+ * on the public restore endpoint. Contains NO secret and NO locator: the
+ * `lookupId` is uploaded separately (see {@link backupUploadRequestSchema}) and
+ * only its hash is ever persisted.
+ *
+ * - `version`       — envelope/KDF version, so a future scheme migration is
+ *   distinguishable at rest.
+ * - `algorithm`     — the AEAD used. Pinned literal so a mismatched decryptor
+ *   fails loudly rather than silently.
+ * - `kdfInfo`       — the HKDF `info` label used to derive the encryption key
+ *   (domain-separation tag; documents exactly which context produced the key).
+ * - `nonce`         — the 24-byte XChaCha20-Poly1305 nonce, hex.
+ * - `ciphertext`    — the encrypted `{privateKey, publicKey, createdAt}` payload
+ *   with the appended Poly1305 tag, hex.
+ * - `publicKeyHint` — a short, non-sensitive prefix of the backed-up identity's
+ *   public key, so the owner can recognise WHICH identity a backup belongs to
+ *   without exposing the full key. Bound into the AEAD associated data.
+ * - `createdAt`     — ISO-8601 creation timestamp.
+ */
+export declare const encryptedBackupEnvelopeSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    algorithm: z.ZodLiteral<"xchacha20poly1305">;
+    kdfInfo: z.ZodString;
+    nonce: z.ZodString;
+    ciphertext: z.ZodString;
+    publicKeyHint: z.ZodString;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    version: number;
+    nonce: string;
+    ciphertext: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    publicKeyHint: string;
+}, {
+    createdAt: string;
+    version: number;
+    nonce: string;
+    ciphertext: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    publicKeyHint: string;
+}>;
+export type EncryptedBackupEnvelope = z.infer<typeof encryptedBackupEnvelopeSchema>;
+/**
+ * Request body of `POST /identity/backup` — the envelope PLUS the raw
+ * `lookupId`. The server sha256-hashes `lookupId` before storing it (it never
+ * persists the raw value), and upserts by the authenticated user id so a
+ * re-upload REPLACES the prior backup rather than accumulating duplicates.
+ */
+export declare const backupUploadRequestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    algorithm: z.ZodLiteral<"xchacha20poly1305">;
+    kdfInfo: z.ZodString;
+    nonce: z.ZodString;
+    ciphertext: z.ZodString;
+    publicKeyHint: z.ZodString;
+    createdAt: z.ZodString;
+} & {
+    /**
+     * The raw 256-bit backup locator (hex), derived client-side from the seed
+     * with a domain-separated HKDF `info`. The server stores ONLY its sha256; a
+     * DB dump therefore cannot recompute a locator to enumerate backups.
+     */
+    lookupId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    version: number;
+    nonce: string;
+    ciphertext: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    publicKeyHint: string;
+    lookupId: string;
+}, {
+    createdAt: string;
+    version: number;
+    nonce: string;
+    ciphertext: string;
+    algorithm: "xchacha20poly1305";
+    kdfInfo: string;
+    publicKeyHint: string;
+    lookupId: string;
+}>;
+export type BackupUploadRequest = z.infer<typeof backupUploadRequestSchema>;
+/**
+ * Response of `GET /identity/backup/status` (and the write/delete acks): whether
+ * the authenticated user has a stored backup, plus the non-sensitive hint +
+ * timestamp when one exists. Carries no ciphertext and no locator.
+ */
+export declare const backupStatusResponseSchema: z.ZodObject<{
+    exists: z.ZodBoolean;
+    publicKeyHint: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    exists: boolean;
+    createdAt?: string | undefined;
+    publicKeyHint?: string | undefined;
+}, {
+    exists: boolean;
+    createdAt?: string | undefined;
+    publicKeyHint?: string | undefined;
+}>;
+export type BackupStatusResponse = z.infer<typeof backupStatusResponseSchema>;

package/dist/types/keyRotation.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Key-rotation contract (b3 Feature 3 — key rotation + last-credential replacement).
+ *
+ * SINGLE SOURCE OF TRUTH for the atomic key-rotation flow:
+ *  - `POST /auth/rotate/challenge` — mint a single-use `rotate_key` challenge.
+ *  - `POST /auth/rotate/complete`  — prove control of the CURRENT (old) key and
+ *    atomically swap in the new one.
+ *
+ * Rotation is an atomic REPLACE of the single identity key, never a
+ * remove-then-add, so it never passes through a zero-auth-method state and is
+ * independent of the unlink guards. Because the client proves possession of the
+ * current key (from SecureStore OR a recovery-phrase re-derivation), the LAST
+ * remaining credential can be replaced — the server only cares that the
+ * signature validates against the current `publicKey`.
+ *
+ * The API validates its output against these schemas; `@oxy.so/core`'s identity
+ * mixin validates its input against the same definitions, so producer and
+ * consumer cannot drift.
+ *
+ * All shapes here are FLAT (no nested objects), so `z.infer<>` is safe under a
+ * consumer's node10 `moduleResolution` — no interface-pinning needed.
+ *
+ * Platform-agnostic — zod only, ESM-safe (no `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Response of `POST /auth/rotate/challenge`: the single-use `rotate_key`
+ * challenge the client must sign with its CURRENT key, plus its expiry.
+ */
+export declare const rotateKeyChallengeResponseSchema: z.ZodObject<{
+    challenge: z.ZodString;
+    /** ISO-8601 expiry timestamp. */
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    expiresAt: string;
+    challenge: string;
+}, {
+    expiresAt: string;
+    challenge: string;
+}>;
+export type RotateKeyChallengeResponse = z.infer<typeof rotateKeyChallengeResponseSchema>;
+/**
+ * Request body of `POST /auth/rotate/complete`.
+ *
+ * Two proofs are required:
+ *  - `signature` — the CURRENT (old) key signs
+ *    `JSON.stringify({ action: 'rotate_key', userId, oldPublicKey, newPublicKey,
+ *    challenge, timestamp })` (proves control of the key being replaced).
+ *  - `newKeyProof` — the NEW key signs
+ *    `JSON.stringify({ action: 'rotate_key_new', userId, newPublicKey, challenge,
+ *    timestamp })` (proof-of-possession of the key being rotated IN; prevents an
+ *    attacker rotating their account to a re-encoding of someone else's key they
+ *    do not control).
+ *
+ * The request carries ONLY `newPublicKey` — `oldPublicKey` and `userId` are
+ * derived server-side from the authenticated user document (never
+ * client-supplied), so a caller cannot prove control of key X while rotating
+ * key Y.
+ */
+export declare const rotateKeyCompleteRequestSchema: z.ZodObject<{
+    newPublicKey: z.ZodString;
+    challenge: z.ZodString;
+    signature: z.ZodString;
+    /** Proof-of-possession: the NEW key signs the rotate_key_new payload. */
+    newKeyProof: z.ZodString;
+    timestamp: z.ZodNumber;
+    /**
+     * When true, all OTHER active sessions for the account are revoked after a
+     * successful rotation (the rotating device stays signed in). Use it when the
+     * old key is presumed compromised.
+     */
+    signOutEverywhere: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    timestamp: number;
+    challenge: string;
+    newPublicKey: string;
+    newKeyProof: string;
+    signOutEverywhere?: boolean | undefined;
+}, {
+    signature: string;
+    timestamp: number;
+    challenge: string;
+    newPublicKey: string;
+    newKeyProof: string;
+    signOutEverywhere?: boolean | undefined;
+}>;
+export type RotateKeyCompleteRequest = z.infer<typeof rotateKeyCompleteRequestSchema>;
+/** Response of `POST /auth/rotate/complete`: the account's new (rotated) public key. */
+export declare const rotateKeyCompleteResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    publicKey: z.ZodString;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    publicKey: string;
+    success: boolean;
+}, {
+    message: string;
+    publicKey: string;
+    success: boolean;
+}>;
+export type RotateKeyCompleteResponse = z.infer<typeof rotateKeyCompleteResponseSchema>;

package/dist/types/links.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Link-preview / unfurl API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of Oxy's link-preview ("unfurl")
+ * resolution surface: the single `GET` lookup and the `POST` batch lookup that
+ * every app calls through the SDK so apps stop duplicating their own
+ * link-metadata fetching. The API validates its OUTPUT against these schemas;
+ * every consumer (`@oxy.so/core`'s link mixin and the apps that call it)
+ * validates its INPUT against the same definitions, so producer and consumers
+ * cannot drift.
+ *
+ * Design anchors:
+ *  - Oxy owns resolution. The `image` (and `favicon`) URLs a preview carries are
+ *    re-hosted on Oxy media (`cloud.oxy.so/<fileId>`), never raw remote URLs —
+ *    apps render them directly with no per-app proxy.
+ *  - Resolution is best-effort and asynchronous. A preview is `'resolved'` once
+ *    metadata is materialised, `'pending'` while a first-seen URL is being
+ *    fetched in the background, or `'empty'` when the target yielded no usable
+ *    metadata. `resolvedAt` (ISO datetime) is present only once `'resolved'`.
+ *  - The batch response is keyed by the REQUESTED url (the exact string the
+ *    caller sent), not the canonical/final URL, so a caller can always look its
+ *    own input back up; the canonical URL lives on `LinkPreview.url`.
+ *
+ * The `LinkPreview` / `LinkPreviewBatchResponse` exports are declared as explicit
+ * `interface`s (with their runtime schemas annotated `z.ZodType<Interface>`),
+ * following the same rationale as `UserNameResponse` in `./userResponse`: a
+ * `z.infer<>` of a nested-object schema can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"` (node10) resolution. A literal interface emits the
+ * field types verbatim in the `.d.ts` and survives BOTH `node` and `bundler`
+ * resolution. The flat batch-request schema (no nested-object hazard) is inferred
+ * via `z.infer<>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Resolution state of a {@link LinkPreview}.
+ *
+ * - `resolved` — metadata materialised; `resolvedAt` is present.
+ * - `pending`  — a first-seen URL is being fetched in the background; metadata
+ *   fields and `resolvedAt` may be absent. The caller may re-fetch shortly.
+ * - `empty`    — the target yielded no usable metadata (e.g. a bare binary, a
+ *   404, or an opted-out host); the negative result is cached.
+ */
+export type LinkPreviewStatus = 'resolved' | 'pending' | 'empty';
+/**
+ * A single resolved (or in-flight) link preview.
+ *
+ * `url` is the canonical / final resolved URL (after redirects). The optional
+ * metadata fields are present on a best-effort basis once `status` is
+ * `'resolved'`. `image` and `favicon` are absolute Oxy-hosted
+ * (`cloud.oxy.so/<fileId>`) URLs — render them directly, never proxy them.
+ */
+export interface LinkPreview {
+    /** Canonical / final resolved URL (after following redirects). */
+    url: string;
+    status: LinkPreviewStatus;
+    title?: string;
+    description?: string;
+    /** Absolute Oxy-hosted (`cloud.oxy.so`) image URL. */
+    image?: string;
+    siteName?: string;
+    /** Absolute Oxy-hosted (`cloud.oxy.so`) favicon URL. */
+    favicon?: string;
+    /** ISO 8601 datetime of resolution; absent while `status` is `'pending'`. */
+    resolvedAt?: string;
+}
+export declare const linkPreviewSchema: z.ZodType<LinkPreview>;
+/**
+ * Request body for the batch unfurl endpoint. Between 1 and 50 URLs per call;
+ * the server resolves each (returning a `'pending'` placeholder for any URL it
+ * has not seen before and is fetching in the background).
+ */
+export declare const linkPreviewBatchRequestSchema: z.ZodObject<{
+    urls: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    urls: string[];
+}, {
+    urls: string[];
+}>;
+export type LinkPreviewBatchRequest = z.infer<typeof linkPreviewBatchRequestSchema>;
+/**
+ * Batch unfurl response. `data` is keyed by the REQUESTED url (the exact string
+ * the caller sent in `urls`), so a caller can always look its own input back up;
+ * the canonical/final URL is on each {@link LinkPreview}'s `url` field.
+ */
+export interface LinkPreviewBatchResponse {
+    data: Record<string, LinkPreview>;
+}
+export declare const linkPreviewBatchResponseSchema: z.ZodType<LinkPreviewBatchResponse>;
+/**
+ * Wire shape of the single-URL unfurl lookup (`GET`) — a bare
+ * {@link LinkPreview}.
+ */
+export declare const linkPreviewResponseSchema: z.ZodType<LinkPreview, z.ZodTypeDef, LinkPreview>;