@oxyhq/contracts 0.27.0 → 0.29.0

package/dist/esm/inference/errors.js

@@ -32,6 +32,17 @@ import { inferenceProviderSlugSchema, requestIdSchema } from './identifiers.js';
  * `quota_exceeded`, `byok_credential_invalid`), routing/permission policy
  * (`policy_violation`, `commercial_permission_denied`, `no_route_available`),
  * and the platform or its upstreams (everything from `deployment_unavailable`).
+ *
+ * The platform group is NOT uniformly retryable, and that is the point of
+ * `provider_credential_invalid` sitting in it: an upstream that refuses the
+ * PLATFORM's own credential fails every identical retry until an operator
+ * rotates a key, so classifying it as `provider_error` would send every client
+ * into a retry loop against a request that cannot succeed.
+ *
+ * `provider_billing_refused` is in that group for the same reason and was found
+ * the same way — an upstream declining to bill OXY (Anthropic answers 402) has
+ * to be distinguishable from the customer's own balance running out, or the
+ * error tells them to go and top up an account that is not the one at fault.
  */
 export const INFERENCE_ERROR_CODES = [
     'invalid_request',
@@ -58,6 +69,8 @@ export const INFERENCE_ERROR_CODES = [
     'provider_error',
     'provider_timeout',
     'provider_overloaded',
+    'provider_credential_invalid',
+    'provider_billing_refused',
     'service_unavailable',
     'internal_error',
 ];
@@ -70,6 +83,19 @@ export const inferenceErrorCodeSchema = z.enum(INFERENCE_ERROR_CODES);
  * names, while a quota is an account-level ceiling that only a human raises.
  * `cancelled` is here because the caller already withdrew the request; a client
  * that retries it is contradicting its own cancellation.
+ *
+ * `byok_credential_invalid` and `provider_credential_invalid` are the same
+ * failure seen from the two sides of the BYOK boundary — the customer's own
+ * upstream credential and the platform's — and they are two codes rather than
+ * one because only the first names an action the customer can take. Both are
+ * non-retryable for the same reason: a credential an upstream has refused keeps
+ * being refused until somebody replaces it.
+ *
+ * `quota_exceeded` and `provider_billing_refused` divide along the same line:
+ * both are money, but one is the CUSTOMER's ceiling and the other is Oxy's
+ * account with an upstream. Reporting the second as the first is retryability-
+ * correct and diagnostically wrong, which is the worst combination — it reads
+ * as actionable and the action does nothing.
  */
 export const NON_RETRYABLE_INFERENCE_ERROR_CODES = [
     'invalid_request',
@@ -91,27 +117,115 @@ export const NON_RETRYABLE_INFERENCE_ERROR_CODES = [
     'no_route_available',
     'upstream_content_filtered',
     'cancelled',
+    'provider_credential_invalid',
+    'provider_billing_refused',
 ];
 const NON_RETRYABLE_CODE_SET = new Set(NON_RETRYABLE_INFERENCE_ERROR_CODES);
+/* -------------------------------------------------------------------------- */
+/*  Credential-shaped text                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * A run of characters long enough and opaque enough to BE a credential.
+ *
+ * The alphabet every bearer token, API key and base64/base64url secret is
+ * written in. The LENGTH floors below are what keep this from being an entropy
+ * heuristic: nothing here fires on a short word, so `authorization: none` and
+ * `api_key=***` read as what they are.
+ */
+const OPAQUE_ALPHABET = '[A-Za-z0-9][A-Za-z0-9._~+/=-]';
+/**
+ * Words a producer substitutes FOR a credential.
+ *
+ * Excluded at the value position so a message whose secret has already been
+ * replaced is accepted. That acceptance is deliberate and is half the fix for
+ * issue #1027: the previous pattern refused `Authorization: [redacted]` — a
+ * correctly redacted string — which is precisely what pushed a producer into
+ * redacting the MARKER instead, and a marker-redacted string carries the secret
+ * and passes.
+ */
+const PLACEHOLDER_WORDS = 'redacted|removed|hidden|masked|scrubbed|elided|omitted|filtered|sanitized|sanitised|none|null|undefined|empty';
+/** A value position whose contents are a placeholder rather than a secret. */
+const NOT_A_PLACEHOLDER = `(?!(?:${PLACEHOLDER_WORDS})\\b)`;
 /**
- * Text that looks like it carries a credential.
+ * Header and parameter names that carry a credential, as any provider spells
+ * them.
  *
- * A deliberately narrow set of literal markers — the shapes upstream providers
- * actually echo — rather than an entropy heuristic, which would reject
- * legitimate error text (a request id, a base64 image fragment) and teach
- * producers to strip messages until they pass.
+ * The prefix group is the whole point of the rewrite: `authorization` and
+ * `api_key` were matched literally, so `x-api-key`, `anthropic-api-key`,
+ * `x-goog-api-key` and `proxy-authorization` — the spellings an upstream
+ * actually echoes — went unrecognised.
  */
-const CREDENTIAL_LIKE_TEXT = /(?:bearer\s+[a-z0-9._~+/=-]{8,}|authorization\s*[:=]|api[_-]?key\s*[:=]|\bsk-[a-z0-9_-]{8,}|\bsk_(?:live|test)_[a-z0-9]{8,})/i;
+const CREDENTIAL_NAME = '(?:[a-z0-9]{1,20}[-_]){0,3}(?:api[-_]?(?:key|token|secret)|authorization|auth[-_]?(?:token|key)?|access[-_]?token|id[-_]?token|refresh[-_]?token|bearer[-_]?token|secret[-_]?key|private[-_]?key|client[-_]?secret|session[-_]?(?:id|key|token)|passwords?|passwd|cookie|credentials?|tokens?|secrets?)';
+/** An auth scheme sitting between the marker and the value. */
+const AUTH_SCHEME = '(?:(?:bearer|basic|token|apikey|digest)\\s+)?';
 /**
- * Free text that is safe to hand a customer: bounded, and refused outright if a
- * credential marker appears in it. Applied to BOTH the Oxy message and the
+ * The four ways a credential is recognisable in free text.
+ *
+ * Each is checked independently, so removing one signal does not clear the
+ * string — which is the failure #1027 reported. All four are load-bearing:
+ * `inference.errors.test.ts` has a case that only one of them catches, and
+ * deleting any one entry turns a test red.
+ */
+const CREDENTIAL_PATTERNS = [
+    // 1. A credential-bearing name ASSIGNED a value that is long enough to be a
+    //    credential. The value is anchored to the separator so a placeholder at
+    //    that position ends the match rather than being skipped over.
+    new RegExp(`(?:^|[^a-z0-9])${CREDENTIAL_NAME}["']?\\s*[:=]\\s*["']?${AUTH_SCHEME}${NOT_A_PLACEHOLDER}${OPAQUE_ALPHABET}{7,}`, 'i'),
+    // 2. A bearer token with no marker in front of it, which is how an upstream
+    //    quotes the header value alone.
+    new RegExp(`\\bbearer\\s+${NOT_A_PLACEHOLDER}${OPAQUE_ALPHABET}{7,}`, 'i'),
+    // 3. Token grammars that ARE credentials wherever they appear, marker or not.
+    //    This is the layer that survives a producer stripping the marker, and it
+    //    is a closed list of issued shapes rather than an entropy score, so a
+    //    request id or a base64 image fragment is unaffected.
+    //
+    //    Case-SENSITIVE on purpose: `AKIA`, `AIza` and `gh[pousr]_` are issued in
+    //    exactly that case, and matching them case-insensitively would start
+    //    firing on ordinary words.
+    /\b(?:sk-[A-Za-z0-9_-]{8,}|[sprk]k_(?:live|test)_[A-Za-z0-9]{8,}|AKIA[0-9A-Z]{12,}|ASIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{20,}|xox[abeprs]-[A-Za-z0-9-]{10,}|glpat-[A-Za-z0-9_-]{16,}|npm_[A-Za-z0-9]{20,}|eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,})/,
+    // 4. A redaction placeholder standing NEXT TO a surviving opaque value — the
+    //    exact residue of the span redaction in #1027 (`{x-[redacted] <key>}`).
+    //    A correct redaction puts the placeholder WHERE the value was, so the two
+    //    never appear side by side; a marker-span redaction leaves them adjacent.
+    //    Both signals are required, which is what keeps an ordinary redacted
+    //    message from being refused.
+    new RegExp(`(?:[[<({]\\s*(?:${PLACEHOLDER_WORDS})[^\\])}>]{0,16}[\\])}>]|\\*{3,})[^A-Za-z0-9]{0,4}${OPAQUE_ALPHABET}{11,}`, 'i'),
+];
+/**
+ * Free text that is safe to hand a customer: bounded, and refused if it still
+ * looks like it carries a credential. Applied to BOTH the Oxy message and the
  * upstream one — a leak is no less a leak for having been written by a provider.
+ *
+ * ## This is a last-resort REFUSAL, not protection
+ *
+ * A pattern over the OUTPUT cannot be the control that keeps a credential out of
+ * an error, and a producer that treats it as one has the hole #1027 reported.
+ * The only reliable control is redacting the KNOWN SECRET VALUE at the point
+ * where the producer still holds the bytes it sent — which is an adapter's job
+ * and is available to nobody else. This refinement exists to catch what that
+ * control missed, and nothing here is a licence to skip it.
+ *
+ * Two rules follow, and they are the whole reason this text is longer than the
+ * pattern it describes:
+ *
+ *  - **Never redact by replacing the span this pattern matched.** The span is
+ *    the MARKER; the secret is what follows it. OxyHQ/Relay#3 measured the
+ *    result: `{x-api-key: <key>}` is refused, `{x-[redacted] <key>}` was
+ *    accepted, and both carry the key. Redaction made the leak worse by
+ *    converting "this string is dangerous" into "this string is fine".
+ *  - **This package deliberately ships no redaction helper.** One keyed on these
+ *    patterns would rebuild the same defect one layer up, and one that took the
+ *    secret as an argument would only restate what the producer already has.
+ *
+ * What it still cannot see, stated so nobody relies on it: a credential with no
+ * marker, no issued-token prefix and no placeholder beside it is bytes that look
+ * like a request id, and refusing those means refusing request ids.
  */
 export const safeErrorTextSchema = z
     .string()
     .min(1)
     .max(2000)
-    .refine((value) => !CREDENTIAL_LIKE_TEXT.test(value), 'error text must not contain credential-shaped material');
+    .refine((value) => !CREDENTIAL_PATTERNS.some((pattern) => pattern.test(value)), 'error text must not contain credential-shaped material');
 /**
  * A coarse classification of an upstream failure (ADR 0010's `upstreamCategory`).
  *

package/dist/esm/inference/identifiers.js

@@ -54,9 +54,17 @@ export const oxyApplicationIdSchema = z.string().min(1).max(64);
 /** An Oxy `ApplicationCredential._id` — the credential used for this request. */
 export const oxyCredentialIdSchema = z.string().min(1).max(64);
 /**
- * A request id generated by the data plane. Correlates the Oxy edge, the data
- * plane, the financial ledger and the customer-visible receipt, so it appears on
- * every stream event and every ledger record.
+ * A request id allocated by the Oxy EDGE, at admission and BEFORE
+ * authentication, so that a request rejected for a bad credential is as
+ * traceable as one that was served (ADR 0007, and step 1 of ADR 0010's edge
+ * order). It is required on the inbound envelope, which is what makes the data
+ * plane a consumer of this id rather than its source: the data plane echoes it
+ * on every stream event, on the usage report and on anything it can be asked
+ * about later.
+ *
+ * Correlates the Oxy edge, the data plane, the financial ledger and the
+ * customer-visible receipt, so it appears on every stream event and every
+ * ledger record.
  */
 export const requestIdSchema = z.string().min(1).max(128);
 /**

package/dist/esm/inference/money.js

@@ -85,6 +85,49 @@ export const moneySchema = z
 /**
  * The closed set of units inference is metered in.
  *
+ * **The units PARTITION a request: every unit counts material no other unit
+ * counts.** `cached_input_tokens` is not part of `input_tokens`, and
+ * `reasoning_tokens` is not part of `output_tokens` — they are siblings, not
+ * subsets. A request whose 10 000-token prompt was served 9 000 tokens from
+ * cache is reported as `input_tokens: 1000` beside `cached_input_tokens: 9000`,
+ * never as `input_tokens: 10000` beside it.
+ *
+ * That belongs to the definition rather than to a convention somewhere else,
+ * because settlement applies a price to EVERY reported unit and sums them
+ * (`inferenceLedger.service.ts`'s `computeCharge`). Under the partition rule
+ * that sum IS the request's cost, and a cached token can carry its own — lower
+ * — price. Under the nested reading the same sum charges the cached and
+ * reasoning tokens twice: once inside their parent and once on their own line.
+ * It fails silently, because every total still looks plausible and the receipt
+ * is still internally consistent, and on a reasoning model the reasoning tokens
+ * can dominate the completion, so the error is not marginal.
+ *
+ * **Every OpenAI-compatible provider reports the other way round**:
+ * `prompt_tokens` INCLUDES `prompt_tokens_details.cached_tokens`, and
+ * `completion_tokens` INCLUDES `completion_tokens_details.reasoning_tokens`.
+ * Normalising is the data plane's job and it is subtraction:
+ *
+ * ```text
+ * input_tokens  = prompt_tokens     - prompt_tokens_details.cached_tokens
+ * output_tokens = completion_tokens - completion_tokens_details.reasoning_tokens
+ * ```
+ *
+ * No refinement in this package can enforce it, and saying so is part of the
+ * rule: a nested report and a disjoint one are the same four non-negative
+ * integers, so no predicate over a single report can tell them apart. The two
+ * structural guards that DO exist — refining `cached <= input` and
+ * `reasoning <= output`, or deriving the parents instead of reporting them —
+ * both encode the nested reading, which is the one this rule rejects. What IS
+ * enforceable is the arithmetic that depends on the rule, and that is where the
+ * enforcement lives — `inferenceLedger.service.test.ts` prices a report in
+ * which cached and reasoning tokens are both non-zero and asserts the exact
+ * total, which the nested reading cannot produce.
+ *
+ * Where the public surface has to speak a nested dialect, the sum is put back
+ * at the boundary rather than the internal reading being bent to it
+ * (`routes/inferenceEdge.ts` renders `prompt_tokens` as
+ * `input_tokens + cached_input_tokens`).
+ *
  * Time is carried in integer MILLISECONDS rather than seconds so that no unit
  * quantity is ever fractional: a 12.5-second transcription is `12500`, exactly,
  * and the "units are integers" rule holds for every modality instead of holding

package/dist/esm/inference/streamEvents.js

@@ -174,12 +174,22 @@ export const inferenceStreamErrorEventSchema = z.object({
     /** Carries its own `schemaVersion`: the same body is returned non-streaming. */
     error: inferenceErrorSchema,
 });
