@open-everywhere/core 0.1.0

package/dist/agent/credentials/config-pr.d.ts

@@ -0,0 +1,148 @@
+/** A commit author identity (name + email) for a bot-authored config commit. */
+export interface CommitIdentity {
+    readonly name: string;
+    readonly email: string;
+}
+/** One config file's text + its blob sha on a branch (the sha is required to UPDATE it). */
+export interface ConfigFileContent {
+    readonly content: string;
+    readonly sha: string;
+}
+/**
+ * One person's feedback on a config PR — a submitted review, or a comment on the PR's own thread.
+ * Read back by the Mode-1 learn loop, whose skill proposals ARE config PRs: a person's correction on
+ * a proposal feeds the next one (memory/dream/correction.ts).
+ *
+ * `authorAssociation` is the STANDING signal and the reason this shape is not the model-facing
+ * digest `scm/pr-feedback.ts` builds. That digest is bounded for context, mixes in CI output, and
+ * drops the association entirely — so it can say WHAT was written but not whether the writer has any
+ * standing in the repository, which is the only question the correction trust arm asks.
+ */
+export interface ConfigPrFeedback {
+    readonly kind: "review" | "comment";
+    /** The author's login. */
+    readonly author: string;
+    readonly body: string;
+    /** The provider's attested author standing (GitHub's `author_association`). */
+    readonly authorAssociation?: string;
+    /** True when the author is a machine account. */
+    readonly bot?: boolean;
+    /** A review's state (`CHANGES_REQUESTED`, `APPROVED`, …); absent on a thread comment. */
+    readonly state?: string;
+    /**
+     * When it was written (ISO-8601), so a caller can order reviews and comments AGAINST EACH OTHER.
+     * The two arrive from separate listings, so without this the only available order is "all of one
+     * kind, then all of the other" — and a caller that keeps the newest N then drops a whole kind.
+     * Optional: a provider that cannot report it leaves the caller on listing order.
+     */
+    readonly at?: string;
+}
+/** The outcome of opening / updating / reopening the deterministic-head config PR. */
+export interface ConfigPrOutcome {
+    /** The PR's web url. */
+    readonly url: string;
+    /** The PR number. */
+    readonly number: number;
+    /** True when the head already had a PR and this call updated it (rather than creating one). */
+    readonly updated: boolean;
+    /** True when a previously CLOSED PR on the head was reopened. */
+    readonly reopened: boolean;
+}
+/**
+ * The config-repo PR mechanism binding-pr.ts drives, one method per real operation it performs
+ * against the config repo (derived from the code, not invented): resolve a write credential, read
+ * the current custody overlay, cut/reuse a deterministic branch, commit the codemod bytes, and open
+ * (or update, or reopen) the PR. A GitHub implementation is the built-in default; a GitLab/Gitea
+ * self-hoster registers their own.
+ */
+export interface ConfigPrProvider {
+    /**
+     * Resolve a WRITE credential (token) for `repo` ("owner/repo"). CUSTODY-CRITICAL: this is the
+     * only place a config-repo write credential enters the flow. Throws (fail-loud) when no write
+     * credential is configured — a config PR must not silently no-op.
+     */
+    resolveWriteToken(repo: string): Promise<string>;
+    /** The bot commit identity used for the overlay commit. */
+    committer(): CommitIdentity;
+    /** The commit sha `branch` points at, or null when the branch doesn't exist. */
+    getBranchSha(args: {
+        repo: string;
+        branch: string;
+        token: string;
+    }): Promise<string | null>;
+    /** Create `branch` at `sha`. Idempotent — an already-existing branch is not an error. */
+    ensureBranch(args: {
+        repo: string;
+        branch: string;
+        sha: string;
+        token: string;
+    }): Promise<void>;
+    /** Read one file's text + sha on `branch`, or null when it doesn't exist. */
+    getFile(args: {
+        repo: string;
+        path: string;
+        branch: string;
+        token: string;
+    }): Promise<ConfigFileContent | null>;
+    /** Create or update one file on `branch` (pass the current `sha` to update an existing file). */
+    putFile(args: {
+        repo: string;
+        path: string;
+        content: string;
+        message: string;
+        branch: string;
+        token: string;
+        committer: CommitIdentity;
+        sha?: string;
+    }): Promise<void>;
+    /**
+     * Open the PR for the deterministic `head`, or — if one already exists — update it, reopening a
+     * CLOSED one (a re-propose on the same branch rather than dead-ending). Returns the outcome with
+     * `updated`/`reopened` flags the caller audits.
+     */
+    openOrReopenPr(args: {
+        repo: string;
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+        token: string;
+        /**
+         * Open the PR as a DRAFT — it exists, it is reviewable, and it cannot be merged until a human
+         * marks it ready. Absent/false is the ordinary PR the binding flow has always opened, so this
+         * is additive and changes no existing caller.
+         *
+         * Added for the Mode-3 last mile (OPE-619, memory/dream/mode3-last-mile.ts), which opens a
+         * REPRO PROPOSAL. Draft is the honest state for a machine-written proposal: the port carries
+         * no merge method at all, and draft says so on the pull request itself as well.
+         */
+        draft?: boolean;
+    }): Promise<ConfigPrOutcome>;
+    /**
+     * Read back the reviews and thread comments on one config PR, oldest first, with each author's
+     * attested standing. The learn loop's correction channel (memory/dream/skill-proposal-pr.ts) is
+     * the one caller.
+     *
+     * OPTIONAL, and the omission is honest rather than convenient: the binding-PR flow that defined
+     * this port never reads a PR back, so a self-hoster's registered GitLab/Gitea provider predates
+     * this method and would break if it were required. A provider without it simply carries no
+     * corrections forward, and the loop AUDITS that it could not read them — it never treats
+     * "unreadable" as "nobody objected".
+     */
+    listPrFeedback?(args: {
+        repo: string;
+        number: number;
+        token: string;
+    }): Promise<readonly ConfigPrFeedback[]>;
+}
+/**
+ * Register the config-PR provider (the app's choice of config-repo PR mechanism, wired at boot).
+ * The last registration wins — a self-host swaps the GitHub default for a GitLab/Gitea one here.
+ */
+export declare function registerConfigPrProvider(provider: ConfigPrProvider): void;
+/**
+ * The registered config-PR provider. Throws (fail-loud) when none is registered — a binding PR
+ * cannot proceed without a config-repo PR mechanism, and a silent skip would hide a misconfig.
+ */
+export declare function getConfigPrProvider(): ConfigPrProvider;
+//# sourceMappingURL=config-pr.d.ts.map

