Feature 57 (config and provisioning): release mesh-sdk, the reviewed release branch on top of main

src/index.ts

@@ -1,13 +1,16 @@
 // @novox/mesh-sdk — the stable spine a module's own code builds against (novox/hq ADR 0039).
 //
-// Import the area you need directly (`@novox/mesh-sdk/tools`, `/provisioner`, …) or the whole
+// Import the area you need directly (`@novox/mesh-sdk/tools`, `/provider-loop`, …) or the whole
 // surface from here. Everything specific to one module — its API client, its tool implementations,
 // its create-a-resource adapter — lives in the module, never here.
 
 export * from "./contracts/index.js";
 export * as tools from "./tools/index.js";
-export * as provisioner from "./provisioner/index.js";
+export * as providerLoop from "./provider-loop/index.js";
+/** @deprecated The provider loop's name before design 57 (novox/hq issue 678): `providerLoop`. */
+export * as provisioner from "./provider-loop/index.js";
 export * as messaging from "./messaging/index.js";
 export * as events from "./events/index.js";
 export * as primitives from "./primitives/index.js";
 export * as state from "./state/index.js";
+export * as seal from "./seal/index.js";

src/provider-loop/index.ts

@@ -1,3 +1,13 @@
+// The provider loop: the reconcile harness every provider on the controller's grant files shares.
+// Called `provisioner` until design 57 (novox/hq issue 678): that word is mesh-provisioner's, which
+// places every value a module needs (ADR 0349), so the loop is named for what it is. The old path
+// `@novox/mesh-sdk/provisioner` and the names `runProvisioner`, `provisionerTools`, `Provisioner` and
+// `ProvisionerOptions` stay as aliases of these until the providers that import them move to the Go
+// helper that answers consumers over the bus (mesh-sdk go/provider, design 57 B2 and B3) and this loop
+// retires with the grant files. The events (`provisioner.failing`, `.recovered`, `.retirement`) and the
+// tool names (`provisioner_retirement`, …) are what the controller and the operator read on the bus,
+// and keep their names.
+//
 // The reconcile harness every provider shares. The loop below is identical for postgres, redis,
 // 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 retire
@@ -140,9 +150,9 @@ export interface Act {
   readonly via?: string;
 }
 
-/** The running provisioner: a stop function, as before, that also answers and takes the person's
+/** The running provider loop: a stop function, as before, that also answers and takes the person's
  *  acts on retirement (novox/hq ADR 0230). */
