@tangle-network/agent-interface 5.2.1 → 5.3.0

package/dist/proxy-secrets.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { agentCandidateSecretRefSchema } from "./agent-candidate-schema-common.js";
+import { boundedIdentifierSchema, CONTRACT_MAX_ARRAY_LENGTH } from "./contract-limits.js";
+/**
+ * Declarations request authority, never grant it. Trusted resolution uses authenticated tenant
+ * and issuer authority, with no personal/team fallback, and pins immutable secret ID/revision.
+ * The issuer intersects requested scope/expiry with its policy and authenticated lineage.
+ * Placeholders are independent unpredictable values per sandbox epoch, generated by the trusted
+ * lifecycle owner, never from secret bytes or public refs. JWT placeholders carry only synthetic
+ * public sub/aud/exp compatibility claims, no upstream claims, account identity or authority.
+ * The sandbox is the isolation boundary; these schemas cannot authenticate guest processes.
+ */
+const unique = (values) => new Set(values).size === values.length;
+const hostSchema = z.string().max(253).regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/, "host must be an exact lowercase FQDN without scheme, port, wildcard or trailing dot");
+const methodSchema = z.string().max(32).regex(/^[A-Z]+$/);
+/** Paths are exact or terminal slash-star subtrees. /v1/* includes /v1/ and /v1/a, never /v1
+ * or /v10. V1 rejects all percent encoding, dot segments, repeated slashes, query, fragments,
+ * backslashes, non-ASCII and controls, rather than normalizing ambiguous spellings.
+ */
+const pathSchema = z.string().max(2048).refine((path) => {
+    const exact = path.endsWith("/*") ? path.slice(0, -1) : path;
+    return /^\/[A-Za-z0-9._~!$&'()+,;=:@/-]*$/.test(exact) && !exact.includes("//") &&
+        !exact.split("/").some((part) => part === "." || part === "..");
+}, "path must be canonical ASCII, exact or a terminal /* subtree");
+const list = (schema) => z.array(schema).min(1).max(CONTRACT_MAX_ARRAY_LENGTH).refine(unique, "selectors must be unique");
+const envNameSchema = z.string().max(256).regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+const headerSchema = z.string().max(256).regex(/^[!#$%&'*+.^_\x60|~0-9A-Za-z-]+$/).refine((name) => !["authorization", "proxy-authorization", "host", "connection", "content-length", "transfer-encoding", "trailer", "upgrade", "te"].includes(name.toLowerCase()), "use bearer/basic for Authorization; routing and framing headers cannot carry secrets");
+/** Match complete components only. Selected header names are case-insensitive; duplicate fields
+ * are refused before coalescing. Query names are case-sensitive after one strict UTF-8 percent
+ * decode (+ means space); malformed encoding and duplicate decoded selector names are refused.
+ * Never scan other query fields. Basic is one strict base64 value decoding to exactly public
+ * username:placeholder; the username is printable ASCII without colon. Bearer is exactly
+ * "Bearer SP placeholder". Embedded placeholders never match. Authority, TLS SNI and validated
+ * destination must agree on the declared FQDN over HTTPS/443; explicit :443 is equivalent.
+ */
+export const ProxySecretPresentationSchema = z.discriminatedUnion("type", [
+    z.strictObject({ type: z.literal("bearer") }),
+    z.strictObject({ type: z.literal("basic"), username: z.string().min(1).max(256).regex(/^[\x21-\x39\x3b-\x7e]+$/) }),
+    z.strictObject({ type: z.literal("header"), name: headerSchema }),
+    z.strictObject({ type: z.literal("query"), name: z.string().max(256).regex(/^[A-Za-z0-9._~-]+$/) }),
+]);
+export const ProxySecretScopeSchema = z.strictObject({
+    hosts: list(hostSchema).readonly(), methods: list(methodSchema).readonly().optional(), paths: list(pathSchema).readonly().optional(),
+});
+const comparableScopeSchema = ProxySecretScopeSchema.strip();
+export const ProxySecretBindingSchema = ProxySecretScopeSchema.extend({
+    envName: envNameSchema,
+    secretRef: agentCandidateSecretRefSchema.omit({ format: true }),
+    presentation: ProxySecretPresentationSchema,
+    placeholderFormat: z.enum(["opaque", "jwt"]).optional(),
+    ttlSeconds: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+});
+export const ProxySecretsSchema = z.array(ProxySecretBindingSchema).max(CONTRACT_MAX_ARRAY_LENGTH)
+    .refine((bindings) => unique(bindings.map((binding) => binding.envName)), "proxy secret env names must be unique");
+export const ProxySecretResolvedIdentitySchema = z.strictObject({
+    tenantId: boundedIdentifierSchema, issuerId: boundedIdentifierSchema,
+    secretId: boundedIdentifierSchema, revision: boundedIdentifierSchema,
+});
+const timestamp = z.iso.datetime();
+export const ProxySecretGrantSchema = z.strictObject({
+    protocolVersion: z.literal(1), grantId: boundedIdentifierSchema,
+    sandboxId: boundedIdentifierSchema, epoch: boundedIdentifierSchema,
+    identity: ProxySecretResolvedIdentitySchema, scope: ProxySecretScopeSchema,
+    presentation: ProxySecretPresentationSchema, placeholderFormat: z.enum(["opaque", "jwt"]),
+    issuedAt: timestamp, expiresAt: timestamp, sourceExpiresAt: timestamp.optional(), parentGrantId: boundedIdentifierSchema.optional(),
+}).refine((grant) => grant.parentGrantId !== grant.grantId && Date.parse(grant.expiresAt) > Date.parse(grant.issuedAt) &&
+    (grant.sourceExpiresAt === undefined || Date.parse(grant.expiresAt) <= Date.parse(grant.sourceExpiresAt)), "grant expiry must follow issuance");
+const receiptShape = {
+    protocolVersion: z.literal(1), sandboxId: boundedIdentifierSchema,
+    generation: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    bindings: z.array(z.strictObject({ envName: envNameSchema, secretRef: agentCandidateSecretRefSchema.omit({ format: true }), grant: ProxySecretGrantSchema })).max(CONTRACT_MAX_ARRAY_LENGTH),
+    proxyAcknowledged: z.literal(true),
+};
+/** proxy-installed is a phase-two input, never dispatch authority. Only installed acknowledges
+ * proxy and placeholder-only materialization. Revoked confirms binding revocation, not upstream
+ * credential revocation. Receipts contain metadata only, never secret or placeholder bytes.
+ */
+export const ProxySecretReceiptSchema = z.discriminatedUnion("status", [
+    z.strictObject({ ...receiptShape, status: z.literal("proxy-installed"), materializationAcknowledged: z.literal(false) }),
+    z.strictObject({ ...receiptShape, status: z.literal("installed"), materializationAcknowledged: z.literal(true) }),
+    z.strictObject({ ...receiptShape, status: z.literal("revoked"), materializationAcknowledged: z.literal(true) }),
+]).superRefine((receipt, ctx) => {
+    if (!unique(receipt.bindings.map((binding) => binding.envName)) ||
+        !unique(receipt.bindings.map((binding) => binding.grant.grantId))) {
+        ctx.addIssue({ code: "custom", path: ["bindings"], message: "receipt binding names and grant IDs must be unique" });
+    }
+    if (receipt.bindings.some((binding) => binding.grant.sandboxId !== receipt.sandboxId)) {
+        ctx.addIssue({ code: "custom", path: ["bindings"], message: "receipt grants must belong to its sandbox" });
+    }
+    if (new Set(receipt.bindings.map((binding) => binding.grant.epoch)).size > 1) {
+        ctx.addIssue({ code: "custom", path: ["bindings"], message: "receipt grants must share one sandbox lifecycle epoch" });
+    }
+    if (receipt.status === "revoked" && receipt.bindings.length !== 0) {
+        ctx.addIssue({ code: "custom", path: ["bindings"], message: "revoked receipt cannot retain bindings" });
+    }
+});
+/** Advertise only when served API, driver, host, proxy and materializer agree. Absence,
+ * protocol skew, or unsupported driver/presentation/format refuses before resolution or launch.
+ */
+export const ProxySecretCapabilitiesSchema = z.strictObject({
+    protocolVersion: z.literal(1), supportedDrivers: list(boundedIdentifierSchema),
+    presentations: list(z.enum(["bearer", "basic", "header", "query"])),
+    placeholderFormats: list(z.enum(["opaque", "jwt"])),
+    enforcement: z.literal("exact"), transports: z.tuple([z.literal("https:443")]),
+    lifecycle: z.literal(true), placementReceiptRequired: z.literal(true),
+});
+export const ProxySecretUpdateControlsSchema = z.strictObject({
+    expectedProxySecretGeneration: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+    requireInPlace: z.boolean().optional(),
+});
+/** Bounded delegation comparison, not proof of issuer authorization, installation, freshness
+ * or authenticated lineage. The trusted lifecycle owner must cascade parent revocation.
+ */
+export function isProxySecretGrantAttenuation(parent, child) {
+    const p = ProxySecretGrantSchema.safeParse(parent);
+    const c = ProxySecretGrantSchema.safeParse(child);
+    if (!p.success || !c.success)
+        return false;
+    const from = p.data, to = c.data;
+    return to.parentGrantId === from.grantId &&
+        Object.keys(from.identity).every((key) => from.identity[key] === to.identity[key]) &&
+        proxySecretPresentationsEqual(from.presentation, to.presentation) && from.placeholderFormat === to.placeholderFormat &&
+        Date.parse(to.issuedAt) >= Date.parse(from.issuedAt) && Date.parse(to.expiresAt) <= Date.parse(from.expiresAt) &&
+        isProxySecretScopeAttenuation(from.scope, to.scope);
+}
+/** Early declaration guard only: matching public refs do not establish resolved authority. */
+export function isProxySecretBindingAttenuation(parent, child) {
+    const p = ProxySecretBindingSchema.safeParse(parent), c = ProxySecretBindingSchema.safeParse(child);
+    if (!p.success || !c.success)
+        return false;
+    const from = p.data, to = c.data;
+    return from.secretRef.key === to.secretRef.key &&
+        proxySecretPresentationsEqual(from.presentation, to.presentation) &&
+        (from.placeholderFormat ?? "opaque") === (to.placeholderFormat ?? "opaque") &&
+        (from.ttlSeconds === undefined || (to.ttlSeconds !== undefined && to.ttlSeconds <= from.ttlSeconds)) &&
+        isProxySecretScopeAttenuation(from, to);
+}
+/** Omitted methods/paths mean all; a bounded parent cannot be widened by omission. */
+export function isProxySecretScopeAttenuation(parent, child) {
+    const p = comparableScopeSchema.safeParse(parent), c = comparableScopeSchema.safeParse(child);
+    if (!p.success || !c.success)
+        return false;
+    return subset(p.data.hosts, c.data.hosts) && subset(p.data.methods, c.data.methods) &&
+        (p.data.paths === undefined || (c.data.paths !== undefined && c.data.paths.every((path) => p.data.paths.some((allowed) => allowed === path || (allowed.endsWith("/*") && path.startsWith(allowed.slice(0, -1)))))));
+}
+/** Header selectors compare case-insensitively; query selectors and Basic usernames are exact. */
+export function proxySecretPresentationsEqual(left, right) {
+    const p = ProxySecretPresentationSchema.safeParse(left), c = ProxySecretPresentationSchema.safeParse(right);
+    if (!p.success || !c.success)
+        return false;
+    const from = p.data, to = c.data;
+    if (from.type !== to.type)
+        return false;
+    if (from.type === "header" && to.type === "header")
+        return from.name.toLowerCase() === to.name.toLowerCase();
+    if (from.type === "query" && to.type === "query")
+        return from.name === to.name;
+    if (from.type === "basic" && to.type === "basic")
+        return from.username === to.username;
+    return true;
+}
+function subset(parent, child) {
+    return parent === undefined || (child !== undefined && child.every((value) => parent.includes(value)));
+}
+/** Merge independent declaration sources. Identical names deduplicate only when the full
+ * schema-parsed declaration agrees; callers preserve omission versus explicit empty selection.
+ * The result is detached public metadata. Conflicts fail without exposing declaration contents.
+ */
+export function mergeProxySecretBindings(...collections) {
+    const merged = new Map();
+    for (const collection of collections) {
+        if (collection === undefined)
+            continue;
+        for (const binding of ProxySecretsSchema.parse(collection)) {
+            const existing = merged.get(binding.envName);
+            if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(binding)) {
+                throw new Error("proxy-secret declarations disagree for the same environment name");
+            }
+            merged.set(binding.envName, binding);
+        }
+    }
+    return ProxySecretsSchema.parse([...merged.values()]);
+}