pinnace 0.0.0 → 0.2.0

package/src/config/config-resolution.ts

@@ -0,0 +1,264 @@
+/**
+ * Config resolution for pinnace.
+ *
+ * Every setting resolves with precedence **CLI arg > env (via `ldenv`) >
+ * `pinnace.json`** (CONTEXT.md "config resolution"). This module owns the typed
+ * `pinnace.json` schema and the resolver.
+ *
+ * SECURITY INVARIANT (hard): the **master secret is env-only**. The resolver
+ * has NO file path for the master — a `master` field placed in `pinnace.json`
+ * is structurally impossible to surface here. Reading the master goes through
+ * {@link resolveMasterSecret}, which consults ONLY env. A compromised node or a
+ * leaked config file therefore cannot leak the master.
+ *
+ * `ldenv` is the env layer in production; to keep tests hermetic (and to keep
+ * the operator's real environment untouched), the resolver takes an explicit
+ * `env` record rather than reading `process.env` directly. A thin production
+ * caller passes `ldenv`-loaded values in.
+ *
+ * SECOND ENV-ONLY SECRET (the bearer TOKEN). A node's bearer `token` is the
+ * SAME CLASS as the master: a secret that must NEVER live in `pinnace.json`.
+ * So {@link HostConfig} has NO `token` field at all (structurally impossible to
+ * leak one via config, exactly like the master), and the token is resolved
+ * ONLY from `CLI > env(PINNACE_HOST_<NAME>_TOKEN)` by {@link resolveHostToken}.
+ * A host with no resolvable token is a LOUD, specific error naming the missing
+ * env var (never a silent `""` that turns into a downstream 401).
+ *
+ * EAGER-VS-LAZY (decided): the token failure is LAZY, not eager. `resolveConfig`
+ * does NOT demand a token for every configured host up front (a host no
+ * operation touches must not block unrelated work); instead a caller resolves a
+ * host's token via {@link resolveHostToken} at the moment it actually builds
+ * that host's client (deploy target / status client), so only hosts an
+ * operation USES must have a token set. See the `## Decisions` block in the
+ * done record.
+ */
+
+/** A node/host role. */
+export type HostRole = 'publisher' | 'replica';
+
+/** A per-site publish mode. */
+export type SiteMode = 'ipfs' | 'ipns';
+
+/**
+ * A host/node entry as it appears in `pinnace.json`.
+ *
+ * NOTE there is DELIBERATELY no `token` field: the bearer token is env-only by
+ * construction (see the module doc), resolved via {@link resolveHostToken}. A
+ * stray `token` in a file object is ignored, exactly as a stray `master` is.
+ */
+export interface HostConfig {
+	/** Stable host name (used to key env/CLI token + endpoint overrides). */
+	name: string;
+	/** The node's Kubo RPC endpoint. */
+	endpoint: string;
+	/** publisher (holds a key, signs) or replica (keyless, re-announces). */
+	role: HostRole;
+	/** For replicas: where to fetch the publisher's exported record. */
+	publisherEndpoint?: string;
+}
+
+/**
+ * A site entry as it appears in `pinnace.json`.
+ *
+ * A site is identified by ONE value: {@link SiteConfig.id}. It is BOTH the MFS
+ * entry (`/sites/<id>`) AND the KDF input fed to the frozen derivation (see
+ * `../derive/ipns-key-derivation.ts` / ADR-0001). There is no separate `name`
+ * and no separate `keyId` — one `id` is the whole identity surface.
+ */
+export interface SiteConfig {
+	/**
+	 * The site's SINGLE identifier: both its MFS entry (`/sites/<id>`) and the KDF
+	 * input for its per-site IPNS key. Frozen once a name is live (changing it
+	 * moves the derived id, per ADR-0001). NOT the ENS name.
+	 */
+	id: string;
+	/** ipfs (land+pin+MFS) or ipns (also publish/refresh). */
+	mode: SiteMode;
+	/** The site source directory to build a CAR from. */
+	sourceDir: string;
+	/**
+	 * OPTIONAL eth.limo-warming hint: when set, the site is ALSO warmed via
+	 * `https://<ensName>.limo`. It is NOT part of identity and NEVER an input to
+	 * the key derivation — purely an opt-in warming lever.
+	 */
+	ensName?: string;
+	/**
+	 * An optional externally-owned key (the escape hatch): when set, this site's
+	 * IPNS key is NOT derived from the master but supplied here.
+	 */
+	externalKey?: string;
+}
+
+/**
+ * The typed `pinnace.json` shape. Note there is DELIBERATELY no `master` field
+ * in the resolved config — see the module doc. If a raw file object carries a
+ * stray `master`, it is ignored (never copied into the resolved config).
+ */
+export interface PinnaceConfigFile {
+	hosts?: HostConfig[];
+	sites?: SiteConfig[];
+	/** Public gateways to warm (dweb.link, eth.limo, ...). */
+	gateways?: string[];
+}
+
+/** The fully resolved config the rest of pinnace consumes. */
+export interface ResolvedConfig {
+	hosts: HostConfig[];
+	sites: SiteConfig[];
+	gateways: string[];
+}
+
+/** An env record (name → value). In production these come from `ldenv`. */
+export type EnvRecord = Record<string, string | undefined>;
+
+/** CLI overrides. Keyed by host name for per-host values. */
+export interface CliOverrides {
+	/** hostName → token override. */
+	hostToken?: Record<string, string>;
+	/** hostName → endpoint override. */
+	hostEndpoint?: Record<string, string>;
+	/** Gateways override (replaces the file/env list). */
+	gateways?: string[];
+}
+
+/** Inputs to {@link resolveConfig}. */
+export interface ResolveConfigInput {
+	/** The parsed `pinnace.json` object (lowest precedence). */
+	file: PinnaceConfigFile;
+	/** The env layer (middle precedence). */
+	env: EnvRecord;
+	/** CLI args (highest precedence). */
+	cli: CliOverrides;
+}
+
+/** Uppercase + non-alphanumeric → `_`, for building env var names. */
+function envKey(...parts: string[]): string {
+	return parts
+		.map((p) => p.toUpperCase().replace(/[^A-Z0-9]+/g, '_'))
+		.join('_');
+}
+
+/**
+ * Resolve the full pinnace config with precedence CLI arg > env > file.
+ *
+ * A stray `master` field on the file object is NEVER read here — the master is
+ * env-only via {@link resolveMasterSecret}.
+ */
+export function resolveConfig(input: ResolveConfigInput): ResolvedConfig {
+	const {file, env, cli} = input;
+
+	const hosts: HostConfig[] = (file.hosts ?? []).map((h) => {
+		const endpoint =
+			cli.hostEndpoint?.[h.name] ??
+			env[envKey('PINNACE_HOST', h.name, 'ENDPOINT')] ??
+			h.endpoint;
+		// The token is NOT resolved here — it is env-only and resolved lazily, per
+		// host, at the moment an operation builds that host's client (see
+		// resolveHostToken + the module doc). Copy only the non-secret fields.
+		return {
+			name: h.name,
+			endpoint,
+			role: h.role,
+			...(h.publisherEndpoint !== undefined
+				? {publisherEndpoint: h.publisherEndpoint}
+				: {}),
+		};
+	});
+
+	const gateways =
+		cli.gateways ?? splitList(env['PINNACE_GATEWAYS']) ?? file.gateways ?? [];
+
+	return {
+		hosts,
+		sites: file.sites ?? [],
+		gateways,
+	};
+}
+
+/**
+ * The env var name a host's bearer token is read from: `PINNACE_HOST_<NAME>_TOKEN`
+ * (uppercased, non-alphanumerics collapsed to `_`). Exposed so error messages
+ * and callers name the EXACT var an operator must set.
+ */
+export function hostTokenEnvVar(hostName: string): string {
+	return envKey('PINNACE_HOST', hostName, 'TOKEN');
+}
+
+/**
+ * A loud, specific failure when a host has no resolvable bearer token. Names the
+ * exact missing env var so the operator knows precisely what to set (never a
+ * silent empty token / downstream 401).
+ */
+export class MissingHostTokenError extends Error {
+	constructor(
+		/** The host whose token could not be resolved. */
+		readonly hostName: string,
+		/** The exact env var that would supply it. */
+		readonly envVar: string,
+	) {
+		super(
+			`host '${hostName}' has no token; set ${envVar} ` +
+				`(the token is env-only, never read from pinnace.json)`,
+		);
+		this.name = 'MissingHostTokenError';
+	}
+}
+
+/** Inputs to {@link resolveHostToken}. */
+export interface ResolveHostTokenInput {
+	/** The host whose token to resolve (its `name` keys the env/CLI override). */
+	hostName: string;
+	/** The env layer (the ONLY file-less source of the token). */
+	env: EnvRecord;
+	/** CLI overrides (highest precedence): `hostToken[hostName]`. */
+	cli?: CliOverrides;
+}
+
+/**
+ * Resolve ONE host's bearer token with precedence `CLI > env` (there is
+ * DELIBERATELY no file layer — the token is env-only, like the master). Throws
+ * {@link MissingHostTokenError} (naming the exact env var) when neither layer
+ * supplies it, so a missing token is a LOUD config error, never a silent `""`.
+ *
+ * Callers invoke this LAZILY — only for hosts an operation actually uses (see
+ * the eager-vs-lazy decision in the module doc) — so a configured-but-unused
+ * host never blocks unrelated work.
+ */
+export function resolveHostToken(input: ResolveHostTokenInput): string {
+	const envVar = hostTokenEnvVar(input.hostName);
+	const token = input.cli?.hostToken?.[input.hostName] ?? input.env[envVar];
+	if (token === undefined || token === '') {
+		throw new MissingHostTokenError(input.hostName, envVar);
+	}
+	return token;
+}
+
+/** Split a comma-separated env list, or return undefined if unset/empty. */
+function splitList(value: string | undefined): string[] | undefined {
+	if (!value) return undefined;
+	const list = value
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean);
+	return list.length > 0 ? list : undefined;
+}
+
+/** Inputs to {@link resolveMasterSecret}. */
+export interface ResolveMasterInput {
+	/** The env layer. This is the ONLY source of the master. */
+	env: EnvRecord;
+	/** The env var name to read (default `PINNACE_MASTER`). */
+	envVar?: string;
+}
+
+/**
+ * Resolve the master secret. It is read ONLY from env (there is deliberately no
+ * `file` parameter): the master must never come from `pinnace.json`. Returns
+ * undefined when the env var is unset.
+ */
+export function resolveMasterSecret(
+	input: ResolveMasterInput,
+): string | undefined {
+	const envVar = input.envVar ?? 'PINNACE_MASTER';
+	return input.env[envVar];
+}

