@uuaid/pillar 0.2.0-alpha.9 → 2.0.2

package/src/blob/broker.mjs

@@ -0,0 +1,129 @@
+/**
+ * Blob challenge broker — single-use redemption tickets for blob transport.
+ *
+ * Flow: reserve (sender announces an upload) -> finalize (upload landed,
+ * challenge is armed) -> redeem (recipient burns it exactly once, and only
+ * after the registry-active sender key check passed).  A challenge that was
+ * never finalized, was already redeemed, or whose holder key is no longer
+ * active is refused — the redeem counter is the anti-replay guard.
+ *
+ * DEV/TEST ONLY. Production uses PillarBlobHttpClient with the UUAID broker;
+ * this in-memory implementation exists for deterministic local tests.
+ */
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { BlobBrokerError } from "./blob.mjs";
+
+export class InMemoryChallengeBroker {
+  constructor({ reserveTtlMs = 5 * 60 * 1000, now = () => Date.now() } = {}) {
+    this.reserveTtlMs = reserveTtlMs;
+    this.now = now;
+    this.challenges = new Map(); // challengeId -> record
+  }
+
+  /** Step 1: sender announces an upload; the challenge starts un-finalized. */
+  async reserve({ sender, recipient, size }) {
+    if (!sender) throw new BlobBrokerError("blob-broker-bad-request", "reserve: sender required");
+    if (!Number.isInteger(size) || size <= 0) throw new BlobBrokerError("blob-broker-bad-request", "reserve: size required");
+    const challengeId = `blob-ch-${this.now().toString(36)}-${randomBytes(8).toString("hex")}`;
+    this.challenges.set(challengeId, {
+      sender, recipient: recipient ?? null, size,
+      reservedAt: this.now(), expiresAt: this.now() + this.reserveTtlMs,
+      state: "reserved", object: null, hash: null, redeemedAt: null,
+    });
+    return { challengeId, expiresAt: this.now() + this.reserveTtlMs };
+  }
+
+  /** Step 2: the upload landed — arm the challenge for redemption. */
+  async finalize({ challengeId, object, hash, size }) {
+    const rec = this.challenges.get(challengeId);
+    if (!rec) throw new BlobBrokerError("blob-broker-not-found", `finalize: unknown challenge ${challengeId}`, 404);
+    if (rec.state !== "reserved") throw new BlobBrokerError("blob-broker-bad-state", `finalize: challenge is ${rec.state}`);
+    if (typeof object !== "string" || !object) throw new BlobBrokerError("blob-broker-bad-request", "finalize: object required");
+    if (typeof hash !== "string" || !/^[0-9a-f]{64}$/i.test(hash)) throw new BlobBrokerError("blob-broker-bad-request", "finalize: hash required");
+    if (!Number.isInteger(size) || size <= 0 || size !== rec.size) {
+      throw new BlobBrokerError("blob-broker-bad-request", `finalize: size ${size} != reserved ${rec.size}`);
+    }
+    rec.object = object; rec.hash = hash.toLowerCase(); rec.state = "finalized"; rec.finalizedAt = this.now();
+    return { challengeId, state: rec.state };
+  }
+
+  /** Step 3: single-use redemption.  Throws on replay, expiry, bad state. */
+  async redeem({ challengeId, object = null, hash = null, sender = null, now = null }) {
+    const rec = this.challenges.get(challengeId);
+    if (!rec) throw new BlobBrokerError("blob-broker-not-found", `redeem: unknown challenge ${challengeId}`, 404);
+    if (rec.state === "redeemed") {
+      throw new BlobBrokerError("blob-broker-already-redeemed", `challenge ${challengeId} already redeemed at ${rec.redeemedAt}`, 409);
+    }
+    if (rec.state !== "finalized") {
+      throw new BlobBrokerError("blob-broker-not-finalized", `challenge ${challengeId} never finalized (state ${rec.state})`, 409);
+    }
+    const t = now ?? this.now();
+    if (rec.expiresAt < t) {
+      throw new BlobBrokerError("blob-broker-expired", `challenge ${challengeId} expired at ${new Date(rec.expiresAt).toISOString()}`, 410);
+    }
+    if (object && object !== rec.object) throw new BlobBrokerError("blob-broker-mismatch", "redeem: object mismatch", 400);
+    if (hash && hash.toLowerCase() !== rec.hash) throw new BlobBrokerError("blob-broker-mismatch", "redeem: hash mismatch", 400);
+    if (sender && sender !== rec.sender) throw new BlobBrokerError("blob-broker-mismatch", "redeem: sender mismatch", 400);
+    rec.state = "redeemed"; rec.redeemedAt = t;
+    return { challengeId, redeemedAt: t, object: rec.object, sender: rec.sender };
+  }
+
+  /** Inspection only — never a substitute for redeem(). */
+  state(challengeId) { return this.challenges.get(challengeId) ?? null; }
+}
+
+/**
+ * Append-only JSONL journal on top of the in-memory broker.  The journal IS
+ * the persistence: construction replays it, so a CLI `put` in one process and
+ * `get` (redemption) in another share the same challenge ledger.
+ */
+export class JournalingBlobBroker extends InMemoryChallengeBroker {
+  constructor({ journalPath = null, ...rest } = {}) {
+    super(rest);
+    this.journalPath = journalPath;
+    this.journal = [];
+    if (journalPath && existsSync(journalPath)) this._replay(journalPath);
+  }
+  _replay(path) {
+    for (const line of readFileSync(path, "utf-8").split("\n")) {
+      if (!line.trim()) continue;
+      let e;
+      try { e = JSON.parse(line); } catch (_err) { continue; }
+      this.journal.push(e);
+      const cid = e.challengeId;
+      if (e.op === "reserve") {
+        this.challenges.set(cid, {
+          sender: e.sender, recipient: e.recipient ?? null, size: e.size,
+          reservedAt: e.at, expiresAt: e.expiresAt,
+          state: "reserved", object: null, hash: null, redeemedAt: null,
+        });
+      } else if (e.op === "finalize") {
+        const rec = this.challenges.get(cid);
+        if (rec) { rec.object = e.object; rec.hash = e.hash; rec.state = "finalized"; rec.finalizedAt = e.at; }
+      } else if (e.op === "redeem") {
+        const rec = this.challenges.get(cid);
+        if (rec) { rec.state = "redeemed"; rec.redeemedAt = e.at; }
+      }
+    }
+  }
+  async reserve(o) {
+    const r = await super.reserve(o);
+    this._log({ op: "reserve", challengeId: r.challengeId, sender: o.sender, recipient: o.recipient ?? null, size: o.size, expiresAt: r.expiresAt, at: this.now() });
+    return r;
+  }
+  async finalize(o) {
+    const r = await super.finalize(o);
+    this._log({ op: "finalize", challengeId: o.challengeId, object: o.object, hash: o.hash, at: this.now() });
+    return r;
+  }
+  async redeem(o) {
+    const r = await super.redeem(o);
+    this._log({ op: "redeem", challengeId: o.challengeId, sender: r.sender, at: r.redeemedAt });
+    return r;
+  }
+  _log(entry) {
+    this.journal.push(entry);
+    if (this.journalPath) appendFileSync(this.journalPath, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+  }
+}

package/src/blob/http.mjs

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import {
+  BlobBrokerError,
+  BlobExpiryError,
+  BlobFetchError,
+  BlobIntegrityError,
+  BlobNotFoundError,
+  BlobSenderKeyError,
+  BlobUploadError,
+  SELF_CERTIFIED_KEY_ID,
+  isSelfCertifiedUuaid,
+  senderSelfCertified,
+} from "./blob.mjs";
+import { REFUSAL_FIXES } from "../net/refusals.mjs";
+
+export const PILLAR_BLOB_AUDIENCE = "uuaid:pillar-blob:v1";
+export { SELF_CERTIFIED_KEY_ID };
+const KEY_ID_TTL_MS = 300_000;
+
+function payloadHash(payload) {
+  return `0x${createHash("sha256").update(jcs(payload)).digest("hex")}`;
+}
+
+function signedRequest(keychain, keyId, challenge, request) {
+  if (!keyId) throw new BlobBrokerError("blob-broker-key-id-required", "a presentation key id is required (registry badge key or self-certified:ed25519)");
+  const payload = { v: 1, audience: PILLAR_BLOB_AUDIENCE, challenge, request };
+  return {
+    payload,
+    payloadHash: payloadHash(payload),
+    signatures: [{
+      alg: "ed25519",
+      keyId,
+      publicKey: keychain._identity.publicKeyHex,
+      signature: keychain.sign(Buffer.from(jcs(payload), "utf-8")).toString("hex"),
+      created: new Date().toISOString(),
+    }],
+  };
+}
+
+/** `{ code, fix, body }` from a refusal body; empty for a non-JSON one (e.g. S3 XML). */
+async function refusalOf(response) {
+  const body = await response.json().catch(() => null);
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  return {
+    code: typeof body.code === "string" && body.code ? body.code : null,
+    fix: typeof body.fix === "string" && body.fix ? body.fix : null,
+    body,
+  };
+}
+
+/** Put the broker's code/fix on a typed error; its own code moves to legacyCode. */
+function withRefusal(error, { code = null, fix = null, body = null } = {}) {
+  if (code && code !== error.code) { error.legacyCode = error.code; error.code = code; }
+  if (fix) error.fix = fix;
+  if (body) error.body = body;
+  return error;
+}
+
+function safeBase(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" && parsed.hostname !== "127.0.0.1" && parsed.hostname !== "localhost") {
+    throw new BlobBrokerError("blob-broker-insecure-url", "blob broker must use HTTPS");
+  }
+  return parsed.href.replace(/\/+$/, "");
+}
+
+/**
+ * HTTP client for the UUAID broker. URLs are returned only to the live caller.
+ *
+ * `keyId` is optional. Given, it is presented as is. Omitted, the client
+ * resolves one per identity (resolveKeyId): the registry badge's key when a
+ * badge names this exact key, else "self-certified:ed25519" when the UUAID is
+ * exactly the key's uuaid:foundation:agent UUAID, else a `blob-key-unproven`
+ * refusal.
+ */
+/**
+ * The brokers this package talks to without being told, same list and order as
+ * @uuaid/pillar-client (hosts.ts BLOB_BROKERS). pillar-sfo runs broker 1.1.0,
+ * which also serves self-certified identities; api.uuaid.org serves registry
+ * badges only, so it is no longer the default (pass --broker to use it).
+ */
+export const BLOB_BROKERS = Object.freeze(["https://pillar-sfo.uuaid.org/blob", "https://pillar-nyc.uuaid.org/blob"]);
+export const DEFAULT_BLOB_BROKER = BLOB_BROKERS[0];
+
+export class PillarBlobHttpClient {
+  constructor({ baseUrl = DEFAULT_BLOB_BROKER, keychain, keyId = null, fetchImpl = globalThis.fetch, timeoutMs = 15_000 } = {}) {
+    if (!keychain?._identity) throw new BlobBrokerError("blob-broker-no-identity", "loaded keychain required");
+    if (typeof fetchImpl !== "function") throw new BlobBrokerError("blob-broker-no-fetch", "fetch implementation required");
+    this.baseUrl = safeBase(baseUrl);
+    this.keychain = keychain;
+    this.keyId = keyId || null;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this._trust = null;
+    this._resolvedKeyId = null;
+  }
+
+  async _json(path, { method = "POST", body } = {}) {
+    let response;
+    try {
+      response = await this.fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: body === undefined ? undefined : { "content-type": "application/json" },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      throw new BlobBrokerError("blob-broker-unreachable", `blob broker request failed: ${error.message}`);
+    }
+    const parsed = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const legacyCode = response.status === 404 ? "blob-broker-not-found"
+        : response.status === 410 ? "blob-broker-expired"
+          : response.status === 409 ? "blob-broker-replay"
+            : "blob-broker-rejected";
+      // The broker's own code + fix win; an older broker sends neither.
+      const brokerCode = typeof parsed?.code === "string" && parsed.code ? parsed.code : null;
+      const fix = typeof parsed?.fix === "string" && parsed.fix ? parsed.fix : null;
+      throw new BlobBrokerError(brokerCode ?? legacyCode, parsed?.error ?? `blob broker returned ${response.status}`, response.status, {
+        fix,
+        legacyCode,
+        body: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null,
+      });
+    }
+    return parsed;
+  }
+
+  /**
+   * The keyId this identity presents, strongest proof first:
+   *   1. the constructor's explicit `keyId`;
+   *   2. the registry badge's presentation keyId, when a fresh registry-signed
+   *      badge for this UUAID names this exact public key (badge limits);
+   *   3. "self-certified:ed25519", when this UUAID is exactly
+   *      `uuaid:foundation:agent:` + the key's local id (self-certified
+   *      limits; the full string, as the broker compares it);
+   * else throws `blob-key-unproven`. A badge that names another key, a
+   * missing badge and an unreachable registry all fall through to 3.
+   * Cached for 5 minutes.
+   */
+  async resolveKeyId() {
+    if (this.keyId) return this.keyId;
+    if (this._resolvedKeyId && this._resolvedKeyId.until > Date.now()) return this._resolvedKeyId.value;
+    const { uuaid, publicKeyHex } = this.keychain._identity;
+    let value = null;
+    let badgeProblem = "no registry badge names this key";
+    try {
+      const presentation = await this._verifiedPresentationKey(uuaid);
+      if (presentation && presentation.publicKey.toLowerCase() === publicKeyHex.toLowerCase()
+        && typeof presentation.keyId === "string" && presentation.keyId) {
+        value = presentation.keyId;
+      }
+    } catch (error) {
+      badgeProblem = `registry badge lookup failed (${error.code ?? error.message})`;
+    }
+    if (!value && isSelfCertifiedUuaid(uuaid, publicKeyHex)) value = SELF_CERTIFIED_KEY_ID;
+    if (!value) {
+      throw new BlobBrokerError(
+        "blob-key-unproven",
+        `${uuaid} cannot sign broker requests: ${badgeProblem}, and it is not the uuaid:foundation:agent UUAID derived from its key`,
+        null,
+        { fix: REFUSAL_FIXES["blob-key-unproven"] },
+      );
+    }
+    this._resolvedKeyId = { value, until: Date.now() + KEY_ID_TTL_MS };
+    return value;
+  }
+
+  challenge(action, objectId = null) {
+    return this._json("/pillar/blobs/challenge", {
+      body: {
+        action,
+        agent_uuaid: this.keychain._identity.uuaid,
+        ...(objectId ? { object_id: objectId } : {}),
+      },
+    }).then((body) => body.challenge);
+  }
+
+  async reserve(challenge, { recipient, ciphertextSha256, ciphertextBytes, expiresAt }) {
+    const keyId = await this.resolveKeyId();
+    return this._json("/pillar/blobs/reserve", {
+      body: signedRequest(this.keychain, keyId, challenge, {
+        action: "reserve",
+        agent_uuaid: this.keychain._identity.uuaid,
+        recipient_uuaid: recipient,
+        ciphertext_sha256: ciphertextSha256,
+        ciphertext_bytes: ciphertextBytes,
+        expires_at: expiresAt,
+      }),
+    });
+  }
+
+  async finalize(objectId) {
+    const keyId = await this.resolveKeyId();
+    const challenge = await this.challenge("finalize", objectId);
+    return this._json("/pillar/blobs/finalize", {
+      body: signedRequest(this.keychain, keyId, challenge, {
+        action: "finalize",
+        agent_uuaid: this.keychain._identity.uuaid,
+      }),
+    });
+  }
+
+  async redeem(objectId) {
+    const keyId = await this.resolveKeyId();
+    const challenge = await this.challenge("redeem", objectId);
+    return this._json("/pillar/blobs/redeem", {
+      body: signedRequest(this.keychain, keyId, challenge, {
+        action: "redeem",
+        agent_uuaid: this.keychain._identity.uuaid,
+      }),
+    });
+  }
+
+  async upload(ticket, ciphertext) {
+    let response;
+    try {
+      response = await this.fetch(ticket.url, {
+        method: "PUT",
+        headers: ticket.headers,
+        body: ciphertext,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      throw new BlobUploadError(`temporary blob upload failed: ${error.message}`, error);
+    }
+    if (!response.ok) {
+      const cause = new Error(`upload returned ${response.status}`);
+      throw withRefusal(new BlobUploadError(`temporary blob upload failed: ${cause.message}`, cause), await refusalOf(response));
+    }
+  }
+
+  async download(ticket) {
+    let response;
+    try {
+      response = await this.fetch(ticket.url, { signal: AbortSignal.timeout(this.timeoutMs) });
+    } catch (error) {
+      throw new BlobFetchError(`temporary blob download failed: ${error.message}`, error);
+    }
+    if (!response.ok) {
+      const error = response.status === 404 ? new BlobNotFoundError("temporary-object")
+        : response.status === 403 ? new BlobExpiryError("temporary blob download capability expired")
+          : new BlobFetchError(`temporary blob download returned ${response.status}`);
+      throw withRefusal(error, await refusalOf(response));
+    }
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  async _registryTrust() {
+    if (this._trust && this._trust.until > Date.now()) return this._trust.value;
+    const value = await this._json("/.well-known/uuaid-registry.json", { method: "GET" });
+    if (value.provisioned !== true || !Array.isArray(value.keys)) {
+      throw new BlobSenderKeyError("registry trust root is not provisioned", "unknown", "unprovisioned");
+    }
+    this._trust = { value, until: Date.now() + 300_000 };
+    return value;
+  }
+
+  /**
+   * The presentation key ({ alg, keyId, publicKey }) of a fresh badge for
+   * `uuaid` whose payload hash matches and whose ed25519 signature pins to a
+   * live key of the registry trust root; null when there is no badge (404)
+   * or it fails any of those checks. Other broker errors propagate.
+   */
+  async _verifiedPresentationKey(uuaid) {
+    let badge;
+    try {
+      badge = await this._json(`/iaaso/v1/badge/${encodeURIComponent(uuaid)}`, { method: "GET" });
+    } catch (error) {
+      if (error?.status === 404) return null;
+      throw error;
+    }
+    const trust = await this._registryTrust();
+    const presentation = badge?.payload?.subject?.presentationKey;
+    const subjectMatches = badge?.payload?.subject?.uuaid === uuaid
+      && presentation?.alg === "ed25519"
+      && typeof presentation?.publicKey === "string";
+    const fresh = Number.isFinite(Date.parse(badge?.payload?.freshUntil)) && Date.parse(badge.payload.freshUntil) > Date.now();
+    let hashMatches = false;
+    try { hashMatches = badge?.payloadHash === payloadHash(badge?.payload); } catch (_error) { hashMatches = false; }
+    const registrySignature = Array.isArray(badge?.signatures)
+      ? badge.signatures.find((signature) => {
+        if (signature.alg !== "ed25519") return false;
+        const pinned = trust.keys.find((key) => key.keyId === signature.keyId && key.alg === "ed25519" && key.retired !== true);
+        if (!pinned || pinned.publicKey.toLowerCase() !== signature.publicKey?.toLowerCase()) return false;
+        try {
+          return Keychain.verifyDetached(signature.publicKey, Buffer.from(jcs(badge.payload), "utf-8"), Buffer.from(signature.signature, "hex"));
+        } catch (_error) { return false; }
+      })
+      : null;
+    return subjectMatches && fresh && hashMatches && registrySignature ? presentation : null;
+  }
+
+  /**
+   * Fail closed unless a fresh registry-signed badge names this exact active
+   * key. The receive flows call this only for a sender whose UUAID does not
+   * derive from its signing key; see assertSenderKey.
+   */
+  async assertRegistryActiveSender(sender, expectedPublicKey) {
+    const presentation = await this._verifiedPresentationKey(sender);
+    const keyMatches = typeof expectedPublicKey === "string"
+      && presentation?.publicKey.toLowerCase() === expectedPublicKey.toLowerCase();
+    if (!keyMatches) {
+      throw new BlobSenderKeyError("sender presentation key is not registry-active", sender, "inactive");
+    }
+    return "active";
+  }
+
+  /**
+   * Recipient sender gate for a received blob-ref. "self-certified" when the
+   * ref's signature verifies and its sender is exactly that signing key's
+   * uuaid:foundation:agent UUAID (proven key holder, unverified identity);
+   * otherwise "active" when a registry badge names that key; otherwise
+   * throws BlobSenderKeyError (code sender-key-not-active, with a fix).
+   */
+  async assertSenderKey(ref) {
+    if (senderSelfCertified(ref)) return "self-certified";
+    return this.assertRegistryActiveSender(ref?.sender, ref?.sig?.publicKey);
+  }
+
+  crossCheckRedemption(ref, brokerRecord) {
+    if (
+      brokerRecord?.object_id !== ref.object ||
+      brokerRecord?.sender_uuaid !== ref.sender ||
+      brokerRecord?.recipient_uuaid !== ref.recipient ||
+      brokerRecord?.ciphertext_sha256 !== ref.hash ||
+      brokerRecord?.ciphertext_bytes !== ref.size ||
+      brokerRecord?.expires_at !== ref.expiry
+    ) {
+      throw new BlobIntegrityError("broker metadata does not match the signed blob-ref");
+    }
+  }
+}

package/src/blob/store.mjs

@@ -0,0 +1,55 @@
+/**
+ * Blob stores — where encrypted blob objects (ciphertext only) live while
+ * they wait to be redeemed.  Stores hold NO plaintext and NO key material:
+ * the DEK travels only inside the sealed envelope's blob-ref.
+ *
+ * Temporary-bucket semantics: objects are ephemeral; the blob-ref carries
+ * the expiry and the receive path re-checks it.  Stores SHOULD garbage-
+ * collect expired objects, but an object living past its expiry is inert —
+ * the ref is refused before any fetch result is trusted.
+ */
+import { mkdirSync } from "node:fs";
+import { readFile, writeFile, rm, access } from "node:fs/promises";
+import { join } from "node:path";
+import { BlobUploadError } from "./blob.mjs";
+
+export class MemoryBlobStore {
+  constructor() { this._map = new Map(); }
+  async put(object, buf) { this._map.set(object, Buffer.from(buf)); return { object, bytes: buf.length }; }
+  async get(object) { return this._map.get(object) ?? null; }
+  async has(object) { return this._map.has(object); }
+  async delete(object) { return this._map.delete(object); }
+  get size() { return this._map.size; }
+}
+
+export class FsBlobStore {
+  constructor({ dir }) {
+    if (!dir) throw new Error("FsBlobStore: dir required");
+    this.dir = dir;
+    this._ready = mkdirSync(dir, { recursive: true });
+  }
+  _path(object) {
+    // Object names are opaque 256-bit hex ids; encode defensively anyway.
+    return join(this.dir, encodeURIComponent(object));
+  }
+  async put(object, buf) {
+    try {
+      await writeFile(this._path(object), buf);
+      return { object, bytes: buf.length };
+    } catch (e) {
+      throw new BlobUploadError(`FsBlobStore write failed for ${object}: ${e.message}`, e);
+    }
+  }
+  async get(object) {
+    try { return await readFile(this._path(object)); }
+    catch (e) { if (e?.code === "ENOENT") return null; throw e; }
+  }
+  async has(object) {
+    try { await access(this._path(object)); return true; }
+    catch (_e) { return false; }
+  }
+  async delete(object) {
+    try { await rm(this._path(object), { force: true }); return true; }
+    catch (_e) { return false; }
+  }
+}

package/src/escrow/box.mjs

@@ -0,0 +1,43 @@
+/**
+ * Content box — symmetric AES-256-GCM under the escrowed 32-byte content
+ * key K.  The seller seals the deliverable with K and sends the box directly
+ * to the buyer; the escrow holds only K (and the sha256 of the plaintext, in
+ * the signed terms) — it never sees the payload.  The buyer can only open
+ * the box after K is released, and the GCM tag makes any tamper or wrong key
+ * fail loudly.
+ */
+import { randomBytes, createCipheriv, createDecipheriv, createHash } from "node:crypto";
+
+export const BOX_ALG = "aes-256-gcm";
+
+export function sealBox(key32, plaintext) {
+  if (!Buffer.isBuffer(key32) || key32.length !== 32) throw new Error("sealBox: key must be 32 bytes");
+  const iv = randomBytes(12);
+  const c = createCipheriv(BOX_ALG, key32, iv);
+  const ct = Buffer.concat([c.update(plaintext), c.final()]);
+  return {
+    alg: BOX_ALG,
+    iv: iv.toString("hex"),
+    ct: Buffer.concat([ct, c.getAuthTag()]).toString("hex"), // tag appended to ct
+  };
+}
+
+/** Throws on wrong key, tamper, or malformed box — never returns garbage. */
+export function openBox(key32, box) {
+  if (!Buffer.isBuffer(key32) || key32.length !== 32) throw new Error("openBox: key must be 32 bytes");
+  if (!box || box.alg !== BOX_ALG || typeof box.iv !== "string" || typeof box.ct !== "string") {
+    throw new Error("openBox: bad box");
+  }
+  const iv = Buffer.from(box.iv, "hex");
+  const buf = Buffer.from(box.ct, "hex");
+  if (iv.length !== 12 || buf.length < 16) throw new Error("openBox: bad lengths");
+  const ct = buf.subarray(0, buf.length - 16);
+  const tag = buf.subarray(buf.length - 16);
+  const d = createDecipheriv(BOX_ALG, key32, iv);
+  d.setAuthTag(tag);
+  return Buffer.concat([d.update(ct), d.final()]);
+}
+
+export function sha256Hex(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}