@open-everywhere/core 0.1.0

package/dist/agent/credentials/reserved-refs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A VENDOR-ISSUED handshake secret captured at subscription time (OPE-195) — today, Notion's
+ * `verification_token`, which is the HMAC key for every subsequent delivery on that subscription.
+ * Same class as `hook:` (an INBOUND authentication key the egress plane must never fetch), and
+ * captured by the one function that mints it, `webhooks/handshake-capture.ts`.
+ *
+ * ⚠️ DELIBERATELY NOT UNDER `hook:`. These are not runtime hooks, and `revealEndpointUrl` renders
+ * `<base>/webhooks/<rest>` for ANY `hook:` ref with no second colon — so a `hook:`-namespaced
+ * handshake ref would print a bogus ingress URL beside the secret on the reveal page. A separate
+ * namespace keeps the endpoint render honest AND still earns the resolver refusal below.
+ */
+export declare const NOTION_HANDSHAKE_REF_NAMESPACE = "notion-handshake:";
+/**
+ * A SELF-SHARED secret this deployment mints for and verifies against ITSELF — no external
+ * counterparty ever holds or presents the value (OPE-408 step 3: `OE_INTAKE_PAGE_SIGNING_KEY`,
+ * `OE_SPAWN_DISPATCH_SECRET`, `OE_TRANSCRIPT_RELAY_SECRET`). Same class as `hook:`/`oe-oauth:`: read
+ * and written directly by {@link import("./self-secrets.js").getOrMintSelfSecret}, never through the
+ * outbound resolver. See `self-secrets.ts` for the mint-on-first-use resolution order.
+ */
+export declare const SELF_SECRET_REF_NAMESPACE = "self:";
+/** Ref prefixes that name HOST-MINTED internal secret material. Never resolvable as an outbound
+ *  credential. Additive-only: adding a prefix here can only ever make the resolver refuse MORE. */
+export declare const RESERVED_REF_NAMESPACES: readonly string[];
+/** The reserved namespace `ref` sits in, or undefined. Case-sensitive on purpose: the refs are
+ *  host-minted with exact spelling, and a case-insensitive test would refuse an operator's
+ *  legitimately-named `Hook:` key for no reason. */
+export declare function reservedRefNamespace(ref: string): string | undefined;
+/** The operator-facing refusal sentence. Names the ref (a POINTER — the class of information every
+ *  other credential error already carries) and never a value. */
+export declare function reservedRefRefusal(ref: string, ns: string): string;
+//# sourceMappingURL=reserved-refs.d.ts.map

package/dist/agent/credentials/reserved-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-refs.d.ts","sourceRoot":"","sources":["../../../agent/credentials/reserved-refs.ts"],"names":[],"mappings":"AAiCA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,sBAAsB,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;mGACmG;AACnG,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAA+F,CAAC;AAErJ;;oDAEoD;AACpD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;iEACiE;AACjE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAOlE"}

package/dist/agent/credentials/reserved-refs.js

