@smonn/ids 0.9.0 → 0.9.1

package/README.md

@@ -105,7 +105,7 @@ try {
 | `empty_keyring`           | the wrapping keyring is empty                   | `createWrappedKeyId({ keys })`                            | Supply at least one `WrappingKey`          |
 | `duplicate_keyring_entry` | two keyring entries share the same raw secret   | `createWrappedKeyId({ keys })`                            | Deduplicate the key list                   |
 | `invalid_lookup_key`      | lookup key is out of range or the wrong JS type | `wrap(lookupKey)`                                         | Check the kind's range and JS type         |
-| `verification_failed`     | no keyring entry verifies the payload tag       | `unwrap(id)`                                              | Check keyring; tamper or wrong key         |
+| `verification_failed`     | no keyring entry verifies the payload tag       | `unwrap(id)`, `verify(id)`                                | Check keyring; tamper or wrong key         |
 | `invalid_id`              | string is not a valid ID for this brand         | `parse()`, ORM adapter read paths                         | Use `safeParse()` for untrusted input      |
 
 `invalid_id` carries the originating `ParseError` string on `cause` — check `err.cause` for `"not_string"`, `"invalid_prefix"`, or `"invalid_base32"` when you need to distinguish the failure mode.
@@ -905,7 +905,7 @@ Brand-agnostic subcommands, no install required. Run `npx @smonn/ids --help` for
 
 ### `inspect` (`i`)
 
-Decode an ID and print brand, timestamp, canonical form, and whether the input was already canonical.
+Decode an ID and print brand, timestamp (or lookup key), canonical form, and whether the input was already canonical.
 
 ```bash
 $ npx @smonn/ids inspect usr_01h7b3k9rqxn1cw3p9r8t2sgkz
@@ -915,13 +915,34 @@ canonical: usr_01h7b3k9rqxn1cw3p9r8t2sgkz
 input:     canonical
 ```
 
-Accepts non-canonical input (uppercase, Crockford aliases). Assumes the **Timestamp codec** — if the brand uses the **Opaque Timestamp codec**, pass `--opaque` and set `IDS_KEY` (below); otherwise the timestamp line is meaningless garbage.
+Accepts non-canonical input (uppercase, Crockford aliases). Pass the flag that matches the codec variant used at generation — without a flag, the **Timestamp codec** is assumed.
+
+| Flag                   | Codec variant           | Env var                      | Notes                                                                                           |
+| ---------------------- | ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| _(none)_               | Timestamp codec         | —                            | Timestamp readable directly                                                                     |
+| `--opaque`             | Opaque Timestamp codec  | `IDS_KEY`                    | Wrong key yields plausible-but-wrong timestamp, not an error (see [CONTEXT.md](./CONTEXT.md))   |
+| `--reverse`            | Reverse Timestamp codec | —                            | No key required; timestamp decoded from inverted bytes                                          |
+| `--wrapped --kind <k>` | Wrapped key codec       | `IDS_WRAPPING_KEY`           | `--kind` required: `u32`, `i32`, `u64`, `i64`; prints `lookup-key`                              |
+| `--signed`             | Signed Timestamp codec  | `IDS_SIGNING_KEY` (optional) | Without key: prints timestamp only. With key: adds `verification: ok` or `verification: failed` |
+
+Key format defaults to `hex` for all keyed modes; override with `--key-format hex|base64url` or the matching `_FORMAT` env var (see [Environment variables](#environment-variables) below).
 
 ```bash
+# Opaque Timestamp (IDS_KEY required):
 IDS_KEY=<hex-or-base64url-key> npx @smonn/ids inspect inv_… --opaque
-```
 
-Prints the decrypted timestamp **assuming `IDS_KEY` matches the key used at generation** — a well-formed but wrong key yields a plausible but incorrect timestamp, not an error (see [CONTEXT.md](./CONTEXT.md)).
+# Wrapped key (IDS_WRAPPING_KEY and --kind required):
+IDS_WRAPPING_KEY=<hex-or-base64url-key> npx @smonn/ids inspect item_… --wrapped --kind u64
+
+# Reverse Timestamp (no key):
+npx @smonn/ids inspect feed_… --reverse
+
+# Signed Timestamp — timestamp only (no key):
+npx @smonn/ids inspect evt_… --signed
+
+# Signed Timestamp — with verification:
+IDS_SIGNING_KEY=<hex-or-base64url-key> npx @smonn/ids inspect evt_… --signed
+```
 
 ### `generate` (`g`)
 
@@ -934,15 +955,29 @@ usr_…
 usr_…
 ```
 
-Flags: `--count` / `-c N` (default 1, max 10000). Uses the Timestamp codec unless `--opaque` is set.
+Flags: `--count` / `-c N` (default 1, max 10000). Uses the Timestamp codec unless a mode flag is set.
+
+| Flag        | Codec variant           | Env var           |
+| ----------- | ----------------------- | ----------------- |
+| _(none)_    | Timestamp codec         | —                 |
+| `--opaque`  | Opaque Timestamp codec  | `IDS_KEY`         |
+| `--reverse` | Reverse Timestamp codec | —                 |
+| `--signed`  | Signed Timestamp codec  | `IDS_SIGNING_KEY` |
 
 ```bash
+# Opaque Timestamp:
 IDS_KEY=<hex-or-base64url-key> npx @smonn/ids generate inv --opaque --count 2
+
+# Reverse Timestamp (newest-first sort order):
+npx @smonn/ids generate feed --reverse --count 5
+
+# Signed Timestamp:
+IDS_SIGNING_KEY=<hex-or-base64url-key> npx @smonn/ids generate evt --signed
 ```
 
 ### `keygen` (`k`)
 
-Emit a random Opaque key to stdout (a secret — do not log or commit). Default: 256-bit hex.
+Emit a random key to stdout — for use with `importOpaqueKey`, `importWrappingKey`, or `importSigningKey` (a secret — do not log or commit). Default: 256-bit hex for the Opaque key domain.
 
 ```bash
 $ npx @smonn/ids keygen
@@ -952,15 +987,53 @@ $ npx @smonn/ids keygen --bits 128 --key-format base64url
 AbCdEf…
 ```
 
-Flags: `--bits 128|192|256` (default 256), `--key-format hex|base64url` (default `hex`). `IDS_KEY_FORMAT` does not affect `keygen` — only `--key-format` on the command line. Output round-trips through `decodeOpaqueKey` / `importOpaqueKey`.
+| Flag        | Key domain | Intended for       | Import function     |
+| ----------- | ---------- | ------------------ | ------------------- |
+| _(none)_    | Opaque     | `IDS_KEY`          | `importOpaqueKey`   |
+| `--wrapped` | Wrapping   | `IDS_WRAPPING_KEY` | `importWrappingKey` |
+| `--signed`  | Signing    | `IDS_SIGNING_KEY`  | `importSigningKey`  |
+
+Flags: `--bits 128|192|256` (default 256), `--key-format hex|base64url` (default `hex`). Key-format env vars do not affect `keygen` — only `--key-format` on the command line.
+
+```bash
+# Wrapping key:
+npx @smonn/ids keygen --wrapped
+
+# Signing key (base64url):
+npx @smonn/ids keygen --signed --key-format base64url
+```
+
+### Environment variables
+
+All keyed modes read secrets from environment variables — not from argv (argv leaks via `ps` and shell history). Missing or malformed key env vars print a clear stderr message and exit non-zero. Invalid input prints the parse error to stderr and exits non-zero.
+
+| Env var                   | Used by                       | Default format |
+| ------------------------- | ----------------------------- | -------------- |
+| `IDS_KEY`                 | `--opaque`                    | `hex`          |
+| `IDS_KEY_FORMAT`          | `--opaque` (format override)  | —              |
+| `IDS_WRAPPING_KEY`        | `--wrapped`                   | `hex`          |
+| `IDS_WRAPPING_KEY_FORMAT` | `--wrapped` (format override) | —              |
+| `IDS_SIGNING_KEY`         | `--signed`                    | `hex`          |
+| `IDS_SIGNING_KEY_FORMAT`  | `--signed` (format override)  | —              |
+
+Key format defaults to `hex` for all modes; override per-invocation with `--key-format hex|base64url` or set the matching `_FORMAT` env var for a session default. `--key-format` on the command line wins over the env var. Key-format env vars do not affect `keygen` output — only `--key-format` applies there.
+
+### Signed mode (`--signed`)
+
+`generate --signed` and `inspect --signed` read the HMAC signing key from `IDS_SIGNING_KEY` — not from argv.
 
-### Opaque mode (`--opaque`)
+`inspect --signed` always emits a full timestamp report on stdout and carries a `verification:` line with a three-value verdict:
 
-`generate --opaque` and `inspect --opaque` read the AES key from the `IDS_KEY` environment variable — not from argv (argv leaks via `ps` and shell history). Missing or malformed `IDS_KEY` prints a clear stderr message and exits non-zero.
+| Case          | stdout                               | stderr                                         | exit |
+| ------------- | ------------------------------------ | ---------------------------------------------- | ---- |
+| Correct key   | report + `verification: ok`          | —                                              | 0    |
+| Tag mismatch  | report + `verification: failed`      | `verification_failed: <message>`               | 1    |
+| Key missing   | report + `verification: unavailable` | `missing IDS_SIGNING_KEY environment variable` | 1    |
+| Key malformed | report + `verification: unavailable` | specific key diagnostic                        | 1    |
 
-Key format defaults to `hex`; override per-invocation with `--key-format` or set `IDS_KEY_FORMAT=hex|base64url` for a session default. `--key-format` on the command line wins over `IDS_KEY_FORMAT`.
+The timestamp is always readable (Signed Timestamp IDs carry a plaintext timestamp), so `inspect` without `--signed` also decodes it — but without verification.
 
-Invalid input prints the parse error to stderr and exits non-zero.
+Key format defaults to `hex`; override with `--key-format` or `IDS_SIGNING_KEY_FORMAT`. `--key-format` wins over the environment variable.
 
 ## Design
 

package/dist/cli.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { n as isIdsError } from "./error-Cp5qYZcv.mjs";
-import { t as createTimestampId } from "./timestamp-BjIMQkJf.mjs";
-import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BQOlZ2oD.mjs";
-import { t as createReverseTimestampId } from "./reverse-C12D1btB.mjs";
-import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-CwqKTFaQ.mjs";
-import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-DKOsN_dq.mjs";
+import { t as createTimestampId } from "./timestamp-BbZL8hwg.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BpqxV8oB.mjs";
+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/codec-options.ts
 function codecOpts(opts) {
 	const o = { allowDuplicateBrand: true };
@@ -31,7 +31,7 @@ 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})`];
-	if (result.verification !== void 0) lines.push(`verification: ${result.verification}`);
+	lines.push(`verification: ${result.verification}`);
 	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
 	return lines.join("\n");
 }
@@ -95,19 +95,12 @@ function splitFlagToken(arg) {
 		inlineValue: arg.slice(eq + 1)
 	};
 }
-function splitFlags(args) {
+function splitFlags(args, valueFlags) {
 	const flags = /* @__PURE__ */ new Set();
 	const values = /* @__PURE__ */ new Map();
 	const positionals = [];
 	const errors = [];
 	const seenFlags = /* @__PURE__ */ new Set();
-	const valueFlags = new Set([
-		"--count",
-		"-c",
-		"--bits",
-		"--key-format",
-		"--kind"
-	]);
 	const addFlag = (flag) => {
 		const canonical = canonicalFlag(flag);
 		if (seenFlags.has(canonical)) errors.push(`duplicate flag: ${canonical}`);
@@ -117,11 +110,6 @@ function splitFlags(args) {
 	for (let i = 0; i < args.length; i++) {
 		const raw = args[i];
 		const { flag, inlineValue } = splitFlagToken(raw);
-		if (flag === "--opaque" || flag === "--wrapped" || flag === "--reverse" || flag === "--signed") {
-			addFlag(flag);
-			if (inlineValue !== void 0) errors.push(`flag does not take a value: ${flag}`);
-			continue;
-		}
 		if (valueFlags.has(flag)) {
 			if (inlineValue !== void 0) {
 				addFlag(flag);
@@ -141,6 +129,7 @@ function splitFlags(args) {
 		}
 		if (flag.startsWith("-")) {
 			addFlag(flag);
+			if (inlineValue !== void 0) errors.push(`flag does not take a value: ${flag}`);
 			continue;
 		}
 		positionals.push(raw);
@@ -156,7 +145,7 @@ function canonicalFlag(flag) {
 	if (flag === "-c") return "--count";
 	return flag;
 }
-const knownFlags = new Set([
+const knownFlags = /* @__PURE__ */ new Set([
 	"--opaque",
 	"--wrapped",
 	"--reverse",
@@ -240,9 +229,6 @@ const opaqueFacet = {
 	decode: decodeOpaqueKey,
 	import: importOpaqueKey
 };
-function parseKeygenFormat(values) {
-	return parseKeyFormatFromFlag(values);
-}
 function parseOpaqueKeyFormat(values, opts) {
 	return parseKeyFormat(values, opts, opaqueFacet);
 }
@@ -266,8 +252,14 @@ async function loadSigningKey(opts, format) {
 //#endregion
 //#region src/cli/commands/generate.ts
 function runGenerate(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args);
-	const unsupported = unsupportedFlagForCommand("generate", flags, new Set([
+	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",
@@ -433,8 +425,14 @@ function usage() {
 //#endregion
 //#region src/cli/commands/inspect.ts
 function runInspect(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args);
-	const unsupported = unsupportedFlagForCommand("inspect", flags, new Set([
+	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",
@@ -663,18 +661,16 @@ async function runSignedInspect(brand, input, format, opts) {
 	const canonical = validation.value;
 	const timestamp = structCodec.extractTimestamp(canonical);
 	const nowMs = (opts.now ?? Date.now)();
-	if ((opts.env ?? process.env).IDS_SIGNING_KEY === void 0) {
+	const keyResult = await loadSigningKey(opts, format);
+	if (typeof keyResult === "string") {
 		opts.stdout(formatSignedInspectOutput({
 			brand,
 			timestamp,
 			canonical,
 			input,
-			nowMs
+			nowMs,
+			verification: "unavailable"
 		}));
-		return 0;
-	}
-	const keyResult = await loadSigningKey(opts, format);
-	if (typeof keyResult === "string") {
 		opts.stderr(keyResult + "\n");
 		return 1;
 	}
@@ -698,6 +694,7 @@ async function runSignedInspect(brand, input, format, opts) {
 			nowMs,
 			verification: "failed"
 		}));
+		opts.stderr("verification_failed: verification failed\n");
 		return 1;
 	}
 	opts.stdout(formatSignedInspectOutput({
@@ -711,15 +708,123 @@ async function runSignedInspect(brand, input, format, opts) {
 	return 0;
 }
 //#endregion
+//#region src/cli/variants.ts
+const opaqueVariant = {
+	flag: "--opaque",
+	key: {
+		envVar: "IDS_KEY",
+		formatEnvVar: "IDS_KEY_FORMAT",
+		encode: encodeOpaqueKey,
+		decode: decodeOpaqueKey,
+		import: importOpaqueKey
+	},
+	inspectMode: "keyed-readable",
+	construct(brand, opts, key) {
+		try {
+			return createOpaqueTimestampId(brand, {
+				key,
+				...codecOpts(opts)
+			});
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const reverseVariant = {
+	flag: "--reverse",
+	inspectMode: "readable",
+	construct(brand, opts) {
+		try {
+			return createReverseTimestampId(brand, codecOpts(opts));
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const wrappedVariant = {
+	flag: "--wrapped",
+	key: {
+		envVar: "IDS_WRAPPING_KEY",
+		formatEnvVar: "IDS_WRAPPING_KEY_FORMAT",
+		encode: encodeWrappingKey,
+		decode: decodeWrappingKey,
+		import: importWrappingKey
+	},
+	inspectMode: "unwrap",
+	extraFlags: ["--kind"],
+	construct(brand, _opts, key, values) {
+		const kind = parseKind(values ?? /* @__PURE__ */ new Map());
+		if (kind === void 0) return "--kind is required with --wrapped";
+		if (isKindError(kind)) return kind;
+		try {
+			return createWrappedKeyId(brand, {
+				kind,
+				keys: [key],
+				allowDuplicateBrand: true
+			});
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const signedVariant = {
+	flag: "--signed",
+	key: {
+		envVar: "IDS_SIGNING_KEY",
+		formatEnvVar: "IDS_SIGNING_KEY_FORMAT",
+		encode: encodeSigningKey,
+		decode: decodeSigningKey,
+		import: importSigningKey
+	},
+	inspectMode: "verify",
+	construct(brand, opts, key) {
+		try {
+			return createSignedTimestampId(brand, {
+				keys: [key],
+				...codecOpts(opts)
+			});
+		} catch (err) {
+			return formatCliError(err);
+		}
+	}
+};
+const conflictPriorityOrder = [
+	signedVariant,
+	reverseVariant,
+	wrappedVariant,
+	opaqueVariant
+];
+const keygenPolicy = {
+	default: opaqueVariant,
+	selectable: [wrappedVariant, signedVariant],
+	intrinsicFlags: ["--bits"]
+};
+//#endregion
+//#region src/cli/dispatch.ts
+function deriveAllowedFlags(policy) {
+	const flags = new Set(policy.intrinsicFlags);
+	let hasKeyed = policy.default.key !== void 0;
+	for (const v of policy.selectable) {
+		if (v.flag !== void 0) flags.add(v.flag);
+		if (v.key !== void 0) hasKeyed = true;
+		if (v.extraFlags !== void 0) for (const f of v.extraFlags) flags.add(f);
+	}
+	if (hasKeyed) flags.add("--key-format");
+	return flags;
+}
+function resolveVariant(policy, flags) {
+	const selected = conflictPriorityOrder.filter((v) => policy.selectable.includes(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`;
+}
+//#endregion
 //#region src/cli/commands/keygen.ts
 function runKeygen(args, opts) {
-	const { flags, values, positionals, errors } = splitFlags(args);
-	const unsupported = unsupportedFlagForCommand("keygen", flags, new Set([
-		"--signed",
-		"--wrapped",
-		"--bits",
-		"--key-format"
-	]));
+	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);
@@ -733,10 +838,9 @@ function runKeygen(args, opts) {
 		opts.stderr(`unexpected argument: ${extra}\n`);
 		return Promise.resolve(1);
 	}
-	const signed = flags.has("--signed");
-	const wrapped = flags.has("--wrapped");
-	if (signed && wrapped) {
-		opts.stderr("cannot use --signed and --wrapped together\n");
+	const variant = resolveVariant(keygenPolicy, flags);
+	if (typeof variant === "string") {
+		opts.stderr(variant + "\n");
 		return Promise.resolve(1);
 	}
 	const bits = parseBits(values);
@@ -744,18 +848,19 @@ function runKeygen(args, opts) {
 		opts.stderr(bits + "\n");
 		return Promise.resolve(1);
 	}
-	const format = parseKeygenFormat(values);
+	const format = parseKeyFormatFromFlag(values);
 	if (isKeyFormatError(format)) {
 		opts.stderr(format + "\n");
 		return Promise.resolve(1);
 	}
+	/* v8 ignore next 4 -- defensive guard; all keygenPolicy variants have key defined */
+	if (variant.key === void 0) {
+		opts.stderr("internal: keygen policy variant has no key facet\n");
+		return Promise.resolve(1);
+	}
 	const bytes = new Uint8Array(bits / 8);
 	crypto.getRandomValues(bytes);
-	let encoded;
-	if (signed) encoded = encodeSigningKey(bytes, format);
-	else if (wrapped) encoded = encodeWrappingKey(bytes, format);
-	else encoded = encodeOpaqueKey(bytes, format);
-	opts.stdout(encoded + "\n");
+	opts.stdout(variant.key.encode(bytes, format) + "\n");
 	return Promise.resolve(0);
 }
 //#endregion