@oxyhq/contracts 0.30.0 → 0.32.0

package/dist/esm/inference/providerConnection.js

@@ -4,7 +4,7 @@
  *
  * The credential itself is NOT here and cannot be put here. This shape carries
  * a locator (`secretRef`) into Vault/KMS/managed secret storage, a prefix short
- * enough to be useless, a fingerprint, and validation state. Two mechanisms
+ * enough to be useless, a fingerprint, and validation state. Three mechanisms
  * make that structural rather than a convention somebody must remember:
  *
  *  - The object is `.strict()`. A producer that attaches `apiKey`, `secret`,
@@ -14,6 +14,10 @@
  *  - `keyPrefix` is capped at 12 characters — shorter than any provider's
  *    usable credential — so the one field designed to show part of a key cannot
  *    be widened into showing all of it without changing the contract.
+ *  - `secretRef` is DERIVED, not free text: the grammar is closed and the
+ *    refinement below requires it to be this connection's own environment,
+ *    owner account and id under one namespace. A field with no free span is a
+ *    field a credential cannot be smuggled through.
  *
  * BYOK does not move the billing relationship: the upstream provider bills the
  * customer's own account directly, and Oxy charges only its platform fee. The
@@ -45,17 +49,61 @@ export const providerConnectionScopeSchema = z.discriminatedUnion('kind', [
     })
         .strict(),
 ]);
+/**
+ * The managed secret stores a reference may point into.
+ *
+ * A closed set, because the scheme is the half of a locator that says who can
+ * resolve it: a scheme nothing in this system can dereference is not a
+ * reference. Restated as a SQL alternation in
+ * `packages/api/src/db/schema/inferenceProviderConnections.ts`, and that file's
+ * schema test holds the two equal.
+ */
+const SECRET_STORE_NAMES = ['vault', 'kms', 'ssm', 'secretsmanager'];
+/**
+ * The namespace every Oxy BYOK locator lives under, whichever store holds it.
+ *
+ * Part of the grammar rather than an implementation detail of the writer: it is
+ * the prefix a store-side IAM or Vault policy is scoped to, so a locator outside
+ * it is one Oxy's own credentials could not resolve anyway.
+ */
+export const PROVIDER_SECRET_REFERENCE_NAMESPACE = 'oxy/inference/byok';
+/**
+ * The two id segments, bounded exactly as the fields they must equal are:
+ * `oxyAccountIdSchema` caps an account id at 64 characters and
+ * `providerConnectionSchema.connectionId` caps a connection id at 128. A tighter
+ * bound here would refuse a reference to a connection the same contract accepts.
+ */
+const ACCOUNT_SEGMENT = '[A-Za-z0-9_-]{1,64}';
+const CONNECTION_SEGMENT = '[A-Za-z0-9_-]{1,128}';
 /**
  * A locator for the credential in managed secret storage — never the credential.
  *
- * The scheme prefix is constrained to the stores Oxy actually uses, so a
- * producer cannot pass a raw key through this field and have it look like a
- * reference; whitespace is excluded for the same reason.
+ * The grammar is CLOSED, and that is the whole of its value: a store from a
+ * four-name set, one fixed namespace, an environment from a three-name set, and
+ * two bounded id segments. Nothing may precede, follow or be interpolated
+ * between them, so there is no free-form span for credential material to occupy:
+ * the only places anything a producer chooses can sit are the two ids, and
+ * `providerConnectionSchema` below pins those to THIS connection's own owner
+ * account and id.
+ *
+ * ## It was not always closed, and the difference was measured
+ *
+ * The previous grammar was `<store>:<anything from a wide charset>`, under a
+ * comment claiming that meant "a producer cannot pass a raw key through this
+ * field and have it look like a reference". It did not. Splicing a credential in
+ * after the store name —
+ * `vault:sk-ant-api03-…/oxy/inference/byok/production/<account>/<id>` — satisfied
+ * that regex, satisfied the storage partition CHECK (which pins the END of the
+ * string and said nothing about its start), and parsed cleanly. Both mechanisms
+ * constrained the SHAPE of the locator; neither constrained what could be put in
+ * front of it. `packages/api`'s `providerSecretLeak.test.ts` plants exactly that
+ * value, and it is now refused here, by the CHECK, and by the refinement below.
  */
 export const providerSecretReferenceSchema = z
     .string()
-    .max(512)
-    .regex(/^(?:vault|kms|ssm|secretsmanager):[A-Za-z0-9/_.:@-]{1,480}$/, 'a secret reference is a <store>:<locator> pointer, never credential material');
+    .regex(new RegExp(`^(?:${SECRET_STORE_NAMES.join('|')}):${PROVIDER_SECRET_REFERENCE_NAMESPACE}/` +
+    `(?:${inferenceEnvironmentSchema.options.join('|')})/${ACCOUNT_SEGMENT}/${CONNECTION_SEGMENT}$`), 'a secret reference is <store>:oxy/inference/byok/<environment>/<accountId>/<connectionId>, ' +
+    'never credential material');
 /** Why a credential check failed, as a closed set the Console can render. */
 export const providerConnectionValidationSchema = z
     .object({
@@ -136,4 +184,26 @@ export const providerConnectionSchema = z
             message: 'a connection whose credential failed validation cannot be active',
         });
     }
+    // The reference is a FUNCTION of this record, not a value a producer chooses:
+    // the store, then the namespace, then this connection's own environment,
+    // owner account and id. `providerSecretReferenceSchema` already refuses
+    // anything outside the grammar; this is what closes the two id segments, the
+    // only spans left that a producer picks the contents of.
+    //
+    // The same rule the `inference_provider_connections_secret_ref_partition`
+    // CHECK enforces on the row. Both exist because they cover different
+    // producers: the CHECK protects the TABLE from a backfill or a service that
+    // skipped the parse, and this protects the WIRE from a producer that never
+    // touches the table — the data plane echoing a connection back, or a future
+    // service building a DTO by hand.
+    const expected = SECRET_STORE_NAMES.map((store) => `${store}:${PROVIDER_SECRET_REFERENCE_NAMESPACE}/${connection.environment}/` +
+        `${connection.ownerAccountId}/${connection.connectionId}`);
+    if (!expected.includes(connection.secretRef)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['secretRef'],
+            message: 'a secret reference must name this connection: ' +
+                '<store>:oxy/inference/byok/<environment>/<ownerAccountId>/<connectionId>',
+        });
+    }
 });

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * 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.2.0';
+export const INFERENCE_CONTRACT_VERSION = '1.3.0';

package/dist/esm/updates.js

@@ -88,6 +88,8 @@ export const assetUploadTicketSchema = z.object({
      * carries the long immutable cache header (assets are content-addressed).
      */
     cacheControl: z.string(),
+    /** Base64 SHA-256 value required in the presigned PUT's checksum header. */
+    checksumSHA256: z.string(),
 });
 /**
  * `POST /updates/v1/assets/init` response. `missing` holds a presigned upload