@@ -0,0 +1,70 @@
+// RESERVED CREDENTIAL-REF NAMESPACES (OPE-150) — the fail-closed line between the two things that
+// share the `stored_credential` table.
+//
+// THE PROBLEM THIS CLOSES. `stored_credential` is one table with two tenants:
+//
+//   1. OUTBOUND credentials an operator or a member deliberately handed us (an API key pasted into
+//      the intake modal). These are resolved by the EGRESS plane through
+//      `getSecretVia("db", ref)` — a read-only CredentialBroker whose whole job is "give the
+//      outbound call its bearer token".
+//   2. INTERNAL secret material the HOST minted for ITSELF and stores through the encrypted KV
+//      vault (`credentials/kv-vault.ts`): the own-rolled OAuth adapter's tokens (`oe-oauth:*`),
+//      the `hook:*` namespace a since-deleted chat-created webhook class minted into (retained: see
+//      below), and since OPE-195
+//      a VENDOR-issued handshake key we merely captured rather than minted (`notion-handshake:*`).
+//
+// Class 2 must never be resolvable as class 1. A webhook signing secret is an INBOUND
+// authentication key: routing it through the outbound resolver would make it something the egress
+// plane can fetch and send to a third party. Today the only way to ask for that is a config
+// credential declaring `broker: "db", secretRef: "hook:…"` — which needs a merged PR, so it is
+// not a live hole. It is also a free guard that costs one map lookup on a path that already does a
+// database read, and it closes the identical residual `oe-oauth:` already carried.
+//
+// 🔴 NOT A DEAD GUARD — the triggering condition is a real, expressible config today. Both
+// `access/bundle.ts`'s `Connection.secretRef` and `webhooks/config.ts`'s `WebhookHook.secretRef`
+// are free-form strings resolved through `getSecretVia`, and neither validator has ever inspected
+// the namespace. `scripts/webhook-runtime-test.ts` drives the guard through the REAL broker.
+//
+// WHY A GUARD AND NOT "PUT THEM IN A DIFFERENT TABLE". A second table is a second migration, a
+// second RLS policy, a second backend triple to keep in sync, and a second crypto path — the exact
+// drift this tree's "one mechanism per concern" rule exists to prevent. The vault ALREADY reads and
+// writes these refs directly (it holds the store handle itself, credentials/kv-vault.ts), so the
+// namespaces are separated where the separation actually has to hold: at the RESOLVER.
+/**
+ * A VENDOR-ISSUED handshake secret captured at subscription time (OPE-195) — today, Notion's
+ * `verification_token`, which is the HMAC key for every subsequent delivery on that subscription.
+ * Same class as `hook:` (an INBOUND authentication key the egress plane must never fetch), and
+ * captured by the one function that mints it, `webhooks/handshake-capture.ts`.
+ *
+ * ⚠️ DELIBERATELY NOT UNDER `hook:`. These are not runtime hooks, and `revealEndpointUrl` renders
+ * `<base>/webhooks/<rest>` for ANY `hook:` ref with no second colon — so a `hook:`-namespaced
+ * handshake ref would print a bogus ingress URL beside the secret on the reveal page. A separate
+ * namespace keeps the endpoint render honest AND still earns the resolver refusal below.
+ */
+export const NOTION_HANDSHAKE_REF_NAMESPACE = "notion-handshake:";
+/**
+ * A SELF-SHARED secret this deployment mints for and verifies against ITSELF — no external
+ * counterparty ever holds or presents the value (OPE-408 step 3: `OE_INTAKE_PAGE_SIGNING_KEY`,
+ * `OE_SPAWN_DISPATCH_SECRET`, `OE_TRANSCRIPT_RELAY_SECRET`). Same class as `hook:`/`oe-oauth:`: read
+ * and written directly by {@link import("./self-secrets.js").getOrMintSelfSecret}, never through the
+ * outbound resolver. See `self-secrets.ts` for the mint-on-first-use resolution order.
+ */
+export const SELF_SECRET_REF_NAMESPACE = "self:";
+/** Ref prefixes that name HOST-MINTED internal secret material. Never resolvable as an outbound
+ *  credential. Additive-only: adding a prefix here can only ever make the resolver refuse MORE. */
+export const RESERVED_REF_NAMESPACES = ["hook:", "oe-oauth:", NOTION_HANDSHAKE_REF_NAMESPACE, SELF_SECRET_REF_NAMESPACE];
+/** The reserved namespace `ref` sits in, or undefined. Case-sensitive on purpose: the refs are
+ *  host-minted with exact spelling, and a case-insensitive test would refuse an operator's
+ *  legitimately-named `Hook:` key for no reason. */
+export function reservedRefNamespace(ref) {
+    return RESERVED_REF_NAMESPACES.find((ns) => ref.startsWith(ns));
+}
+/** The operator-facing refusal sentence. Names the ref (a POINTER — the class of information every
+ *  other credential error already carries) and never a value. */
+export function reservedRefRefusal(ref, ns) {
+    return (`credential ref ${JSON.stringify(ref)} is in the reserved "${ns}" namespace — refusing to resolve it as an ` +
+        `outbound credential (fail closed). Refs in that namespace hold secret material this deployment minted for ` +
+        `ITSELF (an inbound webhook signing secret, an OAuth token the adapter rotates); they are read internally by ` +
+        `the encrypted KV vault, never handed to an outbound call. Pick a different ref.`);
+}
+//# sourceMappingURL=reserved-refs.js.map

package/dist/agent/credentials/reserved-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-refs.js","sourceRoot":"","sources":["../../../agent/credentials/reserved-refs.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,uCAAuC;AACvC,EAAE;AACF,8EAA8E;AAC9E,EAAE;AACF,mGAAmG;AACnG,yEAAyE;AACzE,6FAA6F;AAC7F,wCAAwC;AACxC,+FAA+F;AAC/F,gGAAgG;AAChG,oGAAoG;AACpG,iCAAiC;AACjC,mGAAmG;AACnG,EAAE;AACF,sFAAsF;AACtF,kGAAkG;AAClG,4FAA4F;AAC5F,+FAA+F;AAC/F,mGAAmG;AACnG,mFAAmF;AACnF,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,EAAE;AACF,+FAA+F;AAC/F,mGAAmG;AACnG,oGAAoG;AACpG,iGAAiG;AACjG,uFAAuF;AAEvF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,mBAAmB,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAEjD;mGACmG;AACnG,MAAM,CAAC,MAAM,uBAAuB,GAAsB,CAAC,OAAO,EAAE,WAAW,EAAE,8BAA8B,EAAE,yBAAyB,CAAU,CAAC;AAErJ;;oDAEoD;AACpD,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;iEACiE;AACjE,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,EAAU;IACxD,OAAO,CACL,kBAAkB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,wBAAwB,EAAE,6CAA6C;QAC5G,4GAA4G;QAC5G,8GAA8G;QAC9G,iFAAiF,CAClF,CAAC;AACJ,CAAC"}

