@smonn/ids 0.12.2 → 0.13.0

package/README.md

@@ -44,8 +44,11 @@ JSON Schema.
 ## Choosing a codec
 
 All six codecs share the same `<brand>_<26 chars>` wire shape but make different
-trade-offs. They are wire-indistinguishable, so codec choice is a per-brand
-commitment.
+trade-offs. They are wire-indistinguishable — `safeParse`, `is`, and `parse`
+cannot distinguish an Opaque Timestamp ID from a Timestamp ID at runtime.
+Cross-codec confusion is undetectable by the library; the consumer is
+responsible for routing a given ID to the correct codec for the brand. Codec
+choice is therefore a per-brand commitment.
 
 | Codec             | Import               | Sort direction            | Key required       | Timestamp extractable      |
 | ----------------- | -------------------- | ------------------------- | ------------------ | -------------------------- |
@@ -89,6 +92,33 @@ it slots into Zod, Valibot, ArkType, tRPC, and any validator-aware library.
   known creation time can compute the epoch offset. Use the Opaque Timestamp
   codec to hide creation time per-ID.
 
+## API surface
+
+Exports from the main `@smonn/ids` entry point only. Codec-specific subpath
+exports (`@smonn/ids/reverse`, `@smonn/ids/opaque`, `@smonn/ids/signed`,
+`@smonn/ids/wrapped`, `@smonn/ids/digest`) and adapter subpaths are not listed
+here.
+
+### Types
+
+- `Id<Brand>` — Canonical branded ID string for `Brand`; produced by `generate()` and `safeParse()`.
+- `ParseError` — Parse failure reason string (`"not_string"`, `"invalid_prefix"`, or `"invalid_base32"`) returned by `safeParse()`.
+- `ParseResult<Brand>` — Discriminated union returned by `safeParse()`: `{ ok: true; id: Id<Brand> }` or `{ ok: false; error: ParseError }`.
+- `JsonSchema` — Shape of the object returned by a codec's `toJsonSchema()`.
+- `IdsErrorCode` — String-literal union of the eleven stable error codes carried by `IdsError`.
+- `TimestampCodec<Brand>` — Interface of a brand-scoped Timestamp codec instance returned by `createTimestampId()`.
+- `TimestampOptions` — Construction options for `createTimestampId()`: `now`, `rng`, and `allowDuplicateBrand`.
+- `ValidBrand<S>` — Compile-time validation that `S` is a well-formed brand (three lowercase `a–z` characters); intersect it with a codec constructor's brand parameter (`brand: Brand & ValidBrand<Brand>`) to reject malformed brands at the type level.
+
+### Classes
+
+- `IdsError` — Single error class thrown by caller-reachable failures; carries a stable `code: IdsErrorCode`. Use `isIdsError()` rather than `instanceof` to detect across realms.
+
+### Functions
+
+- `isIdsError(value)` — Type guard for `IdsError`; uses an internal brand to survive ESM/CJS dual-package duplication where bare `instanceof` fails.
+- `createTimestampId(brand, options?)` — Creates a Timestamp codec for `brand` (three lowercase `a–z` characters).
+
 ## Links
 
 - **[Documentation](https://ids.smonn.se)** — full guides, API reference, and playground

package/dist/{adapter-types-CdYJM6Sf.d.mts → adapter-types-CIc-4O-P.d.mts}

@@ -1,4 +1,4 @@
-import { i as ParseResult } from "./types-g7CiQDyE.mjs";
+import { i as ParseResult } from "./types-wplmOgOK.mjs";
 
 //#region src/adapters/adapter-types.d.ts
 /** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */
@@ -17,4 +17,4 @@ type IdCodec<Brand extends string> = {
 type IdColumnCodec<Brand extends string> = IdCodec<Brand>;
 //#endregion
 export { IdColumnCodec as n, IdParamFailure as r, IdCodec as t };
-//# sourceMappingURL=adapter-types-CdYJM6Sf.d.mts.map
+//# sourceMappingURL=adapter-types-CIc-4O-P.d.mts.map

package/dist/{adapter-types-CdYJM6Sf.d.mts.map → adapter-types-CIc-4O-P.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"adapter-types-CdYJM6Sf.d.mts","names":[],"sources":["../src/adapters/adapter-types.ts"],"mappings":";;;;KAIY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,OAAA;EACV,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;AADzC;AAAA,KAKY,aAAA,yBAAsC,OAAA,CAAQ,KAAA"}
+{"version":3,"file":"adapter-types-CIc-4O-P.d.mts","names":[],"sources":["../src/adapters/adapter-types.ts"],"mappings":";;;;KAIY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,OAAA;EACV,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;AADzC;AAAA,KAKY,aAAA,yBAAsC,OAAA,CAAQ,KAAA"}

package/dist/cli.mjs

@@ -1,12 +1,17 @@
 #!/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-YPd58344.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-D7y5cgzT.mjs";
+import { t as createReverseTimestampId } from "./reverse-DrAofYWV.mjs";
+import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-B2Aa3zMg.mjs";
+import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-BjmVzuYc.mjs";
+import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-Drnof-l_.mjs";
 //#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 +37,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: err.message
+		};
 	}
 }
 //#endregion
@@ -235,8 +246,20 @@ function unit(n, name) {
 }
 //#endregion
 //#region src/cli/variants.ts
+function standardValidate(codec, input) {
+	const result = codec["~standard"].validate(input);
+	if (result.issues) return { issue: 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 +277,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 +298,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 +323,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 +355,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 +381,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 +395,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 +443,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 +469,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 +585,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 {
@@ -580,32 +703,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 +743,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 +758,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 +772,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 +811,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 +855,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);
 }
@@ -752,7 +884,7 @@ async function run(opts) {
 		return 0;
 	}
 	opts.stderr(usage());
-	return 1;
+	return 2;
 }
 //#endregion
 //#region bin/cli.ts