@smonn/ids 0.3.1 → 0.3.3

package/README.md

@@ -6,7 +6,7 @@ Public-facing branded IDs for TypeScript apps.
 pnpm add @smonn/ids
 ```
 
-Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The default codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — same byte layout as a [ULID](https://github.com/ulid/spec); see [ADR-0002](./docs/adr/0002-payload-layout.md) for the deliberate divergences. A second codec (`@smonn/ids/opaque`) keeps the same wire shape but encrypts the payload under a key, so the timestamp isn't readable from the ID.
+Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — same byte layout as a [ULID](https://github.com/ulid/spec); see [ADR-0002](./docs/adr/0002-payload-layout.md) for the deliberate divergences. The Opaque codec (`@smonn/ids/opaque`) keeps the same wire shape but encrypts the payload under a key, so the timestamp isn't readable from the ID.
 
 ## What this is for
 
@@ -166,7 +166,7 @@ The `pattern` describes the **canonical form only** — it matches `generate()`
 
 ### "Don't leak creation time in IDs that customers can see"
 
-The default codec exposes the creation timestamp by design — that's what makes `ORDER BY id` work. If that's a leak you can't accept (invoice IDs revealing billing cadence, signup IDs revealing acquisition velocity), use the opaque codec at `@smonn/ids/opaque`. Same `<brand>_<26 chars>` wire shape, but the payload is AES-encrypted under a key you supply.
+The Timestamp codec exposes the creation timestamp by design — that's what makes `ORDER BY id` work. If that's a leak you can't accept (invoice IDs revealing billing cadence, signup IDs revealing acquisition velocity), use the Opaque codec at `@smonn/ids/opaque`. Same `<brand>_<26 chars>` wire shape, but the payload is AES-encrypted under a key you supply.
 
 ```ts
 import { createOpaqueId, importOpaqueKey } from "@smonn/ids/opaque";
@@ -178,20 +178,22 @@ const id = await invoices.generate(); // "inv_…", timestamp not extractable wi
 await invoices.extractTimestamp(id); // Date — same codec, same key required
 ```
 
-Three differences from the default codec:
+Three differences from the Timestamp codec:
 
 - **Async key-dependent methods.** WebCrypto is async-only, so `generate`, `generateAt`, and `extractTimestamp` return `Promise`s. `is`, `parse`, `safeParse`, `toJsonSchema`, and the Standard Schema adapter stay sync — they work on the wire form only ([ADR-0006](./docs/adr/0006-async-keyed-codec-contract.md)).
-- **No `minIdForTime` / `maxIdForTime`.** Encrypted payloads don't sort by time. If you need time-range scans on opaque-coded entities, store the timestamp in a separate column.
-- **Wire-indistinguishable from the default codec.** Codec choice is a per-brand commitment; the brand registry warns if you register the same brand against both in dev ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)).
+- **No `minIdForTime` / `maxIdForTime`.** Encrypted payloads don't sort by time. If you need time-range scans on Opaque-coded entities, store the timestamp in a separate column.
+- **Wire-indistinguishable from the Timestamp codec.** Codec choice is a per-brand commitment; the brand registry warns if you register the same brand against both in dev ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)).
 
 Encryption is AES-CBC with a zero IV. That's deliberately safe here because the plaintext already carries 80 bits of entropy per ID; see [ADR-0004](./docs/adr/0004-aes-cbc-strip-trick.md) for the full rationale.
 
+To store or transport key material outside the library, `encodeOpaqueKey` / `decodeOpaqueKey` round-trip raw bytes in `hex` or `base64url` — distinct from the Crockford base32 used in ID payloads. The CLI's `keygen` subcommand emits keys in this format (see [CLI](#cli)).
+
 ## What this is **not** for
 
 - **Internal surrogate primary keys.** If nobody outside your service ever sees the ID, the brand prefix and lenient parsing are dead weight. Use a `bigint` sequence.
 - **Wire-compatible ULIDs.** The byte layout is ULID-shaped but the encoding is lowercase and wrapped in a brand envelope. Stock ULID parsers will reject these.
 - **Distributed-trace / request-correlation IDs.** Use OpenTelemetry-format IDs.
-- **Hiding creation time with the default codec.** Anyone with one ID at a known creation time can compute the epoch offset. A custom epoch wouldn't help and isn't supported. To hide creation time per-ID, use the opaque codec (above).
+- **Hiding creation time with the Timestamp codec.** Anyone with one ID at a known creation time can compute the epoch offset. A custom epoch wouldn't help and isn't supported. To hide creation time per-ID, use the Opaque codec (above).
 
 ## API surface
 
@@ -209,8 +211,11 @@ import {
 import {
   createOpaqueId, // (brand: string, opts: { key, now?, rng?, allowDuplicateBrand? }) => OpaqueCodec<Brand>
   importOpaqueKey, // (bytes: Uint8Array) => Promise<CryptoKey>
+  encodeOpaqueKey, // (bytes: Uint8Array, format: OpaqueKeyFormat) => string
+  decodeOpaqueKey, // (encoded: string, format: OpaqueKeyFormat) => Uint8Array
   type OpaqueCodec, // returned by createOpaqueId
   type OpaqueOptions, // { key, now, rng, allowDuplicateBrand } injection points
+  type OpaqueKeyFormat, // "hex" | "base64url"
 } from "@smonn/ids/opaque";
 ```
 
