From 436f12edced20bca4b3dc8ccfef3d7fcd541c3b8 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 5 Sep 2026 00:27:24 +0200 Subject: [PATCH] provisioner: a provider consumes the mesh's credential, seals nothing (ADR 0053) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit runProvisioner now reconciles the mesh's `receives` contributions: for each consumer it reads the mesh-minted password from the file the host unsealed and calls the adapter to create the resource under the login the mesh derived. The adapter is create({as,password,values}) / remove({as}), returning nothing — the consumer already receives its copy through the mesh's own asymmetric channel. $MESH_SEAL_KEY, the symmetric seal()/writeSealedCredential path, and the *.grant.json / *.credential files are gone; the seal()/unseal() primitive had no other caller and was removed. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF --- src/primitives/index.ts | 40 +-------- src/provisioner/index.ts | 175 ++++++++++++++++++++++----------------- 2 files changed, 103 insertions(+), 112 deletions(-) diff --git a/src/primitives/index.ts b/src/primitives/index.ts index 5d6edd2..29fbf65 100644 --- a/src/primitives/index.ts +++ b/src/primitives/index.ts @@ -1,42 +1,10 @@ // Small, stable primitives every module's code may need. No behaviour here changes when a module // changes; that is the whole point of it living in the sdk. - -import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto"; - -// --- sealing --- // -// A secret is sealed to a key so a copy of it at rest is not a working credential. AES-256-GCM; -// the key is derived from a per-node passphrase the host holds. The host unseals on the machine; -// nothing else does (novox/hq ADR 0043's link is the boundary — the sdk only carries the mechanism). - -const MAGIC = "msk1"; // versions the sealed format, so it can change without silent misreads - -/** Seal plaintext to a passphrase. Returns `msk1::::`, base64 parts. */ -export function seal(plaintext: string, passphrase: string): string { - const salt = randomBytes(16); - const iv = randomBytes(12); - const key = scryptSync(passphrase, salt, 32); - const cipher = createCipheriv("aes-256-gcm", key, iv); - const enc = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]); - const tag = cipher.getAuthTag(); - return [MAGIC, b64(salt), b64(iv), b64(tag), b64(enc)].join(":"); -} - -/** Unseal what seal produced. Throws — loudly — on any tamper or wrong key. */ -export function unseal(sealed: string, passphrase: string): string { - const parts = sealed.split(":"); - if (parts.length !== 5 || parts[0] !== MAGIC) { - throw new Error("not a sealed value this version understands"); - } - const [, salt, iv, tag, enc] = parts.map((p, i) => (i === 0 ? Buffer.alloc(0) : ub64(p))); - const key = scryptSync(passphrase, salt, 32); - const decipher = createDecipheriv("aes-256-gcm", key, iv); - decipher.setAuthTag(tag); - return Buffer.concat([decipher.update(enc), decipher.final()]).toString("utf8"); -} - -const b64 = (b: Buffer): string => b.toString("base64url"); -const ub64 = (s: string): Buffer => Buffer.from(s, "base64url"); +// There was a symmetric seal()/unseal() here, for a provider to seal a credential to a key before +// writing it. It is gone: a provider is handed the credential the mesh minted and seals nothing +// (novox/hq ADR 0053), the mesh's own secret delivery is asymmetric and belongs to the host, and +// nothing else called it. The primitive left with the provisioner that was its only caller. // --- semver --- // diff --git a/src/provisioner/index.ts b/src/provisioner/index.ts index 2606bf4..f31a445 100644 --- a/src/provisioner/index.ts +++ b/src/provisioner/index.ts @@ -1,74 +1,109 @@ // The reconcile harness every provider shares. The loop below is identical for postgres, redis, -// minio and umami: read the grants the control plane has written, bring each requested resource to -// existence through the provider's adapter, seal and hand back the credential, and remove what is -// no longer requested. A module writes ONLY the adapter — the per-service half — which is why this -// lives in the sdk and the adapter lives in the module (novox/hq ADR 0044). +// minio and umami: read the contributions the mesh delivered, bring each consumer's resource into +// being through the provider's adapter under the login and password the mesh minted, and withdraw +// what the mesh no longer asks for. A module writes ONLY the adapter — the per-service half — which +// is why this lives in the sdk and the adapter lives in the module (novox/hq ADR 0044). +// +// **A provider creates the credential the mesh minted, and seals nothing (novox/hq ADR 0053).** The +// control plane mints one password per consumer and seals it to this node; the host unseals it into +// the file the contribution names. The provider does not generate a password, does not seal one, and +// does not hand one back — the consumer already receives its copy through the mesh's own channel. +// This is why the old $MESH_SEAL_KEY, the symmetric seal, and the *.grant.json / *.credential files +// are gone: they described a second, contradictory credential path the mesh does not have. -import { readdir, readFile, writeFile, rm } from "node:fs/promises"; -import { join } from "node:path"; -import type { Grant, Credential } from "../contracts/index.js"; -import { seal } from "../primitives/index.js"; +import { readFile } from "node:fs/promises"; -/** What a provider implements — the only per-service code. It is handed a Grant and creates (or - * removes) the resource in its own software, returning the credential a consumer receives. */ +/** One consumer's resource to bring into being — everything the mesh derived and delivered. */ +export interface Provision { + /** The login the mesh derived and gave the consumer to present. The provider creates exactly + * this name — a name the consumer cannot learn is a name it cannot authenticate with. */ + readonly as: string; + /** The password the mesh minted for this consumer, read from the file the mesh sealed to this + * node and the host unsealed. The provider sets it; it never invents one. */ + readonly password: string; + /** What the consumer contributed, per the interface's spec keys (e.g. `{ name: "umami" }`). */ + readonly values: Readonly>; + /** Where the consumer is, for a provider that must reach back to it. Usually unused. */ + readonly at?: string; + /** The consumer node, for logging and lifecycle events. */ + readonly consumer?: string; +} + +/** What a provider implements — the only per-service code. It is handed the login and password the + * mesh made and brings the resource into being under them, or withdraws it. It returns nothing: + * the credential is the mesh's, already delivered to the consumer. */ export interface Adapter { - create(grant: Grant): Promise; - remove(grant: Grant): Promise; + create(p: Provision): Promise; + remove(p: { readonly as: string }): Promise; } export interface ProvisionerOptions { - /** Directory the control plane writes grant requests into and the harness writes credentials to. - * Defaults to $GRANTS. */ - grants?: string; - /** Passphrase a credential is sealed to before it is written. Defaults to $MESH_SEAL_KEY. */ - sealKey?: string; + /** The contributions file the mesh writes for this resource (the module's `receives` path). + * Defaults to $MESH_RECEIVES. */ + receives?: string; /** Reconcile interval in ms. Defaults to 5000. */ everyMs?: number; } -export type { Grant, Credential }; +/** One entry in the mesh's contributions file: a consumer the provider must serve. */ +interface Contribution { + readonly as: string; + readonly secret: string; + readonly node?: string; + readonly at?: string; + readonly values?: Readonly>; +} /** * Run the reconcile loop for one provided resource. Returns a stop function. Never throws for a - * single bad grant — it logs and keeps converging, because one consumer's failure must not stop - * the others' provisioning. + * single bad contribution — it logs and keeps converging, because one consumer's failure must not + * stop the others' provisioning. */ export function runProvisioner(resource: string, adapter: Adapter, opts: ProvisionerOptions = {}): () => void { - const dir = opts.grants ?? envOrThrow("GRANTS"); - const sealKey = opts.sealKey ?? envOrThrow("MESH_SEAL_KEY"); + const receives = opts.receives ?? envOrThrow("MESH_RECEIVES"); const everyMs = opts.everyMs ?? 5000; - const applied = new Map(); // consumer -> hash of the grant last applied + const applied = new Map(); // login (`as`) -> hash of what was last applied let stopped = false; async function reconcile(): Promise { - const requested = await readGrants(dir, resource); - const wantById = new Map(requested.map((g) => [g.consumer, g])); + const given = await readContributions(receives, resource); + const wantByAs = new Map(given.map((g) => [g.as, g])); - // Create or update anything requested whose grant has changed. - for (const grant of requested) { - const h = hash(grant); - if (applied.get(grant.consumer) === h) continue; + // Create or update every consumer whose login, password or values changed. + for (const g of given) { + let password: string; try { - const cred = await adapter.create(grant); - await writeSealedCredential(dir, grant, cred, sealKey); - applied.set(grant.consumer, h); + // The file the mesh sealed to this node, unsealed by the host into plaintext. Trailing + // newline trimmed: a sealed value is exactly the secret, and a host writing a file may add + // one. + password = (await readFile(g.secret, "utf8")).replace(/\n$/, ""); } catch (err) { - console.error(`[provisioner:${resource}] ${grant.consumer}: create failed, will retry: ${err}`); + // The contribution names a secret the host has not written yet — a normal race on the + // first pass. Skipped, retried on the next tick, never fatal. + console.error(`[provisioner:${resource}] ${g.as}: secret not readable yet (${g.secret}): ${err}`); + continue; + } + const h = hash(g.as, password, g.values ?? {}); + if (applied.get(g.as) === h) continue; + try { + await adapter.create({ as: g.as, password, values: g.values ?? {}, at: g.at, consumer: g.node }); + applied.set(g.as, h); + } catch (err) { + console.error(`[provisioner:${resource}] ${g.as}: create failed, will retry: ${err}`); } } - // Remove anything applied that is no longer requested. Only the harness's own outputs are - // touched — the credential file it wrote — never anything it did not create. - for (const consumer of [...applied.keys()]) { - if (wantById.has(consumer)) continue; - const grant = lastGrant(dir, resource, consumer); + // Withdraw every login the provider made that the mesh no longer asks for. The mesh drops a + // consumer from the file when it goes away; that is how a login is withdrawn rather than kept + // working for ever. Only logins this harness created are touched. + for (const as of [...applied.keys()]) { + if (wantByAs.has(as)) continue; try { - await adapter.remove(grant); - await rm(credentialPath(dir, resource, consumer), { force: true }); - applied.delete(consumer); + await adapter.remove({ as }); + applied.delete(as); } catch (err) { - console.error(`[provisioner:${resource}] ${consumer}: remove failed, will retry: ${err}`); + console.error(`[provisioner:${resource}] ${as}: remove failed, will retry: ${err}`); } } } @@ -89,47 +124,35 @@ export function runProvisioner(resource: string, adapter: Adapter, opts: Provisi }; } -// --- grant/credential files --- - -async function readGrants(dir: string, resource: string): Promise { - let names: string[]; +/** + * Read the mesh's contributions file for one resource. Absent or empty means "no consumer asks for + * this" — the file is always written, so a provider can tell that from "the mesh never wrote it". + */ +async function readContributions(path: string, resource: string): Promise { + let raw: string; try { - names = await readdir(dir); + raw = await readFile(path, "utf8"); } catch { + return []; // not written yet, or nobody serves anything here — nothing to converge to + } + let doc: { requirement?: string; given?: Contribution[] }; + try { + doc = JSON.parse(raw) as { requirement?: string; given?: Contribution[] }; + } catch (err) { + console.error(`[provisioner:${resource}] contributions file is not JSON (${path}): ${err}`); return []; } - const out: Grant[] = []; - for (const name of names) { - if (!name.endsWith(".grant.json")) continue; - try { - const raw = await readFile(join(dir, name), "utf8"); - const g = JSON.parse(raw) as Grant; - if (g.resource === resource) out.push(g); - } catch (err) { - console.error(`[provisioner:${resource}] unreadable grant ${name}: ${err}`); - } + if (doc.requirement && doc.requirement !== resource) { + console.error(`[provisioner:${resource}] ${path} is for ${doc.requirement}, not ${resource}`); + return []; } - return out; + // A contribution with no `as` is not a credential grant (a module offering something on its own + // machine) — the provisioner has nothing to create for it. + return (doc.given ?? []).filter((g) => g.as && g.secret); } -function credentialPath(dir: string, resource: string, consumer: string): string { - return join(dir, `${consumer}.${resource}.credential`); -} - -async function writeSealedCredential(dir: string, grant: Grant, cred: Credential, key: string): Promise { - const body = JSON.stringify({ resource: grant.resource, consumer: grant.consumer, fields: cred.fields }); - await writeFile(credentialPath(dir, grant.resource, grant.consumer), seal(body, key), { mode: 0o600 }); -} - -function lastGrant(dir: string, resource: string, consumer: string): Grant { - // For removal the harness needs a Grant to hand the adapter; the identity is enough to act on. - return { resource, consumer, node: "", values: {} }; -} - -// --- helpers --- - -function hash(g: Grant): string { - return JSON.stringify([g.resource, g.consumer, g.node, g.values]); +function hash(as: string, password: string, values: Readonly>): string { + return JSON.stringify([as, password, values]); } function envOrThrow(name: string): string {