@oxyhq/contracts 0.25.0 → 0.27.0

package/dist/esm/accountGraph.js

@@ -14,9 +14,10 @@ import { z } from 'zod';
  * `db/schema/users.ts` mirrors to keep the `users_kind_check` CHECK honest.
  *
  * Deriving the union from the array instead would cost nothing here and be paid
- * by consumers: `kind` travels into `@oxyhq/services` through
- * `SwitchableAccount`, where an indexed-access type is materially more
- * expensive to check than a literal union.
+ * by consumers: `kind` travels into `@oxyhq/services` on every device-directory
+ * context (`deviceContextSchema.kind` → `DeviceContext` → the switcher rows),
+ * and an indexed-access type is materially more expensive to check there than a
+ * literal union.
  */
 export const ACCOUNT_KINDS = [
     'personal',

package/dist/esm/browserHub.js

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+import { deviceDirectorySchema } from './deviceDirectory.js';
+/**
+ * The browser DeviceSession hub at `auth.oxy.so` (issue #937, Phase 5, ADR 0003).
+ *
+ * Two wire surfaces live in this file and they are deliberately different
+ * shapes, because they answer to different callers:
+ *
+ *  - The `browserHub*` schemas below the first divider are the API's
+ *    (`api.oxy.so/session/browser-hub/*`), spoken ONLY by the IdP's own
+ *    server/edge layer. They carry the raw handle and a bearer, so nothing that
+ *    speaks them may run in a browser.
+ *  - The `hub*` schemas below the second divider are the EDGE's
+ *    (`auth.oxy.so/hub/*`), spoken by the IdP SPA. They carry neither: the
+ *    handle stays in an `HttpOnly` cookie the script cannot read, and the
+ *    device-wide bearer stays at the edge.
+ *
+ * That split is the whole point of the phase. A single schema covering both
+ * would let a refactor move a credential across the boundary without any type
+ * changing shape.
+ *
+ * ## What is NOT reopened here
+ *
+ * Relying-party origins remain zero-cookie: they keep `{deviceId,
+ * deviceSecret}` + `POST /session/device/token` and set no cookie of any kind.
+ * `auth.oxy.so` alone holds a handle, first-party only. There is no
+ * refresh-token family and no bootstrap hop.
+ */
+/* -------------------------------------------------------------------------- */
+/*  The cookie                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * The one cookie name, `__Host-` prefixed.
+ *
+ * The prefix is not decoration: a browser refuses to store a `__Host-` cookie
+ * that carries a `Domain` attribute or a `Path` other than `/`, or that arrives
+ * without `Secure`. So the name itself is what makes "bound to `auth.oxy.so`
+ * alone, readable by no other `oxy.so` host" enforced by the client rather than
+ * merely intended by the server — including against a compromised sibling
+ * subdomain, which is the specific attack `Domain=.oxy.so` would have opened.
+ */
+export const BROWSER_HUB_COOKIE_NAME = '__Host-oxy-device';
+/**
+ * The exact attribute set the edge sets, in the order it writes them.
+ *
+ * Held as data rather than as a template string so a test can assert the set
+ * rather than a rendered line, and so removing one attribute is a diff to a
+ * named constant instead of an edit inside a string literal.
+ *
+ * `Max-Age` is deliberately NOT in this list — see
+ * {@link BROWSER_HUB_HANDLE_TTL_MS}, which the edge appends. Everything here is
+ * a SECURITY attribute and none of them is ever conditional.
+ */
+export const BROWSER_HUB_COOKIE_ATTRIBUTES = ['Secure', 'HttpOnly', 'SameSite=Lax', 'Path=/'];
+/**
+ * How long a hub handle lives, server-side and in the cookie alike.
+ *
+ * Thirty days. The cookie's `Max-Age` is derived from this same constant so the
+ * two cannot disagree: a cookie outliving its credential produces a browser that
+ * believes it is signed in and is refused on every call, and a credential
+ * outliving its cookie leaves an un-addressable row alive on the server.
+ *
+ * A hub handle is NOT a session cookie (one with no `Max-Age`, discarded when
+ * the browser closes). It cannot be: the thing it identifies is the browser
+ * PROFILE's device session, and a device session that evaporates when the user
+ * quits their browser would send them back to a QR scan every morning — the
+ * exact failure ADR 0003 exists to remove.
+ */
+export const BROWSER_HUB_HANDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/* -------------------------------------------------------------------------- */
+/*  api.oxy.so/session/browser-hub/*  —  spoken by the edge, never a browser   */
+/* -------------------------------------------------------------------------- */
+/**
+ * The raw handle, as it travels between the edge and the API.
+ *
+ * An opaque base64url random value and NOTHING else — no token, no user id, no
+ * device id, no account id, no serialized state. The server stores only
+ * `sha256(handle)`, so a dump of the column cannot address a browser.
+ *
+ * The minimum length is a floor against an empty or truncated value reaching a
+ * hash comparison, not a statement about the entropy: that is fixed by the
+ * issuer (`BROWSER_HUB_HANDLE_BYTES` in the API), and a handle is the only
+ * credential in this flow, so it is 256 bits.
+ */
+export const browserHubHandleSchema = z.string().min(32);
+/** Request body of every handle-presenting API endpoint. */
+export const browserHubHandleRequestSchema = z.object({
+    handle: browserHubHandleSchema,
+});
+/**
+ * Response of `POST /session/browser-hub/establish` and `.../rotate`.
+ *
+ * The raw handle is returned exactly ONCE, to the edge, which puts it straight
+ * into the cookie and keeps no copy. It is never logged, never re-readable, and
+ * never reaches the browser's script context.
+ */
+export const browserHubHandleResponseSchema = z.object({
+    handle: browserHubHandleSchema,
+    expiresAt: z.string(),
+});
+/**
+ * Response of `POST /session/browser-hub/resolve` — the browser's device
+ * session, resolved from the handle alone.
+ *
+ * Carries a bearer because the edge needs one to run the authorize lane on the
+ * browser's behalf. It is the ordinary short-lived access token of the device's
+ * active context, and it stops at the edge.
+ */
+export const browserHubResolveResponseSchema = z.object({
+    accessToken: z.string().min(1),
+    expiresAt: z.string(),
+    directory: deviceDirectorySchema,
+});
+/**
+ * Why a handle did not resolve. A CLOSED set, and deliberately coarse.
+ *
+ *  - `invalid_handle`    — unknown, expired, or revoked. One code for all
+ *                          three: distinguishing them would tell a caller
+ *                          holding a guessed value whether it ever existed.
+ *  - `no_active_session` — the handle is good and the device has nothing live
+ *                          to mint for. The credential is NOT revoked; the
+ *                          browser re-authenticates and keeps its cookie.
+ */
+export const browserHubErrorSchema = z.enum(['invalid_handle', 'no_active_session']);
+/** Response of `POST /session/browser-hub/revoke`. Idempotent by construction. */
+export const browserHubRevokeResponseSchema = z.object({
+    revoked: z.boolean(),
+});
+/* -------------------------------------------------------------------------- */
+/*  auth.oxy.so/hub/*  —  spoken by the IdP SPA                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * What the SPA is allowed to know about the hub session.
+ *
+ * `signed_out` covers "no cookie", "cookie present but the handle no longer
+ * resolves" and "resolved, but the device has nothing live" — from the script's
+ * side those are one state, and collapsing them here is what stops a UI from
+ * branching on a distinction it must not act on.
+ *
+ * `active` carries the DIRECTORY and no credential. A switcher renders from it;
+ * nothing in it can be spent against the API. The bearer that produced it never
+ * left the edge.
+ */
+export const hubSessionSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('signed_out') }),
+    z.object({ status: z.literal('active'), directory: deviceDirectorySchema }),
+]);
+/** Request body of `POST /hub/claim` — the Commons approval lane's handoff. */
+export const hubClaimRequestSchema = z.object({
+    /**
+     * The secret `sessionToken` of an approved `AuthSession`, held only by the
+     * page that created it. The edge spends it server-side: the access token and
+     * device secret the claim yields are consumed to establish the hub and are
+     * then discarded, so neither is ever returned to the script.
+     */
+    sessionToken: z.string().min(1),
+});
+/** Request body of `POST /hub/activate` — pick the globally active context. */
+export const hubActivateRequestSchema = z.object({
+    contextId: z.string().min(1),
+});
+/**
+ * Request body of `POST /hub/authorize` — a later official origin joining.
+ *
+ * There is no `prompt` field, and that is not an omission. `'none'` is absent
+ * from `buildOAuthAuthorizeUrl`'s union in `@oxyhq/core` precisely so a silent
+ * loop cannot be rebuilt in one line, and this endpoint would be the second
+ * place to rebuild it. A caller that needs a login or consent prompt gets one
+ * by not passing `approve`.
+ */
+export const hubAuthorizeRequestSchema = z.object({
+    clientId: z.string().min(1),
+    redirectUri: z.string().url(),
+    state: z.string().optional(),
+    codeChallenge: z.string().min(1),
+    /** S256 only. `plain` is refused before the request leaves the edge. */
+    codeChallengeMethod: z.literal('S256'),
+    scope: z.string().optional(),
+    /**
+     * The user's explicit answer on the consent screen.
+     *
+     * Absent or `false` means "tell me whether consent is needed"; the edge then
+     * returns `consent_required` and mints nothing. Only `true` may mint, and only
+     * the consent screen's own button sends it — which is why the decision of
+     * WHETHER consent is required is re-read from the server on both passes rather
+     * than remembered from the first.
+     */
+    approve: z.boolean().optional(),
+});
+/**
+ * Result of `POST /hub/authorize`.
+ *
+ * `signed_out` is the honest answer for a browser with no hub session: the SPA
+ * runs the ordinary Commons-first authentication and tries again. It is never a
+ * redirect the edge performs on the browser's behalf — no automatic chain
+ * across Oxy origins, and nothing here can be hidden inside an iframe.
+ */
+export const hubAuthorizeResultSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('signed_out') }),
+    z.object({
+        status: z.literal('consent_required'),
+        reason: z.enum(['new', 'scope_changed']),
+        userConsentScopes: z.array(z.string()).optional(),
+    }),
+    z.object({
+        status: z.literal('code'),
+        code: z.string().min(1),
+        state: z.string().nullable(),
+        redirectUri: z.string(),
+        expiresIn: z.number().int().positive(),
+    }),
+]);