package/dist/agent/credentials/config-pr.d.ts.map

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

package/dist/agent/credentials/config-pr.js

@@ -0,0 +1,45 @@
+// ConfigPrProvider — the swap seam for the config-repo PR mechanism the credential-binding flow
+// (credentials/binding-pr.ts) rides (OPE-86 / R6). binding-pr opens a PR against the deployer-owned
+// config repo to re-stamp a credential's custody home; the GITHUB-specific machinery (write-token
+// resolution, branch/commit via the Contents+Refs API, PR open/update/reopen) used to be hardcoded
+// INSIDE binding-pr with no seam — the same closed-vendor shape the R1–R5 ports removed elsewhere,
+// on the credential-custody critical path. This port abstracts exactly the operations binding-pr
+// needs so a GitLab/Gitea self-hoster can register their own mechanism and NOT be excluded from
+// PR-governed bindings.
+//
+// LAYERING (mirrors memory/provider.ts + the connector-owned memory backings): core owns the PORT (this file) and the
+// orchestration (binding-pr.ts drives read → codemod → validate → audit → commit → PR); the GitHub
+// DEFAULT implementation lives in credentials/config-pr-github.ts and is registered at boot by the
+// app (agent/lib/register-adapters.ts, via the adapter-api barrel's registerGitHubConfigPrProvider) —
+// exactly like the github bundle's registerGitHubMemory. GitHub-over-fetch is portable (the whole scm/* layer is core,
+// vendor-SDK-free), so the default lives in core rather than packages/adapters; a self-hoster's
+// GitLab adapter would live in their own adapter package and register through the same barrel seam.
+//
+// CUSTODY: resolveWriteToken is on the credential-custody critical path — it mints/returns the WRITE
+// credential the config PR is authored with. The port carries ONLY repo coordinates + a resolved
+// token + references (branch/path/title/body); never a stored secret VALUE (the pasted key never
+// reaches this plane — see binding-pr.ts's header).
+// The single registered provider — the app wires the GitHub default at boot (register-adapters.ts).
+// `undefined` means "unregistered": getConfigPrProvider() then fails LOUD rather than silently
+// no-op'ing, exactly like the BlobPutter seam (blob/hosting.ts). Tests inject a fake provider
+// directly through binding-pr's deps and never touch this registry.
+let registered;
+/**
+ * Register the config-PR provider (the app's choice of config-repo PR mechanism, wired at boot).
+ * The last registration wins — a self-host swaps the GitHub default for a GitLab/Gitea one here.
+ */
+export function registerConfigPrProvider(provider) {
+    registered = provider;
+}
+/**
+ * The registered config-PR provider. Throws (fail-loud) when none is registered — a binding PR
+ * cannot proceed without a config-repo PR mechanism, and a silent skip would hide a misconfig.
+ */
+export function getConfigPrProvider() {
+    if (!registered) {
+        throw new Error("no ConfigPrProvider registered — the app must register a config-repo PR mechanism at boot " +
+            "(e.g. registerGitHubConfigPrProvider for GitHub, via agent/lib/register-adapters.ts).");
+    }
+    return registered;
+}
+//# sourceMappingURL=config-pr.js.map