@@ -230,7 +235,11 @@ import {
 
 ## CLI
 
-Two brand-agnostic subcommands, no install required:
+Brand-agnostic subcommands, no install required. Run `npx @smonn/ids --help` for the full flag list.
+
+### `inspect` (`i`)
+
+Decode an ID and print brand, timestamp, canonical form, and whether the input was already canonical.
 
 ```bash
 $ npx @smonn/ids inspect usr_01h7b3k9rqxn1cw3p9r8t2sgkz
@@ -238,14 +247,54 @@ brand:     usr
 timestamp: 1983-05-27T10:24:22.469Z (43 years ago)
 canonical: usr_01h7b3k9rqxn1cw3p9r8t2sgkz
 input:     canonical
+```
 
+Accepts non-canonical input (uppercase, Crockford aliases). Assumes the **Timestamp codec** — if the brand uses the **Opaque codec**, pass `--opaque` and set `IDS_KEY` (below); otherwise the timestamp line is meaningless garbage.
+
+```bash
+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)).
+
+### `generate` (`g`)
+
+Mint one or more canonical IDs for a brand. Output is one ID per line (pipeable).
+
+```bash
 $ npx @smonn/ids generate usr --count 3
 usr_…
 usr_…
 usr_…
 ```
 
-`inspect` accepts non-canonical input (uppercase, Crockford aliases) and shows the canonical form. `generate` prints one ID per line so output is pipeable. Invalid input prints the parse error to stderr and exits non-zero.
+Flags: `--count` / `-c N` (default 1). Uses the Timestamp codec unless `--opaque` is set.
+
+```bash
+IDS_KEY=<hex-or-base64url-key> npx @smonn/ids generate inv --opaque --count 2
+```
+
+### `keygen` (`k`)
+
+Emit a random Opaque key to stdout (a secret — do not log or commit). Default: 256-bit hex.
+
+```bash
+$ npx @smonn/ids keygen
+a1b2c3…
+
+$ 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`.
+
+### Opaque mode (`--opaque`)
+
+`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.
+
+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`.
+
+Invalid input prints the parse error to stderr and exits non-zero.
 
 ## Design
 

package/dist/cli.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { t as createId } from "./id-B4GiFKYV.mjs";
+import { t as createId } from "./id-CcoPE2EX.mjs";
+import { i as encodeOpaqueKey, n as importOpaqueKey, r as decodeOpaqueKey, t as createOpaqueId } from "./opaque-B-ttBfHO.mjs";
 //#region src/cli.ts
-function run(opts) {
+async function run(opts) {
 	const [subcommand, ...rest] = opts.argv;
 	if (subcommand === "generate" || subcommand === "g") return runGenerate(rest, opts);
 	if (subcommand === "inspect" || subcommand === "i") return runInspect(rest, opts);
+	if (subcommand === "keygen" || subcommand === "k") return runKeygen(rest, opts);
 	if (subcommand === void 0 || subcommand === "--help" || subcommand === "-h") {
 		opts.stdout(usage());
 		return 0;
@@ -17,21 +19,72 @@ function usage() {
 		"Usage: ids <subcommand> [args]",
 		"",
 		"Subcommands:",
-		"  inspect, i <id>                       Decode an ID and print brand, timestamp, and canonical form.",
-		"  generate, g <brand> [--count, -c N]   Mint one or more canonical IDs for the given brand.",
+		"  inspect, i <id> [--opaque] [--key-format hex|base64url]",
+		"    Decode an ID and print brand, timestamp, and canonical form.",
+		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
+		"  generate, g <brand> [--count, -c N] [--opaque] [--key-format hex|base64url]",
+		"    Mint one or more canonical IDs for the given brand.",
+		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
+		"  keygen, k [--bits 128|192|256] [--key-format hex|base64url]",
+		"    Emit a random AES key for importOpaqueKey (stdout only).",
 		""
 	].join("\n");
 }
 function runInspect(args, opts) {
-	const [input] = args;
+	const { flags, values, positionals } = splitFlags(args);
+	const [input] = positionals;
 	if (input === void 0) {
 		opts.stderr(usage());
-		return 1;
+		return Promise.resolve(1);
 	}
+	const opaque = flags.has("--opaque");
 	const brand = input.slice(0, 3).toLowerCase();
+	if (opaque) {
+		const format = parseOpaqueKeyFormat(values, opts);
+		if (isKeyFormatError(format)) {
+			opts.stderr(format + "\n");
+			return Promise.resolve(1);
+		}
+		return runOpaqueInspect(brand, input, format, opts);
+	}
 	let codec;
 	try {
 		codec = createId(brand, codecOpts(opts));
+	} catch (err) {
+		opts.stderr(err.message + "\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)();
+	const relative = formatRelative(timestamp.getTime(), nowMs);
+	const inputLine = describeInputForm(input, canonical);
+	opts.stdout([
+		`brand:     ${brand}`,
+		`timestamp: ${timestamp.toISOString()} (${relative})`,
+		`canonical: ${canonical}`,
+		`input:     ${inputLine}`,
+		""
+	].join("\n"));
+	return Promise.resolve(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 = createOpaqueId(brand, {
+			key: keyResult,
+			...codecOpts(opts)
+		});
 	} catch (err) {
 		opts.stderr(err.message + "\n");
 		return 1;
@@ -42,10 +95,11 @@ function runInspect(args, opts) {
 		return 1;
 	}
 	const canonical = validation.value;
-	const timestamp = codec.extractTimestamp(canonical);
+	const timestamp = await codec.extractTimestamp(canonical);
 	const nowMs = (opts.now ?? Date.now)();
 	const relative = formatRelative(timestamp.getTime(), nowMs);
 	const inputLine = describeInputForm(input, canonical);
+	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([
 		`brand:     ${brand}`,
 		`timestamp: ${timestamp.toISOString()} (${relative})`,
@@ -89,30 +143,171 @@ function unit(n, name) {
 	return `${n} ${n === 1 ? name : `${name}s`}`;
 }
 function runGenerate(args, opts) {
-	const [brand, ...flags] = args;
-	const count = parseCount(flags);
+	const { flags, values, positionals } = splitFlags(args);
+	const [brand] = positionals;
+	const count = parseCount(values);
 	if (typeof count === "string") {
 		opts.stderr(count + "\n");
-		return 1;
+		return Promise.resolve(1);
+	}
+	if (flags.has("--opaque")) {
+		const format = parseOpaqueKeyFormat(values, opts);
+		if (isKeyFormatError(format)) {
+			opts.stderr(format + "\n");
+			return Promise.resolve(1);
+		}
+		return runOpaqueGenerate(brand ?? "", count, format, opts);
 	}
 	let codec;
 	try {
 		codec = createId(brand ?? "", codecOpts(opts));
 	} catch (err) {
 		opts.stderr(err.message + "\n");
-		return 1;
+		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 = createOpaqueId(brand, {
+			key: keyResult,
+			...codecOpts(opts)
+		});
+	} catch (err) {
+		opts.stderr(err.message + "\n");
+		return 1;
+	}
+	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
 	return 0;
 }
-function parseCount(flags) {
-	const idx = flags.findIndex((f) => f === "--count" || f === "-c");
-	if (idx === -1) return 1;
-	const raw = flags[idx + 1];
-	if (raw === void 0) return "--count requires a value";
+function runKeygen(args, opts) {
+	const { values } = splitFlags(args);
+	const bits = parseBits(values);
+	if (typeof bits === "string") {
+		opts.stderr(bits + "\n");
+		return Promise.resolve(1);
+	}
+	const format = parseKeygenFormat(values);
+	if (isKeyFormatError(format)) {
+		opts.stderr(format + "\n");
+		return Promise.resolve(1);
+	}
+	const bytes = new Uint8Array(bits / 8);
+	crypto.getRandomValues(bytes);
+	opts.stdout(encodeOpaqueKey(bytes, format) + "\n");
+	return Promise.resolve(0);
+}
+async function loadOpaqueKey(opts, format) {
+	const raw = (opts.env ?? process.env).IDS_KEY;
+	if (raw === void 0 || raw === "") return "missing IDS_KEY environment variable";
+	try {
+		return importOpaqueKey(decodeOpaqueKey(raw, format));
+	} catch (err) {
+		return err.message;
+	}
+}
+function parseCount(values) {
+	const raw = values.get("--count") ?? values.get("-c");
+	if (raw === void 0) return 1;
+	if (raw === "") return "--count requires a value";
 	if (!/^[1-9][0-9]*$/.test(raw)) return `--count must be a positive integer, got '${raw}'`;
 	return Number(raw);
 }
+function parseBits(values) {
+	const raw = values.get("--bits");
+	if (raw === void 0) return 256;
+	if (raw === "") return "--bits requires a value";
+	if (raw === "128") return 128;
+	if (raw === "192") return 192;
+	if (raw === "256") return 256;
+	return `--bits must be 128, 192, or 256, got '${raw}'`;
+}
+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 parseKeygenFormat(values) {
+	const fromFlag = parseKeyFormatFlag(values);
+	if (fromFlag === void 0) return "hex";
+	return fromFlag;
+}
+function parseOpaqueKeyFormat(values, opts) {
+	const fromFlag = parseKeyFormatFlag(values);
+	if (fromFlag !== void 0) return fromFlag;
+	const fromEnv = (opts.env ?? process.env).IDS_KEY_FORMAT;
+	if (fromEnv === void 0 || fromEnv === "") return "hex";
+	if (fromEnv === "hex" || fromEnv === "base64url") return fromEnv;
+	return `IDS_KEY_FORMAT must be hex or base64url, got '${fromEnv}'`;
+}
+function splitFlagToken(arg) {
+	const eq = arg.indexOf("=");
+	if (eq <= 0) return {
+		flag: arg,
+		inlineValue: void 0
+	};
+	return {
+		flag: arg.slice(0, eq),
+		inlineValue: arg.slice(eq + 1)
+	};
+}
+function splitFlags(args) {
+	const flags = /* @__PURE__ */ new Set();
+	const values = /* @__PURE__ */ new Map();
+	const positionals = [];
+	const valueFlags = new Set([
+		"--count",
+		"-c",
+		"--bits",
+		"--key-format"
+	]);
+	for (let i = 0; i < args.length; i++) {
+		const raw = args[i];
+		const { flag, inlineValue } = splitFlagToken(raw);
+		if (flag === "--opaque") {
+			flags.add(flag);
+			continue;
+		}
+		if (valueFlags.has(flag)) {
+			if (inlineValue !== void 0) {
+				flags.add(flag);
+				values.set(flag, inlineValue);
+				continue;
+			}
+			const value = args[i + 1];
+			if (value === void 0 || value.startsWith("-")) {
+				values.set(flag, "");
+				continue;
+			}
+			flags.add(flag);
+			values.set(flag, value);
+			i++;
+			continue;
+		}
+		if (flag.startsWith("-")) {
+			flags.add(flag);
+			continue;
+		}
+		positionals.push(raw);
+	}
+	return {
+		flags,
+		values,
+		positionals
+	};
+}
 function codecOpts(opts) {
 	const o = { allowDuplicateBrand: true };
 	if (opts.now !== void 0) o.now = opts.now;
@@ -121,7 +316,7 @@ function codecOpts(opts) {
 }
 //#endregion
 //#region bin/cli.ts
-process.exitCode = run({
+process.exitCode = await run({
 	argv: process.argv.slice(2),
 	stdout: (s) => process.stdout.write(s),
 	stderr: (s) => process.stderr.write(s)

package/dist/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts","../bin/cli.ts"],"sourcesContent":["import { createId, type Options } from \"./id.js\";\nimport type { Id } from \"./types.js\";\n\nexport type RunOpts = {\n  argv: ReadonlyArray<string>;\n  stdout: (chunk: string) => void;\n  stderr: (chunk: string) => void;\n  now?: Options[\"now\"];\n  rng?: Options[\"rng\"];\n};\n\nexport function run(opts: RunOpts): number {\n  const [subcommand, ...rest] = opts.argv;\n  if (subcommand === \"generate\" || subcommand === \"g\") return runGenerate(rest, opts);\n  if (subcommand === \"inspect\" || subcommand === \"i\") return runInspect(rest, opts);\n  if (subcommand === undefined || subcommand === \"--help\" || subcommand === \"-h\") {\n    opts.stdout(usage());\n    return 0;\n  }\n  opts.stderr(usage());\n  return 1;\n}\n\nfunction usage(): string {\n  return [\n    \"Usage: ids <subcommand> [args]\",\n    \"\",\n    \"Subcommands:\",\n    \"  inspect, i <id>                       Decode an ID and print brand, timestamp, and canonical form.\",\n    \"  generate, g <brand> [--count, -c N]   Mint one or more canonical IDs for the given brand.\",\n    \"\",\n  ].join(\"\\n\");\n}\n\nfunction runInspect(args: ReadonlyArray<string>, opts: RunOpts): number {\n  const [input] = args;\n  if (input === undefined) {\n    opts.stderr(usage());\n    return 1;\n  }\n  const brand = input.slice(0, 3).toLowerCase();\n  let codec;\n  try {\n    codec = createId(brand, codecOpts(opts));\n  } catch (err) {\n    opts.stderr((err as Error).message + \"\\n\");\n    return 1;\n  }\n  const validation = codec[\"~standard\"].validate(input);\n  if (validation.issues) {\n    opts.stderr(validation.issues[0]!.message + \"\\n\");\n    return 1;\n  }\n  const canonical = validation.value;\n  const timestamp = codec.extractTimestamp(canonical);\n  const nowMs = (opts.now ?? Date.now)();\n  const relative = formatRelative(timestamp.getTime(), nowMs);\n  const inputLine = describeInputForm(input, canonical);\n  opts.stdout(\n    [\n      `brand:     ${brand}`,\n      `timestamp: ${timestamp.toISOString()} (${relative})`,\n      `canonical: ${canonical}`,\n      `input:     ${inputLine}`,\n      \"\",\n    ].join(\"\\n\"),\n  );\n  return 0;\n}\n\nfunction describeInputForm(input: string, canonical: Id<string>): string {\n  if (input === canonical) return \"canonical\";\n  const notes: string[] = [];\n  if (input !== input.toLowerCase()) notes.push(\"was uppercase\");\n  if (/[ilo]/i.test(input.slice(4))) notes.push(\"used Crockford aliases\");\n  return `not canonical (${notes.join(\" + \")})`;\n}\n\nconst msPerSecond = 1000;\nconst msPerMinute = 60 * msPerSecond;\nconst msPerHour = 60 * msPerMinute;\nconst msPerDay = 24 * msPerHour;\nconst daysPerMonth = 30.44;\nconst monthsPerYear = 12;\n\nfunction formatRelative(thenMs: number, nowMs: number): string {\n  const diff = nowMs - thenMs;\n  const abs = Math.abs(diff);\n  const suffix = diff < 0 ? \"from now\" : \"ago\";\n\n  const head = headUnits(abs);\n  return head === \"\" ? \"just now\" : `${head} ${suffix}`;\n}\n\nfunction headUnits(abs: number): string {\n  if (abs < msPerMinute) return \"\";\n  if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), \"minute\");\n  if (abs < msPerDay) return unit(Math.round(abs / msPerHour), \"hour\");\n  if (abs < msPerDay * daysPerMonth) return unit(Math.round(abs / msPerDay), \"day\");\n\n  const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));\n  if (totalMonths < monthsPerYear) return unit(totalMonths, \"month\");\n\n  const years = Math.floor(totalMonths / monthsPerYear);\n  const months = totalMonths % monthsPerYear;\n  return months === 0 ? unit(years, \"year\") : `${unit(years, \"year\")} ${unit(months, \"month\")}`;\n}\n\nfunction unit(n: number, name: string): string {\n  return `${n} ${n === 1 ? name : `${name}s`}`;\n}\n\nfunction runGenerate(args: ReadonlyArray<string>, opts: RunOpts): number {\n  const [brand, ...flags] = args;\n  const count = parseCount(flags);\n  if (typeof count === \"string\") {\n    opts.stderr(count + \"\\n\");\n    return 1;\n  }\n  let codec;\n  try {\n    codec = createId(brand ?? \"\", codecOpts(opts));\n  } catch (err) {\n    opts.stderr((err as Error).message + \"\\n\");\n    return 1;\n  }\n  for (let i = 0; i < count; i++) opts.stdout(codec.generate() + \"\\n\");\n  return 0;\n}\n\nfunction parseCount(flags: ReadonlyArray<string>): number | string {\n  const idx = flags.findIndex((f) => f === \"--count\" || f === \"-c\");\n  if (idx === -1) return 1;\n  const raw = flags[idx + 1];\n  if (raw === undefined) return \"--count requires a value\";\n  if (!/^[1-9][0-9]*$/.test(raw)) return `--count must be a positive integer, got '${raw}'`;\n  return Number(raw);\n}\n\nfunction codecOpts(opts: RunOpts): Partial<Options> {\n  // CLI invocations are intentionally ephemeral — one codec per run, never\n  // retained — so a repeated `createId(brand)` here is not the bundling/import\n  // bug that the duplicate-brand warning is designed to catch.\n  const o: Partial<Options> = { allowDuplicateBrand: true };\n  if (opts.now !== undefined) o.now = opts.now;\n  if (opts.rng !== undefined) o.rng = opts.rng;\n  return o;\n}\n","#!/usr/bin/env node\nimport { run } from \"../src/cli.js\";\n\nprocess.exitCode = run({\n  argv: process.argv.slice(2),\n  stdout: (s) => process.stdout.write(s),\n  stderr: (s) => process.stderr.write(s),\n});\n"],"mappings":"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"}
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts","../bin/cli.ts"],"sourcesContent":["import { createId, type Options } from \"./id.js\";\nimport {\n  createOpaqueId,\n  decodeOpaqueKey,\n  encodeOpaqueKey,\n  importOpaqueKey,\n  type OpaqueKeyFormat,\n} from \"./opaque.js\";\nimport type { Id } from \"./types.js\";\n\nexport type RunOpts = {\n  argv: ReadonlyArray<string>;\n  stdout: (chunk: string) => void;\n  stderr: (chunk: string) => void;\n  now?: Options[\"now\"];\n  rng?: Options[\"rng\"];\n  /** Defaults to `process.env`. Injected in tests for `IDS_KEY`. */\n  env?: Readonly<Record<string, string | undefined>>;\n};\n\nexport async function run(opts: RunOpts): Promise<number> {\n  const [subcommand, ...rest] = opts.argv;\n  if (subcommand === \"generate\" || subcommand === \"g\") return runGenerate(rest, opts);\n  if (subcommand === \"inspect\" || subcommand === \"i\") return runInspect(rest, opts);\n  if (subcommand === \"keygen\" || subcommand === \"k\") return runKeygen(rest, opts);\n  if (subcommand === undefined || subcommand === \"--help\" || subcommand === \"-h\") {\n    opts.stdout(usage());\n    return 0;\n  }\n  opts.stderr(usage());\n  return 1;\n}\n\nfunction usage(): string {\n  return [\n    \"Usage: ids <subcommand> [args]\",\n    \"\",\n    \"Subcommands:\",\n    \"  inspect, i <id> [--opaque] [--key-format hex|base64url]\",\n    \"    Decode an ID and print brand, timestamp, and canonical form.\",\n    \"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).\",\n    \"  generate, g <brand> [--count, -c N] [--opaque] [--key-format hex|base64url]\",\n    \"    Mint one or more canonical IDs for the given brand.\",\n    \"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).\",\n    \"  keygen, k [--bits 128|192|256] [--key-format hex|base64url]\",\n    \"    Emit a random AES key for importOpaqueKey (stdout only).\",\n    \"\",\n  ].join(\"\\n\");\n}\n\nfunction runInspect(args: ReadonlyArray<string>, opts: RunOpts): Promise<number> {\n  const { flags, values, positionals } = splitFlags(args);\n  const [input] = positionals;\n  if (input === undefined) {\n    opts.stderr(usage());\n    return Promise.resolve(1);\n  }\n  const opaque = flags.has(\"--opaque\");\n  const brand = input.slice(0, 3).toLowerCase();\n  if (opaque) {\n    const format = parseOpaqueKeyFormat(values, opts);\n    if (isKeyFormatError(format)) {\n      opts.stderr(format + \"\\n\");\n      return Promise.resolve(1);\n    }\n    return runOpaqueInspect(brand, input, format, opts);\n  }\n  let codec;\n  try {\n    codec = createId(brand, codecOpts(opts));\n  } catch (err) {\n    opts.stderr((err as Error).message + \"\\n\");\n    return Promise.resolve(1);\n  }\n  const validation = codec[\"~standard\"].validate(input);\n  if (validation.issues) {\n    opts.stderr(validation.issues[0]!.message + \"\\n\");\n    return Promise.resolve(1);\n  }\n  const canonical = validation.value;\n  const timestamp = codec.extractTimestamp(canonical);\n  const nowMs = (opts.now ?? Date.now)();\n  const relative = formatRelative(timestamp.getTime(), nowMs);\n  const inputLine = describeInputForm(input, canonical);\n  opts.stdout(\n    [\n      `brand:     ${brand}`,\n      `timestamp: ${timestamp.toISOString()} (${relative})`,\n      `canonical: ${canonical}`,\n      `input:     ${inputLine}`,\n      \"\",\n    ].join(\"\\n\"),\n  );\n  return Promise.resolve(0);\n}\n\nasync function runOpaqueInspect(\n  brand: string,\n  input: string,\n  format: OpaqueKeyFormat,\n  opts: RunOpts,\n): Promise<number> {\n  const keyResult = await loadOpaqueKey(opts, format);\n  if (typeof keyResult === \"string\") {\n    opts.stderr(keyResult + \"\\n\");\n    return 1;\n  }\n  let codec;\n  try {\n    codec = createOpaqueId(brand, { key: keyResult, ...codecOpts(opts) });\n  } catch (err) {\n    opts.stderr((err as Error).message + \"\\n\");\n    return 1;\n  }\n  const validation = codec[\"~standard\"].validate(input);\n  if (validation.issues) {\n    opts.stderr(validation.issues[0]!.message + \"\\n\");\n    return 1;\n  }\n  const canonical = validation.value;\n  const timestamp = await codec.extractTimestamp(canonical);\n  const nowMs = (opts.now ?? Date.now)();\n  const relative = formatRelative(timestamp.getTime(), nowMs);\n  const inputLine = describeInputForm(input, canonical);\n  opts.stderr(\n    \"note: timestamp assumes IDS_KEY matches the key used at generation; a wrong key yields a plausible but incorrect timestamp\\n\",\n  );\n  opts.stdout(\n    [\n      `brand:     ${brand}`,\n      `timestamp: ${timestamp.toISOString()} (${relative})`,\n      `canonical: ${canonical}`,\n      `input:     ${inputLine}`,\n      \"\",\n    ].join(\"\\n\"),\n  );\n  return 0;\n}\n\nfunction describeInputForm(input: string, canonical: Id<string>): string {\n  if (input === canonical) return \"canonical\";\n  const notes: string[] = [];\n  if (input !== input.toLowerCase()) notes.push(\"was uppercase\");\n  if (/[ilo]/i.test(input.slice(4))) notes.push(\"used Crockford aliases\");\n  return `not canonical (${notes.join(\" + \")})`;\n}\n\nconst msPerSecond = 1000;\nconst msPerMinute = 60 * msPerSecond;\nconst msPerHour = 60 * msPerMinute;\nconst msPerDay = 24 * msPerHour;\nconst daysPerMonth = 30.44;\nconst monthsPerYear = 12;\n\nfunction formatRelative(thenMs: number, nowMs: number): string {\n  const diff = nowMs - thenMs;\n  const abs = Math.abs(diff);\n  const suffix = diff < 0 ? \"from now\" : \"ago\";\n\n  const head = headUnits(abs);\n  return head === \"\" ? \"just now\" : `${head} ${suffix}`;\n}\n\nfunction headUnits(abs: number): string {\n  if (abs < msPerMinute) return \"\";\n  if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), \"minute\");\n  if (abs < msPerDay) return unit(Math.round(abs / msPerHour), \"hour\");\n  if (abs < msPerDay * daysPerMonth) return unit(Math.round(abs / msPerDay), \"day\");\n\n  const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));\n  if (totalMonths < monthsPerYear) return unit(totalMonths, \"month\");\n\n  const years = Math.floor(totalMonths / monthsPerYear);\n  const months = totalMonths % monthsPerYear;\n  return months === 0 ? unit(years, \"year\") : `${unit(years, \"year\")} ${unit(months, \"month\")}`;\n}\n\nfunction unit(n: number, name: string): string {\n  return `${n} ${n === 1 ? name : `${name}s`}`;\n}\n\nfunction runGenerate(args: ReadonlyArray<string>, opts: RunOpts): Promise<number> {\n  const { flags, values, positionals } = splitFlags(args);\n  const [brand] = positionals;\n  const count = parseCount(values);\n  if (typeof count === \"string\") {\n    opts.stderr(count + \"\\n\");\n    return Promise.resolve(1);\n  }\n  const opaque = flags.has(\"--opaque\");\n  if (opaque) {\n    const format = parseOpaqueKeyFormat(values, opts);\n    if (isKeyFormatError(format)) {\n      opts.stderr(format + \"\\n\");\n      return Promise.resolve(1);\n    }\n    return runOpaqueGenerate(brand ?? \"\", count, format, opts);\n  }\n  let codec;\n  try {\n    codec = createId(brand ?? \"\", codecOpts(opts));\n  } catch (err) {\n    opts.stderr((err as Error).message + \"\\n\");\n    return Promise.resolve(1);\n  }\n  for (let i = 0; i < count; i++) opts.stdout(codec.generate() + \"\\n\");\n  return Promise.resolve(0);\n}\n\nasync function runOpaqueGenerate(\n  brand: string,\n  count: number,\n  format: OpaqueKeyFormat,\n  opts: RunOpts,\n): Promise<number> {\n  const keyResult = await loadOpaqueKey(opts, format);\n  if (typeof keyResult === \"string\") {\n    opts.stderr(keyResult + \"\\n\");\n    return 1;\n  }\n  let codec;\n  try {\n    codec = createOpaqueId(brand, { key: keyResult, ...codecOpts(opts) });\n  } catch (err) {\n    opts.stderr((err as Error).message + \"\\n\");\n    return 1;\n  }\n  for (let i = 0; i < count; i++) opts.stdout((await codec.generate()) + \"\\n\");\n  return 0;\n}\n\nfunction runKeygen(args: ReadonlyArray<string>, opts: RunOpts): Promise<number> {\n  const { values } = splitFlags(args);\n  const bits = parseBits(values);\n  if (typeof bits === \"string\") {\n    opts.stderr(bits + \"\\n\");\n    return Promise.resolve(1);\n  }\n  const format = parseKeygenFormat(values);\n  if (isKeyFormatError(format)) {\n    opts.stderr(format + \"\\n\");\n    return Promise.resolve(1);\n  }\n  const bytes = new Uint8Array(bits / 8);\n  crypto.getRandomValues(bytes);\n  opts.stdout(encodeOpaqueKey(bytes, format) + \"\\n\");\n  return Promise.resolve(0);\n}\n\nasync function loadOpaqueKey(opts: RunOpts, format: OpaqueKeyFormat): Promise<CryptoKey | string> {\n  const env = opts.env ?? process.env;\n  const raw = env.IDS_KEY;\n  if (raw === undefined || raw === \"\") return \"missing IDS_KEY environment variable\";\n  try {\n    return importOpaqueKey(decodeOpaqueKey(raw, format));\n  } catch (err) {\n    return (err as Error).message;\n  }\n}\n\nfunction parseCount(values: Map<string, string>): number | string {\n  const raw = values.get(\"--count\") ?? values.get(\"-c\");\n  if (raw === undefined) return 1;\n  if (raw === \"\") return \"--count requires a value\";\n  if (!/^[1-9][0-9]*$/.test(raw)) return `--count must be a positive integer, got '${raw}'`;\n  return Number(raw);\n}\n\nfunction parseBits(values: Map<string, string>): number | string {\n  const raw = values.get(\"--bits\");\n  if (raw === undefined) return 256;\n  if (raw === \"\") return \"--bits requires a value\";\n  if (raw === \"128\") return 128;\n  if (raw === \"192\") return 192;\n  if (raw === \"256\") return 256;\n  return `--bits must be 128, 192, or 256, got '${raw}'`;\n}\n\nfunction isKeyFormatError(result: OpaqueKeyFormat | string): result is string {\n  return result !== \"hex\" && result !== \"base64url\";\n}\n\nfunction parseKeyFormatFlag(values: Map<string, string>): OpaqueKeyFormat | string | undefined {\n  const fromFlag = values.get(\"--key-format\");\n  if (fromFlag === undefined) return undefined;\n  if (fromFlag === \"\") return \"--key-format requires a value\";\n  if (fromFlag === \"hex\" || fromFlag === \"base64url\") return fromFlag;\n  return `--key-format must be hex or base64url, got '${fromFlag}'`;\n}\n\nfunction parseKeygenFormat(values: Map<string, string>): OpaqueKeyFormat | string {\n  const fromFlag = parseKeyFormatFlag(values);\n  if (fromFlag === undefined) return \"hex\";\n  return fromFlag;\n}\n\nfunction parseOpaqueKeyFormat(\n  values: Map<string, string>,\n  opts: RunOpts,\n): OpaqueKeyFormat | string {\n  const fromFlag = parseKeyFormatFlag(values);\n  if (fromFlag !== undefined) return fromFlag;\n  const env = opts.env ?? process.env;\n  const fromEnv = env.IDS_KEY_FORMAT;\n  if (fromEnv === undefined || fromEnv === \"\") return \"hex\";\n  if (fromEnv === \"hex\" || fromEnv === \"base64url\") return fromEnv;\n  return `IDS_KEY_FORMAT must be hex or base64url, got '${fromEnv}'`;\n}\n\ntype ParsedFlags = {\n  flags: Set<string>;\n  values: Map<string, string>;\n  positionals: string[];\n};\n\nfunction splitFlagToken(arg: string): { flag: string; inlineValue: string | undefined } {\n  const eq = arg.indexOf(\"=\");\n  if (eq <= 0) return { flag: arg, inlineValue: undefined };\n  return { flag: arg.slice(0, eq), inlineValue: arg.slice(eq + 1) };\n}\n\nfunction splitFlags(args: ReadonlyArray<string>): ParsedFlags {\n  const flags = new Set<string>();\n  const values = new Map<string, string>();\n  const positionals: string[] = [];\n  const valueFlags = new Set([\"--count\", \"-c\", \"--bits\", \"--key-format\"]);\n  for (let i = 0; i < args.length; i++) {\n    const raw = args[i]!;\n    const { flag, inlineValue } = splitFlagToken(raw);\n    if (flag === \"--opaque\") {\n      flags.add(flag);\n      continue;\n    }\n    if (valueFlags.has(flag)) {\n      if (inlineValue !== undefined) {\n        flags.add(flag);\n        values.set(flag, inlineValue);\n        continue;\n      }\n      const value = args[i + 1];\n      if (value === undefined || value.startsWith(\"-\")) {\n        values.set(flag, \"\");\n        continue;\n      }\n      flags.add(flag);\n      values.set(flag, value);\n      i++;\n      continue;\n    }\n    if (flag.startsWith(\"-\")) {\n      flags.add(flag);\n      continue;\n    }\n    positionals.push(raw);\n  }\n  return { flags, values, positionals };\n}\n\nfunction codecOpts(opts: RunOpts): Partial<Options> {\n  // CLI invocations are intentionally ephemeral — one codec per run, never\n  // retained — so a repeated `createId(brand)` here is not the bundling/import\n  // bug that the duplicate-brand warning is designed to catch.\n  const o: Partial<Options> = { allowDuplicateBrand: true };\n  if (opts.now !== undefined) o.now = opts.now;\n  if (opts.rng !== undefined) o.rng = opts.rng;\n  return o;\n}\n","#!/usr/bin/env node\nimport { run } from \"../src/cli.js\";\n\nprocess.exitCode = await run({\n  argv: process.argv.slice(2),\n  stdout: (s) => process.stdout.write(s),\n  stderr: (s) => process.stderr.write(s),\n});\n"],"mappings":"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"}