package/dist/agent/credentials/self-secrets.d.ts

@@ -0,0 +1,24 @@
+import { type EncryptedKvVault } from "./kv-vault.js";
+/** Injectable seams for tests — the live default is the real encrypted KV vault + `process.env`. */
+export interface SelfSecretDeps {
+    readonly vault?: EncryptedKvVault;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/** Test seam: forget which names have already warned about the env on-ramp. */
+export declare function resetSelfSecretWarnings(): void;
+/** Test seam: forget cached resolutions — needed only by a test that resolves through the DEFAULT
+ *  vault (no `deps.vault` override) and then mutates the vault directly and expects the NEXT
+ *  resolution to observe it. */
+export declare function resetSelfSecretCache(): void;
+/** Is the vault reachable for self-shared secrets at all? A cheap, SYNC predicate — every mount
+ *  predicate / "is this feature armed" check in the four consuming modules uses THIS, not an async
+ *  vault read, because minting never fails once the AES key is armed: "configured" reduces exactly
+ *  to "can I mint", and callers that also need a resolvable base URL AND this. */
+export declare function selfSecretsArmed(): boolean;
+/**
+ * Resolve a self-shared secret by its env-var name, minting it on first use. See the module header
+ * for the resolution order. `name` doubles as the vault ref's suffix (`self:<name>`) — reversible,
+ * and namespaced so it can never collide with an operator-managed `db:`-homed credential.
+ */
+export declare function getOrMintSelfSecret(name: string, deps?: SelfSecretDeps): Promise<string>;
+//# sourceMappingURL=self-secrets.d.ts.map

package/dist/agent/credentials/self-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-secrets.d.ts","sourceRoot":"","sources":["../../../agent/credentials/self-secrets.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAKxE,oGAAoG;AACpG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAID,+EAA+E;AAC/E,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAeD;;gCAEgC;AAChC,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAQD;;;kFAGkF;AAClF,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgClG"}

package/dist/agent/credentials/self-secrets.js

@@ -0,0 +1,138 @@
+// SELF-SHARED SECRETS — mint-on-first-use into the encrypted KV vault (OPE-408 step 3).
+//
+// A self-shared secret is one this deployment mints for and verifies against ITSELF: it has NO
+// external counterparty, so there is no reason an operator should ever have to choose or set a
+// value for it. Today: `OE_INTAKE_PAGE_SIGNING_KEY` (HMAC-signs the intake/reveal page tokens this
+// process both mints and verifies), `OE_SPAWN_DISPATCH_SECRET` (HMAC over the internal self-dispatch
+// hop), `OE_TRANSCRIPT_RELAY_SECRET` (HMAC over the internal transcript-relay hop). All three are
+// "never leaves the deployment" by their own module's doc comment — no human ever needs to read the
+// value back, which is what makes silent minting safe. (`OE_ADMIN_STATIC_TOKEN` is deliberately
+// NOT here — see the OPE-408 ticket comment: an operator must know that value to present it as a
+// bearer credential, so auto-minting it with no reveal path would make the door permanently unusable.)
+//
+// RESOLUTION ORDER (mirrors credentials/operator-secrets.ts's getOperatorSecret, minus its final
+// throw): a value already in the vault WINS; an env var of the same name is the announced-once
+// on-ramp (never promoted into the vault automatically — an operator who wants it off env moves it
+// with `oe secret set`, exactly like any other operator secret); neither ⇒ MINT a fresh
+// high-entropy value, store it, and return it. A vault READ (the stored-wins and env-on-ramp
+// branches) is MEMOISED PER PROCESS (the public pre-auth routes would otherwise pay a vault
+// round-trip on every request) — but a fresh MINT is deliberately NOT memoised (OPE-480): only
+// this process's OWN readback confirms what it just wrote, not what a concurrent racer's write did
+// after it (the vault is last-write-wins; there is no put-if-absent). Leaving a mint uncached means
+// the very next resolution in this process re-reads the vault instead of trusting its own mint, so
+// it converges on whoever actually won — self-healing the race at the cost of one extra round trip
+// after the first mint. The memo still costs one accepted thing: a rotation via `oe secret set`
+// reaches a warm process only at restart. There is no "not configured" outcome: a self-shared
+// secret has no operator step to skip, so the only way to be unavailable is for the vault itself to
+// be unavailable (OE_CREDENTIAL_ENCRYPTION_KEY absent/malformed) — fail-closed, identically to
+// every other consumer of that key.
+//
+// STORED UNDER THE `self:` NAMESPACE (reserved-refs.ts), never under the bare env-var name: that
+// keeps these refs refused by the OUTBOUND db broker (getSecretVia("db", "self:…") 404s just like
+// "hook:"/"oe-oauth:" do) — this is host-internal material, never something a config credential
+// could point an egress call at.
+import { randomBytes } from "node:crypto";
+import { encryptedKvVault } from "./kv-vault.js";
+import { credentialKeyArmed, CREDENTIAL_KEY_ENV } from "./db-broker.js";
+import { CredentialError } from "../access/credentials.js";
+import { SELF_SECRET_REF_NAMESPACE } from "./reserved-refs.js";
+const envOnrampWarned = new Set();
+/** Test seam: forget which names have already warned about the env on-ramp. */
+export function resetSelfSecretWarnings() {
+    envOnrampWarned.clear();
+}
+// Per-process MEMOISATION (OPE-408 reviewer finding 7). Four PUBLIC, unauthenticated routes call
+// getOrMintSelfSecret before they have verified anything about the caller — a vault round trip (and,
+// on this process's first request, a MINT) must not be something an anonymous hit can trigger on
+// every request. Caching a vault-READ result for the process's lifetime means only the FIRST request
+// that finds the value already stored pays for it; every request after reuses the in-memory value
+// with no I/O. Keyed by `name` only — correct because the vault is a process-wide singleton, not a
+// per-request choice, in every real caller. A caller that injects its OWN `deps.vault` (every test in
+// this tree that needs to prove a specific vault state) bypasses the cache entirely, so a test can
+// still delete/rewrite a row and see the effect immediately without reaching for a reset.
+//
+// A fresh MINT is deliberately excluded from this cache (OPE-480) — see resolveOrMint below.
+const resolvedCache = new Map();
+/** Test seam: forget cached resolutions — needed only by a test that resolves through the DEFAULT
+ *  vault (no `deps.vault` override) and then mutates the vault directly and expects the NEXT
+ *  resolution to observe it. */
+export function resetSelfSecretCache() {
+    resolvedCache.clear();
+}
+function noticeOnce(name, message) {
+    if (envOnrampWarned.has(name))
+        return;
+    envOnrampWarned.add(name);
+    console.warn(message);
+}
+/** Is the vault reachable for self-shared secrets at all? A cheap, SYNC predicate — every mount
+ *  predicate / "is this feature armed" check in the four consuming modules uses THIS, not an async
+ *  vault read, because minting never fails once the AES key is armed: "configured" reduces exactly
+ *  to "can I mint", and callers that also need a resolvable base URL AND this. */
+export function selfSecretsArmed() {
+    return credentialKeyArmed();
+}
+/**
+ * Resolve a self-shared secret by its env-var name, minting it on first use. See the module header
+ * for the resolution order. `name` doubles as the vault ref's suffix (`self:<name>`) — reversible,
+ * and namespaced so it can never collide with an operator-managed `db:`-homed credential.
+ */
+export async function getOrMintSelfSecret(name, deps = {}) {
+    if (!credentialKeyArmed()) {
+        throw new CredentialError(`"${name}" is a self-shared secret (minted and held by this deployment for itself) but ${CREDENTIAL_KEY_ENV} is not set ` +
+            `(or is not a base64-encoded 32-byte key) — refusing to read or mint it (fail closed). Set ${CREDENTIAL_KEY_ENV} to arm the ` +
+            `credential store.`);
+    }
+    // The default vault is memoised (see resolvedCache above); an injected one (tests only) is not.
+    if (!deps.vault) {
+        const cached = resolvedCache.get(name);
+        if (cached)
+            return cached;
+        const resolution = resolveOrMint(name, encryptedKvVault(), deps.env ?? process.env);
+        const promise = resolution.then((result) => result.value);
+        resolvedCache.set(name, promise);
+        // Never cache a rejection, and never cache a value THIS process just minted (OPE-480): a fresh
+        // mint reflects only what this process wrote, not what a concurrent racer's later write did (the
+        // vault is last-write-wins, no put-if-absent). Dropping it from the cache means the next
+        // resolution re-reads the vault instead of trusting the stale local mint, self-healing the race.
+        // Only guard against a stale delete: if a later call already replaced this entry, leave it alone.
+        resolution.then((result) => {
+            if (result.mintedFresh && resolvedCache.get(name) === promise)
+                resolvedCache.delete(name);
+        }, () => {
+            if (resolvedCache.get(name) === promise)
+                resolvedCache.delete(name);
+        });
+        return promise;
+    }
+    const result = await resolveOrMint(name, deps.vault, deps.env ?? process.env);
+    return result.value;
+}
+async function resolveOrMint(name, vault, env) {
+    const ref = `${SELF_SECRET_REF_NAMESPACE}${name}`;
+    // A per-process lock narrows the mint race to cross-process only (a rare, self-healing case for
+    // these HMAC secrets — see the module header on why a brief double-mint is within the tolerance
+    // this system already documents for signing-key rotation).
+    return vault.withLock(ref, async () => {
+        const stored = await vault.read(ref);
+        if (stored !== null)
+            return { value: stored, mintedFresh: false };
+        const fromEnv = (env[name] ?? "").trim();
+        if (fromEnv.length > 0) {
+            noticeOnce(name, `[open-everywhere:credentials] self-shared secret "${name}" resolved from the environment — the encrypted vault is its ` +
+                `default home. It will keep reading from the env var until you remove it (nothing here promotes it automatically).`);
+            return { value: fromEnv, mintedFresh: false };
+        }
+        const minted = randomBytes(32).toString("base64url");
+        await vault.write(ref, minted, { createdBy: "host:auto-mint" });
+        // Read back rather than trusting the local candidate. NOT put-if-absent: `vault.write` is a plain
+        // upsert (ON CONFLICT DO UPDATE — operational/postgres.ts), so this read-back does not guarantee
+        // convergence against a concurrent racer, only against ITSELF (confirms what landed, in case a
+        // racer's write happened to land after this one). Two cold processes minting at the same instant
+        // can briefly diverge — the caller marks this branch `mintedFresh` so the per-process memo above
+        // does not trust it past this one call; the NEXT resolution re-reads and converges (OPE-480).
+        const confirmed = await vault.read(ref);
+        return { value: confirmed ?? minted, mintedFresh: true };
+    });
+}
+//# sourceMappingURL=self-secrets.js.map

package/dist/agent/credentials/self-secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-secrets.js","sourceRoot":"","sources":["../../../agent/credentials/self-secrets.ts"],"names":[],"mappings":"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"}

package/dist/agent/credentials/warm.d.ts

@@ -0,0 +1,77 @@
+import type { BrokeredSecret } from "../access/credentials.js";
+import type { CredentialRefreshPosture } from "../access/connector-credentials.js";
+/** Re-mint this long before stated expiry, so a credential is never served so close to death that
+ *  it could expire mid-flight on a slow request. Per-spec overridable (`refreshMarginMs`) because
+ *  a 15-minute credential and a 30-day one do not want the same margin. */
+export declare const DEFAULT_REFRESH_MARGIN_MS: number;
+/**
+ * How a warm credential is minted and how loudly it fails.
+ *
+ * `Ctx` is whatever the mint needs that is only known at call time (an installation id, a repo, a
+ * resolved client id/secret pair). It is passed straight through to {@link mint} and to
+ * {@link key}; it never leaves the process and is never logged.
+ */
+export interface WarmCredentialSpec<Ctx> {
+    /** Stable identity for the console line and the audit detail, e.g. `"linear.app-actor"`. */
+    readonly name: string;
+    /** The audit row's `platform` column (`"linear"`, `"github"`, `"teams"`). */
+    readonly platform: string;
+    /**
+     * The dotted audit action appended on EVERY mint failure. Deployments query it
+     * (`GET /control/v1/audit?actions=<action>`), so it is part of the operator contract — changing
+     * one is a documented behaviour change, not a rename.
+     */
+    readonly auditAction: string;
+    /**
+     * The credential's refresh posture ({@link CredentialRefreshPosture}, access/providers.ts —
+     * the same vocabulary a `ConnectorCredential.lifecycle` declares).
+     *
+     * - `"re-mint"` — a fixed TTL with no refresh token: mint a fresh credential before expiry.
+     *   Every credential on this seam today is this one. Requires {@link fallbackTtlSeconds}.
+     * - `"manual-rotation"` — the credential does not expire on its own; a mint result with no
+     *   stated expiry is held for the life of the process.
+     * - `"refresh-token"` — REFUSED at construction (see the module header): it needs durable,
+     *   cross-process rotation, which a process-local memo cannot provide.
+     */
+    readonly refresh: CredentialRefreshPosture;
+    /** Override {@link DEFAULT_REFRESH_MARGIN_MS}. Must be ≥ 0. */
+    readonly refreshMarginMs?: number;
+    /**
+     * The TTL to assume when a `"re-mint"` mint response states no expiry — REQUIRED for that
+     * posture, because the alternative (hold a credential with an unknown deadline forever) is
+     * exactly the silent-staleness failure this seam exists to prevent. Use the vendor's documented
+     * lifetime.
+     */
+    readonly fallbackTtlSeconds?: number;
+    /**
+     * Cache key derived from the call-time context — one entry per key, each with its OWN
+     * single-flight. Omit when the deployment has exactly one such credential (Linear, Teams). The
+     * returned string lands in the failure audit row's `detail`, so it must carry NO secret material
+     * (GitHub's `"<installationId> <repo>"` is the intended shape).
+     */
+    readonly key?: (ctx: Ctx) => string;
+    /**
+     * The vendor call. MUST throw on any failure — network, non-2xx, malformed body, a 200 carrying
+     * no token — and MUST NOT return an empty or placeholder value; a falsy value is treated as a
+     * mint failure here for exactly that reason. Must never echo the credential (or the secret it
+     * was minted from) in its error message: that message is written to the audit row.
+     */
+    readonly mint: (ctx: Ctx) => Promise<BrokeredSecret>;
+}
+/** A held credential: `get` is the only path callers need. */
+export interface WarmCredential<Ctx> {
+    /** The current value — cached while fresh, minted (single-flight) when not. Rejects, loudly, if
+     *  the mint fails; NEVER resolves with an expired cached value. */
+    get(ctx: Ctx): Promise<string>;
+    /** The cached entry for `ctx`'s key, fresh or not (`undefined` when nothing is held). Diagnostic
+     *  only — reads the memo, never mints. */
+    peek(ctx: Ctx): BrokeredSecret | undefined;
+    /** Test seam: forget everything held. */
+    reset(): void;
+}
+/**
+ * Build a warm credential. Validates the spec EAGERLY (at wiring time, where a mistake is a
+ * startup error an author sees, not a 3am runtime surprise).
+ */
+export declare function warmCredential<Ctx = void>(spec: WarmCredentialSpec<Ctx>): WarmCredential<Ctx>;
+//# sourceMappingURL=warm.d.ts.map

package/dist/agent/credentials/warm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warm.d.ts","sourceRoot":"","sources":["../../../agent/credentials/warm.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAEnF;;2EAE2E;AAC3E,eAAO,MAAM,yBAAyB,QAAgB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,GAAG;IACrC,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACtD;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc,CAAC,GAAG;IACjC;uEACmE;IACnE,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B;8CAC0C;IAC1C,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,GAAG,SAAS,CAAC;IAC3C,yCAAyC;IACzC,KAAK,IAAI,IAAI,CAAC;CACf;AAUD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAG,IAAI,EAAE,IAAI,EAAE,kBAAkB,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,CA8E7F"}

package/dist/agent/credentials/warm.js

@@ -0,0 +1,136 @@
+// THE ALWAYS-WARM MINTED-CREDENTIAL SEAM (OPE-134). One place that holds a credential OE mints
+// for itself, keeps it ahead of its own expiry, and — the property that matters above all others —
+// fails LOUDLY when the mint breaks, never by quietly serving a token that has already died.
+//
+// WHY IT EXISTS. Three surfaces independently grew the same cache-a-minted-token machinery, and
+// they disagreed on exactly the things that decide whether a deployment goes silent at 3am:
+//
+//   surface                       memo   single-flight   refresh-ahead   LOUD on failure
+//   Linear `actor=app` (30d)      yes    yes             5 min           yes (audit row)
+//   GitHub installation (1h)      yes    NO              5 min           NO
+//   Teams Graph app-only (1h)     yes    NO              60 s            NO
+//
+// Two of the three could fail their mint on every single call and leave nothing durable behind:
+// the turn threw somewhere downstream, the operator saw a broken reply, and no audit row said
+// "the credential is dead". Unifying them is therefore not a tidiness exercise — it is how the
+// two quiet paths become as loud as the one that was already right (linear-credentials.ts, the
+// template this generalises).
+//
+// LIFETIME IS THE MISSING CONCEPT. The broker seam (access/credentials.ts `getSecretVia`) reads a
+// STORED secret: an env var, an encrypted row. It had no notion of expiry anywhere, because the
+// things it read do not expire. A minted credential is the opposite — its whole nature is a
+// deadline — and OE's rhythms span four orders of magnitude (Slack workflow token 15 min … GitHub
+// installation 1 h … Linear `actor=app` 30 d … Notion internal integration never). So the broker
+// seam grew {@link BrokeredSecret} — value + OPTIONAL `expiresAtMs` — and this module is the
+// consumer that acts on the deadline. One vocabulary, two halves: the broker says WHEN a secret
+// dies (stored secrets truthfully say "no stated expiry"); the warm seam decides when to re-mint.
+//
+// IN-PROCESS, DELIBERATELY. This is an in-process memo + single-flight, NOT the cross-process
+// row-claim the oe-oauth vault uses (credentials/kv-vault.ts, OPE-91). That pattern protects a
+// SHARED, durably-stored secret record. A minted credential is neither shared nor stored: it is a
+// disposable artifact any process can derive independently from the SAME client credentials, so two
+// cold-started serverless instances racing to mint is harmless — both mints succeed, each token is
+// used only inside the process that minted it, and there is no shared row to corrupt. In-process
+// single-flight exists only to stop ONE process's concurrent turns each kicking off a redundant
+// mint call.
+//
+// WHAT THIS SEAM DOES NOT DO. It does not implement the `refresh-token` posture (the OAuth refresh
+// dance against a stored refresh token). That posture needs durable storage and cross-process
+// rotation safety — the vault's job, not a memo's — so declaring it here THROWS AT CONSTRUCTION
+// rather than silently applying a re-mint rhythm to a credential that needs a different one.
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+/** Re-mint this long before stated expiry, so a credential is never served so close to death that
+ *  it could expire mid-flight on a slow request. Per-spec overridable (`refreshMarginMs`) because
+ *  a 15-minute credential and a 30-day one do not want the same margin. */
+export const DEFAULT_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+/** Stamp a mint result with a concrete deadline, applying the posture's fallback TTL when the
+ *  vendor stated none. A `"manual-rotation"` credential legitimately has no deadline. */
+function stamp(spec, minted, nowMs) {
+    if (minted.expiresAtMs !== undefined && Number.isFinite(minted.expiresAtMs))
+        return minted;
+    if (spec.refresh === "re-mint")
+        return { value: minted.value, expiresAtMs: nowMs + spec.fallbackTtlSeconds * 1000 };
+    return { value: minted.value };
+}
+/**
+ * Build a warm credential. Validates the spec EAGERLY (at wiring time, where a mistake is a
+ * startup error an author sees, not a 3am runtime surprise).
+ */
+export function warmCredential(spec) {
+    if (spec.refresh === "refresh-token") {
+        throw new Error(`warmCredential("${spec.name}"): the "refresh-token" posture is not served by this seam — an OAuth refresh ` +
+            `against a stored refresh token needs durable, cross-process rotation safety (credentials/kv-vault.ts), ` +
+            `not a process-local memo. Refusing to apply a re-mint rhythm to a credential that needs a different one.`);
+    }
+    if (spec.refresh === "re-mint" && !(typeof spec.fallbackTtlSeconds === "number" && spec.fallbackTtlSeconds > 0)) {
+        throw new Error(`warmCredential("${spec.name}"): a "re-mint" credential must declare fallbackTtlSeconds (the vendor's ` +
+            `documented lifetime) — without it, a mint response that omits its expiry would be held forever, which is ` +
+            `the silent-staleness failure this seam exists to prevent.`);
+    }
+    const margin = spec.refreshMarginMs ?? DEFAULT_REFRESH_MARGIN_MS;
+    if (!(Number.isFinite(margin) && margin >= 0)) {
+        throw new Error(`warmCredential("${spec.name}"): refreshMarginMs must be a non-negative number of milliseconds.`);
+    }
+    const held = new Map();
+    // One in-flight mint per key — concurrent callers await the SAME promise instead of each
+    // kicking off their own vendor call.
+    const inflight = new Map();
+    const keyOf = (ctx) => (spec.key ? spec.key(ctx) : "");
+    /** LOUD failure. The console line is the immediate operator-visible signal; the audit row is the
+     *  durable one, queryable long after the triggering turn's own logs have rotated out. The audit
+     *  write is best-effort (it must never mask the mint error with one of its own), and carries only
+     *  the mint's own message — which by contract never echoes credential material. */
+    async function auditMintFailure(key, message) {
+        console.error(`[open-everywhere:credentials] ${spec.name} mint failed${key ? ` (${key})` : ""}: ${message}`);
+        await appendAudit({
+            org: deploymentOrg(),
+            platform: spec.platform,
+            workspace: "unknown",
+            action: spec.auditAction,
+            detail: { credential: spec.name, ...(key ? { key } : {}), error: message.slice(0, 300) },
+        }).catch(() => undefined);
+    }
+    return {
+        async get(ctx) {
+            const key = keyOf(ctx);
+            const now = Date.now();
+            const cached = held.get(key);
+            // Serve the memo only while it is comfortably alive. A cached entry that has crossed the
+            // margin is NOT a fallback: if the re-mint below fails, this call fails.
+            if (cached && (cached.expiresAtMs === undefined || cached.expiresAtMs - margin > now))
+                return cached.value;
+            const flying = inflight.get(key);
+            if (flying)
+                return flying;
+            const mint = (async () => {
+                try {
+                    const minted = await spec.mint(ctx);
+                    if (!minted || typeof minted.value !== "string" || minted.value.length === 0) {
+                        throw new Error(`${spec.name} mint returned no credential value.`);
+                    }
+                    const stamped = stamp(spec, minted, Date.now());
+                    held.set(key, stamped);
+                    return stamped.value;
+                }
+                catch (err) {
+                    await auditMintFailure(key, err instanceof Error ? err.message : String(err));
+                    throw err;
+                }
+                finally {
+                    inflight.delete(key);
+                }
+            })();
+            inflight.set(key, mint);
+            return mint;
+        },
+        peek(ctx) {
+            return held.get(keyOf(ctx));
+        },
+        reset() {
+            held.clear();
+            inflight.clear();
+        },
+    };
+}
+//# sourceMappingURL=warm.js.map

package/dist/agent/credentials/warm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warm.js","sourceRoot":"","sources":["../../../agent/credentials/warm.ts"],"names":[],"mappings":"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"}

package/dist/agent/docs/approver-policy.d.ts

@@ -0,0 +1,70 @@
+/** One registered ActionKind, as the doc renders it. */
+export interface ApproverPolicyRow {
+    /** The registry key, e.g. `spend.set`. */
+    readonly kind: string;
+    /** The kind's runtime `ApproverPolicy` (approvals/types.ts owns the type; this module stays pure,
+     *  so it restates the two values rather than importing the approvals plane into a doc build). */
+    readonly policy: "admin" | "member";
+    /** The propose tool that freezes this kind's args, or undefined when no tool proposes it
+     *  (`session.checkpoint` is raised by the spend path, not by a verb). */
+    readonly proposedBy?: string;
+}
+/** One family of kinds the admin policy covers, and the word the manual uses for it. */
+export interface AdminKindFamily {
+    /** Kind-id prefix. */
+    readonly prefix: string;
+    /** The noun the "Who can click" rule must still use for this family. */
+    readonly noun: string;
+}
+/**
+ * THE ADMIN FAMILY. A kind takes the admin policy if and only if its id starts with one of these
+ * prefixes — the org config/spend mutations. Prefixes rather than a name list on purpose: a fifth
+ * spend or connector write is the same decision already made, while an admin kind in any OTHER
+ * family is a new decision and must be argued for in the prose before this gate will pass it.
+ *
+ * 🔴 KEYED ON THE KIND ID, so a kind named `spend.<anything>` satisfies the rule by its name. That
+ * is a real limit and a deliberate one: the alternative is a hand-kept name list, which is the
+ * maintained enumeration this whole gate exists to delete. The diff that adds such a kind is a diff
+ * to approvals/actions.ts, which is a protected path and is reviewed as one.
+ */
+export declare const ADMIN_KIND_FAMILIES: readonly AdminKindFamily[];
+export declare const APPROVER_POLICY_BEGIN = "<!-- BEGIN GENERATED: approver-policy (scripts/approver-policy-docs.ts) -->";
+export declare const APPROVER_POLICY_END = "<!-- END GENERATED: approver-policy -->";
+/** The two sentences the manual must still make. Matched literally: a reword forces the author to
+ *  this file, which is the point — see check 3 in the header. */
+export declare const ADMIN_RULE_ANCHOR = "**Admin kinds are the org config, spend and break-glass mutations**";
+export declare const MEMBER_RULE_ANCHOR = "**Every other kind is a member kind.**";
+/** Is this kind in the admin family the prose describes? */
+export declare function isAdminFamily(kind: string): boolean;
+/**
+ * Check the rows against the RULE the prose states, and against the shapes that would make this
+ * gate green by looking at nothing. Returns one problem string per violation, empty when clean.
+ *
+ * FAIL-CLOSED on an empty list: no rows would satisfy every rule below, which is a pass produced by
+ * blindness — the same posture consequence-lint takes on an empty registry.
+ */
+export declare function checkApproverPolicyRule(rows: readonly ApproverPolicyRow[]): string[];
+/**
+ * Check that the manual still STATES the rule the table is generated under — the half
+ * {@link checkApproverPolicyRule} cannot see. Both anchors must appear exactly once, in order, and
+ * the admin bullet between them must still name every family.
+ *
+ * Zero matches is a FAILURE, never a skip: a reworded anchor is how a prose gate decays into a green
+ * that checks nothing. More than one is a failure too, because a later fix could land on one copy.
+ */
+export declare function checkApproverPolicyProse(markdown: string): string[];
+/** Rows sorted by kind — the order the table renders in, and the order the check requires. */
+export declare function sortApproverPolicyRows(rows: readonly ApproverPolicyRow[]): ApproverPolicyRow[];
+/** The markdown table, marker comments included. Deterministic for a given row list. */
+export declare function renderApproverPolicyTable(rows: readonly ApproverPolicyRow[]): string;
+/**
+ * Replace the marked block in `markdown` with `table`. Returns the updated document, or a problem
+ * string when the markers are missing or inverted — a generator that appended its table to a
+ * document it could not find its own block in would write a second copy on every run.
+ */
+export declare function spliceApproverPolicyTable(markdown: string, table: string): {
+    readonly updated: string;
+} | {
+    readonly problem: string;
+};
+//# sourceMappingURL=approver-policy.d.ts.map

package/dist/agent/docs/approver-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approver-policy.d.ts","sourceRoot":"","sources":["../../../agent/docs/approver-policy.ts"],"names":[],"mappings":"AAsCA,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;qGACiG;IACjG,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC;6EACyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,eAAe,EAQzD,CAAC;AAKF,eAAO,MAAM,qBAAqB,gFAAQ,CAAC;AAC3C,eAAO,MAAM,mBAAmB,4CAAM,CAAC;AAEvC;iEACiE;AACjE,eAAO,MAAM,iBAAiB,wEAAwE,CAAC;AACvG,eAAO,MAAM,kBAAkB,2CAA2C,CAAC;AAE3E,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAaD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,EAAE,CAuCpF;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAwCnE;AAED,8FAA8F;AAC9F,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CAE9F;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAKpF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAWtI"}