package/dist/agent/credentials/config-pr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-pr.js","sourceRoot":"","sources":["../../../agent/credentials/config-pr.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,oGAAoG;AACpG,kGAAkG;AAClG,mGAAmG;AACnG,mGAAmG;AACnG,iGAAiG;AACjG,gGAAgG;AAChG,wBAAwB;AACxB,EAAE;AACF,sHAAsH;AACtH,mGAAmG;AACnG,mGAAmG;AACnG,sGAAsG;AACtG,uHAAuH;AACvH,gGAAgG;AAChG,oGAAoG;AACpG,EAAE;AACF,qGAAqG;AACrG,iGAAiG;AACjG,iGAAiG;AACjG,oDAAoD;AAqIpD,oGAAoG;AACpG,+FAA+F;AAC/F,8FAA8F;AAC9F,oEAAoE;AACpE,IAAI,UAAwC,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAA0B;IACjE,UAAU,GAAG,QAAQ,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACb,4FAA4F;YAC1F,uFAAuF,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/agent/credentials/db-broker.d.ts

@@ -0,0 +1,82 @@
+import { CREDENTIAL_UNRESOLVED, type CredentialBroker, type UnresolvedReason } from "../access/credentials.js";
+/** The registry name this broker registers under; a credential names it via `broker: "db"`. */
+export declare const DB_BROKER = "db";
+/** The env var holding the base64-encoded 32-byte AES-256-GCM key. Named in every fail-closed error. */
+export declare const CREDENTIAL_KEY_ENV = "OE_CREDENTIAL_ENCRYPTION_KEY";
+/**
+ * Is the AES key armed and well-formed? A pure PREDICATE over the same {@link loadKey} the crypto
+ * uses — so there is still exactly one place that decides what a valid key is. It exists so a caller
+ * can give the operator the fix sentence BEFORE attempting a store (operator-secrets.ts), and so the
+ * env-vs-db resolution order can refuse to fall back to an env var when a stored row exists but is
+ * unreadable. Never returns or logs the key.
+ */
+export declare function credentialKeyArmed(): boolean;
+/**
+ * Encrypt one plaintext secret into the opaque envelope `base64(iv ‖ tag ‖ ciphertext)`. A fresh
+ * random IV per call means the same plaintext stored twice produces different ciphertext (no
+ * equality leak). Never logs the plaintext OR the ciphertext.
+ */
+export declare function encryptCredential(plaintext: string): string;
+/**
+ * Decrypt an envelope produced by {@link encryptCredential}. Throws CredentialError on a malformed
+ * or tampered blob (GCM auth-tag mismatch → the value is NOT returned — fail closed). Never logs
+ * either the ciphertext or the recovered plaintext.
+ */
+export declare function decryptCredential(envelope: string): string;
+/** Input to the host-side write path — the ONLY way a value enters the store. */
+export interface StoreDbSecretInput {
+    /** The tenant the credential belongs to (the intake's org). */
+    readonly org: string;
+    /** The lookup key egress resolves through getSecret, e.g. `db:notion-<domain>-key`. */
+    readonly ref: string;
+    /** The plaintext value — encrypted immediately, never persisted or logged raw. */
+    readonly plaintext: string;
+    /** Connector label (audit/admin views only). */
+    readonly connector?: string;
+    /** Domain label (audit/admin views only). */
+    readonly domain?: string;
+    /** The storing principal (the intake requester). */
+    readonly createdBy: string;
+    /** ISO-8601 store time (defaults to now). */
+    readonly at?: string;
+}
+/**
+ * Host-side WRITE path — encrypt `plaintext` and upsert it under (org, ref). Called ONLY by the
+ * credential-intake webhook handler (agent/credentials/intake.ts), never exposed as an agent tool
+ * and never placed on the read-only CredentialBroker interface. FAIL CLOSED via {@link loadKey}: a
+ * missing/malformed key throws BEFORE anything is stored. The plaintext leaves this function only as
+ * ciphertext; it is never logged.
+ */
+export declare function storeDbSecret(input: StoreDbSecretInput): Promise<void>;
+/**
+ * The read broker. `getSecret(ref)` resolves a stored credential for the deployment org (the egress
+ * plane carries no org — it serves the single service identity, same posture as the env
+ * broker). Missing ref → a CredentialError matching the env broker's shape ("secret not found for
+ * ref ..."). FAIL CLOSED on a bad key (loadKey throws in decryptCredential). Never logs the value.
+ *
+ * RESERVED NAMESPACES ARE REFUSED FIRST (OPE-150), BEFORE ANY STORE READ. `stored_credential` holds
+ * two disjoint tenants — outbound credentials a human handed us, and secret material the HOST
+ * minted for itself (`hook:` inbound webhook signing secrets, `oe-oauth:` adapter tokens). The
+ * second class is read by the encrypted KV vault directly (credentials/kv-vault.ts, which holds the
+ * store handle and never comes through here); this broker is the OUTBOUND resolver, so a config
+ * declaring `broker:"db", secretRef:"hook:…"` must not be able to turn an INBOUND authentication
+ * key into something the egress plane can send to a third party. See credentials/reserved-refs.ts.
+ *
+ * 🔴 EVERY REFUSAL AUDITS ITSELF (OPE-639). The throw below is correct, but on its own it was
+ * INVISIBLE: consumers catch `CredentialError` and degrade quietly, which is the right availability
+ * posture and the wrong observability one. Notion's channel path is the measured case —
+ * `resolveNotionCredential` (notion-api.ts) turns the throw into `undefined`, the webhook acks 200
+ * with `action: "no-api-key"`, and the deployment says nothing at all. That is how the Notion path
+ * stayed dead for weeks. `deploy:census` proves a row EXISTS; nothing proved the deployment REACTS
+ * when one does not. So this broker writes {@link CREDENTIAL_UNRESOLVED} before it throws.
+ *
+ * THE VERDICT DOES NOT CHANGE — availability over integrity still holds. The row is an observation,
+ * the throw is the behaviour, and the audit write is best-effort: it can never be the reason a
+ * resolution fails differently than it did before.
+ */
+export declare function makeDbCredentialBroker(): CredentialBroker;
+export { CREDENTIAL_UNRESOLVED };
+export type { UnresolvedReason };
+/** Register the `db` broker under its canonical name. Call once at startup (register-adapters.ts). */
+export declare function registerDbCredentialBroker(): void;
+//# sourceMappingURL=db-broker.d.ts.map