package/dist/{shared-CmbAeUdM.mjs → codec-shell-C0arqqX3.mjs}

@@ -1,3 +1,10 @@
+//#region src/brand.ts
+const brandPattern = /^[a-z]{3}$/;
+/** Validates a three-character lowercase brand. Throws on invalid input. */
+function validateBrand(brand) {
+	if (!brandPattern.test(brand)) throw new Error("invalid brand, expected three lowercase a-z characters");
+}
+//#endregion
 //#region src/base32.ts
 const alphabet = "0123456789abcdefghjkmnpqrstvwxyz";
 const valueToCharCode = new Uint8Array(32);
@@ -37,13 +44,50 @@ function decodeBase32(str) {
 	return result;
 }
 //#endregion
+//#region src/wire/envelope.ts
+/** Encodes a 16-byte payload as lowercase Crockford base32 (26 chars). */
+function encodePayload(bytes) {
+	return encodeBase32(bytes);
+}
+/** Decodes a 26-char base32 payload suffix to 16 bytes. Trust-the-type. */
+function decodePayload(base32) {
+	return decodeBase32(base32);
+}
+/** Composes a canonical wire ID from a prefix and 16-byte payload. */
+function toWireId(prefix, payload) {
+	return prefix + encodePayload(payload);
+}
+/** Decodes the full 16-byte payload from a trusted wire ID. */
+function payloadBytesFromId(prefix, id) {
+	return decodePayload(id.slice(prefix.length));
+}
+const payloadBase32Length = Math.ceil(128 / 5);
+const base32CharClass = "[0-9a-hjkmnp-tv-z]";
+const timestampBase32Length = Math.ceil(48 / 5);
+/** Write the timestamp in big-endian; encoded via mod-256 to avoid 32-bit bitwise coercion. */
+function writeTimestamp(ms, buffer) {
+	if (Number.isNaN(ms)) throw new Error("timestamp is not a number");
+	if (ms < 0) throw new Error("timestamp is negative");
+	if (ms >= 2 ** 48) throw new Error("timestamp exceeds 48-bit range");
+	for (let i = 5; i >= 0; i--) {
+		buffer[i] = ms % 256;
+		ms = Math.floor(ms / 256);
+	}
+}
+/** Decode the first `timestampByteLength` bytes of a buffer as a big-endian unsigned millisecond timestamp. */
+function readTimestampMs(buffer) {
+	let ms = 0;
+	for (let i = 0; i < 6; i++) ms = ms * 256 + buffer[i];
+	return ms;
+}
+/** Decodes ms from the first 10 base32 chars of a payload suffix (partial decode). */
+function readTimestampMsFromBase32Suffix(base32Suffix) {
+	return readTimestampMs(decodeBase32(base32Suffix.slice(0, timestampBase32Length)));
+}
+//#endregion
 //#region src/registry.ts