-/** Why generation stopped. */
+/**
+ * Why generation stopped.
+ *
+ * `refusal` and `content_filter` are separate members because they are separate
+ * events: the MODEL declining to answer is a property of the answer, while a
+ * filter is an upstream system removing one. The delta channels already carry
+ * that distinction (`channel: 'refusal'` beside the filter's own error code),
+ * so collapsing it here would have made the terminal event less specific than
+ * the stream that produced it.
+ */
 export const inferenceFinishReasonSchema = z.enum([
     'stop',
     'length',
     'tool_calls',
     'content_filter',
+    'refusal',
     'cancelled',
 ]);
 /**

package/dist/esm/inference/usage.js

@@ -128,6 +128,12 @@ export const inferenceRequestOutcomeSchema = z.enum([
  * `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.
  */
 export const normalizedUsageReportSchema = z
     .object({

package/dist/esm/inference/version.js

@@ -34,6 +34,34 @@
  * 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.
+ *
  * Decided in: docs/adr/0006-oxy-relay-boundary.md, docs/adr/0010-public-api-compatibility.md.
  */
 /**
@@ -43,12 +71,19 @@
  *
  * 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; PATCH for documentation-only changes
- * that leave every parsed byte identical.
+ * 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 = '1.0.0';
+export const INFERENCE_CONTRACT_VERSION = '1.1.0';