@oxyhq/contracts 0.26.0 → 0.28.0

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

@@ -0,0 +1,176 @@
+/**
+ * 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';
+/**
+ * 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 declare const INFERENCE_SCOPES: readonly ["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"];
+export declare const inferenceScopeSchema: z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>;
+/**
+ * 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 declare const billingPrincipalSchema: z.ZodObject<{
+    accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+}, "strict", z.ZodTypeAny, {
+    accountId: string & z.BRAND<"OxyAccountId">;
+}, {
+    accountId: string;
+}>;
+/**
+ * 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 declare const authenticatedPrincipalSchema: z.ZodObject<{
+    billing: z.ZodObject<{
+        accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    }, "strict", z.ZodTypeAny, {
+        accountId: string & z.BRAND<"OxyAccountId">;
+    }, {
+        accountId: string;
+    }>;
+    applicationId: z.ZodString;
+    credentialId: z.ZodString;
+    environment: z.ZodEnum<["development", "staging", "production"]>;
+    inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    environment: "development" | "staging" | "production";
+    credentialId: string;
+    applicationId: string;
+    billing: {
+        accountId: string & z.BRAND<"OxyAccountId">;
+    };
+    inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+}, {
+    environment: "development" | "staging" | "production";
+    credentialId: string;
+    applicationId: string;
+    billing: {
+        accountId: string;
+    };
+    inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+}>;
+/**
+ * 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 OXY EDGE, on admission and before
+ * authentication completes, and is always present (ADR 0007). Not by the data
+ * plane: a data plane that minted the correlation key could not correlate a
+ * request it never received, and the requests rejected at the edge are exactly
+ * the ones an operator most needs to find.
+ *
+ * `generationId` is present once a generation exists, which is why it is
+ * optional on a request and expected on a receipt. That one IS the data plane's,
+ * because only the data plane knows how many outputs a request produced.
+ */
+export declare const inferenceAttributionSchema: z.ZodObject<{
+    principal: z.ZodObject<{
+        billing: z.ZodObject<{
+            accountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+        }, "strict", z.ZodTypeAny, {
+            accountId: string & z.BRAND<"OxyAccountId">;
+        }, {
+            accountId: string;
+        }>;
+        applicationId: z.ZodString;
+        credentialId: z.ZodString;
+        environment: z.ZodEnum<["development", "staging", "production"]>;
+        inferenceScopes: z.ZodArray<z.ZodEnum<["inference:invoke", "inference:models:read", "inference:usage:read", "inference:routing:read", "inference:routing:write", "inference:providers:read", "inference:providers:write"]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string & z.BRAND<"OxyAccountId">;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    }, {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    }>;
+    userId: z.ZodOptional<z.ZodBranded<z.ZodString, "DelegatedUserId">>;
+    requestId: z.ZodString;
+    generationId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requestId: string;
+    principal: {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string & z.BRAND<"OxyAccountId">;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    };
+    userId?: (string & z.BRAND<"DelegatedUserId">) | undefined;
+    generationId?: string | undefined;
+}, {
+    requestId: string;
+    principal: {
+        environment: "development" | "staging" | "production";
+        credentialId: string;
+        applicationId: string;
+        billing: {
+            accountId: string;
+        };
+        inferenceScopes: ("inference:invoke" | "inference:models:read" | "inference:usage:read" | "inference:routing:read" | "inference:routing:write" | "inference:providers:read" | "inference:providers:write")[];
+    };
+    userId?: string | undefined;
+    generationId?: string | undefined;
+}>;
+export type InferenceScope = z.infer<typeof inferenceScopeSchema>;
+export type BillingPrincipal = z.infer<typeof billingPrincipalSchema>;
+export type AuthenticatedPrincipal = z.infer<typeof authenticatedPrincipalSchema>;
+export type InferenceAttribution = z.infer<typeof inferenceAttributionSchema>;