-const brandPattern = /^[a-z]{3}$/;
 const registeredBrands = /* @__PURE__ */ new Set();
 const warnedBrands = /* @__PURE__ */ new Set();
-function validateBrand(brand) {
-	if (!brandPattern.test(brand)) throw new Error("invalid brand, expected three lowercase a-z characters");
-}
 function registerBrand(brand, allowDuplicateBrand) {
 	if (typeof process === "undefined" || process.env.NODE_ENV === "production" || allowDuplicateBrand) return;
 	if (registeredBrands.has(brand)) {
@@ -53,8 +97,8 @@ function registerBrand(brand, allowDuplicateBrand) {
 		}
 	} else registeredBrands.add(brand);
 }
-const payloadBase32Length = Math.ceil(128 / 5);
-const base32CharClass = "[0-9a-hjkmnp-tv-z]";
+//#endregion
+//#region src/wire/parse.ts
 const replacePattern = /[ilo]/g;
 const aliasTestPattern = /[ilo]/;
 const replacer = (match) => match === "o" ? "0" : "1";
@@ -97,26 +141,33 @@ function errorMessage(prefix, error) {
 		case "invalid_base32": return "invalid base32 payload";
 	}
 }
-function writeTimestamp(ms, buffer) {
-	if (Number.isNaN(ms)) throw new Error("timestamp is not a number");
-	if (ms < 0) throw new Error("timestamp is negative");
-	if (ms >= 2 ** 48) throw new Error("timestamp exceeds 48-bit range");
-	for (let i = 5; i >= 0; i--) {
-		buffer[i] = ms % 256;
-		ms = Math.floor(ms / 256);
-	}
-}
-function readTimestampMs(buffer) {
-	let ms = 0;
-	for (let i = 0; i < 6; i++) ms = ms * 256 + buffer[i];
-	return ms;
-}
 function standardValidate(prefix, value) {
 	const result = safeParse(prefix, value);
 	if (result.ok) return { value: result.id };
 	return { issues: [{ message: errorMessage(prefix, result.error) }] };
 }
 //#endregion