package/src/deploy/deploy.ts

@@ -0,0 +1,250 @@
+/**
+ * Host-agnostic **deploy** — build one CAR and land the SAME CID on every node.
+ *
+ * This is the core operation user stories 4, 6, 7 describe: build a site's
+ * **CAR** ONCE (via the `car-build` seam), then fan out across every configured
+ * **node** (each with its OWN bearer token) so all nodes serve the IDENTICAL
+ * **CID** with no single point of failure. Per node the flow is: import + pin
+ * the CAR (`dag/import?pin-roots=true`), then place it in MFS at `/sites/<id>`
+ * (mkdir parents / rm old / cp `/ipfs/<cid>`) so `gateway warming`, IPNS
+ * republish, and `status` auto-discover it. Deploy speaks ONLY the Kubo RPC seam
+ * ({@link KuboRpcClient}); it is not host-specific.
+ *
+ * Behaviour ported (not copied) from the reference prototype
+ * `~/searches/ipfs-hetzner/deploy-car.mjs`: the multi-target fan-out, the MFS
+ * placement, the per-`mode` branch, and the `Promise.allSettled` partial-failure
+ * semantics (a non-empty subset of nodes succeeding is still an overall success:
+ * "the site is up on the rest").
+ *
+ * PER-SITE `mode` BRANCH (CONTEXT.md `mode`; spec's "Per-site mode branch"):
+ *  - `ipfs` mode: land + pin + MFS ONLY (no key, no publish). ENS uses
+ *    `ipfs://<cid>`, updated per deploy.
+ *  - `ipns` mode: everything above PLUS the publish path (`key/list` then
+ *    `name/publish`) and ONLY on a PUBLISHER target. A `replica` (or a target
+ *    with {@link DeployTarget.publish} disabled) NEVER signs — it re-announces
+ *    the publisher's record via the on-box `mirror` verb instead. This mirrors
+ *    the prototype's `doPublish = mode === "ipns" && PUBLISH_IPNS` gate, with
+ *    role standing in for the prototype's `PUBLISH_IPNS=0` replica flag.
+ *
+ * SEAM BOUNDARY (see the sibling tasks): this module wires the per-mode call
+ * SEQUENCE only. The full publisher/replica record export+mirror lives in
+ * `publisher-replica-model`, and importing the derived key into the publisher's
+ * keystore lives in `key-import-publisher`. So deploy here does NOT `key/gen`
+ * or `key/import` — it assumes the publisher already holds the key (looked up
+ * via `key/list`) and issues `name/publish`. If a publisher has no matching key
+ * yet, the publish is reported as skipped rather than silently generating one
+ * (key provisioning is that other task's job, not deploy's).
+ */
+import {KuboRpcClient, type FetchLike} from '../rpc/kubo-rpc-client.js';
+import {buildCar, type BuiltCar} from '../car/car-build.js';
+import {placeInMfs} from '../site/site-management.js';
+import type {HostRole, SiteMode} from '../config/config-resolution.js';
+
+/** The MFS directory sites live under (matches site-management). */
+const DEFAULT_SITES_DIR = '/sites';
+
+/** Reference record values (ported from the prototype / on-box republish). */
+const RECORD_LIFETIME = '72h';
+const RECORD_TTL = '1h';
+
+/**
+ * One deploy target: a node's RPC endpoint + its OWN token + its role. In
+ * `ipns` mode only a `publisher` (with publish not disabled) signs the record;
+ * a `replica` lands+pins+MFS but never publishes.
+ */
+export interface DeployTarget {
+	/** The node's Kubo RPC base URL. */
+	baseUrl: string;
+	/** The node's bearer token (each target has its OWN). */
+	token: string;
+	/** publisher (may sign in ipns mode) or replica (never signs). */
+	role: HostRole;
+	/**
+	 * Explicit publish switch. Defaults to true for a publisher. Set false to
+	 * land+pin+MFS on a publisher WITHOUT signing (the prototype's
+	 * `PUBLISH_IPNS=0`). A `replica` never publishes regardless of this flag.
+	 */
+	publish?: boolean;
+	/** Injectable fetch (tests pass a MockKuboApi); defaults to global fetch. */
+	fetchImpl?: FetchLike;
+}
+
+/** Inputs to {@link deploy}. Supply EITHER a `sourceDir` OR a prebuilt `car`. */
+export interface DeployInput {
+	/** The site source directory to build a CAR from (mutually exclusive with `car`). */
+	sourceDir?: string;
+	/** A prebuilt CAR to deploy as-is (mutually exclusive with `sourceDir`). */
+	car?: BuiltCar;
+	/** The site's single `id`: its MFS entry `/sites/<id>` and, in ipns mode, its key name. */
+	id: string;
+	/** ipfs (land+pin+MFS) or ipns (also key/list + name/publish on publishers). */
+	mode: SiteMode;
+	/** The nodes to deploy to (each with its own token); the CAR lands on all. */
+	targets: DeployTarget[];
+	/** The MFS directory sites live under (default `/sites`). */
+	sitesDir?: string;
+}
+
+/** A per-target success record. */
+export interface DeployNodeOk {
+	/** The node's base URL. */
+	baseUrl: string;
+	/** The CID landed on this node (identical across all successful nodes). */
+	cid: string;
+	/** The IPNS id published on this node, if it signed; undefined otherwise. */
+	ipns?: string;
+	/** Whether this node signed+published an IPNS record. */
+	published: boolean;
+}
+
+/** A per-target failure record. */
+export interface DeployNodeFailure {
+	/** The node's base URL. */
+	baseUrl: string;
+	/** The error that failed this node's deploy (its content is up elsewhere). */
+	error: Error;
+}
+
+/** The overall deploy result: the CID, and per-node success/failure. */
+export interface DeployResult {
+	/** The authoritative site CID (identical on every node). */
+	cid: string;
+	/** The site's mode. */
+	mode: SiteMode;
+	/** Nodes the deploy landed on (import + MFS, plus publish where applicable). */
+	ok: DeployNodeOk[];
+	/** Nodes whose deploy failed (reported, not thrown — the rest are up). */
+	failed: DeployNodeFailure[];
+	/** True when at least one node succeeded (some-nodes-up is still success). */
+	success: boolean;
+}
+
+/**
+ * Deploy a site: build the CAR ONCE, then import the SAME CAR into every target
+ * (each with its own token), pin it, place it in MFS, and (in `ipns` mode, on
+ * publisher targets) publish the IPNS record. Fans out with
+ * `Promise.allSettled`: a node that fails is reported in {@link DeployResult.failed}
+ * and does not sink the others; a non-empty success subset is still an overall
+ * success ({@link DeployResult.success}). Throws only if NO node succeeds is
+ * NOT the contract here — deploy always RESOLVES with the per-node breakdown;
+ * callers inspect `success`.
+ *
+ * @throws if neither `sourceDir` nor `car` is supplied, or both are.
+ */
+export async function deploy(input: DeployInput): Promise<DeployResult> {
+	const {sourceDir, car, id, mode, targets} = input;
+	if ((sourceDir === undefined) === (car === undefined)) {
+		throw new Error('deploy requires exactly one of `sourceDir` or `car`');
+	}
+	const sitesDir = input.sitesDir ?? DEFAULT_SITES_DIR;
+
+	// Build the CAR ONCE — the same bytes (and thus the same CID) land on every
+	// node (redundancy, no single point of failure).
+	const built: BuiltCar = car ?? (await buildCar(sourceDir as string));
+
+	// Fan out. allSettled so one node's failure never sinks the others.
+	const settled = await Promise.allSettled(
+		targets.map((target) => deployToNode(target, built, id, mode, sitesDir)),
+	);
+
+	const ok: DeployNodeOk[] = [];
+	const failed: DeployNodeFailure[] = [];
+	settled.forEach((outcome, i) => {
+		const baseUrl = targets[i].baseUrl;
+		if (outcome.status === 'fulfilled') {
+			ok.push(outcome.value);
+		} else {
+			failed.push({baseUrl, error: asError(outcome.reason)});
+		}
+	});
+
+	return {
+		cid: built.rootCid,
+		mode,
+		ok,
+		failed,
+		success: ok.length > 0,
+	};
+}
+
+/**
+ * Deploy the (already-built) CAR to ONE node: import + pin, place in MFS, then
+ * (in ipns mode on a publishing publisher) key/list + name/publish. Rejects on
+ * any RPC failure so the caller's allSettled records it as a per-node failure.
+ */
+async function deployToNode(
+	target: DeployTarget,
+	built: BuiltCar,
+	id: string,
+	mode: SiteMode,
+	sitesDir: string,
+): Promise<DeployNodeOk> {
+	const client = new KuboRpcClient({
+		baseUrl: target.baseUrl,
+		token: target.token,
+		fetchImpl: target.fetchImpl,
+	});
+
+	// 1. Import + pin the CAR (same CID as every other node).
+	await client.dagImport(built.carBytes);
+
+	// 2. Place it in MFS /sites/<id> (mkdir parents / rm old / cp /ipfs/<cid>).
+	//    Reuses the single implementation of that sequence (site-management).
+	await placeInMfs(client, sitesDir, id, built.rootCid);
+
+	// 3. Mode branch: ipns mode ADDS publish, and ONLY on a publishing publisher.
+	if (mode === 'ipns' && shouldPublish(target)) {
+		const ipns = await publish(client, id, built.rootCid);
+		return {baseUrl: target.baseUrl, cid: built.rootCid, ipns, published: true};
+	}
+
+	return {baseUrl: target.baseUrl, cid: built.rootCid, published: false};
+}
+
+/**
+ * Whether this target signs the IPNS record: a `publisher` whose publish switch
+ * is not explicitly disabled. A `replica` NEVER publishes (it re-announces the
+ * publisher's signed record via the on-box `mirror` verb instead).
+ */
+function shouldPublish(target: DeployTarget): boolean {
+	return target.role === 'publisher' && target.publish !== false;
+}
+
+/**
+ * The publish path (ipns mode, publisher only): `key/list` to resolve the site
+ * key's IPNS id, then `name/publish` to sign+refresh the record for
+ * `/ipfs/<cid>`. The keystore key name is the site's single `id` (the same
+ * value key-import imports under — one identifier, so the lookup cannot miss by
+ * a name/keyId split). Does NOT `key/gen`/`key/import`: the key is provisioned
+ * by the sibling `key-import-publisher` task; here we assume it exists. If it
+ * does not yet, we skip the publish (returning undefined) rather than silently
+ * generating a key deploy has no business owning.
+ */
+async function publish(
+	client: KuboRpcClient,
+	id: string,
+	cid: string,
+): Promise<string | undefined> {
+	const keys = await client.keyList<{
+		Keys?: Array<{Name?: string; Id?: string}> | null;
+	}>();
+	const ipns = (keys.Keys ?? []).find((k) => k?.Name === id)?.Id;
+	if (!ipns) {
+		// The publisher has no key for this site yet (key-import-publisher owns
+		// provisioning it). Land the content but do not sign.
+		return undefined;
+	}
+	await client.namePublish({
+		cidPath: `/ipfs/${cid}`,
+		key: id,
+		lifetime: RECORD_LIFETIME,
+		ttl: RECORD_TTL,
+		allowOffline: true,
+	});
+	return ipns;
+}
+
+/** Coerce an unknown rejection reason into an Error. */
+function asError(reason: unknown): Error {
+	return reason instanceof Error ? reason : new Error(String(reason));
+}

