@oxy.so/contracts 1.0.0

package/dist/esm/inference/usage.js

@@ -0,0 +1,326 @@
+/**
+ * The reserve → settle → refund protocol.
+ *
+ * Four records, in the order they happen:
+ *
+ *  1. **Reservation** — before a request enters the data plane, Oxy holds the
+ *     MAXIMUM the request could cost (input units + maximum output + the
+ *     allowed route's price ceiling). A request whose account cannot cover that
+ *     hold is rejected before anything is spent upstream.
+ *  2. **Usage report** — the data plane's technical account of what was
+ *     consumed. Units and route, never money: the data plane measures, the
+ *     control plane prices.
+ *  3. **Receipt** — the immutable settlement. Carries the exact units, a COPY
+ *     of the prices they were charged at, and the amount booked. It is never
+ *     edited afterwards.
+ *  4. **Refund/reversal** — an equally immutable entry that releases an unused
+ *     hold or reverses a settled charge. Settled history is compensated, never
+ *     rewritten, because an invoice a customer already received must remain
+ *     reconstructible.
+ *
+ * Every one of them is keyed by an idempotency key, so a retried call, a
+ * redelivered event or a duplicated webhook produces the same record rather than
+ * a second charge.
+ *
+ * Money is an exact decimal string throughout (ADR 0009 — never integer minor
+ * units, never a float), and unit counts are carried separately from it (see
+ * `money.ts`).
+ *
+ * Decided in: docs/adr/0009-usage-reservation-and-settlement.md.
+ */
+import { z } from 'zod';
+import { inferenceAttributionSchema } from './attribution.js';
+import { deploymentIdSchema, generationIdSchema, idempotencyKeySchema, inferenceProviderSlugSchema, inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from './identifiers.js';
+import { currencyCodeSchema, exactDecimalSchema, usageQuantitySchema, usageSourceSchema, } from './money.js';
+import { priceSnapshotSchema } from './priceVersion.js';
+/* -------------------------------------------------------------------------- */
+/*  1. Reservation                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Ask the ledger to hold the maximum a request could cost.
+ *
+ * `maxAmount` is the number the balance check is made against, and it is
+ * computed from the three inputs beside it rather than guessed: the units
+ * already known (the prompt), the ceiling on units still to come
+ * (`maxOutputTokens`), and the most expensive route the policy allows. Sizing a
+ * hold from a typical response rather than the worst allowed one is how a
+ * balance goes negative on a long generation.
+ */
+export const usageReservationRequestSchema = z.object({
+    /** See `version.ts`: exchanged between the edge and the ledger on its own. */
+    schemaVersion: z.literal(1),
+    idempotencyKey: idempotencyKeySchema,
+    attribution: inferenceAttributionSchema,
+    /** Units already determined by the request itself, e.g. input tokens. */
+    knownUnits: z.array(usageQuantitySchema).default([]),
+    /** The ceiling on generated output, when the request set one. */
+    maxOutputTokens: z.number().int().positive().safe().optional(),
+    /** The price version of the most expensive route the policy permits. */
+    ceilingPriceVersionId: z.string().min(1).max(128),
+    maxAmount: exactDecimalSchema,
+    currency: currencyCodeSchema,
+    expiresInSeconds: z.number().int().positive().max(86400),
+});
+/** Lifecycle of a hold. Terminal states are `settled`, `released`, `expired`. */
+export const usageReservationStatusSchema = z.enum([
+    'held',
+    'settled',
+    'released',
+    'expired',
+]);
+/**
+ * A hold placed against an account's balance.
+ *
+ * Reserved amounts are shown to customers distinctly from settled charges: a
+ * reservation is not money spent, and presenting the two as one number makes a
+ * balance appear to drop and then recover for every request.
+ */
+export const usageReservationSchema = z
+    .object({
+    /** See `version.ts`: read back by the edge and the Console on its own. */
+    schemaVersion: z.literal(1),
+    reservationId: z.string().min(1).max(128),
+    idempotencyKey: idempotencyKeySchema,
+    attribution: inferenceAttributionSchema,
+    status: usageReservationStatusSchema,
+    reservedAmount: exactDecimalSchema,
+    currency: currencyCodeSchema,
+    ceilingPriceVersionId: z.string().min(1).max(128),
+    createdAt: inferenceTimestampSchema,
+    expiresAt: inferenceTimestampSchema,
+    /** The receipt that consumed this hold. Present exactly when `settled`. */
+    settledReceiptId: z.string().min(1).max(128).optional(),
+})
+    .superRefine((reservation, ctx) => {
+    if (reservation.status === 'settled' && reservation.settledReceiptId === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['settledReceiptId'],
+            message: 'a settled reservation must name the receipt that settled it',
+        });
+    }
+    if (reservation.status !== 'settled' && reservation.settledReceiptId !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['settledReceiptId'],
+            message: 'only a settled reservation has a settling receipt',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  2. Usage report (data plane → Oxy)                                        */
+/* -------------------------------------------------------------------------- */
+/** How a request ended, from the data plane's point of view. */
+export const inferenceRequestOutcomeSchema = z.enum([
+    'completed',
+    'partial',
+    'cancelled',
+    'failed',
+]);
+/**
+ * The data plane's technical account of one request, and the ONLY shape a
+ * settlement is written from.
+ *
+ * `inferenceStreamUsageEventSchema` is not a narrower version of this one that
+ * could be widened into it — see that event's own comment. Its units are exact
+ * and settleable; the record around them is not inferable, so an edge settling
+ * from a stream event supplies the outcome itself and never promotes the event.
+ *
+ * No money and no price: the data plane measures units and names the route it
+ * used, and the control plane decides what that costs. Keeping the two apart is
+ * what allows a price to be corrected after the fact without re-running or
+ * re-measuring anything.
+ *
+ * `usageSource` is load-bearing when a provider returns no usage at all: the
+ * report still arrives, marked `estimated`, so settlement can apply the
+ * estimation policy knowingly instead of treating a reconstruction as fact.
+ *
+ * `units` is a PARTITION of what the request consumed, not a set of totals with
+ * details hanging off them — see `USAGE_UNITS` in `money.ts`. Reporting a provider's
+ * nested `prompt_tokens`/`completion_tokens` verbatim charges the cached and
+ * reasoning tokens twice, so subtracting the children out is part of what
+ * "normalized" means in this shape's name.
+ *
+ * **A `completed` report carries at least one unit, and the other outcomes need
+ * not.** `completed` is the one outcome that asserts the customer received the
+ * whole answer, so "delivered in full, consumed nothing measurable" is a
+ * contradiction — and it is one that BILLS NOTHING: settlement prices every
+ * reported unit and sums, so an empty list is a free request produced by a
+ * provider that simply omitted its usage block. The refinement makes that shape
+ * unparseable, and the policy behind it is refuse-and-release: the report is
+ * rejected and the hold is released, never estimated and charged.
+ *
+ * The three other outcomes legitimately carry none, which is why the rule is
+ * conditional rather than a `.min(1)` on the field. In the reference data plane
+ * `failed` is DERIVED from having no units — `outcomeFor` in
+ * Kaana's `internal/kaana/executor.go` returns `partial` when units exist and `failed`
+ * when they do not — and `cancelled` is reported for a client that stopped
+ * before anything was measured. An unconditional minimum would refuse those
+ * reports, and a refused report is a request that ran, cost money upstream and
+ * can never be settled or refunded.
+ */
+export const normalizedUsageReportSchema = z
+    .object({
+    /** See `version.ts`: emitted by the data plane as a whole message. */
+    schemaVersion: z.literal(2),
+    requestId: requestIdSchema,
+    generationId: generationIdSchema.optional(),
+    attribution: inferenceAttributionSchema,
+    outcome: inferenceRequestOutcomeSchema,
+    units: z.array(usageQuantitySchema),
+    usageSource: usageSourceSchema,
+    resolvedModelReference: modelReferenceSchema,
+    servingProvider: inferenceProviderSlugSchema,
+    /** Exact Kaana deployment that attempted the request; never inferred from names. */
+    deploymentId: deploymentIdSchema,
+    /** How many allowed route switches occurred while serving this request. */
+    routeSwitches: z.number().int().nonnegative().max(100),
+    startedAt: inferenceTimestampSchema,
+    completedAt: inferenceTimestampSchema,
+    timeToFirstTokenMs: z.number().int().nonnegative().safe().optional(),
+})
+    .superRefine((report, ctx) => {
+    // Compared as instants: two spellings of one moment sort differently as text.
+    if (Date.parse(report.completedAt) < Date.parse(report.startedAt)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['completedAt'],
+            message: 'a request cannot complete before it started',
+        });
+    }
+    const units = report.units.map((quantity) => quantity.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['units'],
+            message: 'each unit is reported once, as a total',
+        });
+    }
+    if (report.outcome === 'completed' && report.units.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['units'],
+            message: 'a completed request consumed something; report at least one unit',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  3. Receipt (settlement)                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The immutable record of what a request was actually charged.
+ *
+ * `priceSnapshot` is a COPY of the unit prices applied, not just the id of the
+ * price version they came from, so the arithmetic on this receipt can be
+ * checked years later without depending on any other record still existing.
+ *
+ * `platformFeeOnly` marks a BYOK request: the upstream provider billed the
+ * customer's own account directly, and `billedAmount` is Oxy's service fee
+ * rather than the cost of the tokens. Without the flag, the two look identical
+ * and a BYOK customer appears to have been charged twice for one request.
+ */
+export const usageReceiptSchema = z
+    .object({
+    /** See `version.ts`: returned to customers by `GET /v1/generations/:id`. */
+    schemaVersion: z.literal(1),
+    receiptId: z.string().min(1).max(128),
+    /** The hold this settled against. Absent for a charge with no reservation. */
+    reservationId: z.string().min(1).max(128).optional(),
+    idempotencyKey: idempotencyKeySchema,
+    attribution: inferenceAttributionSchema,
+    outcome: inferenceRequestOutcomeSchema,
+    units: z.array(usageQuantitySchema).min(1),
+    usageSource: usageSourceSchema,
+    priceSnapshot: priceSnapshotSchema,
+    billedAmount: exactDecimalSchema,
+    currency: currencyCodeSchema,
+    platformFeeOnly: z.boolean(),
+    resolvedModelReference: modelReferenceSchema,
+    servingProvider: inferenceProviderSlugSchema,
+    settledAt: inferenceTimestampSchema,
+})
+    .superRefine((receipt, ctx) => {
+    if (receipt.currency !== receipt.priceSnapshot.currency) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['priceSnapshot', 'currency'],
+            message: 'a receipt must be settled in the currency it was priced in',
+        });
+    }
+    const units = receipt.units.map((quantity) => quantity.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['units'],
+            message: 'each unit is settled once, as a total',
+        });
+    }
+});
+/* -------------------------------------------------------------------------- */
+/*  4. Refund / reversal                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * What a reversal acts on: an unused hold, or a settled charge.
+ *
+ * A discriminated union, so "release the rest of the hold" and "give back money
+ * already booked" can never be confused for one another — they hit different
+ * ledger accounts and only the second one is visible on an invoice.
+ */
+export const usageRefundSubjectSchema = z.discriminatedUnion('kind', [
+    z
+        .object({ kind: z.literal('reservation'), reservationId: z.string().min(1).max(128) })
+        .strict(),
+    z.object({ kind: z.literal('receipt'), receiptId: z.string().min(1).max(128) }).strict(),
+]);
+/** Why money was given back or a hold was released. */
+export const usageRefundReasonSchema = z.enum([
+    'unused_reservation',
+    'client_cancelled',
+    'upstream_failure',
+    'partial_stream',
+    'usage_unavailable',
+    'billing_correction',
+    'duplicate_charge',
+]);
+/** Reasons that can only ever act on a settled charge. */
+const RECEIPT_ONLY_REFUND_REASONS = new Set([
+    'billing_correction',
+    'duplicate_charge',
+]);
+/**
+ * An immutable reversal entry.
+ *
+ * `amount` is non-negative like every other amount in this contract: the
+ * direction is carried by the record being a refund, not by a sign that a
+ * consumer could read the wrong way round. Idempotent by key, so a retried
+ * refund releases the same money once.
+ */
+export const usageRefundSchema = z
+    .object({
+    /** See `version.ts`: a ledger record read back on its own. */
+    schemaVersion: z.literal(1),
+    refundId: z.string().min(1).max(128),
+    idempotencyKey: idempotencyKeySchema,
+    attribution: inferenceAttributionSchema,
+    subject: usageRefundSubjectSchema,
+    reason: usageRefundReasonSchema,
+    amount: exactDecimalSchema,
+    currency: currencyCodeSchema,
+    createdAt: inferenceTimestampSchema,
+})
+    .superRefine((refund, ctx) => {
+    if (refund.reason === 'unused_reservation' && refund.subject.kind !== 'reservation') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['reason'],
+            message: 'an unused reservation is released against the reservation, not a receipt',
+        });
+    }
+    if (RECEIPT_ONLY_REFUND_REASONS.has(refund.reason) && refund.subject.kind !== 'receipt') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['reason'],
+            message: `${refund.reason} reverses a settled charge, so it acts on a receipt`,
+        });
+    }
+});