-export { readTimestampMs as a, writeTimestamp as c, decodeBase32 as d, encodeBase32 as f, payloadBase32Length as i, registerBrand as l, is as n, safeParse as o, parse as r, standardValidate as s, base32CharClass as t, validateBrand as u };
+//#region src/wire/codec-shell.ts
+/** Wire-only methods shared by every codec variant for a fixed prefix. */
+function wireMethods(prefix) {
+	return {
+		is: (value) => is(prefix, value),
+		parse: (value) => parse(prefix, value),
+		safeParse: (value) => safeParse(prefix, value),
+		toJsonSchema: (brand, example) => ({
+			type: "string",
+			pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,
+			description: `Branded ID for '${brand}'`,
+			example
+		}),
+		"~standard": {
+			version: 1,
+			vendor: "@smonn/ids",
+			validate: (value) => standardValidate(prefix, value)
+		}
+	};
+}
+//#endregion
+export { writeTimestamp as a, toWireId as c, readTimestampMsFromBase32Suffix as i, validateBrand as l, registerBrand as n, payloadBase32Length as o, readTimestampMs as r, payloadBytesFromId as s, wireMethods as t };
 
-//# sourceMappingURL=shared-CmbAeUdM.mjs.map
+//# sourceMappingURL=codec-shell-C0arqqX3.mjs.map

