@open-everywhere/core 0.1.0

package/agent/webhooks/verifier.ts

@@ -0,0 +1,324 @@
+// The WEBHOOK VERIFIER REGISTRY (OPE-164) — WHICH signature scheme authenticates an inbound
+// delivery, resolved from the hook's DECLARED source, never sniffed off the request.
+//
+// WHAT IT BUYS: a hook can declare a VENDOR's source and be verified in that vendor's scheme, so one
+// generic ingress takes a third-party system's webhooks unmodified (one-ingress-per-system). Schemes
+// vary on EVERY axis — header name, basestring, digest, encoding, whether a timestamp participates
+// and WHERE it lives — and this tree already verifies a hex HMAC over the body alone; a hex HMAC over
+// `<version>:<ts>:<body>` with a skew window; an ASYMMETRIC Ed25519 signature over `<ts><body>`; a
+// signature whose freshness timestamp lives INSIDE THE JSON BODY; and a bearer JWT validated against
+// the issuer's rotating public keys. This registry is the seam all of them share.
+//
+// PURE REGISTRY LEAF — the `credentials/home.ts` posture. Types + a Map + five functions; no
+// crypto, no vendor strings, no store, no eve. Verifier IMPLEMENTATIONS live with the code that
+// owns the scheme (core's own in `webhooks/oe-standard-webhook.ts`; a vendor's in its provider bundle, which
+// is also where that vendor's header names and literals stay).
+//
+// RESOLUTION IS BY THE HOOK'S DECLARED SOURCE. NEVER SNIFFED. Three reasons, worst first:
+//   1. Sniffing hands the ATTACKER verifier selection. With N verifiers, "whichever header is
+//      present wins" lets the sender choose which scheme authenticates them — and the moment one
+//      registered verifier is weaker than another (some vendors declare `signedTimestamp: false`;
+//      our own contract is timestamped) that is a live DOWNGRADE PRIMITIVE: present the WEAKER
+//      scheme's header instead of ours and the replay defence evaporates. Verifiers of both
+//      strengths are registered in a normal deployment, so this is not hypothetical.
+//   2. It makes the no-header case ambiguous. Today "no signature header" is unambiguously 401.
+//      Under sniffing it becomes "no verifier selected" — a different branch, and the classic
+//      place a fail-open creeps in.
+//   3. A key is bound to a SCHEME, not to an endpoint. Feeding a Notion verification_token to the
+//      GitHub verifier is a category error the CONFIG must decide, not the request — the same
+//      doctrine `brokerFor` follows: a coincidental value from the wrong resolver is worse than a
+//      clear error.
+//
+// UNREGISTERED SOURCE ⇒ FAIL CLOSED, taking `brokerFor`'s STRENGTH with `credentialHome`'s
+// MECHANISM: {@link webhookVerifier} returns `undefined` (a leaf must not throw) and the gate
+// converts that into a 401 naming the registered set. NOT a throw — a module-load throw on a
+// serverless cold start is the shape of the 12h dark-prod incident, and
+// `access/provider-selection.ts` already fixes "REFUSE, DON'T THROW" as house doctrine.
+// `webhooks.allowUnverified` does NOT waive this: the dev hatch exists for "the secret isn't
+// set on my laptop", not for "this deployment cannot authenticate this scheme at all".
+
+import { admitProviderRegistration } from "../access/provider-selection.js";
+
+/** What a verifier is handed. DELIBERATELY has no `signatureHeader`, and no `parsed`/`json`. */
+export interface WebhookVerifyInput {
+  /**
+   * The EXACT bytes as received — the single `await req.text()` of the ingress, never a
+   * reserialised parse. Re-serialising JSON changes key order, float spelling, escape form and
+   * whitespace, so every vendor scheme breaks on it (Notion, verbatim: *"Pass the raw request
+   * body exactly as it arrived (re-serialized JSON produces different bytes and fails
+   * verification)"*). The invariant is pinned by tests, not by this comment.
+   */
+  readonly rawBody: string;
+  /**
+   * The FULL request headers. A verifier picks its OWN names — there is no "the signature
+   * header" to pre-extract: Linear's freshness timestamp is not in a header at all, and Stripe
+   * packs a timestamp AND N signatures into one. Narrowing this to a single string was the
+   * lowest-common-denominator trap, refuted by three real vendors.
+   */
+  readonly headers: Headers;
+  /**
+   * Ordered candidate keys, CURRENT FIRST, then any previous keys during a rotation overlap
+   * (`webhooks/secrets.ts` resolveHookKeys). A shared secret for `keyKind: "shared-secret"`, a
+   * public key / app identifier for `"public-key"`. Never empty — the gate rejects a keyless
+   * hook before a verifier is ever called.
+   */
+  readonly keys: readonly string[];
+  /** Injected clock (epoch ms), so skew windows are unit-testable without faking Date. */
+  readonly nowMs: number;
+}
+
+/** Why a verification failed — a closed set, so the 401 reason can never carry vendor detail. */
+export type WebhookVerifyFailure =
+  | "missing-signature"
+  | "malformed-signature"
+  | "signature-mismatch"
+  | "missing-timestamp"
+  | "malformed-timestamp"
+  | "stale-timestamp"
+  | "unsupported-scheme";
+
+/** `keyIndex > 0` ⇒ the delivery verified against a PREVIOUS key (a live rotation overlap) and
+ *  is audited as such — the operator's "the old key is still in use" signal.
+ *
+ *  `replayKey` (OPE-176) — an OPAQUE, already-hashed nonce identity for the durable single-use
+ *  dedupe store (webhooks/replay-dedupe.ts), set ONLY by a verifier whose {@link
+ *  WebhookVerifier.signedTimestamp} is true. (WHICH sources those are is registry state and is
+ *  deliberately not written down here — it was, as "currently just `oe-standard-webhook`", and
+ *  OPE-197 falsified it by registering a second one. `scripts/webhook-source-vocabulary-live-test.ts`
+ *  MEASURES the set instead.) The gate (webhooks/gate.ts)
+ *  enforces this itself — it strips `replayKey` from the outcome unless the RESOLVED verifier
+ *  declares `signedTimestamp: true`, so a careless or malicious `signedTimestamp: false` verifier
+ *  cannot smuggle dedupe protection it has no freshness claim to back (an untimestamped source's
+ *  replay window would then be bounded only by an ARBITRARY retention policy dressed up as a real
+ *  guarantee — see the module doc on webhooks/replay-dedupe.ts for why that was rejected). A
+ *  `signedTimestamp: true` verifier that forgets to set `replayKey` on an accepted verdict silently
+ *  loses dedupe for its source — pinned by a test per verifier, not caught structurally here. */
+export type WebhookVerdict =
+  | { readonly ok: true; readonly keyIndex: number; readonly replayKey?: string }
+  | { readonly ok: false; readonly failure: WebhookVerifyFailure };
+
+/**
+ * ⭐ HOW A HUMAN MAKES A SENDER SPEAK THIS SCHEME — structured, never HTML, and rendered by whoever
+ * is showing it (today: `webhooks/reveal-page.ts`, beside the secret it belongs to).
+ *
+ * 🔴 IT LIVES ON THE VERIFIER, NOT IN THE PAGE, because it and {@link verify} are one fact stated
+ * twice — the verifier says what is ACCEPTED, this says what to SEND — and the facts are unguessable
+ * and PER SCHEME (two registered schemes typically agree on no header name, no signed content and no
+ * digest encoding, so one generic paragraph would be wrong for one of them). Any other home drifts
+ * the first time a scheme changes, and drift here is SILENT: a sender follows stale instructions and
+ * gets a 401 with a deliberately reasonless body. `scripts/standard-webhook-test.ts` pins each field
+ * against the exported constants and basestring builders rather than against a copy of the words.
+ *
+ * OPTIONAL, and absence is meaningful rather than lazy: a `vendor-issued` scheme has no instructions
+ * WE are entitled to give (the vendor's own console is the interface, and its docs are authoritative
+ * about its own headers). A renderer shows nothing extra for such a scheme.
+ *
+ * 🔴 EVERY STRING HERE IS A TEMPLATE AND MUST STAY ONE. No live value, no secret, nothing
+ * request-derived. A renderer escapes these, but escaping is not confidentiality — the reason
+ * nothing sensitive is in here is that nothing sensitive is ever PUT in here.
+ */
+export interface WebhookSenderGuidance {
+  /** The headers a delivery must carry, in the order a human should read them. `value` describes the
+   *  SHAPE (`v1,<base64 signature>`), never an instance. */
+  readonly headers: readonly { readonly name: string; readonly value: string }[];
+  /** Exactly what the signature is computed over, written the way the basestring builder builds it. */
+  readonly signedContent: string;
+  /** One short sentence each: key derivation, digest encoding, freshness, replay. Rendered as a list. */
+  readonly notes: readonly string[];
+}
+
+/** One registered signature scheme. */
+export interface WebhookVerifier {
+  /** Registry key = exactly what a hook declares as its `source` (webhooks/config.ts). */
+  readonly source: string;
+  /** Set ⇒ this entry belongs to a provider BUNDLE and its registration is routed through
+   *  `admitProviderRegistration`, so a de-selected provider contributes nothing. Core's own
+   *  verifier leaves it UNSET — `"oe-standard-webhook"` will never appear in a deployment's provider
+   *  selection and must not be gated by it. */
+  readonly provider?: string;
+  /** `"shared-secret"` (HMAC-class) or `"public-key"` (Discord's Ed25519, a JWT issuer's key
+   *  identifier). The field exists so an asymmetric scheme is expressible without reshaping the
+   *  interface later — verified against Discord (Ed25519) and Teams (Bot Connector JWT). */
+  readonly keyKind: "shared-secret" | "public-key";
+  /**
+   * WHO CHOOSES THE KEY — the axis {@link keyKind} does NOT cover, and the one that decides whether
+   * a source's key can be MINTED BY THIS DEPLOYMENT at all (OPE-186).
+   *
+   *   • `"receiver-minted"` — the key is whatever the RECEIVING side puts into the sender's
+   *     configuration, so an arbitrary random secret works. That is the precondition a minted key
+   *     depends on: `approvals/webhook.ts` mints one with `mintSecret()` at the click and a human
+   *     pastes it into the sender.
+   *   • `"vendor-issued"` — the vendor GENERATES the key and hands it to us (Notion's one-time
+   *     `verification_token`; an asymmetric scheme's public key or JWKS). A secret WE minted can
+   *     never verify against it, so a hook that had its key minted here would 401 every delivery for
+   *     as long as it existed — and nothing downstream would say why.
+   *
+   * DECLARED, NOT INFERRED, and required — the {@link signedTimestamp} posture, for the same
+   * reason: the fact lives in a vendor's docs, so a field somebody had to fill in is the only place
+   * it can be reviewed. Read through {@link acceptsMintedSecret} by
+   * `webhooks/source-vocabulary.ts`, so a vendor-issued source is structurally ABSENT from what
+   * chat can mint rather than mintable-and-permanently-broken.
+   */
+  readonly keyOrigin: "receiver-minted" | "vendor-issued";
+  /**
+   * TRUE iff the scheme covers a timestamp AND this verifier enforces a skew window. This is a
+   * DECLARATION, allowlist-tested: a `false` means replay against that source is undefended, and
+   * saying so out loud turns an unwritten fact into a reviewed entry. Since OPE-176, `true` also
+   * turns the accepted verdict's `replayKey` into a durable single-use mark (webhooks/replay-
+   * dedupe.ts, keyed on the durable `markEventSeen` store — NOT `EventDedupe`, which is in-memory
+   * per instance and does not survive a cold start or a sibling instance). A `false` source stays
+   * bounded by nothing at all — see replay-dedupe.ts's module doc for why a vendor delivery id
+   * was rejected as a substitute bound for those.
+   */
+  readonly signedTimestamp: boolean;
+  /**
+   * Async so a JWKS-fetching (Teams-class) verifier fits. MUST NOT throw for a bad signature —
+   * a bad signature is `{ ok: false }`. A throw means a BROKEN verifier; the gate catches it and
+   * turns it into a 401 rather than a 500, so a broken verifier fails closed too.
+   *
+   * ORDERING RULE: a verifier may parse the body ONLY AFTER its digest matches. Parse-before-
+   * verify feeds attacker bytes to an unauthenticated parser. (Linear's scheme needs the body for
+   * its timestamp — it parses second, after the HMAC.)
+   */
+  verify(input: WebhookVerifyInput): Promise<WebhookVerdict> | WebhookVerdict;
+  /**
+   * ⭐ THIS SCHEME'S OWN SECRET FORMAT, when it has one — the minter `approvals/webhook.ts` uses at
+   * the approval click instead of its generic random.
+   *
+   * 🔴 WHY THE SCHEME OWNS THIS AND THE MINT SITE DOES NOT. A stored secret is a STRING; what a
+   * verifier HMACs is BYTES; and the function from one to the other is the scheme's, not the mint
+   * site's (`oe-standard-webhook`'s `standardWebhookKey` base64-decodes a `whsec_` secret and takes
+   * the UTF-8 bytes of anything else). A mint site that picked the string format would be choosing
+   * key material for a derivation it cannot see — the exact shape of a silent signature break.
+   *
+   * ABSENT ⇒ the generic random the mint site has always used. Absence is the DEFAULT, not a gap.
+   *
+   * ⚠️ RESOLVED THROUGH THIS REGISTRY, SO IT DEPENDS ON THE SCHEME'S MODULE BEING ARMED. An UNARMED
+   * registry degrades to the generic mint, which for `oe-standard-webhook` still verifies (its key
+   * rule accepts both forms), so the failure mode is a secret that loses a convention rather than a
+   * hook that cannot authenticate. Stated because the degradation is otherwise invisible;
+   * `scripts/standard-webhook-test.ts` pins the declaration.
+   *
+   * MUST return a fresh, high-entropy value per call — it is a KEY, not an identifier.
+   */
+  readonly mintSecret?: () => string;
+  /** What a human must make their sender send, for a scheme where we are entitled to say. See
+   *  {@link WebhookSenderGuidance} for why this is the verifier's to declare. */
+  readonly senderGuidance?: () => WebhookSenderGuidance;
+}
+
+const VERIFIERS = new Map<string, WebhookVerifier>();
+
+/**
+ * Register (or replace) the verifier for one source. A verifier carrying `provider` is routed
+ * through the provider-selection gate first, so a de-selected bundle writes ZERO rows here and
+ * every hook declaring that source then fails closed at resolution — no new refusal path needed.
+ * Returns whether the row landed.
+ */
+export function registerWebhookVerifier(verifier: WebhookVerifier): boolean {
+  if (verifier.provider !== undefined && !admitProviderRegistration(verifier.provider, "webhook-verifier")) return false;
+  VERIFIERS.set(verifier.source, verifier);
+  return true;
+}
+
+/** The verifier for `source`, or `undefined` when none is registered — the caller (the gate)
+ *  turns that into a 401 naming the registered set. NEVER a fallback to another scheme. */
+export function webhookVerifier(source: string | undefined): WebhookVerifier | undefined {
+  return source === undefined ? undefined : VERIFIERS.get(source);
+}
+
+/** Every registered source, sorted — for the fail-closed refusal copy and the boundary guard. */
+export function registeredWebhookVerifierSources(): readonly string[] {
+  return [...VERIFIERS.keys()].sort();
+}
+
+/** Every registered verifier — for the `signedTimestamp` allowlist guard and the vocabulary
+ *  derivation (`webhooks/source-vocabulary.ts`, which needs the ENTRIES, not just their keys). */
+export function registeredWebhookVerifiers(): readonly WebhookVerifier[] {
+  return [...VERIFIERS.values()];
+}
+
+/**
+ * Can this scheme authenticate a delivery signed with a secret WE minted at random? (OPE-186)
+ *
+ * THE precondition for a hook whose key this deployment mints, which is always `approvals/webhook.ts`'s
+ * `mintSecret()` — never a value handed to us. BOTH clauses are load-bearing: an asymmetric scheme
+ * has no shared secret for us to mint even if something declared its key receiver-chosen, and a
+ * vendor-issued shared secret is a value we RECEIVE rather than choose.
+ *
+ * ONE definition, shared by the vocabulary derivation and the test that pins it against the live
+ * registries. Two copies of this predicate is precisely how the two would drift.
+ */
+export function acceptsMintedSecret(verifier: WebhookVerifier): boolean {
+  return verifier.keyOrigin === "receiver-minted" && verifier.keyKind === "shared-secret";
+}
+
+/**
+ * ⭐⭐ THE AUTHENTICATION-STRENGTH LADDER (OPE-203) — how strongly a delivery was authenticated,
+ * as an ORDERED vocabulary, so a hook can declare a FLOOR and the gate can refuse anything under it.
+ *
+ * 🔴 THREE VALUES, EACH ANCHORED TO SOMETHING THAT ALREADY SHIPS. Nothing here is a new axis:
+ *
+ *   • `"unverified"`  — NO signature was checked at all. The delivery's only proof is possession of
+ *                       the hook URL. Reachable exactly once in this tree, through the local-dev
+ *                       hatch, and already named by `webhooks/gate.ts`'s {@link
+ *                       import("./gate.js").acceptedUnverified}.
+ *   • `"signed"`      — a signature verified against a resolvable key, on a scheme that covers NO
+ *                       timestamp. `signedTimestamp: false`. Ships today for github and notion.
+ *   • `"signed-fresh"`— the above PLUS a scheme-covered timestamp with an enforced skew window, i.e.
+ *                       {@link WebhookVerifier.signedTimestamp}. Ships today for
+ *                       `oe-standard-webhook` and (since OPE-197) slack. This is the SAME bit that
+ *                       already decides whether `gate.ts` lets `replayKey` through, which is the
+ *                       one live grade→consequence edge this ladder generalises.
+ *
+ * 🔴 WHAT IS DELIBERATELY *NOT* ON THE LADDER, because a ladder is a TOTAL ORDER and these are not
+ * points on one. Putting them here would be inventing an ordering nothing in the tree supports:
+ *
+ *   • {@link WebhookVerifier.keyKind} / {@link WebhookVerifier.keyOrigin} — WHO CHOOSES THE KEY, not
+ *     how well a delivery was authenticated. A `vendor-issued` key is not weaker than a
+ *     `receiver-minted` one; an asymmetric `public-key` scheme is arguably STRONGER, and no
+ *     registered verifier declares one today, so ordering it would be a guess dressed as a rule.
+ *     Those two axes have their own derived predicate — {@link acceptsMintedSecret} — answering
+ *     their own question, and that is the shape this one copies rather than absorbs.
+ *   • `keyIndex > 0` (a rotation-overlap acceptance) — KEY CURRENCY, orthogonal to scheme strength,
+ *     and the one fact here a SENDER picks: it chooses which key to sign with. A floor that moved
+ *     with it would be inferred from the delivery, which is the downgrade primitive this whole
+ *     design exists to refuse. It also stays audited-but-unconstraining by explicit decision
+ *     ("No auto-expiry rides on this", channels/webhooks.ts) and this ticket does not reopen that.
+ *
+ * PURE, TOTAL AND ORDERED BY INDEX. The array IS the order; a fourth grade is inserted at its rank
+ * and every comparison below follows, with no switch anywhere to forget to update.
+ */
+export type WebhookAuthGrade = "unverified" | "signed" | "signed-fresh";
+
+/** The ladder, WEAKEST FIRST. Order is semantic — {@link meetsWebhookAuthFloor} compares indices. */
+export const WEBHOOK_AUTH_GRADES: readonly WebhookAuthGrade[] = ["unverified", "signed", "signed-fresh"] as const;
+
+/**
+ * THE STRONGEST GRADE ANY DELIVERY ON THIS SCHEME CAN EVER REACH — a derived predicate over the
+ * verifier's own declared strength fields, exactly as {@link acceptsMintedSecret} is.
+ *
+ * 🔴 IT IS A PROPERTY OF THE REGISTERED SCHEME, NOT OF A REQUEST, AND THAT IS THE WHOLE POINT. The
+ * input is the verifier the hook's DECLARED source resolved to (`webhooks/gate.ts`), never a header,
+ * never a verdict. So "how strong is this hook" has one answer for every delivery it will ever take,
+ * and a sender cannot move it in either direction by choosing what to send.
+ *
+ * NEVER RETURNS `"unverified"`: a resolved verifier means a signature WILL be checked. `unverified`
+ * is not a scheme's ceiling, it is what an acceptance that skipped the check attained — which is why
+ * the gate supplies that value from the hatch branch and this function cannot.
+ */
+export function webhookAuthCeiling(verifier: WebhookVerifier): WebhookAuthGrade {
+  return verifier.signedTimestamp ? "signed-fresh" : "signed";
+}
+
+/** Is `achieved` at least as strong as `floor`? Index comparison over {@link WEBHOOK_AUTH_GRADES} —
+ *  ONE definition, shared by the gate's two refusal arms and the tests that pin them. */
+export function meetsWebhookAuthFloor(achieved: WebhookAuthGrade, floor: WebhookAuthGrade): boolean {
+  return WEBHOOK_AUTH_GRADES.indexOf(achieved) >= WEBHOOK_AUTH_GRADES.indexOf(floor);
+}
+
+/** Test seam: forget every registered verifier (mirrors resetCredentialHomes). No auto-restore —
+ *  a verifier module re-registers on its next load, and a test file owns its own process. */
+export function resetWebhookVerifiersForTest(): void {
+  VERIFIERS.clear();
+}