-export type Provisioner = (() => void) & {
+export type ProviderLoop = (() => void) & {
   retirement(): Promise<Retirement>;
   approve(consumers: readonly string[], act: Act): Promise<{ retired: string[] }>;
   reject(consumers: readonly string[], act: Act): Promise<{ kept: string[] }>;
@@ -167,7 +177,7 @@ export const CLASS_REFUSED = "refused";
 /** How long a consumer fails without one success before it is announced failing (ADR 0224). */
 export const FAILING_AFTER_MS = 5 * 60_000;
 
-export interface ProvisionerOptions {
+export interface ProviderLoopOptions {
   /** The contributions file the mesh writes for this resource (the module's `receives` path).
    *  Defaults to $MESH_RECEIVES. */
   receives?: string;
@@ -250,7 +260,7 @@ interface Contribution {
  * `retireFraction` of those held where more than one is held, is not retired without a person: the
  * provider waits for approve or reject. RETIRED → DELETED only through `provisioner_delete`.
  */
-export function runProvisioner(resource: string, adapter: Adapter, opts: ProvisionerOptions = {}): Provisioner {
+export function runProviderLoop(resource: string, adapter: Adapter, opts: ProviderLoopOptions = {}): ProviderLoop {
   const receives = opts.receives ?? envOrThrow("MESH_RECEIVES");
   const everyMs = opts.everyMs ?? 5000;
   const verifyEveryMs = opts.verifyEveryMs ?? 60_000;
@@ -757,8 +767,8 @@ export function runProvisioner(resource: string, adapter: Adapter, opts: Provisi
   const stop = () => {
     stopped = true;
   };
-  const handle: Provisioner = Object.assign(stop, { retirement, approve, reject, deleteRetired });
-  if (opts.module) registerModuleTools(opts.module, () => provisionerTools(handle));
+  const handle: ProviderLoop = Object.assign(stop, { retirement, approve, reject, deleteRetired });
+  if (opts.module) registerModuleTools(opts.module, () => providerLoopTools(handle));
   return handle;
 }
 
@@ -767,7 +777,7 @@ const text = (v: unknown): string => (typeof v === "string" ? v : "");
 
 /** The four tools every provider serves for retirement (novox/hq ADR 0230), the controller's `retire`
  *  and `cleanup` verbs asking them per machine. */
-export function provisionerTools(p: Provisioner): ToolDefinition[] {
+export function providerLoopTools(p: ProviderLoop): ToolDefinition[] {
   const act = { type: "string" };
   return [
     {
@@ -900,3 +910,12 @@ function envOrThrow(name: string): string {
   if (!v) throw new Error(`${name} is not set — the provisioner cannot run without it`);
   return v;
 }
+
+/** @deprecated The provider loop's name before design 57: {@link runProviderLoop}. */
+export const runProvisioner = runProviderLoop;
+/** @deprecated {@link providerLoopTools}. */
+export const provisionerTools = providerLoopTools;
+/** @deprecated {@link ProviderLoop}. */
+export type Provisioner = ProviderLoop;
+/** @deprecated {@link ProviderLoopOptions}. */
+export type ProvisionerOptions = ProviderLoopOptions;

src/seal/box.ts

@@ -0,0 +1,90 @@
+// The sealed box itself (novox/hq ADR 0183, ADR 0206), with its two sources of randomness as arguments so
+// the tests can prove it byte for byte against the Go package's vectors. Modules import `./index.js`.
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  createPrivateKey,
+  createPublicKey,
+  diffieHellman,
+  hkdfSync,
+  type KeyObject,
+} from "node:crypto";
+
+/** A value sealed to one recipient, as it travels in JSON; every field but `v` is standard base64. */
+export interface SealedBox {
+  readonly v: number;
+  /** The one-time public key, SPKI DER. */
+  readonly eph: string;
+  readonly iv: string;
+  readonly tag: string;
+  readonly ct: string;
+}
+
+/** The only box version `open` opens. */
+export const VERSION = 1;
+
+const INFO = "novox-mesh sealed box v1";
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+function x25519(key: KeyObject, what: string): KeyObject {
+  if (key.asymmetricKeyType !== "x25519") throw new Error(`not an X25519 ${what} key`);
+  return key;
+}
+
+export function publicFromPem(pem: string): KeyObject {
+  return x25519(createPublicKey({ key: pem, format: "pem" }), "public");
+}
+
+export function privateFromPem(pem: string): KeyObject {
+  return x25519(createPrivateKey({ key: pem, format: "pem" }), "private");
+}
+
+/** The recipient's raw 32-byte public key: the last 32 bytes of its SPKI DER. */
+function raw(pub: KeyObject): Buffer {
+  const der = pub.export({ format: "der", type: "spki" });
+  return der.subarray(der.length - 32);
+}
+
+function boxKey(secret: Buffer, ephDer: Buffer, recipientRaw: Buffer): Buffer {
+  return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([ephDer, recipientRaw]), INFO, 32));
+}
+
+/** `seal` with the one-time private key and the iv given. */
+export function sealWith(plaintext: string, recipientPem: string, eph: KeyObject, iv: Buffer): SealedBox {
+  const recipient = publicFromPem(recipientPem);
+  x25519(eph, "one-time");
+  if (iv.length !== IV_BYTES) throw new Error(`an iv of ${iv.length} bytes, not ${IV_BYTES}`);
+  const secret = diffieHellman({ privateKey: eph, publicKey: recipient });
+  const ephDer = createPublicKey(eph).export({ format: "der", type: "spki" });
+  const cipher = createCipheriv("aes-256-gcm", boxKey(secret, ephDer, raw(recipient)), iv);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  return {
+    v: VERSION,
+    eph: ephDer.toString("base64"),
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    ct: ct.toString("base64"),
+  };
+}
+
+/** Open a box with the recipient's PEM private key; throws for a box to another key, changed, or of another version. */
+export function open(box: SealedBox, privatePem: string): string {
+  if (box.v !== VERSION) throw new Error(`a sealed box of version ${box.v}, not ${VERSION}`);
+  const priv = privateFromPem(privatePem);
+  const ephDer = Buffer.from(box.eph, "base64");
+  const eph = x25519(createPublicKey({ key: ephDer, format: "der", type: "spki" }), "one-time");
+  const iv = Buffer.from(box.iv, "base64");
+  const tag = Buffer.from(box.tag, "base64");
+  // node accepts a shorter tag than 16 bytes; the box never has one, so a short one is refused here.
+  if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) throw new Error("the box does not open with this key");
+  const secret = diffieHellman({ privateKey: priv, publicKey: eph });
+  const decipher = createDecipheriv("aes-256-gcm", boxKey(secret, ephDer, raw(createPublicKey(priv))), iv);
+  decipher.setAuthTag(tag);
+  try {
+    return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
+  } catch {
+    throw new Error("the box does not open with this key");
+  }
+}

src/seal/index.ts

@@ -0,0 +1,29 @@
+// Sealing to one recipient (novox/hq ADR 0183, ADR 0206): X25519 for the agreement, HKDF-SHA256 for the
+// key, AES-256-GCM for the box. The TypeScript twin of the Go package `go/seal`, byte for byte: the same
+// fixtures prove both. A box is `{ v: 1, eph, iv, tag, ct }`; keys travel as PEM (SPKI public, PKCS #8
+// private).
+
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+import { sealWith, open, VERSION, type SealedBox } from "./box.js";
+
+export { open, VERSION, type SealedBox };
+
+/** A recipient's keypair as the two PEM strings it is kept and sent as. */
+export interface KeyPair {
+  readonly publicKey: string;
+  readonly privateKey: string;
+}
+
+/** A fresh X25519 keypair, PEM-encoded. */
+export function generateKeyPair(): KeyPair {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  return {
+    publicKey: publicKey.export({ format: "pem", type: "spki" }) as string,
+    privateKey: privateKey.export({ format: "pem", type: "pkcs8" }) as string,
+  };
+}
+
+/** Seal plaintext to the recipient's PEM public key, with a fresh one-time key and iv. */
+export function seal(plaintext: string, recipientPem: string): SealedBox {
+  return sealWith(plaintext, recipientPem, generateKeyPairSync("x25519").privateKey, randomBytes(12));
+}