@smonn/ids 0.12.3 → 0.13.1

package/dist/cli.mjs

@@ -1,12 +1,85 @@
 #!/usr/bin/env node
 import { n as isIdsError } from "./error-Cp5qYZcv.mjs";
-import { t as createTimestampId } from "./timestamp-Cg9nRfnK.mjs";
-import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BQVNoIIh.mjs";
-import { t as createReverseTimestampId } from "./reverse-DsPd7Lco.mjs";
-import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-4h2BnlWx.mjs";
-import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-BQ-lNECo.mjs";
-import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-CknNw2wa.mjs";
+import { t as createTimestampId } from "./timestamp-CleAIdZI.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BW3Uzeeb.mjs";
+import { t as createReverseTimestampId } from "./reverse-BW8g_cln.mjs";
+import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-BTz3ZFYE.mjs";
+import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-DPlsv1x-.mjs";
+import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-DsGeXfk3.mjs";
+//#region src/cli/format.ts
+const invalidIdPrefix = "invalid_id: ";
+function formatCliError(err) {
+	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+}
+function formatWrappedInspectOutput(result) {
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:      ${result.brand}`,
+		`lookup-key: ${result.lookupKey.toString()}`,
+		`canonical:  ${result.canonical}`,
+		`input:      ${inputLine}`,
+		""
+	].join("\n");
+}
+function formatSignedInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
+	lines.push(`verification: ${result.verification}`);
+	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
+	return lines.join("\n");
+}
+function formatInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:     ${result.brand}`,
+		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
+		`canonical: ${result.canonical}`,
+		`input:     ${inputLine}`,
+		""
+	].join("\n");
+}
+function describeInputForm(input, canonical) {
+	if (input === canonical) return "canonical";
+	const notes = [];
+	if (input !== input.toLowerCase()) notes.push("was uppercase");
+	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
+	return `not canonical (${notes.join(" + ")})`;
+}
+const msPerMinute = 60 * 1e3;
+const msPerHour = 60 * msPerMinute;
+const msPerDay = 24 * msPerHour;
+const daysPerMonth = 30.44;
+const monthsPerYear = 12;
+function formatRelative(thenMs, nowMs) {
+	const diff = nowMs - thenMs;
+	const abs = Math.abs(diff);
+	const suffix = diff < 0 ? "from now" : "ago";
+	const head = headUnits(abs);
+	return head === "" ? "just now" : `${head} ${suffix}`;
+}
+function headUnits(abs) {
+	if (abs < 6e4) return "";
+	if (abs < 36e5) return unit(Math.round(abs / msPerMinute), "minute");
+	if (abs < 864e5) return unit(Math.round(abs / msPerHour), "hour");
+	if (abs < 864e5 * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
+	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
+	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
+	const years = Math.floor(totalMonths / monthsPerYear);
+	const months = totalMonths % monthsPerYear;
+	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
+}
+function unit(n, name) {
+	return `${n} ${n === 1 ? name : `${name}s`}`;
+}
+//#endregion
 //#region src/cli/key-io.ts
+function isLoadKeyError(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const kind = value.kind;
+	return kind === "missing" || kind === "import-failure";
+}
 function isKeyFormatError(result) {
 	return result !== "hex" && result !== "base64url";
 }
@@ -32,11 +105,17 @@ function parseKeyFormat(values, opts, facet) {
 }
 async function loadKey(opts, format, facet) {
 	const raw = (opts.env ?? process.env)[facet.envVar];
-	if (raw === void 0 || raw === "") return `missing ${facet.envVar} environment variable`;
+	if (raw === void 0 || raw === "") return {
+		kind: "missing",
+		message: `missing ${facet.envVar} environment variable`
+	};
 	try {
 		return await facet.import(facet.decode(raw, format));
 	} catch (err) {
-		return err.message;
+		return {
+			kind: "import-failure",
+			message: formatCliError(err)
+		};
 	}
 }
 //#endregion
@@ -167,76 +246,21 @@ function isNsError(result) {
 	return result === "--ns requires a value";
 }
 //#endregion
-//#region src/cli/format.ts
-function formatCliError(err) {
-	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
-}
-function formatWrappedInspectOutput(result) {
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:      ${result.brand}`,
-		`lookup-key: ${result.lookupKey.toString()}`,
-		`canonical:  ${result.canonical}`,
-		`input:      ${inputLine}`,
-		""
-	].join("\n");
-}
-function formatSignedInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
-	lines.push(`verification: ${result.verification}`);
-	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
-	return lines.join("\n");
-}
-function formatInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:     ${result.brand}`,
-		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
-		`canonical: ${result.canonical}`,
-		`input:     ${inputLine}`,
-		""
-	].join("\n");
-}
-function describeInputForm(input, canonical) {
-	if (input === canonical) return "canonical";
-	const notes = [];
-	if (input !== input.toLowerCase()) notes.push("was uppercase");
-	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
-	return `not canonical (${notes.join(" + ")})`;
-}
-const msPerMinute = 60 * 1e3;
-const msPerHour = 60 * msPerMinute;
-const msPerDay = 24 * msPerHour;
-const daysPerMonth = 30.44;
-const monthsPerYear = 12;
-function formatRelative(thenMs, nowMs) {
-	const diff = nowMs - thenMs;
-	const abs = Math.abs(diff);
-	const suffix = diff < 0 ? "from now" : "ago";
-	const head = headUnits(abs);
-	return head === "" ? "just now" : `${head} ${suffix}`;
-}
-function headUnits(abs) {
-	if (abs < 6e4) return "";
-	if (abs < 36e5) return unit(Math.round(abs / msPerMinute), "minute");
-	if (abs < 864e5) return unit(Math.round(abs / msPerHour), "hour");
-	if (abs < 864e5 * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
-	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
-	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
-	const years = Math.floor(totalMonths / monthsPerYear);
-	const months = totalMonths % monthsPerYear;
-	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
-}
-function unit(n, name) {
-	return `${n} ${n === 1 ? name : `${name}s`}`;
-}
-//#endregion
 //#region src/cli/variants.ts
+function standardValidate(codec, input) {
+	const result = codec["~standard"].validate(input);
+	if (result.issues) return { issue: invalidIdPrefix + result.issues[0].message };
+	return { value: result.value };
+}
 const timestampVariant = {
-	inspectMode: "readable",
+	inspect: {
+		mode: "readable",
+		note: "note: timestamp assumes a plaintext Timestamp ID; if this ID was Opaque-encoded, the timestamp is meaningless — re-run with --opaque and the correct IDS_KEY",
+		validate: standardValidate,
+		extractTimestamp(codec, id) {
+			return codec.extractTimestamp(id);
+		}
+	},
 	construct(brand, opts) {
 		try {
 			return createTimestampId(brand, codecOpts(opts));
@@ -254,7 +278,14 @@ const opaqueVariant = {
 		decode: decodeOpaqueKey,
 		import: importOpaqueKey
 	},
-	inspectMode: "keyed-readable",
+	inspect: {
+		mode: "keyed-readable",
+		note: "note: timestamp assumes IDS_KEY matches the key used at generation; a wrong key yields a plausible but incorrect timestamp",
+		validate: standardValidate,
+		extractTimestamp(codec, id) {
+			return codec.extractTimestamp(id);
+		}
+	},
 	construct(brand, opts, key) {
 		try {
 			return createOpaqueTimestampId(brand, {
@@ -268,7 +299,14 @@ const opaqueVariant = {
 };
 const reverseVariant = {
 	flag: "--reverse",
-	inspectMode: "readable",
+	inspect: {
+		mode: "readable",
+		note: "note: timestamp assumes a plaintext Timestamp ID; if this ID was Opaque-encoded, the timestamp is meaningless — re-run with --opaque and the correct IDS_KEY",
+		validate: standardValidate,
+		extractTimestamp(codec, id) {
+			return codec.extractTimestamp(id);
+		}
+	},
 	construct(brand, opts) {
 		try {
 			return createReverseTimestampId(brand, codecOpts(opts));
@@ -286,7 +324,13 @@ const wrappedVariant = {
 		decode: decodeWrappingKey,
 		import: importWrappingKey
 	},
-	inspectMode: "unwrap",
+	inspect: {
+		mode: "unwrap",
+		validate: standardValidate,
+		unwrap(codec, id) {
+			return codec.unwrap(id);
+		}
+	},
 	extraFlags: ["--kind"],
 	construct(brand, _opts, key, values) {
 		const kind = parseKind(values ?? /* @__PURE__ */ new Map());
@@ -312,7 +356,12 @@ const signedVariant = {
 		decode: decodeSigningKey,
 		import: importSigningKey
 	},
-	inspectMode: "verify",
+	inspect: {
+		mode: "verify",
+		safeVerify(codec, id) {
+			return codec.safeVerify(id);
+		}
+	},
 	construct(brand, opts, key) {
 		try {
 			return createSignedTimestampId(brand, {
@@ -333,7 +382,7 @@ const digestVariant = {
 		decode: decodeDigestKey,
 		import: importDigestKey
 	},
-	inspectMode: "unsupported",
+	inspect: { mode: "unsupported" },
 	extraFlags: ["--ns"],
 	construct(brand, opts, key, values) {
 		const ns = parseNs(values ?? /* @__PURE__ */ new Map());
@@ -347,8 +396,9 @@ const digestVariant = {
 			});
 			return {
 				safeParse: (v) => codec.safeParse(v),
-				generate() {
-					return (opts.readStdin ?? (() => Promise.resolve("")))().then((material) => codec.digest(material));
+				async generate() {
+					const material = await (opts.readStdin ?? (() => Promise.resolve("")))();
+					return codec.digest(material);
 				}
 			};
 		} catch (err) {
@@ -394,6 +444,11 @@ const keygenPolicy = {
 };
 //#endregion
 //#region src/cli/dispatch.ts
+function isCodecError(v) {
+	if (typeof v !== "object" || v === null) return false;
+	const kind = v.kind;
+	return (kind === "usage" || kind === "runtime") && "message" in v;
+}
 function deriveAllowedFlags(policy) {
 	const flags = new Set(policy.intrinsicFlags);
 	let hasKeyed = policy.default.key !== void 0;
@@ -415,12 +470,106 @@ async function buildCodec(variant, brand, values, opts) {
 	let key;
 	if (variant.key !== void 0) {
 		const format = parseKeyFormat(values, opts, variant.key);
-		if (isKeyFormatError(format)) return format;
+		if (isKeyFormatError(format)) return {
+			kind: "usage",
+			message: format
+		};
 		const keyResult = await loadKey(opts, format, variant.key);
-		if (typeof keyResult === "string") return keyResult;
+		if (isLoadKeyError(keyResult)) return {
+			kind: keyResult.kind === "missing" ? "usage" : "runtime",
+			message: keyResult.message
+		};
 		key = keyResult;
 	}
-	return variant.construct(brand, opts, key, values);
+	const codecOrError = variant.construct(brand, opts, key, values);
+	if (typeof codecOrError === "string") return {
+		kind: codecOrError.startsWith("--") ? "usage" : "runtime",
+		message: codecOrError
+	};
+	return codecOrError;
+}
+//#endregion
+//#region src/cli/usage.ts
+function usageInspect() {
+	return [
+		"Usage: ids inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
+		"",
+		"  Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
+		"  --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
+		"  --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
+		"  --kind is required with --wrapped: u32, i32, u64, or i64.",
+		"  --reverse decodes a Reverse Timestamp ID (newest-first sort order).",
+		"  --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
+		"  Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
+		"  Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
+		""
+	].join("\n");
+}
+function usageGenerate() {
+	return [
+		`Usage: ids generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]`,
+		"",
+		`  Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
+		"  --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
+		"  --reverse mints Reverse Timestamp IDs (newest-first sort order).",
+		"  --signed mints Signed Timestamp IDs; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
+		"  --digest mints a deterministic Digest ID from material read on stdin.",
+		"    --ns <ns> is required: the namespace domain separator (non-secret, non-empty).",
+		"    Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
+		"    Same material + ns + key always produces the same ID. Digest IDs are one-way.",
+		"    --count N > 1 is rejected: same material always produces the same ID.",
+		""
+	].join("\n");
+}
+function usageKeygen() {
+	return [
+		"Usage: ids keygen, k [--wrapped] [--signed] [--digest] [--bits 128|192|256] [--key-format hex|base64url]",
+		"",
+		"  Emit a random key for importOpaqueKey, importWrappingKey, importSigningKey, or importDigestKey (stdout only).",
+		"  --wrapped emits a wrapping key for importWrappingKey instead (IDS_WRAPPING_KEY).",
+		"  --signed emits a signing key for importSigningKey instead (IDS_SIGNING_KEY; hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
+		"  --digest emits a digest key for importDigestKey instead (IDS_DIGEST_KEY; hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
+		""
+	].join("\n");
+}
+function usage() {
+	return [
+		"Usage: ids <subcommand> [args]",
+		"",
+		"Subcommands:",
+		"  inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
+		"    Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
+		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
+		"    --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
+		"    --kind is required with --wrapped: u32, i32, u64, or i64.",
+		"    --reverse decodes a Reverse Timestamp ID (newest-first sort order).",
+		"    --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
+		"    Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
+		"    Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
+		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]",
+		`    Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
+		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
+		"    --reverse mints Reverse Timestamp IDs (newest-first sort order).",
+		"    --signed mints Signed Timestamp IDs; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
+		"    --digest mints a deterministic Digest ID from material read on stdin.",
+		"      --ns <ns> is required: the namespace domain separator (non-secret, non-empty).",
+		"      Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
+		"      Same material + ns + key always produces the same ID. Digest IDs are one-way.",
+		"      --count N > 1 is rejected: same material always produces the same ID.",
+		"  keygen, k [--wrapped] [--signed] [--digest] [--bits 128|192|256] [--key-format hex|base64url]",
+		"    Emit a random key for importOpaqueKey, importWrappingKey, importSigningKey, or importDigestKey (key on stdout; warning on stderr).",
+		"    Safe handling: redirect stdout to a 0600 file (e.g. ids keygen > key.hex && chmod 0600 key.hex);",
+		"    do not let the key appear in shell history or CI logs. A warning is printed to stderr on every run.",
+		"    --wrapped emits a wrapping key for importWrappingKey instead (IDS_WRAPPING_KEY).",
+		"    --signed emits a signing key for importSigningKey instead (IDS_SIGNING_KEY; hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
+		"    --digest emits a digest key for importDigestKey instead (IDS_DIGEST_KEY; hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
+		"",
+		"Exit codes:",
+		"  0  Success",
+		"  1  Runtime/operational error (codec failure, bad key material, verification failure)",
+		"  2  Usage/argument error (unknown subcommand, unrecognised flag, bad flag value, missing required arg)",
+		""
+	].join("\n");
 }
 //#endregion
 //#region src/cli/commands/generate.ts
@@ -437,131 +586,106 @@ function readProcessStdin() {
 	return stdinCache;
 }
 async function runGenerate(args, opts) {
+	if (args.includes("--help") || args.includes("-h")) {
+		opts.stdout(usageGenerate());
+		return 0;
+	}
 	const allowedFlags = deriveAllowedFlags(generatePolicy);
 	const selectorFlags = new Set(generatePolicy.selectable.map((v) => v.flag).filter((f) => f !== void 0));
 	const { flags, values, positionals, errors } = splitFlags(args, new Set([...allowedFlags].filter((f) => !selectorFlags.has(f))));
 	const unsupported = unsupportedFlagForCommand("generate", flags, allowedFlags);
 	if (unsupported !== void 0) {
 		opts.stderr(unsupported + "\n");
-		return 1;
+		return 2;
 	}
 	if (errors[0] !== void 0) {
 		opts.stderr(errors[0] + "\n");
-		return 1;
+		return 2;
 	}
 	const extra = positionals[1];
 	if (extra !== void 0) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
-		return 1;
+		return 2;
 	}
 	const [brand] = positionals;
 	const count = parseCount(values);
 	if (typeof count === "string") {
 		opts.stderr(count + "\n");
-		return 1;
+		return 2;
 	}
 	const variant = resolveVariant(generatePolicy, flags);
 	if (typeof variant === "string") {
 		opts.stderr(variant + "\n");
-		return 1;
+		return 2;
 	}
 	if (variant.key === void 0 && flags.has("--key-format")) {
 		opts.stderr("--key-format requires --opaque, --signed, or --digest\n");
-		return 1;
+		return 2;
 	}
 	if (flags.has("--digest") && count > 1) {
 		opts.stderr("--count N > 1 is rejected with --digest: same material always produces the same ID\n");
-		return 1;
+		return 2;
 	}
 	const optsWithStdin = {
 		...opts,
 		readStdin: opts.readStdin ?? readProcessStdin
 	};
 	const codec = await buildCodec(variant, brand ?? "", values, optsWithStdin);
-	if (typeof codec === "string") {
-		opts.stderr(codec + "\n");
-		return 1;
+	if (isCodecError(codec)) {
+		opts.stderr(codec.message + "\n");
+		return codec.kind === "usage" ? 2 : 1;
 	}
 	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
 	return 0;
 }
 //#endregion
-//#region src/cli/usage.ts
-function usage() {
-	return [
-		"Usage: ids <subcommand> [args]",
-		"",
-		"Subcommands:",
-		"  inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
-		"    Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
-		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
-		"    --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
-		"    --kind is required with --wrapped: u32, i32, u64, or i64.",
-		"    --reverse decodes a Reverse Timestamp ID (newest-first sort order).",
-		"    --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
-		"    Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
-		"    Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
-		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]",
-		`    Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
-		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
-		"    --reverse mints Reverse Timestamp IDs (newest-first sort order).",
-		"    --signed mints Signed Timestamp IDs; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
-		"    --digest mints a deterministic Digest ID from material read on stdin.",
-		"      --ns <ns> is required: the namespace domain separator (non-secret, non-empty).",
-		"      Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
-		"      Same material + ns + key always produces the same ID. Digest IDs are one-way.",
-		"      --count N > 1 is rejected: same material always produces the same ID.",
-		"  keygen, k [--wrapped] [--signed] [--digest] [--bits 128|192|256] [--key-format hex|base64url]",
-		"    Emit a random key for importOpaqueKey, importWrappingKey, importSigningKey, or importDigestKey (stdout only).",
-		"    --wrapped emits a wrapping key for importWrappingKey instead (IDS_WRAPPING_KEY).",
-		"    --signed emits a signing key for importSigningKey instead (IDS_SIGNING_KEY; hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
-		"    --digest emits a digest key for importDigestKey instead (IDS_DIGEST_KEY; hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
-		""
-	].join("\n");
-}
-//#endregion
 //#region src/cli/commands/inspect.ts
 async function runInspect(args, opts) {
+	if (args.includes("--help") || args.includes("-h")) {
+		opts.stdout(usageInspect());
+		return 0;
+	}
 	const allowedFlags = deriveAllowedFlags(inspectPolicy);
 	const selectorFlags = new Set(inspectPolicy.selectable.map((v) => v.flag).filter((f) => f !== void 0));
 	const { flags, values, positionals, errors } = splitFlags(args, new Set([...allowedFlags].filter((f) => !selectorFlags.has(f))));
 	const unsupported = unsupportedFlagForCommand("inspect", flags, allowedFlags);
 	if (unsupported !== void 0) {
 		opts.stderr(unsupported + "\n");
-		return 1;
+		return 2;
 	}
 	if (errors[0] !== void 0) {
 		opts.stderr(errors[0] + "\n");
-		return 1;
+		return 2;
 	}
 	const [input] = positionals;
 	if (input === void 0) {
-		opts.stderr(usage());
-		return 1;
+		opts.stderr(usageInspect());
+		return 2;
 	}
 	const extra = positionals[1];
 	if (extra !== void 0) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
-		return 1;
+		return 2;
 	}
 	const variant = resolveVariant(inspectPolicy, flags);
 	if (typeof variant === "string") {
 		opts.stderr(variant + "\n");
-		return 1;
+		return 2;
 	}
 	if (variant.key === void 0 && flags.has("--key-format")) {
 		opts.stderr("--key-format requires --opaque, --wrapped, or --signed\n");
-		return 1;
+		return 2;
 	}
 	const brand = input.slice(0, 3).toLowerCase();
+	const cap = variant.inspect;
 	let verifyTimestamp;
 	let verifyCanonical;
 	let verifyNowMs;
-	if (variant.inspectMode === "verify") {
+	if (cap.mode === "verify") {
 		const fmtCheck = parseKeyFormat(values, opts, variant.key);
 		if (isKeyFormatError(fmtCheck)) {
 			opts.stderr(fmtCheck + "\n");
-			return 1;
+			return 2;
 		}
 		let tsCodec;
 		try {
@@ -572,7 +696,7 @@ async function runInspect(args, opts) {
 		}
 		const structValidation = tsCodec["~standard"].validate(input);
 		if (structValidation.issues) {
-			opts.stderr(structValidation.issues[0].message + "\n");
+			opts.stderr(invalidIdPrefix + structValidation.issues[0].message + "\n");
 			return 1;
 		}
 		verifyCanonical = structValidation.value;
@@ -580,32 +704,36 @@ async function runInspect(args, opts) {
 		verifyNowMs = (opts.now ?? Date.now)();
 	}
 	const codecOrError = await buildCodec(variant, brand, values, opts);
-	if (typeof codecOrError === "string") {
-		if (variant.inspectMode === "verify") opts.stdout(formatSignedInspectOutput({
-			brand,
-			timestamp: verifyTimestamp,
-			canonical: verifyCanonical,
-			input,
-			nowMs: verifyNowMs,
-			verification: "unavailable"
-		}));
-		opts.stderr(codecOrError + "\n");
-		return 1;
+	if (isCodecError(codecOrError)) {
+		if (cap.mode === "verify") {
+			opts.stdout(formatSignedInspectOutput({
+				brand,
+				timestamp: verifyTimestamp,
+				canonical: verifyCanonical,
+				input,
+				nowMs: verifyNowMs,
+				verification: "unavailable"
+			}));
+			opts.stderr(codecOrError.message + "\n");
+			return 1;
+		}
+		opts.stderr(codecOrError.message + "\n");
+		return codecOrError.kind === "usage" ? 2 : 1;
 	}
 	let canonical;
-	if (variant.inspectMode !== "verify") {
-		const validation = codecOrError["~standard"].validate(input);
-		if (validation.issues) {
-			opts.stderr(validation.issues[0].message + "\n");
+	if (cap.mode !== "verify" && cap.mode !== "unsupported") {
+		const parsed = cap.validate(codecOrError, input);
+		if ("issue" in parsed) {
+			opts.stderr(parsed.issue + "\n");
 			return 1;
 		}
-		canonical = validation.value;
+		canonical = parsed.value;
 	}
-	switch (variant.inspectMode) {
+	switch (cap.mode) {
 		case "readable": {
-			const timestamp = codecOrError.extractTimestamp(canonical);
+			const timestamp = cap.extractTimestamp(codecOrError, canonical);
 			const nowMs = (opts.now ?? Date.now)();
-			opts.stderr("note: timestamp assumes a plaintext Timestamp ID; if this ID was Opaque-encoded, the timestamp is meaningless — re-run with --opaque and the correct IDS_KEY\n");
+			opts.stderr(cap.note + "\n");
 			opts.stdout(formatInspectOutput({
 				brand,
 				timestamp,
@@ -616,9 +744,9 @@ async function runInspect(args, opts) {
 			return 0;
 		}
 		case "keyed-readable": {
-			const timestamp = await codecOrError.extractTimestamp(canonical);
+			const timestamp = await cap.extractTimestamp(codecOrError, canonical);
 			const nowMs = (opts.now ?? Date.now)();
-			opts.stderr("note: timestamp assumes IDS_KEY matches the key used at generation; a wrong key yields a plausible but incorrect timestamp\n");
+			opts.stderr(cap.note + "\n");
 			opts.stdout(formatInspectOutput({
 				brand,
 				timestamp,
@@ -631,7 +759,7 @@ async function runInspect(args, opts) {
 		case "unwrap": {
 			let lookupKey;
 			try {
-				lookupKey = await codecOrError.unwrap(canonical);
+				lookupKey = await cap.unwrap(codecOrError, canonical);
 			} catch (err) {
 				opts.stderr(formatCliError(err) + "\n");
 				return 1;
@@ -645,7 +773,7 @@ async function runInspect(args, opts) {
 			return 0;
 		}
 		case "verify": {
-			const verifyResult = await codecOrError.safeVerify(input);
+			const verifyResult = await cap.safeVerify(codecOrError, input);
 			if (!verifyResult.ok) {
 				/* v8 ignore next 4 -- defensive: both codecs share the same wire parse so ParseError
 				is unreachable after the createTimestampId pre-validation above passes */
@@ -684,38 +812,42 @@ async function runInspect(args, opts) {
 }
 //#endregion
 //#region src/cli/commands/keygen.ts
-function runKeygen(args, opts) {
+async function runKeygen(args, opts) {
+	if (args.includes("--help") || args.includes("-h")) {
+		opts.stdout(usageKeygen());
+		return Promise.resolve(0);
+	}
 	const allowedFlags = deriveAllowedFlags(keygenPolicy);
 	const variantExtraFlags = new Set(keygenPolicy.selectable.flatMap((v) => v.extraFlags ?? []));
 	const { flags, values, positionals, errors } = splitFlags(args, allowedFlags);
 	const unsupported = unsupportedFlagForCommand("keygen", flags, new Set([...allowedFlags].filter((f) => !variantExtraFlags.has(f))));
 	if (unsupported !== void 0) {
 		opts.stderr(unsupported + "\n");
-		return Promise.resolve(1);
+		return Promise.resolve(2);
 	}
 	if (errors[0] !== void 0) {
 		opts.stderr(errors[0] + "\n");
-		return Promise.resolve(1);
+		return Promise.resolve(2);
 	}
 	const extra = positionals[0];
 	if (extra !== void 0) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
-		return Promise.resolve(1);
+		return Promise.resolve(2);
 	}
 	const variant = resolveVariant(keygenPolicy, flags);
 	if (typeof variant === "string") {
 		opts.stderr(variant + "\n");
-		return Promise.resolve(1);
+		return Promise.resolve(2);
 	}
 	const bits = parseBits(values);
 	if (typeof bits === "string") {
 		opts.stderr(bits + "\n");
-		return Promise.resolve(1);
+		return Promise.resolve(2);
 	}
 	const format = parseKeyFormatFromFlag(values);
 	if (isKeyFormatError(format)) {
 		opts.stderr(format + "\n");
-		return Promise.resolve(1);
+		return Promise.resolve(2);
 	}
 	/* v8 ignore next 4 -- defensive guard; all keygenPolicy variants have key defined */
 	if (variant.key === void 0) {
@@ -724,6 +856,7 @@ function runKeygen(args, opts) {
 	}
 	const bytes = new Uint8Array(bits / 8);
 	crypto.getRandomValues(bytes);
+	opts.stderr("Warning: secret key material — redirect to a file (chmod 0600) and avoid shell history.\n");
 	opts.stdout(variant.key.encode(bytes, format) + "\n");
 	return Promise.resolve(0);
 }
@@ -744,15 +877,20 @@ const commands = [
 	}
 ];
 async function run(opts) {
-	const [subcommand, ...rest] = opts.argv;
-	const command = commands.find((candidate) => candidate.names.includes(subcommand ?? ""));
-	if (command !== void 0) return command.run(rest, opts);
-	if (subcommand === void 0 || subcommand === "--help" || subcommand === "-h") {
-		opts.stdout(usage());
-		return 0;
+	try {
+		const [subcommand, ...rest] = opts.argv;
+		const command = commands.find((candidate) => candidate.names.includes(subcommand ?? ""));
+		if (command !== void 0) return await command.run(rest, opts);
+		if (subcommand === void 0 || subcommand === "--help" || subcommand === "-h") {
+			opts.stdout(usage());
+			return 0;
+		}
+		opts.stderr(usage());
+		return 2;
+	} catch (err) {
+		opts.stderr(formatCliError(err) + "\n");
+		return 1;
 	}
-	opts.stderr(usage());
-	return 1;
 }
 //#endregion
 //#region bin/cli.ts