@hadoku/dev-vault 0.0.0-stage → 1.5.0

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @wolffm/dev-vault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local-dev vault-broker shim for the hadoku ecosystem. Fetches secrets from the
+mgmt-api vault broker and execs a child command with them in `process.env` —
+the local-dev counterpart to the production PM2 wrappers.
+
+It execs **any** child command, so it works for Node repos (`vite`, etc.) and
+non-Node repos alike (e.g. a Python CLI). No `.env` files, ever — secret values
+live only in the spawned child's `process.env` and die with the process.
+
+## Why a package
+
+The shim used to live only inside the `hadoku_site` repo at
+`scripts/secrets/dev-vault.mjs`, so every child repo's `pnpm dev` hardcoded a
+`../hadoku_site/scripts/secrets/dev-vault.mjs` path and a contributor had to
+clone `hadoku_site` as a sibling just to reach the vault. Publishing it removes
+that coupling: a child repo depends on a versioned package, not a sibling repo.
+
+## Install (one-time, per machine)
+
+The package lives on GitHub Packages under the `@wolffm` scope. GitHub Packages
+requires auth even to read, so add to your `~/.npmrc`:
+
+```
+@wolffm:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=<a GitHub token with read:packages>
+```
+
+The `read:packages` token is a **bootstrap credential** — like `HADOKU_VAULT_KEY`,
+you receive it directly from the operator; it is _not_ fetched from the vault
+(that would be circular: you'd need the vault to install the tool that reaches
+the vault). See `hadoku_site/docs/operations/SECRETS.md` → "Bootstrap secrets".
+
+## Use
+
+```sh
+# Non-Node repo (e.g. hadoku-scraper) — npx, no install into the repo:
+npx @wolffm/dev-vault -- hs hopper migrate
+
+# Node repo — add as a devDependency, then `pnpm dev` is:
+dev-vault -- vite
+
+# Self-test — diagnoses mapping / broker / vault / per-key fetch / ACL drift:
+npx @wolffm/dev-vault --check
+```
+
+## Your own credential: `dev-vault login`
+
+If the operator gave you a service grant for this repo (command station →
+Account → Service grants), you hold your own credential rather than a copy of
+the repo's key:
+
+```sh
+npx @wolffm/dev-vault login
+```
+
+It prints a code and a hadoku.me link. Open the link signed in, set up your
+authenticator app the first time (a QR code), then approve with your passkey
+and a code from the app. The command writes `.devvault.local.json` (the main
+checkout's, in a worktree) and every later `dev-vault -- …` uses it.
+
+The credential lasts 7 days. dev-vault warns in its last day and refuses once
+it has expired; run `dev-vault login` again. Revoking your grant stops it at
+once, without touching anyone else's.
+
+## How it works
+
+1. Reads `.devvault.json` from the current working directory — a committed
+   file mapping env-var names → vault keys (no secret values in it).
+2. Reads the per-repo service-tier key from `.devvault.local.json`
+   (`{ "key": "<uuid>" }`, gitignored, `chmod 600`).
+3. Fetches each value from the broker: `MGMT_API_BASE` when set; otherwise
+   loopback (`http://127.0.0.1:4000`) when mgmt-api answers there within
+   300 ms — i.e. on the mgmt-api host itself — else `https://hadoku.me/mgmt`.
+   The `[dev-vault] caller=…` line names the broker it chose. The key is sent
+   either way; loopback reads are ACL-checked exactly like edge reads.
+4. Spawns the child command with the fetched values merged into `process.env`.
+
+## `NODE_AUTH_TOKEN` is derived, not fetched
+
+If the repo's `.devvault.json` declares `HADOKU_NPM_READ_TOKEN` and
+`NODE_AUTH_TOKEN` is not already set, dev-vault exports it into the child as
+well.
+
+That name is what a tokenless `~/.npmrc` expands
+(`//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}`) and what
+`actions/setup-node` writes in CI, so one npmrc serves both. Without it every
+`@wolffm/*` install fails:
+
+```
+ERR_PNPM_FETCH_401  GET .../@wolffm/<pkg> — Unauthorized
+No authorization header was set for the request.
+```
+
+Two details worth knowing:
+
+- **It is the `read:packages` token, never `HADOKU_SITE_TOKEN`.** That one is
+  repo/workflow-scoped; its `read:packages` was deliberately removed, so using
+  it authenticates and then 403s on every package — harder to diagnose than an
+  empty variable.
+- **An existing `NODE_AUTH_TOKEN` always wins**, so CI is unaffected.
+
+Derived rather than declared because a repo would otherwise need a vault item
+literally named `NODE_AUTH_TOKEN`, and there isn't one.
+
+Full setup and troubleshooting: `hadoku_site/docs/child-apps/USING_VAULT.md`.
+
+## In a git worktree
+
+dev-vault reads the MAIN checkout's `.devvault.local.json`, not a copy in the
+worktree. A key swap rewrites only the main checkout's file, so a copy goes
+stale at the next swap.
+A stale key does not 401: it resolves to `public`, and every read 403s like a
+missing ACL grant. Don't copy the file into a worktree; if one has a copy,
+delete it. The worktree's own file is used only when the main checkout has none.
+
+## Installation id
+
+Every broker call carries `X-Hadoku-Install`, a random id kept in
+`~/.config/hadoku/install-id` (one per machine and user), and a User-Agent
+naming the host. A key sent as a header never signs in, so this is what lets
+the edge alert when a key is first used from a new machine, including one on a
+network it already knows (edge-router `src/key-use.ts`). It identifies the
+installation and authenticates nothing; the edge stores only its digest. Under
+CI (`CI` or `GITHUB_ACTIONS`) none is sent, because a runner would be a new
+installation every job. Delete the file and the next run is a new installation.
+
+## Env overrides
+
+| Var             | Default                                         | Purpose               |
+| --------------- | ----------------------------------------------- | --------------------- |
+| `MGMT_API_BASE` | loopback if a broker answers, else the edge URL | Vault broker base URL |
+| `DEVVAULT_FILE` | `.devvault.json` (in cwd)                       | Mapping config path   |
+
+## Source of truth
+
+This package is the canonical implementation. `hadoku_site` ships a thin
+re-export at `scripts/secrets/dev-vault.mjs` so child repos that still hardcode
+the legacy `node ../hadoku_site/scripts/secrets/dev-vault.mjs` path keep working
+during migration.

package/broker-base.mjs

@@ -0,0 +1,81 @@
+/**
+ * Which vault broker dev-vault talks to.
+ *
+ * The broker is mgmt-api. Reached through the public edge
+ * (https://hadoku.me/mgmt) it costs a Cloudflare request, an edge-router auth
+ * lookup and a request_logs row per call — and on the host mgmt-api runs on,
+ * every one of those calls is the machine talking to itself. On 2026-10-10 a
+ * single systemd timer (hadoku-scraper's `hadoku-apply`, every ~5 minutes,
+ * ~30 keys per spawn) put ~7,000 such round trips a day through the edge
+ * (issue #463).
+ *
+ * So: an explicit MGMT_API_BASE always wins; otherwise use loopback when a
+ * broker answers there, and fall back to the edge everywhere else (a laptop,
+ * a claw, CI). The probe is the same unauthenticated `/api/secrets/status`
+ * call the pre-flight makes anyway, so its answer is handed back for reuse.
+ *
+ * Its own module, rather than inline in dev-vault.mjs, because dev-vault.mjs
+ * runs on import — this is the part a test can call.
+ */
+
+export const EDGE_BASE = 'https://hadoku.me/mgmt';
+export const LOOPBACK_BASE = 'http://127.0.0.1:4000';
+export const LOOPBACK_PROBE_TIMEOUT_MS = 300;
+
+/**
+ * Whether a `/api/secrets/status` body came from mgmt-api's vault broker.
+ *
+ * Port 4000 is not reserved for mgmt-api — any dev server can hold it on a
+ * laptop — so a bare 200 proves nothing. The broker's status payload always
+ * carries `success: true` and the boolean pair `sealed` / `unlocked`.
+ */
+export function isBrokerStatus(body) {
+	return (
+		body !== null &&
+		typeof body === 'object' &&
+		body.success === true &&
+		typeof body.sealed === 'boolean' &&
+		typeof body.unlocked === 'boolean'
+	);
+}
+
+/**
+ * Ask the loopback broker for its status.
+ *
+ * Returns the status body when a broker answered, `null` otherwise. `null` is
+ * the ordinary answer on every machine that is not the mgmt-api host
+ * (connection refused, or nothing answers inside the timeout), so a failure
+ * here is the RESULT, not an error to report: the caller falls back to the
+ * edge, where a real problem surfaces with the edge's own diagnostics.
+ */
+export async function probeLoopback(
+	base = LOOPBACK_BASE,
+	{ timeoutMs = LOOPBACK_PROBE_TIMEOUT_MS, fetchImpl = fetch } = {}
+) {
+	let res;
+	try {
+		res = await fetchImpl(`${base}/api/secrets/status`, {
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+	} catch {
+		return null; // refused / timed out: no broker on this host
+	}
+	if (res.status !== 200) return null;
+	const body = await res.json().catch(() => null);
+	return isBrokerStatus(body) ? body : null;
+}
+
+/**
+ * Pick the broker base.
+ *
+ * Returns `{ base, source, status }`:
+ *   - source `MGMT_API_BASE`: the caller set it; never probed, never second-guessed.
+ *   - source `loopback`: a broker answered on this host; `status` is its body.
+ *   - source `edge`: the default.
+ */
+export async function chooseBrokerBase({ override, probe = probeLoopback } = {}) {
+	if (override) return { base: override, source: 'MGMT_API_BASE', status: null };
+	const status = await probe(LOOPBACK_BASE);
+	if (status) return { base: LOOPBACK_BASE, source: 'loopback', status };
+	return { base: EDGE_BASE, source: 'edge', status: null };
+}

package/dev-vault.mjs

@@ -0,0 +1,545 @@
+#!/usr/bin/env node
+/**
+ * dev-vault — local-dev counterpart to the PM2 wrappers.
+ *
+ * Fetches secrets from the mgmt-api vault broker and execs a child
+ * command with them in process.env. Same model as services/pm2/lib/
+ * vault-fetch.mjs, but for `pnpm dev`-style local invocations from
+ * sibling repos.
+ *
+ * Published as @wolffm/dev-vault on GitHub Packages. Invoke it however
+ * suits the consuming repo — it execs ANY child command, so it works
+ * for Node and non-Node (e.g. Python CLI) repos alike:
+ *
+ *   npx @wolffm/dev-vault -- hs hopper migrate   # no install, any repo
+ *   dev-vault -- pnpm vite dev                   # installed as a devDependency
+ *   node ../hadoku_site/scripts/secrets/dev-vault.mjs --check   # legacy in-repo path
+ *
+ * Reads `.devvault.json` from the current working directory:
+ *
+ *   {
+ *     "// comment": "left-hand side = env var name the child reads",
+ *     "// comment": "right-hand side = vault key to fetch",
+ *     "QBIT_HOST": "SCRAPE_QBIT_HOST",
+ *     "QBIT_USERNAME": "SCRAPE_QBIT_USERNAME",
+ *     "GITHUB_TOKEN": "HADOKU_SITE_TOKEN"
+ *   }
+ *
+ * The .devvault.json file holds NO secret values — only a name-to-name
+ * mapping. Safe to commit. Secret values are fetched at runtime, live
+ * only in the spawned child's process.env, and die with the process.
+ *
+ * Comments (keys starting with "//") are ignored. Empty file or missing
+ * file means no secrets are fetched (still execs the child command).
+ *
+ * Modes:
+ *   login      put your own 7-day credential into this clone: prints a code
+ *              and a hadoku.me link, waits for you to approve it there with
+ *              your passkey and authenticator, then writes
+ *              .devvault.local.json (login.mjs). Needs a service grant.
+ *   --check    self-test: shows mapping, broker reachability, vault
+ *              status, per-key fetch result. Exits without spawning.
+ *   -- CMD ... runs CMD with vault env populated.
+ *
+ * Broker:
+ *   An explicit MGMT_API_BASE always wins. Otherwise dev-vault probes
+ *   http://127.0.0.1:4000/api/secrets/status (300 ms) and uses loopback when
+ *   mgmt-api's broker answers there — on the mgmt-api host itself, a call
+ *   through the edge is the machine talking to itself through Cloudflare
+ *   (issue #463). Everywhere else it falls back to https://hadoku.me/mgmt.
+ *
+ * Auth:
+ *   The vault broker traverses edge-router at https://hadoku.me/mgmt/*,
+ *   which admits service tier and above, resolved from the edge key
+ *   registry. Each repo needs its own per-repo service-tier key in
+ *   `<repo>/.devvault.local.json` of the
+ *   shape `{ "key": "<uuid>" }`. The file is gitignored. Mint via
+ *   `python ../hadoku_site/scripts/administration.py key-generate
+ *   --tier service --repo <path>` — that command writes the local file
+ *   and grants the ACL rows for declared vault keys in one shot. See
+ *   ../operations/SECRETS.md "Bootstrap secrets".
+ *
+ * Env overrides:
+ *   MGMT_API_BASE   vault broker base URL (default: loopback when a broker
+ *                   answers on this host, else https://hadoku.me/mgmt)
+ *   DEVVAULT_FILE   config path (default: .devvault.json in cwd)
+ *
+ * Exit codes:
+ *    0  ok / child exited 0
+ *    1  fetch / spawn failure (broker unreachable, vault sealed,
+ *       missing key, child failed to spawn)
+ *    2  usage error (no command after --, malformed config)
+ *    N  whatever the child process exited with
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { chooseBrokerBase } from './broker-base.mjs';
+import { resolveKeyFile } from './key-file.mjs';
+import { INSTALL_HEADER, installId, userAgent } from './install-id.mjs';
+import { credentialState, login } from './login.mjs';
+
+// `dev-vault login` needs no key and no broker: it is how a key arrives.
+if (process.argv[2] === 'login') process.exit(await login());
+
+const BROKER = await chooseBrokerBase({ override: process.env.MGMT_API_BASE });
+const MGMT_API_BASE = BROKER.base;
+const CONFIG_PATH = resolve(process.cwd(), process.env.DEVVAULT_FILE || '.devvault.json');
+// In a linked worktree this is the MAIN checkout's file (key-file.mjs).
+const LOCAL_KEY_PATH = resolveKeyFile(process.cwd());
+const UNLOCK_URL = `${MGMT_API_BASE}/api/secrets/admin/unlock`;
+
+// Per-repo service-tier key: each sibling repo carries its own UUID in
+// .devvault.local.json (gitignored, mode 0600) of the shape { "key": "<uuid>" }.
+// There is no env-var fallback — the local file is the single source of truth
+// so the ACL grants tracked server-side always match the key being used here.
+function loadLocalKey() {
+	if (!existsSync(LOCAL_KEY_PATH)) return { key: '', raw: null };
+	try {
+		const raw = JSON.parse(readFileSync(LOCAL_KEY_PATH, 'utf-8'));
+		if (raw && typeof raw === 'object' && typeof raw.key === 'string') {
+			return { key: raw.key.trim(), raw };
+		}
+		return { key: '', raw: null };
+	} catch {
+		return { key: '', raw: null };
+	}
+}
+const LOCAL = loadLocalKey();
+const VAULT_KEY = LOCAL.key;
+
+// A credential from `dev-vault login` lives 7 days. An expired one would
+// authenticate as nobody and every read would 404 or 403 like a missing
+// grant, so say what it is instead.
+const KEY_STATE = credentialState(LOCAL.raw);
+if (KEY_STATE === 'expired') {
+	console.error(
+		`[dev-vault] your credential expired ${new Date(LOCAL.raw.expiresAt).toLocaleString()}.`
+	);
+	console.error('[dev-vault]   run: dev-vault login');
+	process.exit(1);
+}
+if (KEY_STATE === 'expiring') {
+	console.error(
+		`[dev-vault] your credential expires ${new Date(LOCAL.raw.expiresAt).toLocaleString()}; ` +
+			'run `dev-vault login` to renew it.'
+	);
+}
+// VIA_EDGE: requests cross edge-router, which 404s (not 401s) a rejected key —
+// that is what the 404 disambiguation below keys on.
+const VIA_EDGE = /\/mgmt\b/.test(MGMT_API_BASE) && !MGMT_API_BASE.includes('localhost');
+// An auto-selected loopback still needs the key: requireKeyAccess checks the
+// per-key ACL by X-User-Key on loopback too. Without an override the key was
+// always required, and choosing loopback must not change that.
+const KEY_REQUIRED = VIA_EDGE || BROKER.source === 'loopback';
+
+if (KEY_REQUIRED && !VAULT_KEY) {
+	console.error('[dev-vault] error: no service-tier key found.');
+	console.error(`[dev-vault]   broker: ${MGMT_API_BASE}`);
+	console.error(`[dev-vault]   expected file: ${LOCAL_KEY_PATH}`);
+	console.error('[dev-vault]');
+	console.error(
+		"[dev-vault]   in a worktree, the main checkout's file is read; it has none either."
+	);
+	console.error('[dev-vault]   a person with a service grant for this repo: run  dev-vault login');
+	console.error('[dev-vault]   otherwise the operator mints the repo key, which writes the file:');
+	console.error('[dev-vault]     python3 ../hadoku_site/scripts/administration.py \\');
+	console.error('[dev-vault]       key-generate --tier service --repo <this-repo-path> \\');
+	console.error('[dev-vault]       --name <repo>-service-key --confirm');
+	console.error('[dev-vault]   See ../hadoku_site/docs/child-apps/USING_VAULT.md');
+	process.exit(1);
+}
+
+const { version: VERSION } = JSON.parse(
+	readFileSync(new URL('./package.json', import.meta.url), 'utf8')
+);
+// Who is calling, for the edge's key-use alert (install-id.mjs). Sent only
+// with the key: without one there is no identity to attribute it to.
+const INSTALL_ID = VAULT_KEY ? installId() : null;
+
+function authHeaders() {
+	if (!VAULT_KEY) return {};
+	return {
+		'X-User-Key': VAULT_KEY,
+		'User-Agent': userAgent(VERSION),
+		...(INSTALL_ID ? { [INSTALL_HEADER]: INSTALL_ID } : {}),
+	};
+}
+
+const argv = process.argv.slice(2);
+
+// `--` separates dev-vault's own flags from the child command. Anything
+// after `--` belongs to the child (which often has its own `-c` / `--check`)
+// and must not be parsed as a shim flag — see e.g. `-- sh -c '…'`, which
+// previously short-circuited to doctor mode because of a naive `argv.includes`.
+const sepIdx = argv.indexOf('--');
+const shimArgs = sepIdx === -1 ? argv : argv.slice(0, sepIdx);
+
+// ─── --check mode: self-test ─────────────────────────────────────────────
+if (shimArgs.includes('--check') || shimArgs.includes('-c')) {
+	await runDoctor();
+	process.exit(0);
+}
+
+// ─── Normal mode: -- separator splits shim args from child command ───────
+if (sepIdx === -1) {
+	printUsage();
+	process.exit(2);
+}
+const childCmd = argv.slice(sepIdx + 1);
+if (childCmd.length === 0) {
+	console.error('[dev-vault] error: missing command after `--`');
+	console.error('[dev-vault]');
+	printUsage();
+	process.exit(2);
+}
+
+// ─── Read .devvault.json mapping ────────────────────────────────────────
+let mapping;
+try {
+	mapping = readMapping(CONFIG_PATH);
+} catch (err) {
+	console.error(`[dev-vault] error: ${err.message}`);
+	console.error(`[dev-vault]   path: ${CONFIG_PATH}`);
+	console.error('[dev-vault]   the file should be JSON of the shape:');
+	console.error('[dev-vault]     { "ENV_VAR_NAME": "VAULT_KEY_NAME", ... }');
+	process.exit(2);
+}
+if (mapping === null) {
+	console.warn(`[dev-vault] no ${CONFIG_PATH} found — running child with no vault env`);
+	console.warn('[dev-vault]   if this child needs vault values, create the file:');
+	console.warn(`[dev-vault]     echo '{}' > ${CONFIG_PATH}`);
+	mapping = {};
+}
+
+// ─── Pre-flight: broker reachability + unlock state ─────────────────────
+let status = BROKER.status;
+try {
+	status ??= await fetchStatus();
+} catch (err) {
+	console.error(`[dev-vault] error: cannot reach broker at ${MGMT_API_BASE}`);
+	console.error(`[dev-vault]   ${err.message}`);
+	console.error('[dev-vault]   is mgmt-api running and the tunnel up?');
+	console.error(`[dev-vault]   override the URL with:  MGMT_API_BASE=<url> pnpm dev`);
+	process.exit(1);
+}
+if (!status.unlocked) {
+	console.error('[dev-vault] error: vault is sealed');
+	console.error(`[dev-vault]   unlock at:  ${UNLOCK_URL}`);
+	console.error('[dev-vault]   (operator unlocks once with master password + TOTP;');
+	console.error('[dev-vault]    after that the broker is open behind the tunnel)');
+	process.exit(1);
+}
+
+// ─── Fetch every requested key ─────────────────────────────────────────
+const fetched = {};
+const errors = [];
+for (const [envName, vaultKey] of Object.entries(mapping)) {
+	try {
+		fetched[envName] = await fetchKey(vaultKey);
+	} catch (err) {
+		errors.push({ envName, vaultKey, err: err.message });
+	}
+}
+
+if (errors.length > 0) {
+	const allDenied = errors.every((e) => /HTTP 403 access denied/.test(e.err));
+	console.error('[dev-vault] error: missing or unfetchable keys:');
+	for (const e of errors) {
+		console.error(`[dev-vault]   ${e.envName} → ${e.vaultKey}: ${e.err}`);
+	}
+	console.error('[dev-vault]');
+	if (allDenied) {
+		// All 403s → key exists in vault but caller lacks per-key ACL grant.
+		// Remediate via key-acl-sync, NOT set-many.
+		const prefix = VAULT_KEY ? `${VAULT_KEY.slice(0, 8)}…` : '<no key>';
+		console.error(`[dev-vault]   all errors are HTTP 403 — secrets exist, but caller ${prefix}`);
+		console.error('[dev-vault]   lacks per-key ACL grants. Operator: from hadoku_site/,');
+		console.error(`[dev-vault]     python scripts/administration.py key-acl-sync \\`);
+		console.error(`[dev-vault]       --repo ${process.cwd()} --prune`);
+		console.error('[dev-vault]   (--key auto-resolves from .devvault.local.json)');
+		console.error('[dev-vault]   (needs HADOKU_ADMIN_KEY or HADOKU_VAULT_KEY + fresh agent-token)');
+	} else {
+		// Name the command, not a curl. The snippet that used to live here
+		// omitted X-User-Key against an admin-tier route, so it was rejected as
+		// printed — and it routed around provision-secret, which is what writes
+		// the classification, the ACL grants and the Cloudflare push. A
+		// vault-only write is the half-state that broke
+		// ARCHIVEBOT_SPACES_WEBHOOK_SECRET on 2026-09-07.
+		const absent = errors.filter((e) => /not in vault/.test(String(e.err))).map((e) => e.vaultKey);
+		const example = absent[0] ?? 'VAULT_KEY';
+		console.error('[dev-vault]   to add a missing key to the vault, from hadoku_site/:');
+		for (const name of absent.length ? absent : [example]) {
+			console.error(
+				`[dev-vault]     python3 scripts/administration.py provision-secret ${name} --prompt --confirm`
+			);
+		}
+		console.error(
+			'[dev-vault]   --prompt reads the value hidden; never paste a secret as an argv.'
+		);
+		console.error(
+			'[dev-vault]   Or in the browser: hadoku.me/command-station → Account → Vault keys.'
+		);
+	}
+	console.error('[dev-vault]   then retry pnpm dev.');
+	process.exit(1);
+}
+
+const keyCount = Object.keys(fetched).length;
+const keyPreview = VAULT_KEY ? `${VAULT_KEY.slice(0, 8)}…` : '(none)';
+// stderr, like every other line dev-vault prints: stdout belongs to the child,
+// and a caller that captures it (a `cmd:` credential helper running
+// `dev-vault -- printenv NAME`) must get the child's output and nothing else.
+console.error(
+	`[dev-vault] caller=${keyPreview} (from ${LOCAL_KEY_PATH}) broker=${MGMT_API_BASE} (${BROKER.source}) — fetched ${keyCount} key(s); exec: ${childCmd.join(' ')}`
+);
+
+// ─── Derive NODE_AUTH_TOKEN for @wolffm installs ────────────────────────
+// `~/.npmrc` on the dev host is deliberately TOKENLESS and reads
+// `//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}`. That is the name
+// `actions/setup-node` writes in CI, so the same npmrc serves both places —
+// but locally NOTHING set it, and pnpm expanded it to empty. Every
+// `@wolffm/*` install then failed:
+//
+//   [ERR_PNPM_FETCH_401] GET .../@wolffm/dataplatform — Unauthorized
+//   No authorization header was set for the request.
+//
+// which reads as a broken lockfile or a revoked token rather than a missing
+// variable, and `pnpm vault-install` — the documented fix — failed the same
+// way because it never provided the name the npmrc actually asks for.
+//
+// Derived rather than declared: a repo would otherwise need a vault item
+// literally named NODE_AUTH_TOKEN, and there isn't one. The value is the
+// registry-scoped token, never HADOKU_SITE_TOKEN — that one carried
+// `read:packages` historically but had it deliberately removed in the
+// 2026-08-19 rotation (it is a repo/workflow credential), so falling back to
+// it would authenticate and then 403 on every package, which is strictly
+// worse than not setting the variable at all.
+//
+// An existing NODE_AUTH_TOKEN always wins, so CI is untouched.
+const derived = {};
+if (!process.env.NODE_AUTH_TOKEN && fetched.HADOKU_NPM_READ_TOKEN) {
+	derived.NODE_AUTH_TOKEN = fetched.HADOKU_NPM_READ_TOKEN;
+}
+
+// ─── Spawn child with merged env ────────────────────────────────────────
+// HADOKU_DEV_VAULT_ACTIVE lets a child process detect it's already running
+// inside dev-vault and skip any self-re-exec. (The old root `preinstall`
+// guard that consumed this was removed 2026-08-03 — pnpm 11 runs preinstall
+// AFTER dependency fetch, so it could never rescue an unauthenticated
+// install; `pnpm vault-install` is the documented path.)
+const child = spawn(childCmd[0], childCmd.slice(1), {
+	stdio: 'inherit',
+	env: { ...process.env, ...fetched, ...derived, HADOKU_DEV_VAULT_ACTIVE: '1' },
+});
+
+child.on('error', (err) => {
+	console.error(`[dev-vault] error: failed to spawn ${childCmd[0]}: ${err.message}`);
+	console.error(`[dev-vault]   is ${childCmd[0]} on PATH? did you forget pnpm install?`);
+	process.exit(1);
+});
+child.on('close', (code) => process.exit(code ?? 0));
+
+for (const sig of ['SIGINT', 'SIGTERM']) {
+	process.on(sig, () => child.kill(sig));
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function printUsage() {
+	console.error('[dev-vault] usage:');
+	console.error('[dev-vault]   npx @wolffm/dev-vault -- <command> [args...]');
+	console.error('[dev-vault]   dev-vault -- <command> [args...]   (if installed as a dep)');
+	console.error(
+		'[dev-vault]   node ../hadoku_site/scripts/secrets/dev-vault.mjs -- <command> [args...]'
+	);
+	console.error('[dev-vault]   <any of the above> --check');
+	console.error('[dev-vault]');
+	console.error('[dev-vault] reads .devvault.json from cwd, fetches values from the');
+	console.error('[dev-vault] vault broker, execs <command> with them in process.env.');
+}
+
+function readMapping(path) {
+	if (!existsSync(path)) return null;
+	let raw;
+	try {
+		raw = readFileSync(path, 'utf-8');
+	} catch (e) {
+		throw new Error(`cannot read ${path}: ${e.message}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		throw new Error(`${path} is not valid JSON: ${e.message}`);
+	}
+	if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+		throw new Error(
+			`${path} must be a JSON object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`
+		);
+	}
+	const out = {};
+	for (const [k, v] of Object.entries(parsed)) {
+		if (k.startsWith('//')) continue; // comments
+		if (typeof v !== 'string' || !v) {
+			throw new Error(`${path}: value for "${k}" must be a non-empty vault key string`);
+		}
+		out[k] = v;
+	}
+	return out;
+}
+
+async function fetchStatus() {
+	const r = await fetch(`${MGMT_API_BASE}/api/secrets/status`, { headers: authHeaders() });
+	// 404 is edge-router's deliberate response to an unauthenticated caller on a
+	// gated prefix (it does not advertise the surface), so it is the LIKELY
+	// rejection signal — but it is not proof: a routing change or a broker that
+	// simply isn't there produces the same status. Say what we actually know.
+	if (r.status === 404 && VIA_EDGE) {
+		throw new Error(
+			'broker /status returned HTTP 404 from the gated edge path. Most likely the key ' +
+				'was rejected: edge-router 404s (rather than 401s) an unrecognised caller so it ' +
+				'does not advertise the surface. Check the key resolves — it needs a live, ' +
+				'service-tier record in the edge key registry AND a vault item holding its value ' +
+				'(hadoku_site: `pnpm run check:key-sync`). If it does, the 404 is a routing or ' +
+				'broker-availability problem instead. Ping the operator.'
+		);
+	}
+	if (!r.ok) throw new Error(`broker /status returned HTTP ${r.status}`);
+	return await r.json();
+}
+
+async function fetchKey(vaultKey) {
+	const r = await fetch(`${MGMT_API_BASE}/api/secrets/get/${encodeURIComponent(vaultKey)}`, {
+		headers: authHeaders(),
+	});
+	const body = await r.json().catch(() => null);
+	// On the gated path, 404 ambiguously means either "key not in vault" OR
+	// "edge-router rejected your key". Disambiguate by body shape: vault-broker
+	// 404s have JSON; edge-router auth-failure 404s have plain text.
+	if (r.status === 404 && VIA_EDGE && body === null) {
+		throw new Error('gated /mgmt/* rejected HADOKU_VAULT_KEY (not "vault key missing")');
+	}
+	if (r.status === 404) throw new Error(`not in vault`);
+	if (!r.ok) throw new Error(`HTTP ${r.status} ${body?.error || ''}`.trim());
+	if (!body?.success || typeof body.value !== 'string') throw new Error('malformed response');
+	return body.value;
+}
+
+// ─── Doctor mode (--check) ─────────────────────────────────────────────
+
+async function runDoctor() {
+	console.log('[dev-vault] doctor');
+	console.log('-----------------');
+	console.log(`broker:  ${MGMT_API_BASE}  (${BROKER.source})`);
+	console.log(`config:  ${CONFIG_PATH}`);
+	if (KEY_REQUIRED) {
+		// Show only the prefix — never the full key, even in --check output, so
+		// pasting the doctor report into chat doesn't leak credentials.
+		const preview = VAULT_KEY ? `${VAULT_KEY.slice(0, 8)}…` : '(unset!)';
+		console.log(`auth:    key=${preview}  source=${LOCAL_KEY_PATH}`);
+	}
+	console.log();
+
+	// 1. mapping file
+	let mapping;
+	try {
+		mapping = readMapping(CONFIG_PATH);
+	} catch (err) {
+		console.log(`✗ mapping: ${err.message}`);
+		return;
+	}
+	if (mapping === null) {
+		console.log('✗ mapping: file not found');
+		console.log(`  create one:  echo '{}' > ${CONFIG_PATH}`);
+		return;
+	}
+	const entries = Object.entries(mapping);
+	console.log(`✓ mapping: ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`);
+	for (const [envName, vaultKey] of entries) {
+		console.log(`    ${envName.padEnd(36)} → ${vaultKey}`);
+	}
+	console.log();
+
+	// 2. broker reachability
+	let status;
+	try {
+		status = await fetchStatus();
+	} catch (err) {
+		console.log(`✗ broker: unreachable (${err.message})`);
+		console.log(`  override URL with: MGMT_API_BASE=<url>`);
+		return;
+	}
+	console.log(`✓ broker: reachable, ${status.keyCount ?? 0} keys cached`);
+
+	if (!status.unlocked) {
+		console.log('✗ vault: SEALED');
+		console.log(`  unlock at: ${UNLOCK_URL}`);
+		return;
+	}
+	const ageS = status.cacheAgeMs ? Math.round(status.cacheAgeMs / 1000) : '?';
+	console.log(`✓ vault: unlocked (cache age ${ageS}s)`);
+	console.log();
+
+	// 3. per-key fetch
+	let okCount = 0;
+	for (const [envName, vaultKey] of entries) {
+		try {
+			const v = await fetchKey(vaultKey);
+			console.log(`✓ ${envName.padEnd(36)} → ${vaultKey}  (${v.length} chars)`);
+			okCount++;
+		} catch (err) {
+			console.log(`✗ ${envName.padEnd(36)} → ${vaultKey}  (${err.message})`);
+		}
+	}
+	console.log();
+
+	// 4. ACL drift check. Cross-references .devvault.json against the grants
+	// attached to this key. Catches "I added a new line to .devvault.json
+	// but the operator hasn't granted it yet" and "operator pruned a key
+	// from my grants but I still have it in the manifest". Service-tier
+	// callers can hit /secrets/acl/me without admin auth.
+	try {
+		const r = await fetch(`${MGMT_API_BASE}/api/secrets/acl/me`, { headers: authHeaders() });
+		if (r.ok) {
+			const aclBody = await r.json();
+			const granted = new Set(aclBody.grants ?? []);
+			const declared = new Set(entries.map(([, v]) => v));
+			const missingGrants = [...declared].filter((k) => !granted.has(k));
+			const extraGrants = [...granted].filter((k) => !declared.has(k));
+			if (granted.size === 0 && declared.size > 0) {
+				console.log(`⚠  ACL: 0 grants attached to this key — every read will 403.`);
+				console.log(`   → operator: key-acl-sync --repo .`);
+			} else if (missingGrants.length === 0 && extraGrants.length === 0) {
+				console.log(`✓ ACL: ${granted.size} grant(s), all match .devvault.json`);
+			} else {
+				console.log(`⚠  ACL drift detected:`);
+				if (missingGrants.length) {
+					console.log(`   declared in .devvault.json but NOT granted: ${missingGrants.join(', ')}`);
+					console.log(`   → operator: key-acl-sync --repo .`);
+				}
+				if (extraGrants.length) {
+					console.log(`   granted but NOT in .devvault.json: ${extraGrants.join(', ')}`);
+					console.log(`   → operator: key-acl-sync --repo . --prune`);
+				}
+			}
+		}
+		// /secrets/acl/me may not exist on a stale mgmt-api; skip rather than
+		// fail the doctor.
+	} catch {
+		/* swallow */
+	}
+	console.log();
+
+	console.log(`summary: ${okCount}/${entries.length} keys fetchable`);
+	if (okCount < entries.length) {
+		console.log('next: add the missing keys, from hadoku_site/:');
+		console.log(
+			'        python3 scripts/administration.py provision-secret <NAME> --prompt --confirm'
+		);
+		console.log('      or in the browser: hadoku.me/command-station → Account → Vault keys');
+		console.log('      OR fix the mapping in .devvault.json');
+	}
+}

package/install-id.mjs

@@ -0,0 +1,66 @@
+/**
+ * The installation id dev-vault sends as `X-Hadoku-Install`, and the
+ * User-Agent it sends beside it.
+ *
+ * A key sent as a header never signs in, so the edge's device ledger never
+ * saw where one was used from: on 2026-10-28 the hopper service key was set up
+ * on a new machine on the operator's home network and nothing alerted. The
+ * network cannot tell two machines on it apart; a random id kept per machine
+ * and user can. The edge records each identity's installations and alerts on
+ * an unseen one (edge-router `src/key-use.ts`).
+ *
+ * Not under CI: a runner is a fresh installation every job, so every service
+ * key would page on every run. CI is recognised by its network instead.
+ *
+ * The id is not a credential: it identifies, it authenticates nothing, and
+ * the edge stores only its digest.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir, hostname, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const INSTALL_HEADER = 'X-Hadoku-Install';
+
+export function installIdPath(env = process.env) {
+	const base = env.XDG_CONFIG_HOME || join(homedir(), '.config');
+	return join(base, 'hadoku', 'install-id');
+}
+
+/** Whether this process runs under CI, where no installation id is sent. */
+export function underCi(env = process.env) {
+	return env.CI === 'true' || env.CI === '1' || env.GITHUB_ACTIONS === 'true';
+}
+
+/**
+ * This installation's id, created on first use. Null under CI, or when the
+ * file can be neither read nor written: the id only feeds detection, so a
+ * read-only home must not stop dev-vault.
+ */
+export function installId(env = process.env, path = installIdPath(env)) {
+	if (underCi(env)) return null;
+	try {
+		if (existsSync(path)) {
+			const id = readFileSync(path, 'utf8').trim();
+			if (/^[0-9a-f]{32}$/.test(id)) return id;
+		}
+		const id = randomBytes(16).toString('hex');
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${id}\n`, { mode: 0o600 });
+		chmodSync(path, 0o600);
+		return id;
+	} catch (err) {
+		console.error(`[dev-vault] warning: no installation id (${path}): ${err.message}`);
+		return null;
+	}
+}
+
+/** `dev-vault/1.4.0 (linux) host:desk`, in characters the alert keeps. */
+export function userAgent(version, host = hostname(), os = platform()) {
+	const clean = (s) =>
+		String(s)
+			.replace(/[^\w.-]/g, '')
+			.slice(0, 32);
+	return `dev-vault/${clean(version)} (${clean(os)}) host:${clean(host)}`;
+}

package/key-file.mjs

@@ -0,0 +1,42 @@
+/**
+ * Which `.devvault.local.json` holds this repo's caller key.
+ *
+ * In a linked git worktree, the MAIN checkout's file wins over a copy in the
+ * worktree. A key swap rewrites the file in the main checkout only — it has
+ * no way to know where copies went. A worktree carrying its own copy therefore
+ * holds a retired key after the next swap, and a retired key does not
+ * 401: it resolves to `public`, so every vault read 403s and looks like a
+ * missing ACL grant (hadoku-task worktree, 2026-10-25). A worktree's own file
+ * is used only when the main checkout has none.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+
+const FILE = '.devvault.local.json';
+
+/**
+ * The main checkout of the repo `cwd` is in, when `cwd` is inside a LINKED
+ * worktree; null in the main checkout itself, outside git, or when git is
+ * missing.
+ */
+export function mainCheckoutOf(cwd, git = runGit) {
+	const common = git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+	const own = git(cwd, ['rev-parse', '--path-format=absolute', '--git-dir']);
+	if (!common || !own || resolve(common) === resolve(own)) return null;
+	// A bare repo's worktrees have no main checkout to read from.
+	return basename(common) === '.git' ? dirname(common) : null;
+}
+
+/** Absolute path of the key file dev-vault should read. */
+export function resolveKeyFile(cwd, { git = runGit, exists = existsSync } = {}) {
+	const main = mainCheckoutOf(cwd, git);
+	if (main && exists(resolve(main, FILE))) return resolve(main, FILE);
+	return resolve(cwd, FILE);
+}
+
+function runGit(cwd, args) {
+	const r = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+	return r.status === 0 ? r.stdout.trim() : '';
+}

package/login.mjs

@@ -0,0 +1,134 @@
+/**
+ * `dev-vault login`: put a grantee's own 7-day credential into this clone
+ * (hadoku_site docs/planning/service-grants-2026-10-31.md).
+ *
+ * A passkey lives in the browser; dev-vault needs a key on disk. So this asks
+ * hadoku.me for a login request, prints a short code and a link, and waits.
+ * The person opens the link signed in, and approves with their passkey and a
+ * code from their authenticator app. This then receives the key, once, and
+ * writes `.devvault.local.json` (the main checkout's, in a worktree) with its
+ * expiry, mode 0600. When it expires, dev-vault says to run this again.
+ *
+ * Everything that touches the network, git or the clock is injected, so the
+ * flow is testable without hadoku.me.
+ */
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { hostname as osHostname } from 'node:os';
+import { resolve } from 'node:path';
+import { mainCheckoutOf } from './key-file.mjs';
+
+export const EDGE = 'https://hadoku.me';
+const FILE = '.devvault.local.json';
+const POLL_MS = 3000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function runGit(cwd, args) {
+	const r = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+	return r.status === 0 ? r.stdout.trim() : '';
+}
+
+/** `owner/name` from the origin remote (ssh or https), or null. */
+export function repoSlug(cwd, git = runGit) {
+	const url = git(cwd, ['remote', 'get-url', 'origin']);
+	const m = /github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(url);
+	return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Where the key goes: the main checkout's file in a worktree, else this one's. */
+export function keyFileTarget(cwd, git = runGit) {
+	return resolve(mainCheckoutOf(cwd, git) ?? cwd, FILE);
+}
+
+/**
+ * Whether a key file's credential still works: `ok`, `expiring` (under a day
+ * left) or `expired`. A file without `expiresAt` (a key minted before service
+ * grants) never expires here.
+ */
+export function credentialState(raw, now = Date.now()) {
+	const at = raw && typeof raw.expiresAt === 'number' ? raw.expiresAt : null;
+	if (at === null) return 'ok';
+	if (at <= now) return 'expired';
+	return at - now < DAY_MS ? 'expiring' : 'ok';
+}
+
+async function postJson(fetchImpl, url, body) {
+	const res = await fetchImpl(url, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify(body),
+	});
+	const data = await res.json().catch(() => ({}));
+	return { status: res.status, data };
+}
+
+/**
+ * Run the login. Resolves to the process exit code: 0 written, 1 refused,
+ * expired or unreachable.
+ */
+export async function login({
+	cwd = process.cwd(),
+	base = process.env.HADOKU_BASE || EDGE,
+	fetchImpl = fetch,
+	git = runGit,
+	host = osHostname(),
+	log = (line) => console.error(line),
+	sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+	now = () => Date.now(),
+} = {}) {
+	const repo = repoSlug(cwd, git);
+	let started;
+	try {
+		started = await postJson(fetchImpl, `${base}/auth/service-access/device`, { host, repo });
+	} catch (err) {
+		log(`[dev-vault] login: cannot reach ${base}: ${err instanceof Error ? err.message : err}`);
+		return 1;
+	}
+	if (started.status !== 200) {
+		log(`[dev-vault] login: ${started.data.error ?? `HTTP ${started.status}`}`);
+		return 1;
+	}
+	const { deviceCode, userCode, verifyUrl, expiresIn } = started.data;
+	log('[dev-vault] login: open this link, signed in, and approve:');
+	log(`[dev-vault]   ${verifyUrl}`);
+	log(`[dev-vault]   code ${userCode}  ·  ${host}${repo ? `  ·  ${repo}` : ''}`);
+	log('[dev-vault] waiting for approval…');
+
+	const deadline = now() + (Number(expiresIn) || 600) * 1000;
+	while (now() < deadline) {
+		await sleep(POLL_MS);
+		let polled;
+		try {
+			polled = await postJson(fetchImpl, `${base}/auth/service-access/device/poll`, {
+				deviceCode,
+			});
+		} catch {
+			continue;
+		}
+		const { data } = polled;
+		if (data.status === 'pending') continue;
+		if (data.status !== 'approved' || typeof data.key !== 'string') {
+			log('[dev-vault] login: the request expired or was refused. Run `dev-vault login` again.');
+			return 1;
+		}
+		const target = keyFileTarget(cwd, git);
+		let prior = {};
+		if (existsSync(target)) {
+			try {
+				prior = JSON.parse(readFileSync(target, 'utf-8'));
+			} catch {
+				prior = {};
+			}
+		}
+		const next = { ...prior, key: data.key, expiresAt: data.expiresAt, identity: data.name };
+		writeFileSync(target, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+		chmodSync(target, 0o600);
+		log(
+			`[dev-vault] login: ${data.name} written to ${target}, ` +
+				`valid until ${new Date(data.expiresAt).toLocaleString()}.`
+		);
+		return 0;
+	}
+	log('[dev-vault] login: nobody approved within 10 minutes. Run `dev-vault login` again.');
+	return 1;
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@hadoku/dev-vault",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.0",
+  "description": "Local-dev vault-broker shim — fetches secrets from the hadoku mgmt-api broker and execs a child command with them in process.env. Works for any consuming repo (Node or non-Node).",
+  "type": "module",
+  "bin": {
+    "dev-vault": "./dev-vault.mjs"
+  },
+  "files": [
+    "dev-vault.mjs",
+    "broker-base.mjs",
+    "key-file.mjs",
+    "install-id.mjs",
+    "login.mjs",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WolffM/hadoku_site.git",
+    "directory": "packages/dev-vault"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "hadoku",
+    "vault",
+    "secrets",
+    "dev"
+  ],
+  "license": "ISC"
+}