package/src/derive/ipns-key-derivation.ts

@@ -0,0 +1,173 @@
+/**
+ * Master-key -> per-site IPNS key derivation. **THIS IS A FROZEN CONTRACT.**
+ *
+ * Every `ipns`-mode site's key is derived deterministically from one operator
+ * master secret, so names are recoverable from the master alone and
+ * provisioning is stateless (CONTEXT.md `master key`, `keyId`). The scheme,
+ * pinned FOREVER by docs/adr/0001-frozen-ipns-key-derivation.md:
+ *
+ *   seed = HKDF-SHA256(ikm = master, salt = "", info = "pinnace:ipns:v1:" + keyId, length = 32)
+ *   -> the 32 bytes ARE the ed25519 private seed
+ *   -> its public key IS the IPNS name, rendered as a CIDv1 `k51...` id.
+ *
+ * Frozen invariants (changing ANY of these moves every live name irreversibly):
+ *   - the KDF is HKDF-SHA256;
+ *   - the `info` prefix is exactly `pinnace:ipns:v1:` (the version `v1` lives in
+ *     the `info` string, NOT in a separate parameter — a v2 scheme would use a
+ *     new prefix and never re-derive existing names);
+ *   - `keyId` is the SOLE per-site input, appended verbatim (UTF-8) to the info
+ *     prefix. The ENS name is mutable and MUST NEVER enter derivation, so this
+ *     surface has no `ensName` parameter at all;
+ *   - the HKDF `salt` is the RFC 5869 default (empty / zero-length). The spec
+ *     pins only ikm/info/length; an empty salt is the standard "no salt" case
+ *     and is pinned here so the contract is total (see ADR-0001);
+ *   - the 32 HKDF output bytes are used directly as the ed25519 seed (RFC 8032
+ *     private key), NOT hashed or expanded again.
+ *
+ * Key IMPORT into a node keystore and the "no client signing" boundary are a
+ * SEPARATE concern (the `key-import-publisher` task): this module derives the
+ * key + id only, with no node, network, or deploy.
+ */
+import {createPrivateKey, createPublicKey, hkdfSync} from 'node:crypto';
+
+/** The frozen `info`-string prefix. The version (`v1`) is encoded HERE. */
+export const IPNS_INFO_PREFIX = 'pinnace:ipns:v1:';
+
+/** The master secret: a UTF-8 string or raw bytes. Never read from a node/file. */
+export type Master = string | Uint8Array;
+
+/** Inputs to the derivation: the master secret and the frozen per-site keyId. */
+export interface DeriveIpnsInput {
+	/** The operator master secret (env-only in production; see config module). */
+	master: Master;
+	/**
+	 * The site's frozen, internal key identity — the SOLE per-site KDF input.
+	 * NOT the ENS name (which is mutable and never enters derivation).
+	 */
+	keyId: string;
+}
+
+/** A fully derived per-site IPNS key. */
+export interface DerivedIpnsKey {
+	/** The 32-byte ed25519 private seed (the raw HKDF output). */
+	readonly seed: Uint8Array;
+	/** The 32-byte raw ed25519 public key. */
+	readonly publicKey: Uint8Array;
+	/** The IPNS name: a CIDv1 (libp2p-key, base36) `k51...` id. */
+	readonly ipnsId: string;
+}
+
+/** PKCS#8 DER prefix wrapping a raw 32-byte ed25519 seed (RFC 8410). */
+const ED25519_PKCS8_PREFIX = Buffer.from(
+	'302e020100300506032b657004220420',
+	'hex',
+);
+
+/** base36 lowercase alphabet (multibase `k`), per the multiformats spec. */
+const BASE36_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+function toBytes(master: Master): Uint8Array {
+	return typeof master === 'string' ? new TextEncoder().encode(master) : master;
+}
+
+/**
+ * HKDF-SHA256(master, salt = "", info = IPNS_INFO_PREFIX + keyId, 32).
+ * Returns the 32-byte ed25519 seed. Frozen — see the module doc.
+ */
+function deriveSeed(master: Master, keyId: string): Uint8Array {
+	const info = new TextEncoder().encode(IPNS_INFO_PREFIX + keyId);
+	const seed = hkdfSync(
+		'sha256',
+		toBytes(master),
+		new Uint8Array(0), // RFC 5869 default (empty) salt — pinned by ADR-0001.
+		info,
+		32,
+	);
+	return new Uint8Array(seed);
+}
+
+/** Derive the raw 32-byte ed25519 public key from a 32-byte private seed. */
+function ed25519PublicKeyFromSeed(seed: Uint8Array): Uint8Array {
+	const pkcs8 = Buffer.concat([ED25519_PKCS8_PREFIX, Buffer.from(seed)]);
+	const priv = createPrivateKey({key: pkcs8, format: 'der', type: 'pkcs8'});
+	const spki = createPublicKey(priv).export({format: 'der', type: 'spki'});
+	// An ed25519 SPKI DER is a fixed 12-byte header + the 32 raw public bytes.
+	return new Uint8Array(spki.subarray(spki.length - 32));
+}
+
+/** Encode bytes as multibase-less base36 (lowercase), preserving leading zeros. */
+function base36Encode(bytes: Uint8Array): string {
+	const digits = [0];
+	for (const byte of bytes) {
+		let carry = byte;
+		for (let i = 0; i < digits.length; i++) {
+			const value = digits[i] * 256 + carry;
+			digits[i] = value % 36;
+			carry = (value / 36) | 0;
+		}
+		while (carry > 0) {
+			digits.push(carry % 36);
+			carry = (carry / 36) | 0;
+		}
+	}
+	let out = '';
+	for (let i = 0; i < bytes.length && bytes[i] === 0; i++) out += '0';
+	for (let i = digits.length - 1; i >= 0; i--)
+		out += BASE36_ALPHABET[digits[i]];
+	return out;
+}
+
+/**
+ * Encode a raw 32-byte ed25519 public key as an IPNS name (`k51...`).
+ *
+ * The name is a CIDv1 with the libp2p-key multicodec, whose multihash inlines
+ * the libp2p PublicKey protobuf via the identity hash (the default for
+ * ed25519), rendered in case-insensitive base36 with the `k` multibase prefix:
+ *
+ *   0x01 (CIDv1) 0x72 (libp2p-key)
+ *   0x00 (identity mh) 0x24 (len 36)
+ *   0x08 0x01 (protobuf field1 Type = Ed25519) 0x12 0x20 (field2 Data, len 32)
+ *   <32 raw public key bytes>
+ *
+ * @see https://specs.ipfs.tech/ipns/ipns-record/
+ */
+function ipnsIdFromPublicKey(publicKey: Uint8Array): string {
+	const pbHeader = Uint8Array.from([0x08, 0x01, 0x12, 0x20]);
+	const protobuf = new Uint8Array(pbHeader.length + publicKey.length);
+	protobuf.set(pbHeader, 0);
+	protobuf.set(publicKey, pbHeader.length);
+
+	const multihash = new Uint8Array(2 + protobuf.length);
+	multihash[0] = 0x00; // identity multihash function
+	multihash[1] = protobuf.length; // digest length (36)
+	multihash.set(protobuf, 2);
+
+	const cid = new Uint8Array(2 + multihash.length);
+	cid[0] = 0x01; // CIDv1
+	cid[1] = 0x72; // libp2p-key multicodec
+	cid.set(multihash, 2);
+
+	return 'k' + base36Encode(cid); // multibase base36 (lowercase) prefix.
+}
+
+/**
+ * Derive the full per-site IPNS key (seed + public key + `k51...` id) from the
+ * master secret and the frozen `keyId`. Pure and deterministic — no node,
+ * network, or deploy. This is the FROZEN CONTRACT; see the module doc.
+ */
+export function deriveIpnsKey(input: DeriveIpnsInput): DerivedIpnsKey {
+	const seed = deriveSeed(input.master, input.keyId);
+	const publicKey = ed25519PublicKeyFromSeed(seed);
+	const ipnsId = ipnsIdFromPublicKey(publicKey);
+	return {seed, publicKey, ipnsId};
+}
+
+/**
+ * Derive-and-print path (user story 22): return a site's `k51...` IPNS id from
+ * the master + keyId with NO deploy and NO network, so an operator can set the
+ * ENS contenthash to `ipns://<id>` before the first deploy. The id depends ONLY
+ * on (master, keyId) — never the ENS name.
+ */
+export function deriveIpnsId(input: DeriveIpnsInput): string {
+	return deriveIpnsKey(input).ipnsId;
+}