@smonn/ids 0.9.1 → 0.9.3

package/dist/cli.mjs

@@ -5,6 +5,40 @@ import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as
 import { t as createReverseTimestampId } from "./reverse-d5uEoIET.mjs";
 import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-BnRSC03a.mjs";
 import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-BI9UXnAm.mjs";
+//#region src/cli/key-io.ts
+function isKeyFormatError(result) {
+	return result !== "hex" && result !== "base64url";
+}
+function parseKeyFormatFlag(values) {
+	const fromFlag = values.get("--key-format");
+	if (fromFlag === void 0) return void 0;
+	if (fromFlag === "") return "--key-format requires a value";
+	if (fromFlag === "hex" || fromFlag === "base64url") return fromFlag;
+	return `--key-format must be hex or base64url, got '${fromFlag}'`;
+}
+function parseKeyFormatFromFlag(values) {
+	const fromFlag = parseKeyFormatFlag(values);
+	if (fromFlag === void 0) return "hex";
+	return fromFlag;
+}
+function parseKeyFormat(values, opts, facet) {
+	const fromFlag = parseKeyFormatFlag(values);
+	if (fromFlag !== void 0) return fromFlag;
+	const fromEnv = (opts.env ?? process.env)[facet.formatEnvVar];
+	if (fromEnv === void 0 || fromEnv === "") return "hex";
+	if (fromEnv === "hex" || fromEnv === "base64url") return fromEnv;
+	return `${facet.formatEnvVar} must be hex or base64url, got '${fromEnv}'`;
+}
+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`;
+	try {
+		return await facet.import(facet.decode(raw, format));
+	} catch (err) {
+		return err.message;
+	}
+}
+//#endregion
 //#region src/cli/codec-options.ts
 function codecOpts(opts) {
 	const o = { allowDuplicateBrand: true };
@@ -13,73 +47,6 @@ function codecOpts(opts) {
 	return o;
 }
 //#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 < msPerMinute) return "";
-	if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), "minute");
-	if (abs < msPerDay) return unit(Math.round(abs / msPerHour), "hour");
-	if (abs < msPerDay * 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/constants.ts
 const maxGenerateCount = 1e4;
 //#endregion
@@ -188,527 +155,84 @@ function isKindError(result) {
 	return result !== "u32" && result !== "i32" && result !== "u64" && result !== "i64";
 }
 //#endregion
-//#region src/cli/key-io.ts
-function isKeyFormatError(result) {
-	return result !== "hex" && result !== "base64url";
-}
-function parseKeyFormatFlag(values) {
-	const fromFlag = values.get("--key-format");
-	if (fromFlag === void 0) return void 0;
-	if (fromFlag === "") return "--key-format requires a value";
-	if (fromFlag === "hex" || fromFlag === "base64url") return fromFlag;
-	return `--key-format must be hex or base64url, got '${fromFlag}'`;
+//#region src/cli/format.ts
+function formatCliError(err) {
+	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
 }
-function parseKeyFormatFromFlag(values) {
-	const fromFlag = parseKeyFormatFlag(values);
-	if (fromFlag === void 0) return "hex";
-	return fromFlag;
+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 parseKeyFormat(values, opts, facet) {
-	const fromFlag = parseKeyFormatFlag(values);
-	if (fromFlag !== void 0) return fromFlag;
-	const fromEnv = (opts.env ?? process.env)[facet.formatEnvVar];
-	if (fromEnv === void 0 || fromEnv === "") return "hex";
-	if (fromEnv === "hex" || fromEnv === "base64url") return fromEnv;
-	return `${facet.formatEnvVar} must be hex or base64url, got '${fromEnv}'`;
+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");
 }
-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`;
-	try {
-		return await facet.import(facet.decode(raw, format));
-	} catch (err) {
-		return err.message;
-	}
+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");
 }