package/dist/agent/credentials/db-broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-broker.d.ts","sourceRoot":"","sources":["../../../agent/credentials/db-broker.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAOlC,+FAA+F;AAC/F,eAAO,MAAM,SAAS,OAAO,CAAC;AAE9B,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,iCAAiC,CAAC;AAmCjE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAO5C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuB1D;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAgBzD;AAMD,OAAO,EAAE,qBAAqB,EAAE,CAAC;AACjC,YAAY,EAAE,gBAAgB,EAAE,CAAC;AA0BjC,sGAAsG;AACtG,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/agent/credentials/db-broker.js

@@ -0,0 +1,231 @@
+// The `db` credential broker (task #113) — a core, vendor-SDK-free CredentialBroker whose secret
+// store is our own operational DB (stored_credential). It is the self-host path between the env
+// broker (a secret per env var, set by the operator) and a managed vault (KMS/Vault): an org
+// member pastes an API key into a native Slack modal, the webhook encrypts it here, and egress
+// resolves it later through the SAME getSecretVia("db", ref) seam as every other broker — zero
+// resolver changes. It is REGISTERED (available) when its AES key is armed (register-adapters.ts);
+// a credential reaches it by naming `broker: "db"` — there is no global selection.
+//
+// SECURITY CONTRACT (the whole point):
+//   • The value is stored ENCRYPTED at rest — AES-256-GCM, node:crypto, key from
+//     OE_CREDENTIAL_ENCRYPTION_KEY (32-byte, base64). Random IV per record, auth tag stored.
+//   • FAIL CLOSED: with the key env absent or malformed, the broker refuses BOTH store and read —
+//     it never falls back to storing plaintext, and never returns a value it cannot authenticate.
+//   • The plaintext NEVER touches the model, a log, or audit detail. `encryptCredential` /
+//     `decryptCredential` are the only two functions that see it, and neither logs. The stored
+//     ciphertext is opaque even to the operational store (it holds a base64 blob).
+//   • The WRITE path (`storeDbSecret`) is a plain exported function, NOT on the CredentialBroker
+//     interface (which is read-only by design) — only the credential-intake webhook handler calls
+//     it. The model-facing egress plane only ever calls getSecret (read).
+import { randomBytes, createCipheriv, createDecipheriv } from "node:crypto";
+import { CredentialError, registerBroker, registeredBrokerNames, CREDENTIAL_UNRESOLVED, } from "../access/credentials.js";
+import { getOperationalStore } from "../operational/provider.js";
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { registerCredentialHome } from "./home.js";
+import { reservedRefNamespace, reservedRefRefusal } from "./reserved-refs.js";
+/** The registry name this broker registers under; a credential names it via `broker: "db"`. */
+export const DB_BROKER = "db";
+/** The env var holding the base64-encoded 32-byte AES-256-GCM key. Named in every fail-closed error. */
+export const CREDENTIAL_KEY_ENV = "OE_CREDENTIAL_ENCRYPTION_KEY";
+const KEY_BYTES = 32; // AES-256
+const IV_BYTES = 12; // GCM standard nonce length
+const TAG_BYTES = 16; // GCM auth tag length
+/**
+ * Load + validate the AES-256-GCM key from {@link CREDENTIAL_KEY_ENV}. FAIL CLOSED: an absent or
+ * non-32-byte key throws a CredentialError that NAMES the env (operator-facing) — the broker never
+ * proceeds to store plaintext or read an un-authenticatable value. Read fresh each call (cheap; no
+ * process-lifetime caching of key material beyond the env itself). The key VALUE is never logged.
+ */
+function loadKey() {
+    const raw = process.env[CREDENTIAL_KEY_ENV];
+    if (!raw) {
+        throw new CredentialError(`db credential broker: ${CREDENTIAL_KEY_ENV} is not set — refusing to store or read credentials ` +
+            `(fail closed). Set it to a base64-encoded 32-byte key.`);
+    }
+    let key;
+    try {
+        key = Buffer.from(raw, "base64");
+    }
+    catch {
+        throw new CredentialError(`db credential broker: ${CREDENTIAL_KEY_ENV} is not valid base64 — refusing (fail closed).`);
+    }
+    if (key.length !== KEY_BYTES) {
+        throw new CredentialError(`db credential broker: ${CREDENTIAL_KEY_ENV} decodes to ${key.length} bytes, need ${KEY_BYTES} ` +
+            `(a base64-encoded 32-byte AES-256 key) — refusing (fail closed).`);
+    }
+    return key;
+}
+/**
+ * Is the AES key armed and well-formed? A pure PREDICATE over the same {@link loadKey} the crypto
+ * uses — so there is still exactly one place that decides what a valid key is. It exists so a caller
+ * can give the operator the fix sentence BEFORE attempting a store (operator-secrets.ts), and so the
+ * env-vs-db resolution order can refuse to fall back to an env var when a stored row exists but is
+ * unreadable. Never returns or logs the key.
+ */
+export function credentialKeyArmed() {
+    try {
+        loadKey();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Encrypt one plaintext secret into the opaque envelope `base64(iv ‖ tag ‖ ciphertext)`. A fresh
+ * random IV per call means the same plaintext stored twice produces different ciphertext (no
+ * equality leak). Never logs the plaintext OR the ciphertext.
+ */
+export function encryptCredential(plaintext) {
+    const key = loadKey();
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, ct]).toString("base64");
+}
+/**
+ * Decrypt an envelope produced by {@link encryptCredential}. Throws CredentialError on a malformed
+ * or tampered blob (GCM auth-tag mismatch → the value is NOT returned — fail closed). Never logs
+ * either the ciphertext or the recovered plaintext.
+ */
+export function decryptCredential(envelope) {
+    const key = loadKey();
+    let buf;
+    try {
+        buf = Buffer.from(envelope, "base64");
+    }
+    catch {
+        throw new CredentialError("db credential broker: stored ciphertext is not valid base64 — refusing (fail closed).");
+    }
+    if (buf.length < IV_BYTES + TAG_BYTES) {
+        throw new CredentialError("db credential broker: stored ciphertext is truncated — refusing (fail closed).");
+    }
+    const iv = buf.subarray(0, IV_BYTES);
+    const tag = buf.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const ct = buf.subarray(IV_BYTES + TAG_BYTES);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+    }
+    catch {
+        // GCM final() throws on an auth-tag mismatch (wrong key, or tampered ciphertext) — surface it as
+        // a CredentialError, never the raw crypto error (which could hint at internals), and NEVER the value.
+        throw new CredentialError("db credential broker: ciphertext failed authentication (wrong key or tampered) — refusing (fail closed).");
+    }
+}
+/**
+ * Host-side WRITE path — encrypt `plaintext` and upsert it under (org, ref). Called ONLY by the
+ * credential-intake webhook handler (agent/credentials/intake.ts), never exposed as an agent tool
+ * and never placed on the read-only CredentialBroker interface. FAIL CLOSED via {@link loadKey}: a
+ * missing/malformed key throws BEFORE anything is stored. The plaintext leaves this function only as
+ * ciphertext; it is never logged.
+ */
+export async function storeDbSecret(input) {
+    const ciphertext = encryptCredential(input.plaintext); // throws (fail closed) if the key env is bad — before any store write
+    await getOperationalStore().putStoredCredential(input.org, {
+        ref: input.ref,
+        ciphertext,
+        ...(input.connector ? { connector: input.connector } : {}),
+        ...(input.domain ? { domain: input.domain } : {}),
+        createdBy: input.createdBy,
+        createdAt: input.at ?? new Date().toISOString(),
+    });
+}
+/**
+ * The read broker. `getSecret(ref)` resolves a stored credential for the deployment org (the egress
+ * plane carries no org — it serves the single service identity, same posture as the env
+ * broker). Missing ref → a CredentialError matching the env broker's shape ("secret not found for
+ * ref ..."). FAIL CLOSED on a bad key (loadKey throws in decryptCredential). Never logs the value.
+ *
+ * RESERVED NAMESPACES ARE REFUSED FIRST (OPE-150), BEFORE ANY STORE READ. `stored_credential` holds
+ * two disjoint tenants — outbound credentials a human handed us, and secret material the HOST
+ * minted for itself (`hook:` inbound webhook signing secrets, `oe-oauth:` adapter tokens). The
+ * second class is read by the encrypted KV vault directly (credentials/kv-vault.ts, which holds the
+ * store handle and never comes through here); this broker is the OUTBOUND resolver, so a config
+ * declaring `broker:"db", secretRef:"hook:…"` must not be able to turn an INBOUND authentication
+ * key into something the egress plane can send to a third party. See credentials/reserved-refs.ts.
+ *
+ * 🔴 EVERY REFUSAL AUDITS ITSELF (OPE-639). The throw below is correct, but on its own it was
+ * INVISIBLE: consumers catch `CredentialError` and degrade quietly, which is the right availability
+ * posture and the wrong observability one. Notion's channel path is the measured case —
+ * `resolveNotionCredential` (notion-api.ts) turns the throw into `undefined`, the webhook acks 200
+ * with `action: "no-api-key"`, and the deployment says nothing at all. That is how the Notion path
+ * stayed dead for weeks. `deploy:census` proves a row EXISTS; nothing proved the deployment REACTS
+ * when one does not. So this broker writes {@link CREDENTIAL_UNRESOLVED} before it throws.
+ *
+ * THE VERDICT DOES NOT CHANGE — availability over integrity still holds. The row is an observation,
+ * the throw is the behaviour, and the audit write is best-effort: it can never be the reason a
+ * resolution fails differently than it did before.
+ */
+export function makeDbCredentialBroker() {
+    return {
+        async getSecret(ref) {
+            const reserved = reservedRefNamespace(ref);
+            if (reserved) {
+                await auditUnresolved(ref, "reserved-namespace");
+                throw new CredentialError(reservedRefRefusal(ref, reserved));
+            }
+            const row = await getOperationalStore().getStoredCredential(deploymentOrg(), ref);
+            if (!row) {
+                await auditUnresolved(ref, "no-stored-row");
+                throw new CredentialError(`secret not found for ref "${ref}" (no stored credential — store one via the "Set API key" flow)`);
+            }
+            return decryptCredential(row.ciphertext);
+        },
+    };
+}
+// The audit action and the reason vocabulary are the BROKER SEAM's (access/credentials.ts), not this
+// broker's: OPE-776 added two more refusal classes one layer up, and one census / forensic read /
+// test must be able to ask for the same string whichever layer refused. Re-exported here so every
+// importer that already reads them from this module is unchanged.
+export { CREDENTIAL_UNRESOLVED };
+/**
+ * Record ONE unresolvable db credential ref. Best-effort and silent on failure — an audit write must
+ * never turn a clean refusal into a different one.
+ *
+ * 🔴 THE DETAIL CARRIES POINTERS, NEVER MATERIAL: the broker name, the ref, and a fixed reason
+ * string. No value, no length, no prefix, no hash, and no caught error text — a broker error is not
+ * ours to trust into an audit row. The ref is the whole point: it is what an operator needs to act
+ * ("store a row for db:notion:channel-key"), and it is a NAME, not a secret.
+ *
+ * `platform: "credential"` follows approvals/actions.ts `whereFromScope`: the platform column says
+ * what KIND of thing a row is about when no surface owns it, and `workspace` carries the identifier
+ * — here the broker. A ref that stays unresolvable writes a row per attempt on purpose. A repeated
+ * refusal is the signal, and its rate is what tells a dead path from a one-off.
+ */
+async function auditUnresolved(ref, reason) {
+    await appendAudit({
+        org: deploymentOrg(),
+        platform: "credential",
+        workspace: DB_BROKER,
+        action: CREDENTIAL_UNRESOLVED,
+        detail: { broker: DB_BROKER, ref, reason },
+    }).catch(() => undefined);
+}
+/** Register the `db` broker under its canonical name. Call once at startup (register-adapters.ts). */
+export function registerDbCredentialBroker() {
+    registerBroker(DB_BROKER, makeDbCredentialBroker());
+}
+// The `db` CredentialHome (R1) — the WRITE target the intake resolves for a `db:` ref. Registered at
+// module load (this module is value-imported wherever a db ref is stored), INDEPENDENT of the db
+// broker's registration: `store` writes via storeDbSecret (which needs only the AES key, not the
+// registered read broker), while `hostWriteAvailable` separately reflects whether the read broker is
+// armed — so the connector offer only advertises "Set API key" once the db broker is registered.
+registerCredentialHome({
+    name: DB_BROKER,
+    hostWriteAvailable: () => registeredBrokerNames().includes(DB_BROKER),
+    async store(input) {
+        await storeDbSecret({
+            org: input.org,
+            ref: input.ref,
+            plaintext: input.plaintext,
+            ...(input.connector ? { connector: input.connector } : {}),
+            ...(input.domain ? { domain: input.domain } : {}),
+            createdBy: input.createdBy,
+        });
+    },
+});
+//# sourceMappingURL=db-broker.js.map