package/bin/oe-eve-patch.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// The `oe-eve-patch` bin (OPE-2184) — the one command a consumer runs to put the OE eve patch into
+// the eve it installed.
+//
+//   npm i @open-everywhere/core eve@<pin>
+//   npx oe-eve-patch
+//
+// WHY A CONSUMER HAS TO RUN THIS AT ALL. eve is a PEER dependency, so the consumer installs the
+// registry copy, and the OE patch is not in it. Without the patch the untrusted-projection fence and
+// every per-wake seat cut are silently inert (OPE-2168). The published package cannot apply the patch
+// by itself: a publishable OE manifest carries no `preinstall`, `install`, `postinstall`,
+// `prepublish` or `prepare` script and `scripts/publish-lint.ts` refuses one — rewriting a
+// dependency's bytes at install time is exactly what a consumer must be able to refuse. So the patch
+// ships in the tarball and this command applies it, explicitly, when the consumer asks.
+//
+// 🔴 PLAIN JAVASCRIPT, AND NO `tsx` REGISTER CALL. The sibling `bin/oe.js` registers `tsx` to run a
+// TypeScript dispatcher; `tsx` is a devDependency, so that route needs a toolchain a consumer's
+// install does not carry. This bin imports the compiled `dist/` instead, which is what every other
+// consumer entry point does, and spawns patch-package — core's one runtime dependency for it.
+//
+// Every DECISION this file makes lives in `agent/publish/eve-patch-pack.ts` as a pure function with
+// its own test (`packages/core/scripts/eve-patch-applier-test.ts`). What is left here is the parts
+// that touch the world: resolving eve, reading files, spawning patch-package, printing.
+
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, readFileSync, readdirSync, realpathSync, renameSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  checkEveResolution,
+  evePatchFileName,
+  evePatchSharedTargets,
+  evePatchTargets,
+  missingEveMarkers,
+  patchDirArgument,
+} from "../dist/agent/publish/eve-patch-pack.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = dirname(HERE);
+
+/** Fail with one clear reason per line, and never a stack trace — this is a consumer-facing tool. */
+function refuse(problems) {
+  console.error(`✗ oe-eve-patch: ${problems.length} problem(s)`);
+  for (const problem of problems) console.error(`  - ${problem}`);
+  process.exit(1);
+}
+
+/** A real path, or undefined when the path is not there. */
+function realOrUndefined(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+const pin = manifest.peerDependencies?.eve;
+if (typeof pin !== "string") {
+  refuse([`${manifest.name ?? "@open-everywhere/core"} declares no eve peer dependency — this install is not usable`]);
+}
+
+// 🔴 RESOLVE EVE FROM THE CONSUMER'S CWD, NOT FROM THIS FILE. Walking up from the bin's own path
+// finds the eve nested beside THIS package, which under a hoisted install is the same directory and
+// under any other layout is the wrong one. The consumer's project root is what owns the eve the
+// consumer's own code will import, so that is the tree to patch.
+const consumerRoot = realpathSync(process.cwd());
+const fromConsumer = createRequire(pathToFileURL(join(consumerRoot, "package.json")).href);
+let resolvedManifest;
+try {
+  resolvedManifest = realpathSync(fromConsumer.resolve("eve/package.json"));
+} catch {
+  resolvedManifest = undefined;
+}
+const addressableManifest = realOrUndefined(join(consumerRoot, "node_modules", "eve", "package.json"));
+const installedVersion =
+  resolvedManifest === undefined ? undefined : JSON.parse(readFileSync(resolvedManifest, "utf8")).version;
+
+const resolutionProblems = checkEveResolution({
+  consumerRoot,
+  resolvedManifest,
+  addressableManifest,
+  installedVersion,
+  pin,
+});
+if (resolutionProblems.length > 0) refuse(resolutionProblems);
+
+const eveRoot = dirname(resolvedManifest);
+const patchFile = evePatchFileName(pin);
+const packedPatchDir = realOrUndefined(join(PACKAGE_ROOT, "patches"));
+if (packedPatchDir === undefined || !existsSync(join(packedPatchDir, patchFile))) {
+  refuse([
+    `this @open-everywhere/core install carries no patches/${patchFile}. The tarball ships it (the publish gate asserts ` +
+      `that), so a copy without it is an incomplete install — reinstall @open-everywhere/core`,
+  ]);
+}
+const extra = readdirSync(packedPatchDir).filter((f) => f.endsWith(".patch") && f !== patchFile);
+if (extra.length > 0) {
+  refuse([
+    `patches/ in this install holds ${extra.join(", ")} beside ${patchFile}. patch-package applies EVERY patch in the ` +
+      `directory it is pointed at, so the applier refuses rather than change a package nobody asked it to`,
+  ]);
+}
+
+const patchDir = patchDirArgument({ consumerRoot, packedPatchDir });
+if (!patchDir.ok) refuse([patchDir.problem]);
+
+const patchBody = readFileSync(join(packedPatchDir, patchFile), "utf8");
+const targets = evePatchTargets(patchBody);
+if (targets.length === 0) {
+  refuse([`patches/${patchFile} declares no target files (no "+++ b/…" header) — it cannot be applied`]);
+}
+
+// patch-package is core's runtime dependency for exactly this command. Resolve its own bin rather
+// than a `node_modules/.bin` shim: the shim's location is a hoisting detail, the package's is not.
+// npm allows `bin` as a bare string or a name→path map, so read both shapes rather than assume one.
+let patchPackageBin;
+try {
+  const patchPackageManifest = createRequire(import.meta.url).resolve("patch-package/package.json");
+  const { bin } = JSON.parse(readFileSync(patchPackageManifest, "utf8"));
+  const entry = typeof bin === "string" ? bin : bin?.["patch-package"];
+  if (typeof entry !== "string") throw new Error(`its manifest declares no patch-package bin (bin: ${JSON.stringify(bin)})`);
+  patchPackageBin = join(dirname(patchPackageManifest), entry);
+} catch (err) {
+  refuse([
+    `patch-package could not be resolved from this install: ${err instanceof Error ? err.message : String(err)}. It is a ` +
+      `dependency of @open-everywhere/core, so a tree without it is incomplete — reinstall @open-everywhere/core`,
+  ]);
+}
+
+console.log(
+  `oe-eve-patch: eve@${installedVersion} at ${consumerRoot}/node_modules/eve — applying ${patchFile} ` +
+    `(${targets.length} file(s))`,
+);
+
+// 🔴 DETACH ANY TARGET THAT IS HARDLINKED INTO A SHARED PACKAGE STORE, BEFORE patch-package RUNS.
+// pnpm and bun import a package's files by hardlink, so one inode is shared with every project that
+// installed that version — and patch-package rewrites a target with `writeFileSync(path, …)`, which
+// truncates that inode rather than replacing the directory entry. Copy to a fresh inode and rename
+// over the entry: the store keeps the original bytes, and only this project's file moves.
+// `copyFileSync` carries the source's mode, and the rename is atomic, so a killed run leaves either
+// the old file or the new one — never a half-written target.
+const linkCounts = new Map();
+for (const target of targets) {
+  if (target.insidePackage === "") continue;
+  const file = join(eveRoot, target.insidePackage);
+  if (existsSync(file)) linkCounts.set(target.insidePackage, statSync(file).nlink);
+}
+const shared = evePatchSharedTargets(targets, linkCounts);
+for (const rel of shared) {
+  const file = join(eveRoot, rel);
+  const detached = `${file}.oe-detach`;
+  copyFileSync(file, detached);
+  renameSync(detached, file);
+}
+if (shared.length > 0) {
+  console.log(
+    `  · detached ${shared.length} file(s) from a shared package store before patching — pnpm and bun ` +
+      `hardlink from a store, and patching in place would have rewritten eve for every project on this machine`,
+  );
+}
+
+// 🔴 `--error-on-fail` IS REQUIRED AND IS NOT ENOUGH. Without it patch-package exits 0 on a hunk it
+// could not apply (its own default is a warning), so the consumer would be told nothing. With it, a
+// FAILED apply still exits 0 when the reverse dry run succeeds — which is exactly what makes a second
+// run on an already-patched tree a no-op. Neither route reads the bytes afterwards, so the marker
+// check below is the evidence, not this exit code.
+const applied = spawnSync(process.execPath, [patchPackageBin, "--patch-dir", patchDir.value, "--error-on-fail"], {
+  cwd: consumerRoot,
+  stdio: ["ignore", "inherit", "inherit"],
+});
+if (applied.error !== undefined) {
+  refuse([`patch-package could not be started: ${applied.error.message}`]);
+}
+if (applied.status !== 0) {
+  refuse([
+    `patch-package exited ${applied.status ?? `on signal ${applied.signal}`} — the patch did not apply. Its output above ` +
+      `names the hunk. An eve whose bytes were already modified is the usual cause: reinstall eve@${pin} and try again`,
+  ]);
+}
+
+// The proof. Read each patched file out of the installed eve and assert every marker the patch adds.
+const contents = new Map();
+for (const target of targets) {
+  if (target.insidePackage === "") continue;
+  const file = join(eveRoot, target.insidePackage);
+  contents.set(target.insidePackage, existsSync(file) ? readFileSync(file, "utf8") : undefined);
+}
+const missing = missingEveMarkers(targets, contents);
+if (missing.length > 0) refuse(missing);
+
+// One line per PART, and one line for a file whose hunks declare no part header — patch part 9
+// (OPE-2106) is such a file, so a report built from part headers alone would leave it invisible.
+for (const target of targets) {
+  for (const part of target.parts) console.log(`  ✓ ${part.ticket} — ${part.title} (${target.path})`);
+  if (target.parts.length > 0) continue;
+  console.log(
+    `  ✓ ${target.path} — applied; the patch declares no part header for this file` +
+      `${target.markers.length > 0 ? `, markers: ${target.markers.join(", ")}` : " and it adds no __oe marker"}`,
+  );
+}
+
+console.log(`✓ oe-eve-patch: eve@${installedVersion} carries the OE patch (${targets.length} file(s) verified)`);

package/bin/oe.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// The `oe` bin — a shim so the dispatcher itself can be TypeScript.
+//
+// 🔴 WHY THIS REGISTERS `tsx` RATHER THAN RELYING ON NODE'S TYPE STRIPPING. Node 24 strips types,
+// but stripping is NOT a substitute for a resolver, and two measured limits bite here (both
+// verified on Node 24.18.0, both contradicting the "zero toolchain" hope):
+//   1. A relative `import "./x.js"` from a `.ts` file is NOT rewritten to `./x.ts`. Node reports
+//      ERR_MODULE_NOT_FOUND. Only an `exports` map can perform that rewrite, and only for BARE
+//      specifiers — which every module in this package's import graph is not.
+//   2. Type stripping is DISABLED for anything whose realpath is inside `node_modules`
+//      (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). In this monorepo the workspace symlink means
+//      the realpath is `packages/core/…`, so it would work here and fail in a registry install —
+//      the worst possible split.
+// `tsx` is already this repo's universal script runner (every gate is `tsx scripts/*.ts`), so using
+// it here is the boring choice rather than a new dependency. When the packages are first published
+// they will ship compiled JS, and this shim can drop the register call.
+const { register } = await import("tsx/esm/api");
+register();
+await import("../scripts/oe-cli.ts");

package/dist/agent/access/access-referenced-link-sets.d.ts

@@ -0,0 +1,8 @@
+import type { Binding } from "./bundle.js";
+import { type Group } from "../identity/groups.js";
+/** Every link-set id referenced by access config — `linkSet:` principal bindings and person-group link-set members. Exact principal-key and `platform/<id>` entries are excluded: a directory sync can change only which accounts a link-set holds. */
+export declare function accessReferencedLinkSets(input: {
+    readonly bindings?: readonly Binding[];
+    readonly groups?: readonly Group[];
+}): Set<string>;
+//# sourceMappingURL=access-referenced-link-sets.d.ts.map

package/dist/agent/access/access-referenced-link-sets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-referenced-link-sets.d.ts","sourceRoot":"","sources":["../../../agent/access/access-referenced-link-sets.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGlE,uPAAuP;AACvP,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;CACpC,GAAG,GAAG,CAAC,MAAM,CAAC,CAYd"}

package/dist/agent/access/access-referenced-link-sets.js

@@ -0,0 +1,20 @@
+// Collects the link-set ids that ACCESS config names, so a directory auto-confirm into one is suppressed and downgraded to a suggestion the person must still complete. It answers only that question: a link-set-vault-armed deployment reaches a live token through membership alone, which is planDirectorySync's separate blanket input.
+import { groupLinkSets } from "../identity/groups.js";
+import { parseLinkSetRef } from "../identity/link-set-ref.js";
+/** Every link-set id referenced by access config — `linkSet:` principal bindings and person-group link-set members. Exact principal-key and `platform/<id>` entries are excluded: a directory sync can change only which accounts a link-set holds. */
+export function accessReferencedLinkSets(input) {
+    const out = new Set();
+    for (const b of input.bindings ?? []) {
+        if (b.scope.level === "principal" && b.scope.principal !== undefined) {
+            const id = parseLinkSetRef(b.scope.principal);
+            if (id !== undefined)
+                out.add(id);
+        }
+    }
+    for (const g of input.groups ?? []) {
+        for (const id of groupLinkSets(g))
+            out.add(id);
+    }
+    return out;
+}
+//# sourceMappingURL=access-referenced-link-sets.js.map

package/dist/agent/access/access-referenced-link-sets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-referenced-link-sets.js","sourceRoot":"","sources":["../../../agent/access/access-referenced-link-sets.ts"],"names":[],"mappings":"AAAA,6UAA6U;AAG7U,OAAO,EAAE,aAAa,EAAc,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,uPAAuP;AACvP,MAAM,UAAU,wBAAwB,CAAC,KAGxC;IACC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACrE,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC9C,IAAI,EAAE,KAAK,SAAS;gBAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACnC,KAAK,MAAM,EAAE,IAAI,aAAa,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/agent/access/admin-read-venue.d.ts

@@ -0,0 +1,48 @@
+import { type BindableContext } from "../identity/binding.js";
+import { type FloorAttestation } from "./audience-floor.js";
+/** Where an admin memory read may answer, and with WHICH roles. */
+export type AdminReadVenue = 
+/** The full org-wide view, rendered in place. */
+{
+    readonly placement: "org-wide";
+    readonly via: "governance-channel" | "requester-dm";
+    readonly roles: readonly string[];
+}
+/** Narrowed to this room's own domain — the answer no longer exceeds the room's scope. */
+ | {
+    readonly placement: "domain-scoped";
+    readonly domain: string;
+    readonly roles: readonly string[];
+}
+/** Nothing this asker holds is sayable here. `channel` is the governance channel, when one exists. */
+ | {
+    readonly placement: "redirect";
+    readonly target: "governance-channel" | "requester-dm";
+    readonly channel?: string;
+};
+/** The classification inputs — all resolved by the caller, so the core stays pure. */
+export interface AdminReadVenueInput {
+    /** The asker's roles, from the caller's OWN role gate (adminControlRoles). Never re-derived here. */
+    readonly roles: readonly string[];
+    readonly isRequesterDm: boolean;
+    readonly isGovernanceChannel: boolean;
+    /** The governance floor attestation for the asking room (present iff isGovernanceChannel). */
+    readonly attestation?: FloorAttestation;
+    /** The explicit domain this room resolves to (domainForChannel), if any. */
+    readonly roomDomain?: string;
+    /** The configured governance-channel target (governanceChannelFor); undefined ⇒ none configured. */
+    readonly governanceChannel?: string;
+}
+/** The pure venue decision: an armed governance channel, then the asker's DM, then this room's explicit domain when the asker administers it, else a redirect. A breached floor is an ordinary room, and step 3 narrows an org admin to exactly `domain:<room>`. */
+export declare function classifyAdminReadVenue(input: AdminReadVenueInput): AdminReadVenue;
+/** The venue half of the gate — call it right AFTER the role gate; that composition IS the dual gate. It returns the EFFECTIVE roles the read may spend, always a subset of what was passed in, and throws {@link PaneRedirectError} when the room may hear nothing. */
+export declare function requireAdminReadVenue(ctx: BindableContext, input: {
+    readonly roles: readonly string[];
+    readonly principalId?: string;
+    readonly kind: string;
+}): Promise<{
+    readonly roles: readonly string[];
+    readonly decision: AdminReadVenue;
+    readonly note?: string;
+}>;
+//# sourceMappingURL=admin-read-venue.d.ts.map

package/dist/agent/access/admin-read-venue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-read-venue.d.ts","sourceRoot":"","sources":["../../../agent/access/admin-read-venue.ts"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIxE,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAOrF,mEAAmE;AACnE,MAAM,MAAM,cAAc;AACxB,iDAAiD;AAC/C;IAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,oBAAoB,GAAG,cAAc,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AAC5H,0FAA0F;GACxF;IAAE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AACrG,sGAAsG;GACpG;IAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1H,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,qGAAqG;IACrG,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,oQAAoQ;AACpQ,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,mBAAmB,GAAG,cAAc,CAcjF;AAoED,wQAAwQ;AACxQ,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjG,OAAO,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAa3G"}