-//#endregion
-//#region src/cli/opaque-key.ts
-const opaqueFacet = {
-	envVar: "IDS_KEY",
-	formatEnvVar: "IDS_KEY_FORMAT",
-	decode: decodeOpaqueKey,
-	import: importOpaqueKey
-};
-function parseOpaqueKeyFormat(values, opts) {
-	return parseKeyFormat(values, opts, opaqueFacet);
+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(" + ")})`;
 }
-async function loadOpaqueKey(opts, format) {
-	return loadKey(opts, format, opaqueFacet);
+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}`;
 }
-//#endregion
-//#region src/cli/signing-key.ts
-const signingFacet = {
-	envVar: "IDS_SIGNING_KEY",
-	formatEnvVar: "IDS_SIGNING_KEY_FORMAT",
-	decode: decodeSigningKey,
-	import: importSigningKey
-};
-function parseSigningKeyFormat(values, opts) {
-	return parseKeyFormat(values, opts, signingFacet);
+function headUnits(abs) {
+	if (abs < msPerMinute) return "";
+	if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), "minute");
+	if (abs < msPerDay) return unit(Math.round(abs / msPerHour), "hour");
+	if (abs < msPerDay * 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")}`;
 }
-async function loadSigningKey(opts, format) {
-	return loadKey(opts, format, signingFacet);
+function unit(n, name) {
+	return `${n} ${n === 1 ? name : `${name}s`}`;
 }
 //#endregion
-//#region src/cli/commands/generate.ts
-function runGenerate(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args, /* @__PURE__ */ new Set([
-		"--count",
-		"-c",
-		"--bits",
-		"--key-format",
-		"--kind"
-	]));
-	const unsupported = unsupportedFlagForCommand("generate", flags, /* @__PURE__ */ new Set([
-		"--count",
-		"-c",
-		"--opaque",
-		"--reverse",
-		"--signed",
-		"--key-format"
-	]));
-	if (unsupported !== void 0) {
-		opts.stderr(unsupported + "\n");
-		return Promise.resolve(1);
-	}
-	if (errors[0] !== void 0) {
-		opts.stderr(errors[0] + "\n");
-		return Promise.resolve(1);
-	}
-	const extra = positionals[1];
-	if (extra !== void 0) {
-		opts.stderr(`unexpected argument: ${extra}\n`);
-		return Promise.resolve(1);
-	}
-	const [brand] = positionals;
-	const count = parseCount(values);
-	if (typeof count === "string") {
-		opts.stderr(count + "\n");
-		return Promise.resolve(1);
-	}
-	const opaque = flags.has("--opaque");
-	const reverse = flags.has("--reverse");
-	const signed = flags.has("--signed");
-	if (reverse && opaque) {
-		opts.stderr("cannot use --reverse and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && opaque) {
-		opts.stderr("cannot use --signed and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && reverse) {
-		opts.stderr("cannot use --signed and --reverse together\n");
-		return Promise.resolve(1);
-	}
-	if (!opaque && !signed && flags.has("--key-format")) {
-		opts.stderr("--key-format requires --opaque or --signed\n");
-		return Promise.resolve(1);
-	}
-	if (opaque) {
-		const format = parseOpaqueKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runOpaqueGenerate(brand ?? "", count, format, opts);
-	}
-	if (signed) {
-		const format = parseSigningKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runSignedGenerate(brand ?? "", count, format, opts);
-	}
-	if (reverse) {
-		let codec;
+//#region src/cli/variants.ts
+const timestampVariant = {
+	inspectMode: "readable",
+	construct(brand, opts) {
 		try {
-			codec = createReverseTimestampId(brand ?? "", codecOpts(opts));
+			return createTimestampId(brand, codecOpts(opts));
 		} catch (err) {
-			opts.stderr(formatCliError(err) + "\n");
-			return Promise.resolve(1);
+			return formatCliError(err);
 		}
-		for (let i = 0; i < count; i++) opts.stdout(codec.generate() + "\n");
-		return Promise.resolve(0);
-	}
-	let codec;
-	try {
-		codec = createTimestampId(brand ?? "", codecOpts(opts));
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return Promise.resolve(1);
-	}
-	for (let i = 0; i < count; i++) opts.stdout(codec.generate() + "\n");
-	return Promise.resolve(0);
-}
-async function runOpaqueGenerate(brand, count, format, opts) {
-	const keyResult = await loadOpaqueKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
-		return 1;
 	}
-	let codec;
-	try {
-		codec = createOpaqueTimestampId(brand, {
-			key: keyResult,
-			...codecOpts(opts)
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
-	return 0;
-}
-async function runSignedGenerate(brand, count, format, opts) {
-	const keyResult = await loadSigningKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
-		return 1;
-	}
-	let codec;
-	try {
-		codec = createSignedTimestampId(brand, {
-			keys: [keyResult],
-			allowDuplicateBrand: true,
-			...codecOpts(opts)
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
-	return 0;
-}
-//#endregion
-//#region src/cli/wrapping-key.ts
-const wrappingFacet = {
-	envVar: "IDS_WRAPPING_KEY",
-	formatEnvVar: "IDS_WRAPPING_KEY_FORMAT",
-	decode: decodeWrappingKey,
-	import: importWrappingKey
 };
-function parseWrappingKeyFormat(values, opts) {
-	return parseKeyFormat(values, opts, wrappingFacet);
-}
-async function loadWrappingKey(opts, format) {
-	return loadKey(opts, format, wrappingFacet);
-}
-//#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.",
-		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--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).",
-		"  keygen, k [--wrapped] [--signed] [--bits 128|192|256] [--key-format hex|base64url]",
-		"    Emit a random key for importOpaqueKey, importWrappingKey, or importSigningKey (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).",
-		""
-	].join("\n");
-}
-//#endregion
-//#region src/cli/commands/inspect.ts
-function runInspect(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args, /* @__PURE__ */ new Set([
-		"--count",
-		"-c",
-		"--bits",
-		"--key-format",
-		"--kind"
-	]));
-	const unsupported = unsupportedFlagForCommand("inspect", flags, /* @__PURE__ */ new Set([
-		"--opaque",
-		"--wrapped",
-		"--reverse",
-		"--signed",
-		"--kind",
-		"--key-format"
-	]));
-	if (unsupported !== void 0) {
-		opts.stderr(unsupported + "\n");
-		return Promise.resolve(1);
-	}
-	if (errors[0] !== void 0) {
-		opts.stderr(errors[0] + "\n");
-		return Promise.resolve(1);
-	}
-	const [input] = positionals;
-	if (input === void 0) {
-		opts.stderr(usage());
-		return Promise.resolve(1);
-	}
-	const extra = positionals[1];
-	if (extra !== void 0) {
-		opts.stderr(`unexpected argument: ${extra}\n`);
-		return Promise.resolve(1);
-	}
-	const opaque = flags.has("--opaque");
-	const wrapped = flags.has("--wrapped");
-	const reverse = flags.has("--reverse");
-	const signed = flags.has("--signed");
-	if (opaque && wrapped) {
-		opts.stderr("cannot use --wrapped and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (reverse && opaque) {
-		opts.stderr("cannot use --reverse and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (reverse && wrapped) {
-		opts.stderr("cannot use --reverse and --wrapped together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && opaque) {
-		opts.stderr("cannot use --signed and --opaque together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && wrapped) {
-		opts.stderr("cannot use --signed and --wrapped together\n");
-		return Promise.resolve(1);
-	}
-	if (signed && reverse) {
-		opts.stderr("cannot use --signed and --reverse together\n");
-		return Promise.resolve(1);
-	}
-	if (!opaque && !wrapped && !signed && flags.has("--key-format")) {
-		opts.stderr("--key-format requires --opaque, --wrapped, or --signed\n");
-		return Promise.resolve(1);
-	}
-	const brand = input.slice(0, 3).toLowerCase();
-	if (wrapped) {
-		const kind = parseKind(values);
-		if (kind === void 0) {
-			opts.stderr("--kind is required with --wrapped\n");
-			return Promise.resolve(1);
-		}
-		if (isKindError(kind)) {
-			opts.stderr(kind + "\n");
-			return Promise.resolve(1);
-		}
-		const format = parseWrappingKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runWrappedInspect(brand, input, kind, format, opts);
-	}
-	if (opaque) {
-		const format = parseOpaqueKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runOpaqueInspect(brand, input, format, opts);
-	}
-	if (signed) {
-		const format = parseSigningKeyFormat(values, opts);
-		if (isKeyFormatError(format)) {
-			opts.stderr(format + "\n");
-			return Promise.resolve(1);
-		}
-		return runSignedInspect(brand, input, format, opts);
-	}
-	if (reverse) {
-		let reverseCodec;
-		try {
-			reverseCodec = createReverseTimestampId(brand, codecOpts(opts));
-		} catch (err) {
-			opts.stderr(formatCliError(err) + "\n");
-			return Promise.resolve(1);
-		}
-		const reverseValidation = reverseCodec["~standard"].validate(input);
-		if (reverseValidation.issues) {
-			opts.stderr(reverseValidation.issues[0].message + "\n");
-			return Promise.resolve(1);
-		}
-		const reverseCanonical = reverseValidation.value;
-		const reverseTimestamp = reverseCodec.extractTimestamp(reverseCanonical);
-		const reverseNowMs = (opts.now ?? Date.now)();
-		opts.stdout(formatInspectOutput({
-			brand,
-			timestamp: reverseTimestamp,
-			canonical: reverseCanonical,
-			input,
-			nowMs: reverseNowMs
-		}));
-		return Promise.resolve(0);
-	}
-	let codec;
-	try {
-		codec = createTimestampId(brand, codecOpts(opts));
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return Promise.resolve(1);
-	}
-	const validation = codec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return Promise.resolve(1);
-	}
-	const canonical = validation.value;
-	const timestamp = codec.extractTimestamp(canonical);
-	const nowMs = (opts.now ?? Date.now)();
-	opts.stdout(formatInspectOutput({
-		brand,
-		timestamp,
-		canonical,
-		input,
-		nowMs
-	}));
-	return Promise.resolve(0);
-}
-async function runWrappedInspect(brand, input, kind, format, opts) {
-	const keyResult = await loadWrappingKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
-		return 1;
-	}
-	let codec;
-	try {
-		codec = createWrappedKeyId(brand, {
-			kind,
-			keys: [keyResult],
-			allowDuplicateBrand: true
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	const validation = codec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return 1;
-	}
-	const canonical = validation.value;
-	let lookupKey;
-	try {
-		lookupKey = await codec.unwrap(canonical);
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	opts.stdout(formatWrappedInspectOutput({
-		brand,
-		lookupKey,
-		canonical,
-		input
-	}));
-	return 0;
-}
-async function runOpaqueInspect(brand, input, format, opts) {
-	const keyResult = await loadOpaqueKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stderr(keyResult + "\n");
-		return 1;
-	}
-	let codec;
-	try {
-		codec = createOpaqueTimestampId(brand, {
-			key: keyResult,
-			...codecOpts(opts)
-		});
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	const validation = codec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return 1;
-	}
-	const canonical = validation.value;
-	const timestamp = await codec.extractTimestamp(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.stdout(formatInspectOutput({
-		brand,
-		timestamp,
-		canonical,
-		input,
-		nowMs
-	}));
-	return 0;
-}
-async function runSignedInspect(brand, input, format, opts) {
-	let structCodec;
-	try {
-		structCodec = createTimestampId(brand, codecOpts(opts));
-	} catch (err) {
-		opts.stderr(formatCliError(err) + "\n");
-		return 1;
-	}
-	const validation = structCodec["~standard"].validate(input);
-	if (validation.issues) {
-		opts.stderr(validation.issues[0].message + "\n");
-		return 1;
-	}
-	const canonical = validation.value;
-	const timestamp = structCodec.extractTimestamp(canonical);
-	const nowMs = (opts.now ?? Date.now)();
-	const keyResult = await loadSigningKey(opts, format);
-	if (typeof keyResult === "string") {
-		opts.stdout(formatSignedInspectOutput({
-			brand,
-			timestamp,
-			canonical,
-			input,
-			nowMs,
-			verification: "unavailable"
-		}));
-		opts.stderr(keyResult + "\n");
-		return 1;
-	}
-	const verifyResult = await createSignedTimestampId(brand, {
-		keys: [keyResult],
-		allowDuplicateBrand: true,
-		...codecOpts(opts)
-	}).safeVerify(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 */
-		if (verifyResult.error !== "verification_failed") {
-			opts.stderr(verifyResult.error + "\n");
-			return 1;
-		}
-		opts.stdout(formatSignedInspectOutput({
-			brand,
-			timestamp,
-			canonical,
-			input,
-			nowMs,
-			verification: "failed"
-		}));
-		opts.stderr("verification_failed: verification failed\n");
-		return 1;
-	}
-	opts.stdout(formatSignedInspectOutput({
-		brand,
-		timestamp,
-		canonical: verifyResult.id,
-		input,
-		nowMs,
-		verification: "ok"
-	}));
-	return 0;
-}
-//#endregion
-//#region src/cli/variants.ts
 const opaqueVariant = {
 	flag: "--opaque",
 	key: {
@@ -794,6 +318,25 @@ const conflictPriorityOrder = [
 	wrappedVariant,
 	opaqueVariant
 ];
+const generatePolicy = {
+	default: timestampVariant,
+	selectable: [
+		opaqueVariant,
+		reverseVariant,
+		signedVariant
+	],
+	intrinsicFlags: ["--count", "-c"]
+};
+const inspectPolicy = {
+	default: timestampVariant,
+	selectable: [
+		reverseVariant,
+		wrappedVariant,
+		opaqueVariant,
+		signedVariant
+	],
+	intrinsicFlags: []
+};
 const keygenPolicy = {
 	default: opaqueVariant,
 	selectable: [wrappedVariant, signedVariant],
@@ -813,11 +356,248 @@ function deriveAllowedFlags(policy) {
 	return flags;
 }
 function resolveVariant(policy, flags) {
-	const selected = conflictPriorityOrder.filter((v) => policy.selectable.includes(v) && v.flag !== void 0 && flags.has(v.flag));
+	const selected = conflictPriorityOrder.filter((v) => policy.selectable.some((d) => d === v) && v.flag !== void 0 && flags.has(v.flag));
 	if (selected.length === 0) return policy.default;
 	if (selected.length === 1) return selected[0];
 	return `cannot use ${selected[0].flag} and ${selected[1].flag} together`;
 }
+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;
+		const keyResult = await loadKey(opts, format, variant.key);
+		if (typeof keyResult === "string") return keyResult;
+		key = keyResult;
+	}
+	return variant.construct(brand, opts, key, values);
+}
+//#endregion
+//#region src/cli/commands/generate.ts
+async function runGenerate(args, opts) {
+	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;
+	}
+	if (errors[0] !== void 0) {
+		opts.stderr(errors[0] + "\n");
+		return 1;
+	}
+	const extra = positionals[1];
+	if (extra !== void 0) {
+		opts.stderr(`unexpected argument: ${extra}\n`);
+		return 1;
+	}
+	const [brand] = positionals;
+	const count = parseCount(values);
+	if (typeof count === "string") {
+		opts.stderr(count + "\n");
+		return 1;
+	}
+	const variant = resolveVariant(generatePolicy, flags);
+	if (typeof variant === "string") {
+		opts.stderr(variant + "\n");
+		return 1;
+	}
+	if (variant.key === void 0 && flags.has("--key-format")) {
+		opts.stderr("--key-format requires --opaque or --signed\n");
+		return 1;
+	}
+	const codec = await buildCodec(variant, brand ?? "", values, opts);
+	if (typeof codec === "string") {
+		opts.stderr(codec + "\n");
+		return 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.",
+		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--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).",
+		"  keygen, k [--wrapped] [--signed] [--bits 128|192|256] [--key-format hex|base64url]",
+		"    Emit a random key for importOpaqueKey, importWrappingKey, or importSigningKey (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).",
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/cli/commands/inspect.ts
+async function runInspect(args, opts) {
+	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;
+	}
+	if (errors[0] !== void 0) {
+		opts.stderr(errors[0] + "\n");
+		return 1;
+	}
+	const [input] = positionals;
+	if (input === void 0) {
+		opts.stderr(usage());
+		return 1;
+	}
+	const extra = positionals[1];
+	if (extra !== void 0) {
+		opts.stderr(`unexpected argument: ${extra}\n`);
+		return 1;
+	}
+	const variant = resolveVariant(inspectPolicy, flags);
+	if (typeof variant === "string") {
+		opts.stderr(variant + "\n");
+		return 1;
+	}
+	if (variant.key === void 0 && flags.has("--key-format")) {
+		opts.stderr("--key-format requires --opaque, --wrapped, or --signed\n");
+		return 1;
+	}
+	const brand = input.slice(0, 3).toLowerCase();
+	let verifyTimestamp;
+	let verifyCanonical;
+	let verifyNowMs;
+	if (variant.inspectMode === "verify") {
+		const fmtCheck = parseKeyFormat(values, opts, variant.key);
+		if (isKeyFormatError(fmtCheck)) {
+			opts.stderr(fmtCheck + "\n");
+			return 1;
+		}
+		let tsCodec;
+		try {
+			tsCodec = createTimestampId(brand, codecOpts(opts));
+		} catch (err) {
+			opts.stderr(formatCliError(err) + "\n");
+			return 1;
+		}
+		const structValidation = tsCodec["~standard"].validate(input);
+		if (structValidation.issues) {
+			opts.stderr(structValidation.issues[0].message + "\n");
+			return 1;
+		}
+		verifyCanonical = structValidation.value;
+		verifyTimestamp = tsCodec.extractTimestamp(verifyCanonical);
+		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;
+	}
+	let canonical;
+	if (variant.inspectMode !== "verify") {
+		const validation = codecOrError["~standard"].validate(input);
+		if (validation.issues) {
+			opts.stderr(validation.issues[0].message + "\n");
+			return 1;
+		}
+		canonical = validation.value;
+	}
+	switch (variant.inspectMode) {
+		case "readable": {
+			const timestamp = codecOrError.extractTimestamp(canonical);
+			const nowMs = (opts.now ?? Date.now)();
+			opts.stdout(formatInspectOutput({
+				brand,
+				timestamp,
+				canonical,
+				input,
+				nowMs
+			}));
+			return 0;
+		}
+		case "keyed-readable": {
+			const timestamp = await codecOrError.extractTimestamp(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.stdout(formatInspectOutput({
+				brand,
+				timestamp,
+				canonical,
+				input,
+				nowMs
+			}));
+			return 0;
+		}
+		case "unwrap": {
+			let lookupKey;
+			try {
+				lookupKey = await codecOrError.unwrap(canonical);
+			} catch (err) {
+				opts.stderr(formatCliError(err) + "\n");
+				return 1;
+			}
+			opts.stdout(formatWrappedInspectOutput({
+				brand,
+				lookupKey,
+				canonical,
+				input
+			}));
+			return 0;
+		}
+		case "verify": {
+			const verifyResult = await codecOrError.safeVerify(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 */
+				if (verifyResult.error !== "verification_failed") {
+					opts.stderr(verifyResult.error + "\n");
+					return 1;
+				}
+				opts.stdout(formatSignedInspectOutput({
+					brand,
+					timestamp: verifyTimestamp,
+					canonical: verifyCanonical,
+					input,
+					nowMs: verifyNowMs,
+					verification: "failed"
+				}));
+				opts.stderr("verification_failed: verification failed\n");
+				return 1;
+			}
+			opts.stdout(formatSignedInspectOutput({
+				brand,
+				timestamp: verifyTimestamp,
+				canonical: verifyResult.id,
+				input,
+				nowMs: verifyNowMs,
+				verification: "ok"
+			}));
+			return 0;
+		}
+	}
+}
 //#endregion
 //#region src/cli/commands/keygen.ts
 function runKeygen(args, opts) {