package/dist/agent/credentials/db-broker.js.map

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

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

@@ -0,0 +1,51 @@
+/** The context a home's write needs. Vendor-neutral: `parsed` carries the RefCodec's structured
+ *  fields (parseCredentialRef result — e.g. a db home reads none) and `deps` is an opaque per-call DI
+ *  bag (the intake test seam) each home narrows for the one key it understands. */
+export interface CredentialHomeStoreInput {
+    /** The tenant the credential belongs to (the intake's org). */
+    readonly org: string;
+    /** The full stored ref (db:… / a vendor's) — the lookup key egress later resolves. */
+    readonly ref: string;
+    /** The pasted value — handed straight to the home's write path, NEVER logged/audited/held. */
+    readonly plaintext: string;
+    /** Connector label (audit/admin views only). */
+    readonly connector?: string;
+    /** Domain label (audit/admin views only). */
+    readonly domain?: string;
+    /** The storing principal (the intake requester). */
+    readonly createdBy: string;
+    /** The RefCodec's structured fields for `ref` (parseCredentialRef result, minus `home`). */
+    readonly parsed: Readonly<Record<string, string>>;
+    /** Per-call DI overrides (the intake test seam). Structurally typed so this module stays vendor-free;
+     *  each home narrows the one key it understands. */
+    readonly deps?: Readonly<Record<string, unknown>>;
+}
+/** A place a pasted work-surface secret can live, host-side. */
+export interface CredentialHome {
+    /** The home name — the RefCodec home the ref stamps (credentials/ref.ts DB_HOME, or a registered
+     *  vendor home). */
+    readonly name: string;
+    /** Can a pasted key be WRITTEN to this home host-side right now? Registration-gated: the connector
+     *  offer keys the "Set API key" option off ANY registered home returning true. (db: its broker is
+     *  registered; env: false — operator-only.) */
+    hostWriteAvailable(): boolean;
+    /** Store a pasted secret under this home. FAIL CLOSED (throw) if the home's backing layer is not
+     *  configured — NEVER silently redirect to another home (a value in the wrong custody home is the bug). */
+    store(input: CredentialHomeStoreInput): Promise<void>;
+}
+/** Register a credential home by name. Idempotent overwrite (last wins), mirroring registerBroker. */
+export declare function registerCredentialHome(home: CredentialHome): void;
+/** The registered home for `name`, or undefined when none is registered (the caller fails closed —
+ *  never a silent fallback to another home). */
+export declare function credentialHome(name: string): CredentialHome | undefined;
+/** Every registered home (the connector offer passes this to {@link hostWriteHomeAvailable}). */
+export declare function registeredCredentialHomes(): readonly CredentialHome[];
+/** Test seam: forget all registered homes. (No auto-restore — the core homes re-register on their
+ *  modules' next load; a single test file runs in its own process.) */
+export declare function resetCredentialHomes(): void;
+/** Is a host-write-capable HOME available among `homes` — can a pasted key be stored somewhere
+ *  host-side? True iff any home reports {@link CredentialHome.hostWriteAvailable}. The connector offer
+ *  passes {@link registeredCredentialHomes}; a bounded set is passed in tests. Fail closed (false) on
+ *  an empty set. */
+export declare function hostWriteHomeAvailable(homes: Iterable<CredentialHome>): boolean;
+//# sourceMappingURL=home.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"home.d.ts","sourceRoot":"","sources":["../../../agent/credentials/home.ts"],"names":[],"mappings":"AAcA;;mFAEmF;AACnF,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD;wDACoD;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B;wBACoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;mDAE+C;IAC/C,kBAAkB,IAAI,OAAO,CAAC;IAC9B;+GAC2G;IAC3G,KAAK,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAID,sGAAsG;AACtG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAEjE;AAED;gDACgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEvE;AAED,iGAAiG;AACjG,wBAAgB,yBAAyB,IAAI,SAAS,cAAc,EAAE,CAErE;AAED;uEACuE;AACvE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;oBAGoB;AACpB,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,OAAO,CAG/E"}

