@open-everywhere/core 0.1.0

package/agent/access/bundle.ts

@@ -0,0 +1,716 @@
+// The access-bundle data model: a named bundle groups connections, connectors, work surfaces, repos, plugins and instructions, and a binding attaches it to a scope. resolver.ts turns a request plus the bundle set into one session's effective access.
+
+import type { OperatorApprover } from "./approver-chain.js";
+import { preApprovalRuleProblems, type PreApprovalRule } from "./pre-approval-rules.js";
+import { repoCapabilityProblems, type RepoCapability } from "./repo-capabilities.js";
+import { resourceGrantProblems, type ResourceGrant } from "./resource-grant.js";
+import { isQualifiedPrincipalKey } from "../identity/principal-key.js";
+import { parseSurfaceKeyEntry } from "../identity/surface-key-grammar.js";
+import { tenantRungRemedy } from "./tenant-admission.js";
+import { isValidLinkSetRef } from "../identity/link-set-ref.js";
+// Type-only (erased at runtime, so no import cycle): the merged config-load check for a binding
+// naming an UNKNOWN group needs the registry's shape, never its behaviour.
+import type { Group } from "../identity/groups.js";
+
+export type ScopeLevel = "org" | "tenant" | "domain" | "surface" | "group" | "principal";
+
+// glossary: Four rungs of increasing specificity — org < tenant < domain < surface — plus the off-ladder personal levels `group` and `principal`.
+// `group` and `principal` resolve ONLY in the DM universe: a service bundle grants nothing in a DM, and a personal binding grants nothing in a channel.
+// glossary: 🔴 `tenant`, `surface` and `principal` are PLATFORM-QUALIFIED because bare vendor ids come from namespaces that never agreed to share one — two platforms' user ids can be identical digit strings, and a collision there resolves a stranger's personal-credential universe in a DM. `domain` and `group` stay BARE, being cross-platform by construction.
+export interface Scope {
+  readonly level: ScopeLevel;
+  /** `platform/<tenant-id>` — required when level is "tenant". */
+  readonly tenant?: string;
+  /** A memory/config/domains.ts domain NAME, bare (no tenant qualifier) — required when level is "domain". */
+  readonly domain?: string;
+  /** `platform/<tenant-id>/<container-id>` — required when level is "surface". */
+  readonly surface?: string;
+  /** An identity/groups.ts group NAME, bare (no platform qualifier — a group is a set of humans,
+   *  cross-platform by construction) — required when level is "group". */
+  readonly group?: string;
+  /** Required at `principal` level: EITHER `platform/<principal-id>` (one account) OR `linkSet:<id>` (one human across their confirmed accounts). The two forms are disjoint — a key contains "/", a ref never does — so a matcher tells them apart by shape. */
+  readonly principal?: string;
+}
+
+// The egress credential plane: static, header-stampable credentials injected at the sandbox firewall. The exchange/OAuth types belong to the host-side connector plane instead; `github-app` here is a pre-provisioned installation token.
+export type CredentialType = "bearer" | "basic" | "github-app";
+
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+// A custom header whose VALUE is a secret. The secret is REFERENCED (`secretRef`), never inlined: it resolves through the credential broker host-side and is injected at the firewall.
+export interface CustomHeader {
+  readonly name: string;
+  /** Optional literal prefix before the secret, e.g. "Token " or "SSWS ". */
+  readonly prefix?: string;
+  /** Reference to the secret value (resolved via the credential broker). */
+  readonly secretRef: string;
+}
+
+// A down-scoping detail forwarded OPAQUELY to the broker's `getSecret`. Core stays vendor-SDK-free, so only the `type` discriminant is pinned here and a broker adapter narrows the rest; a broker that does not support scoping ignores it.
+export interface CredentialAuthorizationDetail {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+// The generic connection schema for any HTTP connector. The secret itself is NEVER stored here — `secretRef` names where the runtime fetches it (env var, db store, secret manager).
+export interface Connection {
+  readonly id: string;
+  readonly credentialType: CredentialType;
+  /** Reference to the secret (e.g. env key), never the secret value itself. */
+  readonly secretRef: string;
+  /**
+   * The HOME broker `secretRef` resolves through ("env", "db", or any registered name); custom headers ride the same one.
+   * There is NO default: an absent broker on a connection that actually resolves FAILS CLOSED rather than guessing. It is optional in the type only for a fixture connection that never resolves.
+   */
+  readonly broker?: string;
+  /** Hosts this connection may reach AND the only hosts its credential is sent to. A wildcard is allowed only as the leftmost label, e.g. "*.googleapis.com". */
+  readonly allowedWebsites: readonly string[];
+  /** Optional path-prefix narrowing (OAuth-authcode connections only, upstream). */
+  readonly pathPrefixes?: readonly string[];
+  /** Secret-valued custom headers (Claude Tag's "Custom headers": name + prefix +
+   *  secret value). Resolved from `secretRef`s via the broker, stacked on top of the
+   *  credentialType's own header. */
+  readonly customHeaders?: readonly CustomHeader[];
+  /** Optional read-only narrowing: restrict to these methods. */
+  readonly methods?: readonly HttpMethod[];
+  /** Optional down-scoping detail forwarded verbatim to the broker's `getSecret`. Unset means exactly today's behaviour: the broker mints its default (blanket) grant for this ref. */
+  readonly authorizationDetails?: readonly CredentialAuthorizationDetail[];
+}
+
+/**
+ * ONE normalised egress host — the single spelling every plane compares by. The egress policy keys the credential on the host alone, so two modules normalising differently would hide a collision from the guard that refuses it.
+ * A wildcard label SURVIVES: this normalises a spelling, it does not expand a pattern.
+ */
+export function normaliseEgressHost(host: string): string {
+  return host.trim().toLowerCase();
+}
+
+/**
+ * Can these two host patterns ever name ONE destination? String equality is not that test: `*.vendor.com` and `api.vendor.com` are two map keys and one destination, so equality lets two connections claim it and the firewall's matching order then decides which credential is stamped.
+ * The relation is symmetric and one wildcard form is expanded — a LEADING `*.`, which covers subdomains but not the apex.
+ * 🔴 That is the only wildcard spelling config may carry, refused elsewhere by `assertBundlesValid`, so this grammar is total over what can reach it.
+ */
+export function egressHostsOverlap(a: string, b: string): boolean {
+  if (a === b) return true;
+  return wildcardCovers(a, b) || wildcardCovers(b, a);
+}
+
+/** Does the leftmost-label wildcard `pattern` match everything `other` can name? */
+function wildcardCovers(pattern: string, other: string): boolean {
+  if (!pattern.startsWith("*.")) return false;
+  const suffix = pattern.slice(1); // "*.vendor.com" → ".vendor.com"
+  return other.endsWith(suffix) && other.length > suffix.length;
+}
+
+// `contentOrigin` is the operator's assertion about WHO AUTHORS the bytes a connection returns — not about how it is authenticated.
+// 🔴 It has teeth: the source-tier table is enforced, so `internal` is the difference between a result that marks the turn as having ingested untrusted content and one that does not.
+// 🔴 Mandatory on a bundle grant and never inferred: `assertBundlesValid` rejects an entry without one, because a defaulted value could not be told from a considered one.
+// 🔴 Silence is still a real state and means "nothing declared", never "external" — a plugin's connectors and a failed resolve both reach it, so the runtime keeps its own fail-closed default and its own tests. Per-tool grain exists because one tool of a connection routinely differs from the rest.
+
+/** What a connector grant may declare about who authors the bytes the connection returns. Both
+ *  members are real claims — unlike `SurfaceTrust`, `"external"` IS writable here, because the
+ *  table has a positive row for it (an exact verdict, not the fail-closed default wearing its
+ *  clothes). */
+export type ConnectorContentOrigin = "internal" | "external";
+
+/** The per-tool form of a content-origin declaration: one answer for the connection, overridden
+ *  for named tools. `except` keys are BARE tool names — the eve-mounted name with its
+ *  `<connection>__` prefix stripped — so an entry can only ever apply to its own connection. */
+export interface ConnectorContentOriginOverrides {
+  readonly default: ConnectorContentOrigin;
+  readonly except: Readonly<Record<string, ConnectorContentOrigin>>;
+}
+
+export type ConnectorContentOriginSpec = ConnectorContentOrigin | ConnectorContentOriginOverrides;
+
+/**
+ * The one connector-grant grammar: `name` is the eve connection slug, `credential` names which configured identity this scope reaches it as, and `contentOrigin` says who authors what it returns.
+ * 🔴 `credential` is MANDATORY and has no default — one list with one mandatory field leaves no second place for consumers to disagree about which connectors a config defines. `contentOrigin` is optional in the TYPE and required by `assertBundlesValid` outside the machine-written overlays.
+ */
+export interface ConnectorGrant {
+  readonly name: string;
+  /** A credential id configured for `name` in the connector's credential catalogue
+   *  (access/connector-credentials.ts). MANDATORY; `lint:connections` fails a grant naming one that
+   *  is not configured, and the resolver contributes nothing for it. */
+  readonly credential: string;
+  readonly contentOrigin?: ConnectorContentOriginSpec;
+}
+
+/**
+ * The bare-slug member is no longer valid config — `assertBundlesValid` rejects it for every bundle, the machine-written overlays included.
+ * It stays in the TYPE so the shared readers still serve the plugin connector lists, so the pure resolver still answers correctly for a grant that never passed validation, and so the rejection stays testable.
+ */
+export type ConnectorGrantSpec = string | ConnectorGrant;
+
+/** The allowlist `assertBundlesValid` validates a declared origin against (fail-loud on config). */
+const KNOWN_CONTENT_ORIGINS: ReadonlySet<string> = new Set<ConnectorContentOrigin>(["internal", "external"]);
+
+/** The Eve connection slug a grant names, whichever form it is written in. Every consumer that
+ *  wants "which connectors does this bundle grant" goes through this — there is deliberately no
+ *  second place that knows the two shapes. */
+export function connectorGrantName(grant: ConnectorGrantSpec): string {
+  return typeof grant === "string" ? grant : grant.name;
+}
+
+/** The content origin a grant DECLARES, or `undefined` when it declares nothing. `undefined` is not
+ *  `"external"` — see the plane header. */
+export function connectorGrantContentOrigin(grant: ConnectorGrantSpec): ConnectorContentOriginSpec | undefined {
+  return typeof grant === "string" ? undefined : grant.contentOrigin;
+}
+
+/** The credential id a grant NAMES, or `undefined` for the bare-slug form that names none. Every
+ *  consumer that asks "as which identity?" goes through this, exactly as `connectorGrantName` is the
+ *  only reader of the two shapes' slug. `undefined` here is not a default — it is a grant
+ *  `assertBundlesValid` refuses and the resolver resolves to nothing. */
+export function connectorGrantCredential(grant: ConnectorGrantSpec): string | undefined {
+  return typeof grant === "string" ? undefined : grant.credential;
+}
+
+/**
+ * Resolve a spec to ONE origin for one BARE tool name — the only place that knows the scalar-versus-object shapes.
+ * `Object.hasOwn` rather than a bare index, so a tool named `__proto__` reads the operator's declaration or nothing; an unvalidated override falls back to `default`, because `undefined` at this seam would erase a declaration the operator did write.
+ */
+export function contentOriginForTool(spec: ConnectorContentOriginSpec, bareToolName: string): ConnectorContentOrigin {
+  if (typeof spec === "string") return spec;
+  const override = Object.hasOwn(spec.except, bareToolName) ? spec.except[bareToolName] : undefined;
+  return override === "internal" || override === "external" ? override : spec.default;
+}
+
+/** Every connector slug a bundle grants, in declaration order (duplicates are a config error the
+ *  load-time assert rejects, so this does not dedupe). */
+export function bundleConnectorNames(bundle: Pick<Bundle, "connectors">): readonly string[] {
+  return (bundle.connectors ?? []).map(connectorGrantName);
+}
+
+// A plugin is a Claude-Code-format capability package (skills, connectors, subagents) granted by NAME and expanded by the registry to its artifacts — an alias over the primitives, not a thing of its own.
+// A cloned repo's own `.mcp.json` is NEVER loaded: capabilities come only from bundle grants, which is the boundary against cloned code self-granting.
+
+/**
+ * Raise the consequence tier of NAMED operations on one connector.
+ * 🔴 RAISE-ONLY, and the vocabulary is why: there is no `open`/`read` field, so no config can spell a lowering — and the runtime combines declarations by lattice JOIN rather than assignment.
+ * The baseline is the verb classifier, where an unrecognised verb already fails closed to `destructive`. Op names match the operation half of `<connection>__<op>` case-insensitively, with `-`/`_` equivalent and "*" for every op.
+ */
+export interface ConnectorOpGating {
+  /** The connector slug these ops belong to — the `<connection>` half of `<connection>__<op>`. */
+  readonly connector: string;
+  /** Ops raised to at least `write`: gated behind an approval card, but session-skippable — an "Approve for session" grant may cover the rest of the session. */
+  readonly gated?: readonly string[];
+  /** Ops raised to `destructive`: gated PER CALL, never covered by a session grant. For an irreversible op whose verb the classifier does not recognise as destructive. */
+  readonly destructive?: readonly string[];
+}
+
+// An AWS role a bundle grants. NOT a `Connection` and carrying NO `secretRef`: there is no long-lived AWS secret.
+// The identity is minted host-side by federating the deployment's own OIDC identity into short-lived STS credentials, injected into a single `aws` invocation — the sandbox never holds the credential.
+// `roleArn`, `region` and `audience` are CONFIG, not secrets, so a grant is safe in the transparent config repo; which domain may assume which role is the reviewed-git boundary, and the role's IAM policy is the true blast radius.
+export interface AwsRoleGrant {
+  /** The IAM role to assume, e.g. "arn:aws:iam::123456789012:role/oe-payments". */
+  readonly roleArn: string;
+  /** AWS region for STS + the signed calls (e.g. "eu-west-2"). Optional — the adapter
+   *  may default it (global services sign against us-east-1 regardless). */
+  readonly region?: string;
+  /** OIDC audience claim the role's trust policy pins (the `aud` the deployment token
+   *  is minted for). Optional — the adapter may carry a deployment-wide default. */
+  readonly audience?: string;
+  /**
+   * REQUIRED host-side service/action allow-list, enforced before the CLI runs.
+   * 🔴 Unrestricted MUST be spelled ["*"]: absence or emptiness is a config error AND a runtime refusal, never a pass-through, because an omitted narrowing and a decision not to narrow looked the same in review.
+   * Grammar: a bare `service`, or `service:action` with IAM-native names and globs or the CLI kebab spelling; s3 high-level commands fan out to enumerated IAM action sets. Matched case-insensitively.
+   * On the domain-role mint path the same list compiles into an STS session policy — defence-in-depth on top of the IAM role, able only to restrict further.
+   */
+  readonly allow: readonly string[];
+}
+
+// 🔴 The GitHub App installation is the only global ceiling, and it is deliberately not restated here: a config-side ceiling would duplicate a decision that already lives on GitHub, and two ceilings that can disagree are worse than one.
+// What a binding decides is default-versus-more: every mint starts from a closed, in-code, per-job permission set, and a binding may name capability sets to expand from there and nothing else.
+// Org-scoped GitHub power stays a non-route structurally — every binding is per-repo, and no shape in this file can express an org-level action.
+
+/** A repo grant that opts INTO named capability sets over the per-plane defaults. `capabilities` names sets from access/repo-capabilities.ts and can never name a raw vendor permission string — `assertBundlesValid` refuses an unknown name, so the reachable permission families stay closed in code. */
+export interface RepoGrant {
+  /** "owner/name", the same form the bare-string spelling takes. */
+  readonly repo: string;
+  /** Named capability sets this binding expands into. Absent = the per-plane defaults, which is
+   *  exactly what the bare-string spelling means. An EMPTY array is a config error, not a synonym
+   *  for absent (see repoCapabilityProblems). */
+  readonly capabilities?: readonly RepoCapability[];
+}
+
+/** One entry of `Bundle.repos`: the bare string (defaults) or the object form (opt-in expansion). */
+export type RepoGrantSpec = string | RepoGrant;
+
+/** The "owner/name" a repo grant names, whichever spelling it is written in. Every consumer that
+ *  asks "which repos does this bundle grant" goes through this — there is deliberately no second
+ *  place that knows the two shapes (the `connectorGrantName` convention). */
+export function repoGrantName(grant: RepoGrantSpec): string {
+  return typeof grant === "string" ? grant : grant.repo;
+}
+
+/** The capability sets a repo grant opts into — EMPTY for the bare string, which is what makes the
+ *  back-compatible spelling mean "today's defaults" rather than "unspecified". */
+export function repoGrantCapabilities(grant: RepoGrantSpec): readonly RepoCapability[] {
+  return typeof grant === "string" ? [] : (grant.capabilities ?? []);
+}
+
+export interface Bundle {
+  /** ⚠️ IMMUTABLE ONCE REFERENCED: renaming orphans every binding that names it — config load catches the ones in this repo, but a live grants overlay written against the old name silently resolves to nothing. Change {@link Bundle.title} for anything a human reads. */
+  readonly name: string;
+  /** Optional human-facing display label. Cosmetic only — no binding, resolver rule, lint
+   *  or audit record reads it. Absent → `name`. */
+  readonly title?: string;
+  /** Egress (sandbox-firewall) credential plane. */
+  readonly connections?: readonly Connection[];
+  /**
+   * CONNECTOR plane: eve connection slugs this bundle grants, host-side MCP/OpenAPI — distinct from the egress `connections` above. Additive union across matching scopes.
+   * One grant grammar, `{ name, credential, contentOrigin }`: the resolver binds the credential per surface, narrowest-wins, and a bare slug is refused at config load.
+   */
+  readonly connectors?: readonly ConnectorGrantSpec[];
+  /** CONNECTOR-OP plane: RAISE the consequence tier of named operations on a granted connector. Purely additive over the verb classifier — see {@link ConnectorOpGating} for the raise-only guarantee. */
+  readonly connectorOps?: readonly ConnectorOpGating[];
+  /**
+   * WORK-SOURCE plane: GitHub repos this bundle grants. A grant is not an auto-clone; a repo clones only when named.
+   * The bare string is today's grant byte-for-byte (the per-plane job sets decide what a call may do); the object form is the opt-in expansion. Additive union, capabilities unioned per repo.
+   */
+  readonly repos?: readonly RepoGrantSpec[];
+  /**
+   * RESOURCE plane: named CONTAINERS on a chat surface this scope may act on, beyond the container its turns arrive in. One row per connector, additive union, capabilities unioned per address.
+   * 🔴 It grants reach, NEVER a domain crossing: a granted container is admitted only when it is also in the caller's own memory domain, checked at execute, which is what makes a cross-domain post unreachable rather than merely refused.
+   */
+  readonly resourceGrants?: readonly ResourceGrant[];
+  /** Credential-LESS egress allowlist: hosts reachable without a credential. These are egress HOSTS, distinct from the `domain` SCOPE level — different concept, unfortunate word overlap. */
+  readonly domains?: readonly string[];
+  /** Plugin grants by NAME; each expands via the registry to its connectors, skills and subagents. Additive union across matching scopes. */
+  readonly plugins?: readonly string[];
+  /** AWS-ROLE plane: IAM roles this bundle grants permission to assume host-side. Additive union deduped by `roleArn` (narrowest-wins for region/audience); credentialed capability, but carrying no `secretRef`. */
+  readonly awsRoles?: readonly AwsRoleGrant[];
+  /**
+   * APPROVER plane: operator-authored chain elements that join L1 for every scope this bundle binds to, config-ordered within the band — config can never reorder the LEVELS.
+   * An operator element may LOWER a built-in verdict, since a bundle author already grants the credentials this plane governs; a connector or remote element is clamped raise-only unless granted `mayAllow`. No runtime surface edits this.
+   */
+  readonly approvers?: readonly OperatorApprover[];
+  /** Scope custom instructions: standing rules that outrank channel memory. Verbatim plain text, no templating, concatenated across matching scopes in precedence order. */
+  readonly instructions?: string;
+  /**
+   * Admin-authored pre-approval rules that reach the approval judge as curated context, resolved per scope and ADDED down the ladder.
+   * 🔴 A rule can PRE-APPROVE a routine action; it can never remove an ask that policy code forces — it is an input to the judge, not a chain element.
+   */
+  readonly preApprovalRules?: readonly PreApprovalRule[];
+}
+
+export interface Binding {
+  readonly bundle: string; // references Bundle.name
+  readonly scope: Scope;
+  /**
+   * EXPLICIT escape for the broad-grant lint: binding a bundle with credentialed capability (connections, repos, connectors, awsRoles) at `org` or `tenant` scope is a hard CI failure, because every channel beneath the scope, including future ones, inherits it.
+   * Set a non-empty REASON to accept that deliberately; an empty string fails the lint, and credential-less grants never need it.
+   */
+  readonly allowBroad?: string;
+}
+
+/**
+ * The package-registry hosts, offered as a named constant a bundle grants in one reviewed line (`domains: [...PACKAGE_REGISTRY_HOSTS]`).
+ * 🔴 Deliberately NOT a compiled-in default: a default would widen every deployment's egress with no diff to review, reach domains scoped to nothing on purpose, and make `compileNetworkPolicy`'s `deny-all` branch unreachable.
+ */
+export const PACKAGE_REGISTRY_HOSTS: readonly string[] = [
+  "registry.npmjs.org",
+  "jsr.io",
+  "npm.jsr.io",
+  "pypi.org",
+  "files.pythonhosted.org",
+  "crates.io",
+  "static.crates.io",
+  "proxy.golang.org",
+  "sum.golang.org",
+];
+
+// Identity-with-types helpers (Eve's define* convention; return unchanged).
+export function defineBundle(bundle: Bundle): Bundle {
+  return bundle;
+}
+
+export function defineBinding(binding: Binding): Binding {
+  return binding;
+}
+
+// These asserts pin the SEMANTICS the resolver depends on but the compiler cannot see, once at config load, throwing with every problem listed — a silent misconfiguration here IS the security bug.
+// Every check is an objective misconfig (the config cannot mean anything), never a policy opinion; the resolver's broad-grant warnings own the judgement calls.
+
+/** GitHub repo grants are `owner/name` — exactly one slash, no URL/branch/whitespace. */
+const REPO_FORM = /^[\w.-]+\/[\w.-]+$/u;
+
+/** An IAM role ARN: `arn:aws[-partition]:iam::<12-digit account>:role/<path>`. Partition
+ *  segment tolerates aws / aws-cn / aws-us-gov. */
+const ROLE_ARN_FORM = /^arn:aws[\w-]*:iam::\d{12}:role\/.+$/u;
+
+/** An AWS region: a two-letter group, one or more lowercase words, then a number
+ *  (e.g. eu-west-2, ap-southeast-1, us-gov-east-1). The `(-[a-z]+)+` middle admits the
+ *  extra segment gov/ISO partitions carry, and stays loose on new region names. */
+const AWS_REGION_FORM = /^[a-z]{2}(?:-[a-z]+)+-\d+$/u;
+
+/** Overly-broad egress pattern: bare "*" (any host) or a single-label wildcard like
+ *  "*.com" (an entire TLD). Wildcards are for one org's subdomains ("*.googleapis.com"). */
+function isOverlyBroadHost(pattern: string): boolean {
+  return pattern === "*" || /^\*\.[^.]+$/u.test(pattern);
+}
+
+/**
+ * A wildcard this tree does not speak: any `*` that is not a single leading `*.`. Every other spelling is compared as a LITERAL, so the one-credential-per-host rungs read it as a destination of its own — and whether the sandbox proxy globs it is not established here, which makes refusing the same answer either way.
+ * It is a deliberate config break: an operator whose own bundles carry such a spelling now fails the boot assertion rather than deploying a pattern that means nothing.
+ */
+function isUnexpandableWildcardHost(pattern: string): boolean {
+  if (!pattern.includes("*")) return false;
+  // The one admitted form, in full: a single leading `*.` and no other star anywhere.
+  return !(pattern.startsWith("*.") && !pattern.slice(2).includes("*"));
+}
+
+/** Flag every unusable pattern in one host list (shared by both egress surfaces): the overly-broad
+ *  ones, and the wildcard spellings this tree never expands. */
+function broadHostProblems(bundleName: string, field: string, hosts: readonly string[]): string[] {
+  const problems: string[] = [];
+  for (const h of hosts) {
+    if (isOverlyBroadHost(h)) {
+      problems.push(
+        `  bundle "${bundleName}" ${field} pattern "${h}" is overly broad (matches ${h === "*" ? "every host" : "an entire TLD"}) — name real hosts, wildcard only one org's subdomains (e.g. "*.googleapis.com")`,
+      );
+      continue; // one verdict per pattern: a bare "*" is both, and the broader message is the useful one
+    }
+    if (isUnexpandableWildcardHost(h)) {
+      problems.push(
+        `  bundle "${bundleName}" ${field} pattern "${h}" spells a wildcard this deployment cannot expand — the ONLY wildcard form is a ` +
+          `single LEADING "*." (e.g. "*.vendor.com"). Every other spelling is compared as a literal, so the one-credential-per-host ` +
+          `rungs read it as a destination of its own and never pair it with the hosts you meant (OPE-1685). Name the real hosts, or ` +
+          `use a leading "*." over the suffix they share.`,
+      );
+    }
+  }
+  return problems;
+}
+
+/** Is this a bundle name a CODEMOD writes (`grants:` / `agent:`) rather than one a human writes? Both codemods refuse a declared connector grant on their own input path, so the prefixes are the only way to tell "nobody could ever declare here" from "an operator omitted it" — an exemption from a hole. */
+function isMachineWrittenBundleName(name: string): boolean {
+  return name.startsWith("grants:") || name.startsWith("agent:");
+}
+
+/**
+ * Every problem with one grant's `contentOrigin`, in either spelling; empty = valid.
+ * Fail-LOUD on anything unrecognised at every depth: a typo that booted to "declares nothing" would read as fail-closed while the operator believed they had vouched. An `except` map must also be non-empty.
+ */
+function contentOriginProblems(bundleName: string, connector: string, spec: unknown): string[] {
+  const known = [...KNOWN_CONTENT_ORIGINS].map((t) => JSON.stringify(t)).join(", ");
+  const where = `bundle "${bundleName}" connector "${connector}"`;
+  // The MANDATORY case gets its own message rather than falling into "unknown value: undefined" —
+  // an operator who omitted the field needs to be told what to write, not what they got wrong.
+  if (spec === undefined) {
+    return [
+      `  ${where} has no \`contentOrigin\` — say who authors the bytes it returns: ` +
+        `contentOrigin: "internal" (only org members can write what it returns) or "external" (anyone can), ` +
+        `or contentOrigin: { default: "internal", except: { "<bare-tool-name>": "external" } } when only some of its tools reach outside content`,
+    ];
+  }
+  if (typeof spec === "string" || spec === null || typeof spec !== "object") {
+    if (KNOWN_CONTENT_ORIGINS.has(spec as string)) return [];
+    return [
+      `  ${where} declares unknown contentOrigin ${JSON.stringify(spec)} — known: ${known}, or { default, except } for per-tool grain (omit the field entirely to declare nothing)`,
+    ];
+  }
+  const obj = spec as { default?: unknown; except?: unknown };
+  const bad: string[] = [];
+  if (!KNOWN_CONTENT_ORIGINS.has(obj.default as string)) {
+    bad.push(`  ${where} declares contentOrigin.default ${JSON.stringify(obj.default)} — known: ${known}`);
+  }
+  if (obj.except === null || typeof obj.except !== "object" || Array.isArray(obj.except)) {
+    bad.push(`  ${where} declares a contentOrigin object whose \`except\` is not a { toolName: origin } map — got ${JSON.stringify(obj.except)}`);
+    return bad;
+  }
+  const except = obj.except as Record<string, unknown>;
+  const toolNames = Object.keys(except);
+  if (toolNames.length === 0) {
+    bad.push(`  ${where} declares contentOrigin \`except: {}\` — an empty exception map is just ${JSON.stringify(obj.default)}; write the scalar, or name the tools that differ`);
+  }
+  for (const tool of toolNames) {
+    if (tool.trim() === "") {
+      bad.push(`  ${where} declares a contentOrigin exception for an empty tool name — name the BARE tool the override applies to`);
+      continue;
+    }
+    // The one objectively-wrong spelling, and the mistake an operator reading a transcript will
+    // make: copying the eve-mounted `<connection>__<tool>` name in. It would never match (the seam
+    // strips the prefix before looking up), so the tool would silently stay on `default` — a silent
+    // wrong answer about taint is exactly what this field exists to prevent.
+    if (tool.startsWith(`${connector}__`)) {
+      bad.push(`  ${where} declares a contentOrigin exception for "${tool}" — \`except\` keys are BARE tool names; drop the "${connector}__" prefix (write "${tool.slice(connector.length + 2)}")`);
+    }
+    if (!KNOWN_CONTENT_ORIGINS.has(except[tool] as string)) {
+      bad.push(`  ${where} declares contentOrigin exception "${tool}" as ${JSON.stringify(except[tool])} — known: ${known}`);
+    }
+  }
+  return bad;
+}
+
+/** Validate the bundle DEFINITIONS at config load and fail loud, listing every problem. Pairs with {@link assertBindingsValid}, the binding side. */
+export function assertBundlesValid(bundles: readonly Bundle[]): void {
+  const bad: string[] = [];
+  const seen = new Set<string>();
+  // Rule ids are unique across the WHOLE config, not per bundle — the id is what an
+  // `approval.judge.verdict` row cites, so a duplicate makes an auto-allow untraceable (OPE-512).
+  const seenRuleIds = new Set<string>();
+  for (const b of bundles) {
+    bad.push(...preApprovalRuleProblems(b.name, b.preApprovalRules, seenRuleIds));
+    if (seen.has(b.name)) bad.push(`  bundle name "${b.name}" is defined more than once (bindings reference bundles by name — names must be unique)`);
+    seen.add(b.name);
+    for (const c of b.connections ?? []) {
+      if (c.allowedWebsites.length === 0) {
+        bad.push(`  bundle "${b.name}" connection "${c.id}" has an empty allowedWebsites — the credential can be sent nowhere; name the host(s) it may reach`);
+      }
+      bad.push(...broadHostProblems(b.name, `connection "${c.id}" allowedWebsites`, c.allowedWebsites));
+    }
+    bad.push(...broadHostProblems(b.name, "domains", b.domains ?? []));
+    const connectors = new Set<string>();
+    for (const grant of b.connectors ?? []) {
+      // Validated at RUNTIME, not only by the compiler: bundles also arrive from JSON the codemods parse and from a deployer's own app tree, so an unknown origin must be a boot error rather than a value that silently reads as "declares nothing".
+      // This is the ONLY place the bare-slug spelling is rejected, and the message carries both accepted shapes because whoever reaches it has not read the connector-plane docs.
+      if (typeof grant === "string") {
+        bad.push(
+          `  bundle "${b.name}" grants connector "${grant}" as a bare slug — a grant names the identity it reaches the connector as: ` +
+            `{ name: "${grant}", credential: "<a credential id from the connector's catalogue>", contentOrigin: "internal" | "external" }. ` +
+            `The machine-written overlays write { name, credential } and omit contentOrigin; every other bundle declares all three.`,
+        );
+      } else if (grant === null || typeof grant !== "object" || typeof (grant as ConnectorGrant).name !== "string" || (grant as ConnectorGrant).name.trim() === "") {
+        bad.push(`  bundle "${b.name}" has a connector grant that is not a { name, credential, contentOrigin } object — got ${JSON.stringify(grant)}`);
+        continue; // no usable name — nothing to duplicate-check against
+      } else {
+        const g = grant as ConnectorGrant;
+        // The credential is mandatory on EVERY grant, machine-written overlays included, unlike `contentOrigin`: a content origin is an operator assertion a codemod may not invent, while a credential is a choice the requester already made at propose time and the codemod only writes through.
+        if (typeof g.credential !== "string" || g.credential.trim() === "") {
+          bad.push(
+            `  bundle "${b.name}" grants connector "${g.name}" with no \`credential\` — name which configured identity this scope reaches it as, ` +
+              `e.g. { name: "${g.name}", credential: "team-key", contentOrigin: "external" }. The ids come from that connector's credential catalogue ` +
+              `(agent/access/connector-credentials.ts); \`npm run lint:connections\` fails a grant naming one that is not configured.`,
+          );
+        }
+        // Machine-written overlays are EXEMPT from `contentOrigin`, the one carve-out: both codemods refuse a declared origin so that nothing on that path is model-authored past propose time, so those grants declare nothing and stay on the fail-closed default. An operator who wants one grants the same connector from a reviewed code bundle.
+        if (g.contentOrigin !== undefined || !isMachineWrittenBundleName(b.name)) {
+          bad.push(...contentOriginProblems(b.name, g.name, g.contentOrigin));
+        }
+      }
+      // Duplicate check is by NAME, and it runs even for a grant that already failed above (via
+      // `connectorGrantName`, which knows both spellings) so a tree with several problems reports
+      // ALL of them in one pass rather than one per fix-and-rerun cycle.
+      const name = connectorGrantName(grant);
+      if (connectors.has(name)) bad.push(`  bundle "${b.name}" grants connector "${name}" more than once — remove the duplicate`);
+      connectors.add(name);
+    }
+    // connectorOps: OBJECTIVE misconfigs only (the file's stated rule). Whether the connector is
+    // also granted here is NOT checked — a raise on an ungranted connector cannot widen anything,
+    // and the join is deployment-wide anyway (connector-op-gating.ts), so refusing it would be a
+    // policy opinion, not a "this config cannot mean anything".
+    const gatedConnectors = new Set<string>();
+    for (const g of b.connectorOps ?? []) {
+      const key = g.connector.trim().toLowerCase();
+      if (key === "") {
+        bad.push(`  bundle "${b.name}" has a connectorOps entry with an empty connector name — name the connector its ops belong to`);
+        continue;
+      }
+      if (gatedConnectors.has(key)) {
+        bad.push(`  bundle "${b.name}" declares connectorOps for "${g.connector}" more than once — merge the entries (two entries for one connector make the declaration ambiguous)`);
+      }
+      gatedConnectors.add(key);
+      const ops = [...(g.gated ?? []), ...(g.destructive ?? [])];
+      if (ops.length === 0) {
+        bad.push(`  bundle "${b.name}" connectorOps entry for "${g.connector}" names no ops — it raises nothing; list ops under gated/destructive or drop the entry`);
+      }
+      if (ops.some((op) => op.trim() === "")) {
+        bad.push(`  bundle "${b.name}" connectorOps entry for "${g.connector}" has an empty op name — every entry must name a real operation (or "*" for all of them)`);
+      }
+    }
+    // REPO GRANTS (OPE-1024): both spellings validated in one pass. Runtime shape checks, not just
+    // the compiler's, because bundles also arrive from JSON the codemods parse and from a
+    // deployer's own app tree — an unknown capability must be a boot error, never an expansion that
+    // silently reads as the narrow default until a mint 403s in production.
+    const repoNames = new Set<string>();
+    for (const grant of b.repos ?? []) {
+      if (grant === null || (typeof grant !== "string" && typeof grant !== "object") || Array.isArray(grant)) {
+        bad.push(`  bundle "${b.name}" has a repo grant that is neither "owner/name" nor a { repo, capabilities } object — got ${JSON.stringify(grant)}`);
+        continue;
+      }
+      const name = repoGrantName(grant as RepoGrantSpec);
+      if (typeof name !== "string" || !REPO_FORM.test(name)) {
+        bad.push(`  bundle "${b.name}" repo ${JSON.stringify(name)} must be bare owner/name form (e.g. "acme/web") — not a URL, a bare owner, or an owner/name/extra path`);
+      }
+      // A repo declared twice in one bundle makes "which capabilities does this grant carry?"
+      // depend on declaration order — the same ambiguity the connector duplicate check refuses.
+      if (repoNames.has(name)) {
+        bad.push(`  bundle "${b.name}" grants repo ${JSON.stringify(name)} more than once — merge the entries (two entries for one repo make its capabilities ambiguous)`);
+      }
+      repoNames.add(name);
+      if (typeof grant === "object") {
+        for (const k of Object.keys(grant)) {
+          if (k !== "repo" && k !== "capabilities") {
+            bad.push(`  bundle "${b.name}" repo grant ${JSON.stringify(name)} has unknown field "${k}" — a repo grant carries { repo, capabilities } only`);
+          }
+        }
+        bad.push(...repoCapabilityProblems(`bundle "${b.name}" repo ${JSON.stringify(name)}`, (grant as RepoGrant).capabilities));
+      }
+    }
+    // RESOURCE GRANTS (OPE-1064): the same runtime-shape discipline the repo grants above take, and
+    // for the same reason — a bundle can arrive from parsed JSON, where the compiler proves nothing.
+    // An unknown connector, a malformed address or an unknown capability is a BOOT error, never a
+    // row that reads as a working grant until a member watches the tool refuse.
+    bad.push(...resourceGrantProblems(`bundle "${b.name}"`, b.resourceGrants));
+    const roleArns = new Set<string>();
+    for (const grant of b.awsRoles ?? []) {
+      if (!ROLE_ARN_FORM.test(grant.roleArn)) {
+        bad.push(`  bundle "${b.name}" awsRoles roleArn "${grant.roleArn}" must be an IAM role ARN (e.g. "arn:aws:iam::123456789012:role/oe-agent")`);
+      }
+      if (roleArns.has(grant.roleArn)) {
+        bad.push(`  bundle "${b.name}" grants awsRole "${grant.roleArn}" more than once — remove the duplicate`);
+      }
+      roleArns.add(grant.roleArn);
+      if (grant.region !== undefined && !AWS_REGION_FORM.test(grant.region)) {
+        bad.push(`  bundle "${b.name}" awsRoles region "${grant.region}" is not a well-formed AWS region (e.g. "eu-west-2")`);
+      }
+      // allow is REQUIRED (OPE-296 §8): absent-or-empty used to mean unrestricted, which made an
+      // omitted narrowing and a deliberate decision not to narrow indistinguishable in review.
+      // Unrestricted must now be a reviewed line: allow: ["*"].
+      if (grant.allow === undefined || grant.allow.length === 0) {
+        bad.push(
+          `  bundle "${b.name}" awsRoles grant "${grant.roleArn}" has no \`allow\` list — REQUIRED: spell unrestricted access explicitly as allow: ["*"] (an absent narrowing and a decision not to narrow must not look the same; at runtime an allow-less grant REFUSES, never passes through)`,
+        );
+      }
+      const seenAllow = new Set<string>();
+      for (const entry of grant.allow ?? []) {
+        if (entry.trim() === "") {
+          bad.push(`  bundle "${b.name}" awsRoles allow entry for "${grant.roleArn}" is empty/whitespace — an allow entry must be a "service" (e.g. "logs") or "service:operation" (e.g. "s3:cp")`);
+          continue;
+        }
+        const colons = entry.split(":").length - 1;
+        if (colons > 1) {
+          bad.push(`  bundle "${b.name}" awsRoles allow entry "${entry}" (role "${grant.roleArn}") is malformed — an entry has at most one ":" ("service" or "service:operation")`);
+          continue;
+        }
+        if (colons === 1) {
+          const [service, operation] = entry.split(":");
+          if (service!.trim() === "" || operation!.trim() === "") {
+            bad.push(`  bundle "${b.name}" awsRoles allow entry "${entry}" (role "${grant.roleArn}") is malformed — both sides of the ":" must be non-empty ("service:operation", e.g. "s3:cp")`);
+            continue;
+          }
+        }
+        // Dedupe on the same normal form the runtime matcher uses (service lowercased,
+        // operation lowercased with `-`/`_` unified) — "S3:cp" and "s3:cp" are one entry.
+        const [svc, op] = entry.split(":");
+        const norm = op === undefined ? svc!.trim().toLowerCase() : `${svc!.trim().toLowerCase()}:${op.trim().toLowerCase().replace(/_/gu, "-")}`;
+        if (seenAllow.has(norm)) {
+          bad.push(`  bundle "${b.name}" awsRoles allow lists "${entry}" (role "${grant.roleArn}") more than once — remove the duplicate`);
+        }
+        seenAllow.add(norm);
+      }
+    }
+    // Objective misconfigs only: an approver name must be non-empty and unique within the bundle (the row's `resolvedBy` is `custom:<name>`), and the element must be callable.
+    // `mayAllow` is refused on an operator-authored element — it is the clamp escape for connector and remote sources, and an operator element already holds the full verdict range.
+    const approverNames = new Set<string>();
+    for (const a of b.approvers ?? []) {
+      const name = a.name?.trim() ?? "";
+      if (name === "") {
+        bad.push(`  bundle "${b.name}" has an approver with an empty name — the audit row's resolvedBy is "custom:<name>", so every element needs one`);
+        continue;
+      }
+      if (approverNames.has(name)) bad.push(`  bundle "${b.name}" declares approver "${name}" more than once — names must be unique within a bundle (resolvedBy would be ambiguous)`);
+      approverNames.add(name);
+      if (typeof a.approve !== "function") bad.push(`  bundle "${b.name}" approver "${name}" has no callable approve() — an element that cannot answer is config that means nothing`);
+      if (a.mayAllow === true && (a.source === undefined || a.source === "operator")) {
+        bad.push(`  bundle "${b.name}" approver "${name}" sets mayAllow on an operator-authored element — mayAllow is the clamp escape for source:"connector"/"remote" elements only (an operator element already holds the full verdict range)`);
+      }
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      "open-everywhere: invalid access bundle(s):\n" + bad.join("\n") + "\n(access/bundle.ts / docs/how-it-works/access-and-scoping.md)",
+    );
+  }
+}
+
+/** The ONE address field each scope level carries — nothing else may be set (a stray
+ *  field means the author meant a different level, which is exactly how the pre-OPE-219
+ *  `{ level: "domain", workspace: … }` shape read). */
+type ScopeAddressField = "tenant" | "domain" | "surface" | "group" | "principal";
+const LEVEL_FIELD: Record<string, ScopeAddressField | null | undefined> = {
+  org: null,
+  tenant: "tenant",
+  domain: "domain",
+  surface: "surface",
+  group: "group",
+  principal: "principal",
+};
+
+/** `platform/<tenant-id>` — exactly two non-empty, slash-free segments. */
+export const TENANT_KEY = /^[^/\s]+\/[^/\s]+$/u;
+/** `platform/<tenant-id>/<container-id>` — three+ segments; only the container may hold a "/".
+ *  The one authority on the surface-key form: bindings (assertBindingsValid), the
+ *  access-request delta (delta.ts) and the grants codemod all test against THIS. */
+export const SURFACE_KEY = /^[^/\s]+\/[^/\s]+\/\S+$/u;
+
+/**
+ * Validate the BINDINGS at config load (fail loud): a known bundle, exactly the level's one address field, qualified tenant/surface/principal keys, and bare domain and group names. Pairs with {@link assertBundlesValid}.
+ * 🔴 The group registry is an ARGUMENT, not a lookup: existence is a joint property of two config files, so the check belongs to the app tier's merged validation — and `undefined` SKIPS the existence check, it does not silently approve.
+ */
+export function assertBindingsValid(bindings: readonly Binding[], bundles: readonly Bundle[], groups?: readonly Group[]): void {
+  const known = new Set(bundles.map((b) => b.name));
+  const knownGroups = groups === undefined ? undefined : new Set(groups.map((g) => g.name));
+  const bad: string[] = [];
+  for (const b of bindings) {
+    const where = `binding "${b.bundle}" (${b.scope.level} scope)`;
+    if (!known.has(b.bundle)) bad.push(`  ${where} references unknown bundle "${b.bundle}" — define it in the bundles list or fix the name`);
+    const { level, tenant, domain, surface, group, principal } = b.scope;
+    const required = LEVEL_FIELD[level];
+    if (required === undefined) {
+      bad.push(`  ${where} has an unknown scope.level "${level}" — the levels are org | tenant | domain | surface | group | principal`);
+      continue;
+    }
+    for (const [field, value] of [["tenant", tenant], ["domain", domain], ["surface", surface], ["group", group], ["principal", principal]] as const) {
+      if (field === required) {
+        if (!value) bad.push(`  ${where} needs scope.${field} — a ${level}-level binding can never match without one`);
+      } else if (value !== undefined) {
+        bad.push(
+          `  ${where} also sets scope.${field} — a ${level}-level scope carries ${required ? `only scope.${required}` : "no address field"}; drop it or change the level`,
+        );
+      }
+    }
+    if (tenant && !TENANT_KEY.test(tenant)) {
+      bad.push(
+        `  ${where} scope.tenant "${tenant}" must be the PLATFORM-QUALIFIED tenant key "platform/<tenant-id>" (e.g. "slack/T0123ABC", "discord/1300000000000000100", "github/acme") — a bare vendor id has no platform and will NEVER match`,
+      );
+    }
+    if (surface && !SURFACE_KEY.test(surface)) {
+      bad.push(
+        `  ${where} scope.surface "${surface}" must be the fully-qualified surface key "platform/<tenant-id>/<container-id>" (e.g. "slack/T0123ABC/C0123ABC") — the SAME form memory domains' \`channels\` use; a bare channel id will NEVER match`,
+      );
+    }
+    if (domain?.includes("/")) {
+      bad.push(
+        `  ${where} scope.domain "${domain}" contains "/" — a domain scope takes the BARE domain name from memory/config/domains.ts ("payments"), deliberately NOT tenant-qualified: domains are cross-platform, so one grant is one binding`,
+      );
+    }
+    // A group address is a BARE name, like a domain's, for the same reason: a set of humans spans
+    // platforms, so qualifying it by one would need N bindings for one grant. The only objective
+    // misconfig checkable without the registry is emptiness (whitespace can never name a group);
+    // EXISTENCE needs both files and is checked just below, when the caller supplied the registry.
+    if (group !== undefined && group.trim().length === 0) {
+      bad.push(`  ${where} scope.group is empty — a group-level binding takes the BARE group name from agent/identity/groups.ts (e.g. "payments-team")`);
+    } else if (group !== undefined && knownGroups !== undefined && !knownGroups.has(group)) {
+      bad.push(
+        `  ${where} scope.group "${group}" is not a declared person-group — define it with defineGroup() in agent/identity/groups.ts (or fix the name). A binding onto a group nobody declared can never match, so it is refused rather than ignored.`,
+      );
+    }
+    // A `principal` address is EITHER the qualified `platform/<principal-id>` key OR a `linkSet:<id>` reference; anything else is the pre-P0 bare form, which cannot match what the resolver composes.
+    // Fail-loud rather than a lint, because the config cannot mean what it says; the `dm:` sentinel gets its own message because its author needs a different instruction.
+    if (principal !== undefined && !isQualifiedPrincipalKey(principal) && !isValidLinkSetRef(principal)) {
+      bad.push(
+        principal.startsWith("dm:")
+          ? `  ${where} scope.principal "${principal}" still carries the old \`workspace: "dm:<id>"\` sentinel — the DM universe is the first-class \`principal\` level now, so drop the "dm:" prefix and write the PLATFORM-QUALIFIED key "platform/<principal-id>" (e.g. "slack/U0123ABC")`
+          : `  ${where} scope.principal "${principal}" must be the qualified principal key "platform/<principal-id>" — or, on a tenant-scoped platform, "platform/<tenant-id>/<principal-id>" (e.g. "slack/T0AB1CD2E/U0123ABC", "discord/300000000000000104") — or a link-set reference "linkSet:<link-set-id>" (one human across their confirmed accounts). A BARE member id has no platform namespace and will NEVER match, and on Slack a key missing its workspace has no tenant namespace and will never match either (identity/principal-key.ts, identity/link-set-ref.ts).${tenantRungRemedy(principal)}`,
+      );
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      "open-everywhere: invalid access binding(s):\n" + bad.join("\n") + "\n(access/bundle.ts / docs/how-it-works/access-and-scoping.md)",
+    );
+  }
+}