package/dist/esm/inference/version.js

@@ -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 const INFERENCE_CONTRACT_VERSION = '2.0.0';

package/dist/esm/keyRecovery.js

@@ -0,0 +1,88 @@
+/**
+ * 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 const backupLookupIdSchema = z
+    .string()
+    .trim()
+    .regex(/^[0-9a-fA-F]{64}$/, 'lookupId must be 64 hex characters');
+/**
+ * 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 const encryptedBackupEnvelopeSchema = z.object({
+    version: z.number().int().positive(),
+    algorithm: z.literal('xchacha20poly1305'),
+    kdfInfo: z.string().min(1),
+    nonce: z.string().trim().min(1),
+    ciphertext: z.string().trim().min(1),
+    publicKeyHint: z.string().trim().min(1),
+    createdAt: z.string().trim().min(1),
+});
+/**
+ * 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 const backupUploadRequestSchema = encryptedBackupEnvelopeSchema.extend({
+    /**
+     * 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: backupLookupIdSchema,
+});
+/**
+ * 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 const backupStatusResponseSchema = z.object({
+    exists: z.boolean(),
+    publicKeyHint: z.string().optional(),
+    createdAt: z.string().optional(),
+});

package/dist/esm/keyRotation.js

@@ -0,0 +1,72 @@
+/**
+ * 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 const rotateKeyChallengeResponseSchema = z.object({
+    challenge: z.string(),
+    /** ISO-8601 expiry timestamp. */
+    expiresAt: z.string(),
+});
+/**
+ * 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 const rotateKeyCompleteRequestSchema = z.object({
+    newPublicKey: z.string().trim().min(1),
+    challenge: z.string().trim().min(1),
+    signature: z.string().trim().min(1),
+    /** Proof-of-possession: the NEW key signs the rotate_key_new payload. */
+    newKeyProof: z.string().trim().min(1),
+    timestamp: z.number(),
+    /**
+     * 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.boolean().optional(),
+});
+/** Response of `POST /auth/rotate/complete`: the account's new (rotated) public key. */
+export const rotateKeyCompleteResponseSchema = z.object({
+    success: z.boolean(),
+    publicKey: z.string(),
+    message: z.string(),
+});

package/dist/esm/links.js

@@ -0,0 +1,65 @@
+/**
+ * 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';
+export const linkPreviewSchema = z.object({
+    url: z.string(),
+    status: z.enum(['resolved', 'pending', 'empty']),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    image: z.string().optional(),
+    siteName: z.string().optional(),
+    favicon: z.string().optional(),
+    resolvedAt: z.string().optional(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Batch request / response                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const linkPreviewBatchRequestSchema = z.object({
+    urls: z.array(z.string().max(2048)).min(1).max(50),
+});
+export const linkPreviewBatchResponseSchema = z.object({
+    data: z.record(z.string(), linkPreviewSchema),
+});
+/**
+ * Wire shape of the single-URL unfurl lookup (`GET`) — a bare
+ * {@link LinkPreview}.
+ */
+export const linkPreviewResponseSchema = linkPreviewSchema;