package/dist/esm/deviceDirectory.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { accountKindSchema } from './accountGraph.js';
+import { activeTokenSchema, deviceSessionStateSchema } from './deviceSession.js';
+import { userNameSchema } from './userResponse.js';
+/**
+ * The canonical device directory — the ONE server-authoritative read model an
+ * account switcher renders (issue #937, ADR 0002).
+ *
+ * It replaces the client-side union of `DeviceSessionState.accounts[]` with a
+ * separately fetched `AccountNode[]` graph. That union cannot be correct on a
+ * device holding more than one person: the client only ever holds ONE caller's
+ * account graph, so it cannot enumerate what the OTHER principals may act as.
+ * Switchability is an authorization question, so the server answers it.
+ *
+ * The directory is deterministic and revision-bound: two reads at the same
+ * `revision` describe the same device state, and `revision` only advances on a
+ * real mutation (an idempotent activation advances nothing — ADR 0002).
+ */
+/**
+ * How a principal reaches an account.
+ *
+ * Mirrors `AccountRelationship` in `@oxyhq/core`'s account graph rather than
+ * inventing a second vocabulary for the same fact:
+ *  - `self`   — the principal's own personal account (`principal.userId === accountId`)
+ *  - `owner`  — the principal owns this account
+ *  - `member` — the principal holds a membership granting `account:act_as`
+ */
+export const deviceContextRelationshipSchema = z.enum(['self', 'owner', 'member']);
+/**
+ * Sanitized display metadata for a principal or an account context.
+ *
+ * Deliberately NOT `userResponseSchema`: a switcher needs a handle, a name, an
+ * avatar and the accent the row is drawn in, and the directory is read by every
+ * app on the device — so it carries the minimum that renders a row and nothing
+ * that would make it a general profile feed. `name.displayName` stays OPTIONAL;
+ * consumers fall back to the handle (`getNormalizedUserHandle`), never to a
+ * synthesized name.
+ *
+ * `color` is here and `email` is not, and the line between them is what the
+ * field is FOR rather than how sensitive it looks. An accent is a property of
+ * drawing the row — without it every non-active row falls back to the ambient
+ * theme accent and a device holding two people renders them identically
+ * (issue #961). An address is somebody's contact detail, and the `@handle` the
+ * secondary line already shows fills the same slot, so putting one in a payload
+ * every installed app reads would widen the profile for no rendering gain.
+ */
+export const deviceDirectoryProfileSchema = z.object({
+    id: z.string().min(1),
+    username: z.string(),
+    name: userNameSchema.optional(),
+    avatar: z.string().nullable().optional(),
+    /**
+     * Named Bloom color preset (e.g. `"blue"`), or null when the account has
+     * none. Same shape as `userResponseSchema.color` — one spelling of one fact,
+     * so a consumer that themes a row from either source reads the same values.
+     */
+    color: z.string().nullable().optional(),
+});
+/**
+ * One `principal acting as account` pair — the globally switchable unit.
+ *
+ * `id` is the identifier `POST /session/device/activate` takes. It names the
+ * PAIR, not the account: the same `accountId` legitimately appears under two
+ * principals on a shared device, and those are different sessions, permissions,
+ * audit actors and revocation paths.
+ *
+ * `onDevice` is `false` for a context the principal may act as but has never
+ * activated here — it exists as a row so it has a stable id to activate, and
+ * its delegated session is minted on first activation rather than eagerly for
+ * every organization the principal belongs to.
+ *
+ * `available` is `principalLive && (personal || live account:act_as)`, and the
+ * principal clause is not decoration: a principal whose own personal session
+ * has died makes EVERY context of theirs unavailable, including delegated ones
+ * whose sessions are perfectly alive. Activation verifies the principal's
+ * personal session (ADR 0002 step 3), so a client that models availability as
+ * "delegated context has a live session ⇒ activatable" will be refused by the
+ * server and the context healed away.
+ *
+ * A managed account whose membership was revoked is returned with
+ * `available: false` rather than silently omitted, so the UI can explain a row
+ * disappearing instead of just dropping it.
+ *
+ * (An earlier version of this comment described `available` as the
+ * `account:act_as` verdict alone. It was written before the server existed and
+ * was weaker than the code that shipped — the kind of wrong statement nothing
+ * recomputes, so it is spelled out here in full.)
+ */
+export const deviceAccountContextSchema = z.object({
+    id: z.string().min(1),
+    accountId: z.string().min(1),
+    kind: accountKindSchema,
+    relationship: deviceContextRelationshipSchema,
+    account: deviceDirectoryProfileSchema,
+    onDevice: z.boolean(),
+    available: z.boolean(),
+    active: z.boolean(),
+    lastUsedAt: z.number().nullable(),
+});
+/**
+ * A human who authenticated onto this device.
+ *
+ * Never an organization, project, channel or bot — those are subjects a
+ * principal acts as, and they appear only in `contexts`. `authuser` is the
+ * Google-style signed-in-human slot and belongs HERE, not to an account: adding
+ * an organization must never consume one.
+ */
+export const devicePrincipalSchema = z.object({
+    id: z.string().min(1),
+    userId: z.string().min(1),
+    authuser: z.number().int().nonnegative(),
+    user: deviceDirectoryProfileSchema,
+    contexts: z.array(deviceAccountContextSchema),
+});
+/**
+ * Response of `GET /session/device/directory`.
+ *
+ * `activeContextId` is the authority for what every official app in
+ * `sessionMode: 'account'` renders. It is null when the device has no active
+ * context — a real state (every context removed, or an active context healed
+ * away), not an error.
+ */
+export const deviceDirectorySchema = z.object({
+    deviceId: z.string().min(1),
+    revision: z.number().int().nonnegative(),
+    activeContextId: z.string().nullable(),
+    principals: z.array(devicePrincipalSchema),
+    updatedAt: z.number(),
+});
+/**
+ * Request body of `POST /session/device/activate`.
+ *
+ * `contextId`, never `accountId`: an account id cannot name a context on a
+ * device where two people can both reach the same organization, and resolving
+ * that ambiguity server-side would mean guessing inside an authorization path.
+ */
+export const deviceActivateRequestSchema = z.object({
+    contextId: z.string().min(1),
+});
+/**
+ * Response of `POST /session/device/activate`.
+ *
+ * Carries the post-transition directory AND the bearer for the newly active
+ * context, because the client's ordering invariant is
+ * `commit token → reset caches → publish snapshot → notify` (ADR 0002). Handing
+ * the directory back without the token would force a second round trip in the
+ * middle of that sequence, which is exactly where a component would render the
+ * new subject while still holding the previous subject's bearer.
+ *
+ * `activeToken` is null when the activation legitimately produced no bearer for
+ * THIS caller — an identity-pinned client, or a caller whose application is not
+ * entitled to a token for the new context. It is never an error signal.
+ */
+export const deviceActivateResponseSchema = z.object({
+    directory: deviceDirectorySchema,
+    activeToken: activeTokenSchema.nullable(),
+});
+/**
+ * Response of the CONTEXT-aware removals — `POST /session/device/signout` with
+ * `{ contextId }` (one `principal → account` pair) or `{ principalId }` (one
+ * person and every context they reach, and nobody else's).
+ *
+ * It carries BOTH halves because a removal elects a replacement active context,
+ * so both the directory and the flat compatibility projection move in the same
+ * transition — and a client that learned only one of them would render one
+ * half of a device that no longer exists.
+ *
+ * This is deliberately NOT {@link deviceSessionSyncSchema} and must never be
+ * merged into it. A zod object strips unknown keys, so `{directory, state,
+ * activeToken}` parses cleanly as `{state, activeToken}` — silently dropping the
+ * directory. One schema covering both shapes would therefore make "the server
+ * stopped sending the directory" and "this endpoint never sends one"
+ * indistinguishable at the parse, on the exact path that decides which identity
+ * the app is running as. Two schemas fail closed instead: `directory` is
+ * required here, so a directory-less payload is refused outright.
+ *
+ * `activeToken` is null on the same terms as everywhere else — an identity-
+ * pinned caller, or one not entitled to a bearer for the newly-elected context —
+ * and null is also the honest answer when the removal left the device with no
+ * active context at all.
+ */
+export const deviceDirectorySyncSchema = z.object({
+    directory: deviceDirectorySchema,
+    state: deviceSessionStateSchema,
+    activeToken: activeTokenSchema.nullable(),
+});