package/dist/codec-shell-C0arqqX3.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-shell-C0arqqX3.mjs","names":[],"sources":["../src/brand.ts","../src/base32.ts","../src/wire/envelope.ts","../src/wire/invariants.ts","../src/wire/timestamp-bytes.ts","../src/registry.ts","../src/wire/parse.ts","../src/wire/codec-shell.ts"],"sourcesContent":["const brandPattern = /^[a-z]{3}$/;\n\n/** Validates a three-character lowercase brand. Throws on invalid input. */\nexport function validateBrand(brand: string): void {\n  if (!brandPattern.test(brand)) {\n    throw new Error(\"invalid brand, expected three lowercase a-z characters\");\n  }\n}\n","/*\n  This is based on Crockford's Base32 spec: https://www.crockford.com/base32.html\n  One difference is that it uses lowercase instead of uppercase when encoding.\n\n  These functions are internal: callers (id.ts) guarantee that input is a\n  16-byte buffer for encode, or a string of characters drawn from the alphabet\n  for decode. Invalid input produces silent garbage rather than a thrown error,\n  consistent with the trust-the-type rule in ADR-0003.\n*/\n\nexport const alphabet = \"0123456789abcdefghjkmnpqrstvwxyz\";\n\n// 0–31 → ASCII char code, for write-into-codes-then-fromCharCode encoding.\nconst valueToCharCode = new Uint8Array(32);\nfor (let i = 0; i < 32; i++) valueToCharCode[i] = alphabet.charCodeAt(i);\n\n// charCode → 0–31 value. Canonical lowercase only; upstream resolves case and\n// o/i/l aliases before any string reaches decodeBase32.\nconst INVALID = 0xff;\nconst charCodeToValue = new Uint8Array(256).fill(INVALID);\nfor (let i = 0; i < alphabet.length; i++) charCodeToValue[alphabet.charCodeAt(i)] = i;\n\nexport function encodeBase32(bytes: Uint8Array): string {\n  // Build an Array<number> of char codes and pass it to fromCharCode.apply.\n  // Faster than `result += char` (avoids cons-string overhead) and than\n  // Uint8Array variants (apply has a fast path for plain Arrays).\n  // oxlint-disable-next-line no-new-array\n  const codes = new Array<number>(Math.floor((bytes.length * 8) / 5) + 1);\n  let chi = 0;\n  let bits = 0;\n  let value = 0;\n\n  for (let i = 0; i < bytes.length; i++) {\n    value = (value << 8) | bytes[i]!;\n    bits += 8;\n    while (bits >= 5) {\n      bits -= 5;\n      codes[chi++] = valueToCharCode[(value >>> bits) & 0x1f]!;\n    }\n  }\n  codes[chi] = valueToCharCode[(value << (5 - bits)) & 0x1f]!;\n  return String.fromCharCode.apply(null, codes);\n}\n\nexport function decodeBase32(str: string): Uint8Array {\n  const result = new Uint8Array(Math.floor((str.length * 5) / 8));\n  let bits = 0;\n  let value = 0;\n  let index = 0;\n\n  for (let i = 0; i < str.length; i++) {\n    const v = charCodeToValue[str.charCodeAt(i)]!;\n    value = (value << 5) | v;\n    bits += 5;\n    if (bits >= 8) {\n      bits -= 8;\n      result[index++] = (value >>> bits) & 0xff;\n    }\n  }\n  return result;\n}\n","import { decodeBase32, encodeBase32 } from \"../base32.js\";\nimport type { Id, Prefix } from \"../types.js\";\n\n/** Encodes a 16-byte payload as lowercase Crockford base32 (26 chars). */\nfunction encodePayload(bytes: Uint8Array): string {\n  return encodeBase32(bytes);\n}\n\n/** Decodes a 26-char base32 payload suffix to 16 bytes. Trust-the-type. */\nfunction decodePayload(base32: string): Uint8Array {\n  return decodeBase32(base32);\n}\n\n/** Composes a canonical wire ID from a prefix and 16-byte payload. */\nexport function toWireId<Brand extends string>(\n  prefix: Prefix<Brand>,\n  payload: Uint8Array,\n): Id<Brand> {\n  return (prefix + encodePayload(payload)) as Id<Brand>;\n}\n\n/** Decodes the full 16-byte payload from a trusted wire ID. */\nexport function payloadBytesFromId<Brand extends string>(\n  prefix: Prefix<Brand>,\n  id: Id<Brand>,\n): Uint8Array {\n  return decodePayload(id.slice(prefix.length));\n}\n","// Payload is always 16 bytes on the wire (every codec). 16 bytes → 26 Crockford\n// base32 chars. ADR-0002 codifies this as the shared wire-format invariant.\nexport const payloadByteLength: number = 16;\nexport const payloadBase32Length: number = Math.ceil((payloadByteLength * 8) / 5);\n\n// Compact regex character class for the canonical lowercase Crockford alphabet\n// (`0123456789abcdefghjkmnpqrstvwxyz` — excludes i, l, o, u). Used in the JSON\n// Schema `pattern`, which describes the canonical wire form only (ADR-0003).\nexport const base32CharClass: string = \"[0-9a-hjkmnp-tv-z]\";\n","import { decodeBase32 } from \"../base32.js\";\n\n// Timestamp byte layout: first N bytes of the plaintext payload encode a\n// big-endian Unix-ms timestamp. Shared by Timestamp and Opaque layouts.\nexport const timestampByteLength: number = 6;\n\nconst timestampBase32Length: number = Math.ceil((timestampByteLength * 8) / 5);\n\n/** Write the timestamp in big-endian; encoded via mod-256 to avoid 32-bit bitwise coercion. */\nexport function writeTimestamp(ms: number, buffer: Uint8Array): void {\n  if (Number.isNaN(ms)) throw new Error(\"timestamp is not a number\");\n  if (ms < 0) throw new Error(\"timestamp is negative\");\n  if (ms >= 2 ** (timestampByteLength * 8)) {\n    throw new Error(\"timestamp exceeds 48-bit range\");\n  }\n  for (let i = timestampByteLength - 1; i >= 0; i--) {\n    buffer[i] = ms % 256;\n    ms = Math.floor(ms / 256);\n  }\n}\n\n/** Decode the first `timestampByteLength` bytes of a buffer as a big-endian unsigned millisecond timestamp. */\nexport function readTimestampMs(buffer: Uint8Array): number {\n  let ms = 0;\n  for (let i = 0; i < timestampByteLength; i++) ms = ms * 256 + buffer[i]!;\n  return ms;\n}\n\n/** Decodes ms from the first 10 base32 chars of a payload suffix (partial decode). */\nexport function readTimestampMsFromBase32Suffix(base32Suffix: string): number {\n  return readTimestampMs(decodeBase32(base32Suffix.slice(0, timestampBase32Length)));\n}\n","const registeredBrands = new Set<string>();\nconst warnedBrands = new Set<string>();\n\nexport function registerBrand(brand: string, allowDuplicateBrand: boolean | undefined): void {\n  if (\n    typeof process === \"undefined\" ||\n    process.env.NODE_ENV === \"production\" ||\n    allowDuplicateBrand\n  ) {\n    return;\n  }\n\n  if (registeredBrands.has(brand)) {\n    if (!warnedBrands.has(brand)) {\n      console.warn(\n        `[@smonn/ids] brand \"${brand}\" was registered more than once — this usually indicates a bundling or import bug, or that more than one codec variant is using the same brand. Pass { allowDuplicateBrand: true } to silence.`,\n      );\n      warnedBrands.add(brand);\n    }\n  } else {\n    registeredBrands.add(brand);\n  }\n}\n","import { alphabet } from \"../base32.js\";\nimport type { Id, ParseError, ParseResult, Prefix } from \"../types.js\";\nimport { payloadBase32Length } from \"./invariants.js\";\n\nconst replacePattern = /[ilo]/g;\nconst aliasTestPattern = /[ilo]/;\nconst replacer = (match: string): string => (match === \"o\" ? \"0\" : \"1\");\nconst base32Pattern = new RegExp(`^[${alphabet}]{${payloadBase32Length}}$`);\n\nexport function safeParse<Brand extends string>(\n  prefix: Prefix<Brand>,\n  value: unknown,\n): ParseResult<Brand> {\n  if (typeof value !== \"string\") return { ok: false, error: \"not_string\" };\n  const lowercase = value.toLowerCase();\n  if (!lowercase.startsWith(prefix)) return { ok: false, error: \"invalid_prefix\" };\n\n  const sliced = lowercase.slice(prefix.length);\n  const base32 = aliasTestPattern.test(sliced)\n    ? sliced.replaceAll(replacePattern, replacer)\n    : sliced;\n\n  if (!base32Pattern.test(base32)) return { ok: false, error: \"invalid_base32\" };\n\n  const id = (prefix + base32) as Id<Brand>;\n  return { ok: true, id };\n}\n\nexport function parse<Brand extends string>(prefix: Prefix<Brand>, value: unknown): Id<Brand> {\n  const result = safeParse(prefix, value);\n  if (result.ok) return result.id;\n  throw new Error(`Invalid ID: ${result.error}`);\n}\n\nexport function is<Brand extends string>(\n  prefix: Prefix<Brand>,\n  value: unknown,\n): value is Id<Brand> {\n  if (typeof value !== \"string\") return false;\n  if (!value.startsWith(prefix)) return false;\n  return base32Pattern.test(value.slice(prefix.length));\n}\n\nfunction errorMessage<Brand extends string>(prefix: Prefix<Brand>, error: ParseError): string {\n  switch (error) {\n    case \"not_string\":\n      return \"expected string\";\n    case \"invalid_prefix\":\n      return `expected prefix '${prefix}'`;\n    case \"invalid_base32\":\n      return \"invalid base32 payload\";\n  }\n}\n\nexport function standardValidate<Brand extends string>(\n  prefix: Prefix<Brand>,\n  value: unknown,\n):\n  | { readonly value: Id<Brand>; readonly issues?: undefined }\n  | { readonly issues: ReadonlyArray<{ readonly message: string }> } {\n  const result = safeParse(prefix, value);\n  if (result.ok) return { value: result.id };\n  return { issues: [{ message: errorMessage(prefix, result.error) }] };\n}\n","import type { Id, JsonSchema, ParseResult, Prefix, StandardSchemaProps } from \"../types.js\";\nimport { base32CharClass, payloadBase32Length } from \"./invariants.js\";\nimport { is, parse, safeParse, standardValidate } from \"./parse.js\";\n\ntype WireMethods<Brand extends string> = {\n  is: (value: unknown) => value is Id<Brand>;\n  parse: (value: unknown) => Id<Brand>;\n  safeParse: (value: unknown) => ParseResult<Brand>;\n  toJsonSchema: (brand: Brand, example: string) => JsonSchema;\n  \"~standard\": StandardSchemaProps<Brand>;\n};\n\n/** Wire-only methods shared by every codec variant for a fixed prefix. */\nexport function wireMethods<Brand extends string>(prefix: Prefix<Brand>): WireMethods<Brand> {\n  const standard: StandardSchemaProps<Brand> = {\n    version: 1,\n    vendor: \"@smonn/ids\",\n    validate: (value: unknown) => standardValidate(prefix, value),\n  };\n  return {\n    is: (value: unknown): value is Id<Brand> => is(prefix, value),\n    parse: (value: unknown): Id<Brand> => parse(prefix, value),\n    safeParse: (value: unknown): ParseResult<Brand> => safeParse(prefix, value),\n    toJsonSchema: (brand: Brand, example: string): JsonSchema => ({\n      type: \"string\",\n      pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,\n      description: `Branded ID for '${brand}'`,\n      example,\n    }),\n    \"~standard\": standard,\n  };\n}\n"],"mappings":"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"}