package/dist/agent/credentials/home.js

@@ -0,0 +1,43 @@
+// The CredentialHome registry (R1 — provider-agnostic credential homes) — WHERE a pasted work-surface
+// secret is WRITTEN, host-side, and whether ANY home can take one right now.
+//
+// The credential-intake webhook (credentials/intake.ts) used to hand-enumerate write homes by a closed
+// vendor branch, and the connector offer keyed its "Set API key" option off a per-vendor "armed"
+// signal. A CredentialHome instead REGISTERS one write target under a home name (the same name the
+// RefCodec stamps, credentials/ref.ts). Intake resolves `credentialHome(parsedRef.home).store(...)`;
+// the offer asks `hostWriteHomeAvailable(registeredCredentialHomes())`. A new vendor (ToolHive-class)
+// registers its home and BOTH paths route it — no edit to intake or the offer.
+//
+// This module is a PURE registry leaf: it holds no vendor logic and imports nothing. The core db home
+// registers from its OWN module (credentials/db-broker.ts), so a home's backing (the db AES key) lives
+// with the home.
+const HOMES = new Map();
+/** Register a credential home by name. Idempotent overwrite (last wins), mirroring registerBroker. */
+export function registerCredentialHome(home) {
+    HOMES.set(home.name, home);
+}
+/** The registered home for `name`, or undefined when none is registered (the caller fails closed —
+ *  never a silent fallback to another home). */
+export function credentialHome(name) {
+    return HOMES.get(name);
+}
+/** Every registered home (the connector offer passes this to {@link hostWriteHomeAvailable}). */
+export function registeredCredentialHomes() {
+    return [...HOMES.values()];
+}
+/** Test seam: forget all registered homes. (No auto-restore — the core homes re-register on their
+ *  modules' next load; a single test file runs in its own process.) */
+export function resetCredentialHomes() {
+    HOMES.clear();
+}
+/** Is a host-write-capable HOME available among `homes` — can a pasted key be stored somewhere
+ *  host-side? True iff any home reports {@link CredentialHome.hostWriteAvailable}. The connector offer
+ *  passes {@link registeredCredentialHomes}; a bounded set is passed in tests. Fail closed (false) on
+ *  an empty set. */
+export function hostWriteHomeAvailable(homes) {
+    for (const h of homes)
+        if (h.hostWriteAvailable())
+            return true;
+    return false;
+}
+//# sourceMappingURL=home.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"home.js","sourceRoot":"","sources":["../../../agent/credentials/home.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,6EAA6E;AAC7E,EAAE;AACF,uGAAuG;AACvG,iGAAiG;AACjG,mGAAmG;AACnG,qGAAqG;AACrG,sGAAsG;AACtG,+EAA+E;AAC/E,EAAE;AACF,sGAAsG;AACtG,uGAAuG;AACvG,iBAAiB;AAuCjB,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEhD,sGAAsG;AACtG,MAAM,UAAU,sBAAsB,CAAC,IAAoB;IACzD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;gDACgD;AAChD,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,yBAAyB;IACvC,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,oBAAoB;IAClC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;oBAGoB;AACpB,MAAM,UAAU,sBAAsB,CAAC,KAA+B;IACpE,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,IAAI,CAAC,CAAC,kBAAkB,EAAE;YAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,KAAK,CAAC;AACf,CAAC"}