package/dist/esm/index.js

@@ -70,6 +70,9 @@ export {
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
 export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
+export { deviceContextRelationshipSchema, deviceDirectoryProfileSchema, deviceAccountContextSchema, devicePrincipalSchema, deviceDirectorySchema, deviceActivateRequestSchema, deviceActivateResponseSchema, deviceDirectorySyncSchema, } from './deviceDirectory.js';
+export { oauthConsentDecisionSchema, oauthAuthorizeCodeResponseSchema, } from './oauth.js';
+export { BROWSER_HUB_COOKIE_NAME, BROWSER_HUB_COOKIE_ATTRIBUTES, BROWSER_HUB_HANDLE_TTL_MS, browserHubHandleSchema, browserHubHandleRequestSchema, browserHubHandleResponseSchema, browserHubResolveResponseSchema, browserHubErrorSchema, browserHubRevokeResponseSchema, hubSessionSchema, hubClaimRequestSchema, hubActivateRequestSchema, hubAuthorizeRequestSchema, hubAuthorizeResultSchema, } from './browserHub.js';
 export { 
 // Schemas
 loginResultSchema, } from './deviceBoot.js';
@@ -99,3 +102,48 @@ devicePairingStatusSchema, deviceTransferInitRequestSchema, deviceTransferInitRe
 export { 
 // Schemas — transparency log (checkpoints + inclusion proofs)
 transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency.js';
+/* -------------------------------------------------------------------------- */
+/*  Inference (Oxy↔data-plane) — issue #972                                        */
+/* -------------------------------------------------------------------------- */
+export { 
+// The version of the contract SET; per-shape versions live in the data.
+INFERENCE_CONTRACT_VERSION, } from './inference/version.js';
+export { 
+// Principal identifiers. `oxyAccountIdSchema` and `delegatedUserIdSchema`
+// are branded apart so a delegated end user can never become the payer.
+oxyAccountIdSchema, delegatedUserIdSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, generationIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, 
+// Wire primitives
+inferenceTimestampSchema, inferenceDateSchema, inferenceHttpsUrlSchema, 
+// Catalogue references
+publisherSlugSchema, modelSlugSchema, modelIdSchema, modelRevisionLabelSchema, modelReferenceSchema, routingProfileSlugSchema, inferenceProviderSlugSchema, deploymentIdSchema, inferenceRegionSchema, RESERVED_ALIA_PUBLISHER, } from './inference/identifiers.js';
+export { 
+// Exact money and metered units — never floats, units never money.
+currencyCodeSchema, INFERENCE_MONEY_SCALE, exactDecimalSchema, moneySchema, USAGE_UNITS, usageUnitSchema, USAGE_SOURCES, usageSourceSchema, usageQuantitySchema, unitPriceSchema, } from './inference/money.js';
+export { 
+// Canonical attribution: who pays, which app, which credential, which user.
+INFERENCE_SCOPES, inferenceScopeSchema, billingPrincipalSchema, authenticatedPrincipalSchema, inferenceAttributionSchema, } from './inference/attribution.js';
+export { 
+// Closed error vocabulary + retryability + a leak-proof provider passthrough.
+INFERENCE_ERROR_CODES, NON_RETRYABLE_INFERENCE_ERROR_CODES, inferenceErrorCodeSchema, upstreamErrorCategorySchema, safeErrorTextSchema, providerErrorPassthroughSchema, inferenceErrorSchema, } from './inference/errors.js';
+export { 
+// Price versions and the snapshot a settled receipt keeps.
+priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
+export { 
+// The six distinct catalogue objects + the customer-safe projection.
+inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
+export { 
+// Routing policy: every control, plus the refinement that rejects a policy
+// no route could ever satisfy.
+routingTargetSchema, routingPolicyScopeSchema, routingFallbackPolicySchema, routingPolicySchema, routingPolicyReferenceSchema, } from './inference/routingPolicy.js';
+export { 
+// The normalized Oxy→data-plane request envelope.
+inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, } from './inference/request.js';
+export { 
+// Normalized SSE events.
+inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents.js';
+export { 
+// Reserve → settle → refund.
+usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage.js';
+export { 
+// BYOK connection metadata that structurally cannot carry a secret.
+providerConnectionScopeSchema, providerSecretReferenceSchema, providerConnectionValidationSchema, providerConnectionStatusSchema, providerConnectionSchema, } from './inference/providerConnection.js';

package/dist/esm/inference/attribution.js

@@ -0,0 +1,98 @@
+/**
+ * Canonical attribution for an inference request.
+ *
+ * Every accepted request resolves to an Oxy account, an Oxy application, the
+ * Oxy credential that authenticated it, an optional delegated end user, and the
+ * ids that correlate it across the edge, the data plane and the ledger. The
+ * data plane may store these as immutable references; it never owns or mutates
+ * them, and it never mints a customer identity of its own.
+ *
+ * The rule this file encodes structurally, rather than restating in prose:
+ * **the delegated `userId` can never be the billing identity.** Two independent
+ * mechanisms enforce it, one at compile time and one at parse time, because a
+ * delegated identity being charged for somebody else's workload is the kind of
+ * mistake that produces a correct-looking invoice for the wrong customer:
+ *
+ *  1. `accountId` and `userId` carry DIFFERENT brands, so neither is assignable
+ *     to the other in any consumer without a cast.
+ *  2. {@link billingPrincipalSchema} is `.strict()` and holds exactly one field,
+ *     so a payload that smuggles `userId` into the billing block is rejected at
+ *     the parse rather than stripped and forgotten.
+ *
+ * These shapes are EMBEDDED — they ride inside a request envelope, a receipt or
+ * a ledger record and inherit its `schemaVersion`. Versioning them separately
+ * would let one message claim two versions.
+ *
+ * Decided in: docs/adr/0007-canonical-request-attribution.md.
+ */
+import { z } from 'zod';
+import { delegatedUserIdSchema, generationIdSchema, inferenceEnvironmentSchema, oxyAccountIdSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, } from './identifiers.js';
+/**
+ * The inference capability scopes the data plane needs to know about.
+ *
+ * A credential may carry many other Oxy scopes; only these cross the boundary,
+ * because the data plane's authorization questions are exactly "may this caller
+ * invoke", "may it read the catalogue", "may it read usage", "may it read or
+ * write routing", "may it read or write provider connections". Everything else
+ * is the control plane's business and is not the data plane's to hold.
+ */
+export const INFERENCE_SCOPES = [
+    'inference:invoke',
+    'inference:models:read',
+    'inference:usage:read',
+    'inference:routing:read',
+    'inference:routing:write',
+    'inference:providers:read',
+    'inference:providers:write',
+];
+export const inferenceScopeSchema = z.enum(INFERENCE_SCOPES);
+/**
+ * The financially responsible principal, and the ONLY identity a charge may be
+ * booked against.
+ *
+ * It is its own type — not a field on a larger principal object — precisely so
+ * that a function taking "who pays" cannot be handed a user, a session, a
+ * device or an application. It cannot be constructed from a delegated user id:
+ * the brands differ, and this object accepts no other key.
+ */
+export const billingPrincipalSchema = z
+    .object({
+    accountId: oxyAccountIdSchema,
+})
+    .strict();
+/**
+ * Who authenticated, as resolved by the Oxy edge before a request is forwarded.
+ *
+ * Mirrors what a verified Oxy service token carries (`appId`, `credentialId`,
+ * `ownerAccountId`, `environment`, effective scopes) so that the two
+ * authentication paths — a machine API key and a first-party service token —
+ * produce one shape downstream. The data plane authorizes against this
+ * envelope; it does not re-derive access from its own database, because it has
+ * no account graph to re-derive it from.
+ */
+export const authenticatedPrincipalSchema = z.object({
+    billing: billingPrincipalSchema,
+    applicationId: oxyApplicationIdSchema,
+    credentialId: oxyCredentialIdSchema,
+    environment: inferenceEnvironmentSchema,
+    inferenceScopes: z.array(inferenceScopeSchema),
+});
+/**
+ * The attribution block carried by every request, receipt and ledger record.
+ *
+ * `userId` is the OPTIONAL delegated end user — Alia's `X-Oxy-User-Id`. It is
+ * attribution only: it never changes which account is charged, never grants
+ * access, and lives outside {@link billingPrincipalSchema} so that no code path
+ * can read it as the payer.
+ *
+ * `requestId` is generated by the data plane and always present; `generationId`
+ * is present
+ * once a generation exists, which is why it is optional on a request and
+ * expected on a receipt.
+ */
+export const inferenceAttributionSchema = z.object({
+    principal: authenticatedPrincipalSchema,
+    userId: delegatedUserIdSchema.optional(),
+    requestId: requestIdSchema,
+    generationId: generationIdSchema.optional(),
+});