@zackbart/connecta 0.30.0 → 0.31.0

package/dist/providers/_shared/rest/value-safety.js

@@ -0,0 +1,580 @@
+/** What a removed secret reads as. */
+export const REDACTED = "[redacted]";
+/** Credential vocabulary over normalized names, matched anywhere; mirrors `scripts/value-safety.mjs`. */
+export const CREDENTIAL_WORDS = [
+    "token",
+    "secret",
+    "password",
+    "passphrase",
+    "privatekey",
+    "apikey",
+    "accesskey",
+    "authorization",
+    "cookie",
+    "signature",
+    "jwt",
+    "credential",
+    "bypass",
+    "verifier",
+    "devicecode",
+    "authcode",
+    "keyvalue",
+    "invitecode",
+    "joincode",
+    "claimcode",
+    "transfercode",
+    "accesscode",
+];
+/** Credential vocabulary matched at the end of a normalized name; mirrors the script. */
+export const CREDENTIAL_SUFFIX = /(tokens?|secrets?|passwords?|passphrases?|privatekeys?|apikeys?|authkey|authorization|cookies?|signature|jwts?|credentials?|psks?|streamkeys?|uploadurl|signedurl|jwks?|verifier|devicecode|bypass)$/;
+/** Request fields that carry secrets into a vendor without naming a credential: headers, environment values, bindings. */
+const INPUT_CONTAINERS = /(envvars|environmentvariables|bindings|headers?)$/;
+/** Suffixes of metadata about a credential (ids, prefixes, last four, counts, expiry, scopes); mirrors the script. */
+export const METADATA_SUFFIXES = [
+    "id",
+    "ids",
+    "prefix",
+    "suffix",
+    "lastfour",
+    "lastfourchars",
+    "count",
+    "type",
+    "types",
+    "name",
+    "names",
+    "at",
+    "expiry",
+    "expires",
+    "scope",
+    "scopes",
+    "enabled",
+    "changed",
+    "protection",
+    "details",
+    "length",
+    "mode",
+    "kind",
+    "status",
+];
+/** Exact metadata names that contain a credential word; mirrors the script. */
+export const METADATA_NAMES = [
+    "partialkeyvalue",
+    "partialkey",
+    "inputtokens",
+    "outputtokens",
+    "totaltokens",
+    "cachecreationinputtokens",
+    "cachereadinputtokens",
+    "usedapptoken",
+    "includesrefreshtoken",
+    "hasauthorizationdetails",
+    "tokensdeleted",
+    "istokenexpired",
+    "tokenclaims",
+    "oidctokenclaims",
+    "preauthorizationamount",
+    "secretrotation",
+    "secretssync",
+    "strictpasswordprotectionsettings",
+    "disjunctiveproductionsecretpolicy",
+    "stripesharedpaymenttokenused",
+    "bypassall",
+    "bypasssystem",
+];
+/** Keys whose contents are environment variables, whatever their `key` or `type` says. */
+const ENV_CONTAINERS = ["env", "envs", "envvar", "envvars", "newenvvar", "oldenvvar", "sharedenvvar", "sharedenvvars"];
+const ENV_VALUE_FIELDS = ["value", "vsmValue", "legacyValue", "decryptedValue"];
+/** The fields of a labelled or typed secret record that hold what the label names. */
+const LABELLED_VALUE_FIELDS = [...ENV_VALUE_FIELDS, "args", "text"];
+/** Query parameters that carry a credential in a URL: either rule. */
+const URL_PARAM_CONTAINS = /token|secret|password|passwd|signature|^sig$|key|auth|code|jwt|credential|bypass/i;
+const URL_PARAM_SUFFIX = /(token|secret|password|passphrase|key|signature|sig|credential|auth|authorization|jwt)$/;
+const URL_SHAPE = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** The fields of a header, cookie, or query rule that hold the matched or set value. */
+const HEADER_RULE_VALUES = ["value", "values", "args"];
+/** Keys whose absolute URL is a route or redirect destination. */
+const DESTINATION_KEYS = ["dest", "destination", "location"];
+const MAX_DEPTH = 48;
+/** Deny by default: an object is a guest's only when no binding field holds anything but a reviewed guest value. */
+function guestOnly(resource, guest) {
+    for (const [field, allowed] of Object.entries(guest.bindings)) {
+        const value = resource[field];
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (typeof value === "string" && allowed.includes(value))
+            continue;
+        return false;
+    }
+    for (const [field, allowed] of Object.entries(guest.requires ?? {})) {
+        const value = resource[field];
+        if (typeof value !== "string" || !allowed.includes(value))
+            return false;
+    }
+    return true;
+}
+export const refuse = (reason) => ({ verdict: "refuse", reason });
+export const redact = (reason, paths, keep = []) => ({
+    verdict: "redact",
+    reason,
+    paths,
+    ...(keep.length ? { keep } : {}),
+});
+export const safe = (reason, keep = []) => ({
+    verdict: "safe",
+    reason,
+    ...(keep.length ? { keep } : {}),
+});
+/** A verdict whose failures keep the vendor's text: reviewed, for operations whose errors echo no stored secret. */
+export const vendorErrors = (verdict) => verdict.verdict === "refuse" ? verdict : { ...verdict, errors: "vendor" };
+/** Paths under each prefix; a `url:` or `origin:` directive stays in front. */
+export function under(prefixes, paths) {
+    return prefixes.flatMap((prefix) => paths.map((path) => {
+        if (!prefix)
+            return path;
+        const directive = /^(?:url|origin):/.exec(path)?.[0] ?? "";
+        return `${directive}${prefix}.${path.slice(directive.length)}`;
+    }));
+}
+function normalizedName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function metadataName(normalized) {
+    return (METADATA_NAMES.includes(normalized) ||
+        METADATA_SUFFIXES.some((suffix) => normalized.endsWith(suffix) && normalized !== suffix));
+}
+/** Vercel's former rule: a credential word anywhere in a name that is not metadata. Its value goes whole. */
+function containsCredential(normalized) {
+    return CREDENTIAL_WORDS.some((word) => normalized.includes(word)) && !metadataName(normalized);
+}
+/**
+ * Whether a key names a credential: a credential word anywhere in a name
+ * that is not metadata (Vercel's former rule), or a credential suffix
+ * (Cloudflare's).
+ */
+export function credentialName(name) {
+    const normalized = normalizedName(name);
+    return containsCredential(normalized) || CREDENTIAL_SUFFIX.test(normalized);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A URL without userinfo, credential query parameters, or a credential-looking fragment; anything unparseable is withheld. */
+function sanitizeUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return REDACTED;
+    }
+    let changed = false;
+    if (url.username || url.password) {
+        url.username = "redacted";
+        url.password = "";
+        changed = true;
+    }
+    // A snapshot of the names: setting a parameter while iterating the live list is unsafe.
+    for (const name of Array.from(url.searchParams.keys())) {
+        if (URL_PARAM_CONTAINS.test(name) || URL_PARAM_SUFFIX.test(name.toLowerCase().replace(/[_-]/g, ""))) {
+            url.searchParams.set(name, REDACTED);
+            changed = true;
+        }
+    }
+    if (url.hash && /token|secret|key|code|auth/i.test(url.hash)) {
+        url.hash = "";
+        changed = true;
+    }
+    // An ordinary URL comes back exactly as the vendor sent it.
+    return changed ? url.toString() : value;
+}
+/**
+ * A destination URL reduced to its origin: webhook, drain, and bearer URLs
+ * can carry a secret in the path itself (`hooks.slack.com/services/…`), so
+ * only the scheme and host come back.
+ */
+function originOnly(value) {
+    if (value === null || value === undefined)
+        return value;
+    // A destination given as several URLs (`{ traces: "https://…" }`) keeps its shape.
+    if (Array.isArray(value))
+        return value.map(originOnly);
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, originOnly(item)]));
+    if (typeof value !== "string")
+        return REDACTED;
+    try {
+        const url = new URL(value);
+        const bare = (url.pathname === "/" || url.pathname === "") && !url.search && !url.hash && !url.username;
+        // Scheme and host, never userinfo; `origin` reads "null" for non-web schemes (s3://).
+        const base = `${url.protocol}//${url.host}`;
+        return bare ? base : `${base}/${REDACTED}`;
+    }
+    catch {
+        return REDACTED;
+    }
+}
+/** Every label a record carries for its value: `key`, `name`, or a transform's `target.key`. */
+function labelsOf(value) {
+    const labels = [];
+    if (typeof value["key"] === "string")
+        labels.push(value["key"]);
+    if (typeof value["name"] === "string")
+        labels.push(value["name"]);
+    const target = value["target"];
+    if (isRecord(target) && typeof target["key"] === "string")
+        labels.push(target["key"]);
+    return labels;
+}
+/** Whether a record's label names a credential, so its value or args are one. */
+function credentialLabelled(value) {
+    return isRecord(value) && labelsOf(value).some(credentialName);
+}
+/** A header, cookie, or query rule (`request.headers`, `header`, `cookie`, `query`, …). */
+function headerLike(value) {
+    return isRecord(value) && typeof value["type"] === "string" && /header|cookie|query/i.test(value["type"]);
+}
+/** A route-like object: its `headers` are set on requests or responses. */
+function routeLike(value) {
+    return ["src", "source", "dest", "destination"].some((key) => key in value);
+}
+/** Every value of a headers map, or of a list of `{ key, value }` header pairs, withheld. */
+function headerValues(value) {
+    if (isRecord(value))
+        return Object.fromEntries(Object.keys(value).map((name) => [name, REDACTED]));
+    if (Array.isArray(value)) {
+        return value.map((item) => (isRecord(item) && "value" in item ? { ...item, value: REDACTED } : item));
+    }
+    return value;
+}
+/** A credential-named key's value: everything but null goes. */
+function withheld(value) {
+    return value === null || value === undefined ? value : REDACTED;
+}
+/** Every string under a credential-suffixed key, keeping the subtree's shape (Cloudflare's former rule). */
+function scrubStrings(value) {
+    if (typeof value === "string")
+        return REDACTED;
+    if (Array.isArray(value))
+        return value.map(scrubStrings);
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrubStrings(item)]));
+    return value;
+}
+/** One reviewed path, split into segments; `#url` is the same as an `origin:` prefix. */
+function parsePath(raw) {
+    let path = raw;
+    let mode = "redact";
+    if (path.startsWith("url:")) {
+        mode = "url";
+        path = path.slice(4);
+    }
+    else if (path.startsWith("origin:")) {
+        mode = "origin";
+        path = path.slice(7);
+    }
+    if (path.endsWith("#url")) {
+        mode = "origin";
+        path = path.slice(0, -4);
+    }
+    const segments = path.split(".").flatMap((part) => {
+        if (part === "")
+            return [];
+        const match = /^([^[{@]*)((?:\[\??[a-z]*\]|\{\}|@keys)*)$/.exec(part);
+        if (!match)
+            return [part];
+        const out = [];
+        if (match[1])
+            out.push(match[1] === "*" ? "{}" : match[1]);
+        for (const token of match[2].match(/\[\??[a-z]*\]|\{\}|@keys/g) ?? [])
+            out.push(token);
+        return out;
+    });
+    return { mode, segments };
+}
+const SEGMENT = /^(?:\[\]|\[\?(?:env|credential|header)\]|\{\}|@keys|[^[\]{}@]+)$/;
+/** Whether every segment of a reviewed path is in the path language; the harness checks each table. */
+export function validPath(raw) {
+    const { segments } = parsePath(raw);
+    return segments.length > 0 && segments.every((segment) => SEGMENT.test(segment));
+}
+/** Apply one reviewed path to a body in place of its value. */
+function applyPath(body, raw) {
+    const { mode, segments } = parsePath(raw);
+    const step = (current, index) => {
+        if (index === segments.length) {
+            if (current === undefined || current === null)
+                return current;
+            if (mode === "url")
+                return typeof current === "string" ? sanitizeUrl(current) : REDACTED;
+            if (mode === "origin")
+                return originOnly(current);
+            return REDACTED;
+        }
+        const segment = segments[index];
+        if (segment === "[]" || segment === "[?env]" || segment === "[?credential]" || segment === "[?header]") {
+            if (!Array.isArray(current))
+                return current;
+            return current.map((item) => {
+                if (segment === "[?env]" && !/env/i.test(String(isRecord(item) ? item["type"] : "")))
+                    return item;
+                if (segment === "[?credential]" && !credentialLabelled(item))
+                    return item;
+                if (segment === "[?header]" && !headerLike(item))
+                    return item;
+                return step(item, index + 1);
+            });
+        }
+        // A named segment, a map, or its keys reached through a list applies to every item.
+        if (Array.isArray(current))
+            return current.map((item) => step(item, index));
+        if (segment === "{}") {
+            if (!isRecord(current))
+                return current;
+            return Object.fromEntries(Object.entries(current).map(([key, item]) => [key, step(item, index + 1)]));
+        }
+        if (segment === "@keys") {
+            if (!isRecord(current))
+                return current;
+            return Object.fromEntries(Object.values(current).map((item, position) => [`${REDACTED} ${position + 1}`, item]));
+        }
+        if (!isRecord(current) || !Object.hasOwn(current, segment))
+            return current;
+        return { ...current, [segment]: step(current[segment], index + 1) };
+    };
+    return step(body, 0);
+}
+/** A reviewed path as the key trail the heuristic walks: list markers dropped, `*` and `{}` match any key. */
+function trailOf(path) {
+    return parsePath(path).segments.filter((segment) => !segment.startsWith("[") && segment !== "@keys");
+}
+function matches(paths, trail) {
+    return paths.some((path) => path.length === trail.length && path.every((part, index) => part === "{}" || part === trail[index]));
+}
+/**
+ * The contents of an environment container: every variable loses its value
+ * fields whether or not it has a `key` or `type`, a `NAME → value` map (no
+ * `key` or `id`, only strings) loses every value, and `NAME=value` strings go.
+ */
+function scrubEnv(value, depth) {
+    if (depth > 32)
+        return REDACTED;
+    if (Array.isArray(value)) {
+        return value.map((item) => (typeof item === "string" && item.includes("=") ? REDACTED : scrubEnv(item, depth + 1)));
+    }
+    if (!isRecord(value))
+        return value;
+    const entries = Object.entries(value);
+    const map = !("key" in value) &&
+        !("id" in value) &&
+        !ENV_VALUE_FIELDS.some((field) => field in value) &&
+        entries.length > 0 &&
+        entries.every(([, item]) => typeof item === "string");
+    if (map)
+        return Object.fromEntries(entries.map(([key]) => [key, REDACTED]));
+    const out = {};
+    for (const [key, item] of entries) {
+        // A value is replaced, so the caller can see one exists without reading it.
+        if (ENV_VALUE_FIELDS.includes(key)) {
+            out[key] = withheld(item);
+            continue;
+        }
+        out[key] = scrubEnv(item, depth + 1);
+    }
+    return out;
+}
+/** An operation body that is environment variables: values go, nothing else changes. */
+function scrubValues(value, depth) {
+    if (depth > 32)
+        return REDACTED;
+    if (Array.isArray(value))
+        return value.map((item) => scrubValues(item, depth + 1));
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (!ENV_VALUE_FIELDS.includes(key))
+            out[key] = scrubValues(item, depth + 1);
+    }
+    return out;
+}
+/**
+ * Apply resource rules to every discriminated object in a body, innermost
+ * first, and to the partial copies events carry beside one. Records the
+ * reviewed payer-facing URL fields of objects that keep them.
+ */
+function resourcePass(value, resources, verbatim, depth) {
+    if (depth > MAX_DEPTH)
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => resourcePass(item, resources, verbatim, depth + 1));
+    if (!isRecord(value))
+        return value;
+    let out = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resourcePass(item, resources, verbatim, depth + 1)]));
+    const ruleFor = (type) => typeof type === "string" && Object.hasOwn(resources.rules, type) ? resources.rules[type] : undefined;
+    // An event's `previous_attributes` is a partial copy of `data.object`: every reviewed path applies to it.
+    const inner = out[resources.key];
+    const innerRule = isRecord(inner) ? ruleFor(inner[resources.key]) : undefined;
+    if (innerRule) {
+        for (const partial of resources.partials ?? []) {
+            let copy = out[partial];
+            if (!isRecord(copy))
+                continue;
+            for (const path of [...(innerRule.paths ?? []), ...(innerRule.withheld ?? [])])
+                copy = applyPath(copy, path);
+            out = { ...out, [partial]: copy };
+        }
+    }
+    const rule = ruleFor(out[resources.key]);
+    if (!rule)
+        return out;
+    for (const path of rule.paths ?? [])
+        out = applyPath(out, path);
+    if (rule.guest && !guestOnly(out, rule.guest)) {
+        for (const path of rule.withheld ?? [])
+            out = applyPath(out, path);
+    }
+    else if (rule.verbatim?.length) {
+        verbatim.set(out, new Set(rule.verbatim));
+    }
+    return out;
+}
+/**
+ * The defense-in-depth pass over any body: credential-named subtrees,
+ * labelled and typed secret records, environment containers, deploy hook
+ * URLs, destination headers, header/cookie/query rule values, route headers,
+ * external route destinations reduced to their origin, and other URLs
+ * sanitized. Reviewed `keep` paths and fields are exempt from the name rule
+ * only; a resource rule's reviewed payer-facing URLs come back verbatim.
+ */
+function heuristic(value, exempt) {
+    const walk = (current, trail, parent, depth) => {
+        if (depth > MAX_DEPTH)
+            return REDACTED;
+        if (typeof current === "string")
+            return URL_SHAPE.test(current) ? sanitizeUrl(current) : current;
+        if (Array.isArray(current))
+            return current.map((item) => walk(item, trail, parent, depth + 1));
+        if (!isRecord(current))
+            return current;
+        const labelled = credentialLabelled(current) || (typeof current["type"] === "string" && /secret/i.test(current["type"]));
+        const destination = parent === "delivery" || "endpoint" in current || "deliveryFormat" in current;
+        const out = {};
+        const verbatim = exempt.verbatim.get(current);
+        for (const [key, item] of Object.entries(current)) {
+            const path = [...trail, key];
+            const normalized = normalizedName(key);
+            const review = Object.hasOwn(exempt.fields, key) ? exempt.fields[key] : undefined;
+            if (review?.verdict === "redact") {
+                out[key] = withheld(item);
+            }
+            else if (labelled && LABELLED_VALUE_FIELDS.includes(key)) {
+                out[key] = withheld(item);
+            }
+            else if (exempt.scopeMaps.includes(parent) &&
+                Array.isArray(item) &&
+                item.every((entry) => typeof entry === "string")) {
+                // Permission scopes: action names under a resource name, never secrets.
+                out[key] = item;
+            }
+            else if (review?.verdict !== "keep" && !matches(exempt.keep, path) && containsCredential(normalized)) {
+                // Both former rules apply: a value either would have removed is removed.
+                out[key] = withheld(item);
+            }
+            else if (review?.verdict !== "keep" && !matches(exempt.keep, path) && CREDENTIAL_SUFFIX.test(normalized)) {
+                out[key] = scrubStrings(item);
+            }
+            else if (ENV_CONTAINERS.includes(normalized)) {
+                // Values go structurally; the rest of the container is still walked.
+                out[key] = walk(scrubEnv(item, depth + 1), path, normalized, depth + 1);
+            }
+            else if (parent === "deployhooks" && key === "url") {
+                out[key] = withheld(item);
+            }
+            else if (key === "headers" && destination && isRecord(item)) {
+                out[key] = Object.fromEntries(Object.keys(item).map((header) => [header, REDACTED]));
+            }
+            else if (HEADER_RULE_VALUES.includes(key) && headerLike(current)) {
+                // Any header, cookie, or query rule matches or sets this value,
+                // wherever the rule sits and whatever its key's form.
+                out[key] = withheld(item);
+            }
+            else if (key === "headers" && routeLike(current)) {
+                out[key] = headerValues(item);
+            }
+            else if (DESTINATION_KEYS.includes(key) && typeof item === "string" && URL_SHAPE.test(item)) {
+                // An external destination can carry its secret in the path; relative paths stay.
+                out[key] = originOnly(item);
+            }
+            else if (typeof item === "string" && verbatim?.has(key)) {
+                out[key] = item;
+            }
+            else {
+                out[key] = walk(item, path, normalized, depth + 1);
+            }
+        }
+        return out;
+    };
+    return walk(value, [], "", 0);
+}
+/** Whether a request field submits a credential or a stored secret. */
+function credentialInput(name) {
+    return credentialName(name) || INPUT_CONTAINERS.test(normalizedName(name));
+}
+/** Whether a request-side schema names a credential input, to a fixed depth. */
+function acceptsCredential(schema, depth) {
+    if (depth > 4 || typeof schema !== "object" || schema === null)
+        return false;
+    const node = schema;
+    return (Object.entries(node.properties ?? {}).some(([name, child]) => credentialInput(name) || acceptsCredential(child, depth + 1)) ||
+        acceptsCredential(node.items, depth + 1) ||
+        (node.anyOf ?? []).some((branch) => acceptsCredential(branch, depth + 1)));
+}
+/** A vendor's value-safety mechanism over its reviewed table and pinned index. */
+export function valueSafety(table, index) {
+    const fields = table.fields ?? {};
+    const scopeMaps = table.scopeMaps ?? [];
+    const inputs = new Map();
+    const verdict = (method, template) => {
+        const key = `${method} ${template}`;
+        return Object.hasOwn(table.operations, key) ? table.operations[key] : undefined;
+    };
+    return {
+        table,
+        verdict,
+        refusal(method, template) {
+            const reviewed = verdict(method, template);
+            return reviewed?.verdict === "refuse" ? `Connecta refuses ${method} ${template}. ${reviewed.reason}` : undefined;
+        },
+        redact(data, method, template) {
+            const reviewed = verdict(method, template);
+            let out = data;
+            if (reviewed?.verdict === "redact")
+                for (const path of reviewed.paths)
+                    out = applyPath(out, path);
+            if (table.envBodies?.test(template))
+                out = scrubValues(out, 0);
+            const verbatim = new WeakMap();
+            if (table.resources)
+                out = resourcePass(out, table.resources, verbatim, 0);
+            const keep = reviewed && reviewed.verdict !== "refuse" ? (reviewed.keep ?? []) : [];
+            return heuristic(out, { keep: keep.map(trailOf), verbatim, fields, scopeMaps });
+        },
+        withholdsErrors(op) {
+            const reviewed = verdict(op.method, op.path);
+            if (reviewed !== undefined)
+                return reviewed.verdict === "refuse" || reviewed.errors !== "vendor";
+            if (op.row < 0)
+                return false;
+            let known = inputs.get(op.row);
+            if (known === undefined) {
+                const contract = index().contract(op);
+                known =
+                    contract.parameters.some((parameter) => parameter.in === "query" && credentialInput(parameter.name)) ||
+                        (contract.body !== undefined &&
+                            (typeof contract.body.schema !== "object" || acceptsCredential(contract.body.schema, 0)));
+                inputs.set(op.row, known);
+            }
+            return known;
+        },
+    };
+}