@smonn/ids 0.3.0 → 0.3.2

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 encoding 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.
+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
 
@@ -117,7 +117,7 @@ Both `Options` fields are optional. Defaults are `Date.now` and an entropy harve
 
 ### "Catch a double-registered brand before it bites in production"
 
-The intended pattern is one codec per brand per process, constructed at module init. Calling `createId(brand)` a second time for the same brand usually means a bundling or import bug (accidental re-export, a test re-importing without resetting). In development (`process.env.NODE_ENV !== "production"`), the second call emits a one-shot `console.warn`; the brand-tracking registry is skipped in production. Tests that intentionally re-create codecs can opt out:
+The intended pattern is one codec per brand per process, constructed at module init. Calling `createId(brand)` a second time for the same brand usually means a bundling or import bug (accidental re-export, a test re-importing without resetting). In development (`process.env.NODE_ENV !== "production"`), the second call emits a one-shot `console.warn`; the brand-tracking registry is skipped in production. The same registry covers cross-codec collisions: `createId("usr")` followed by `createOpaqueId("usr")` warns too, because codec choice is a per-brand commitment ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)). Tests that intentionally re-create codecs can opt out:
 
 ```ts
 const users = createId("usr", { allowDuplicateBrand: true });
@@ -164,12 +164,36 @@ The `pattern` describes the **canonical form only** — it matches `generate()`
 
 `example` is produced by calling `generate()` on each invocation, so it is fresh (non-deterministic) and always matches the returned `pattern`. One consequence: a codec wired with an injected `now` outside the 48-bit range — the same misconfiguration that breaks `generate()` — makes `toJsonSchema()` throw too.
 
+### "Don't leak creation time in IDs that customers can see"
+
+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";
+
+const key = await importOpaqueKey(new Uint8Array(16)); // 128- or 256-bit raw key
+const invoices = createOpaqueId("inv", { key });
+
+const id = await invoices.generate(); // "inv_…", timestamp not extractable without the key
+await invoices.extractTimestamp(id); // Date — same codec, same key required
+```
+
+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 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 when your system launched.** Anyone with one known-time ID can compute the epoch offset. A custom epoch isn't supported, and wouldn't help anyway.
+- **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
 
@@ -183,25 +207,39 @@ import {
   type ParseResult, // safeParse return type
   type JsonSchema, // toJsonSchema return type
 } from "@smonn/ids";
+
+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";
 ```
 
-### `Codec<Brand>`
+### Codec methods
 
-| Method                 | Description                                                                   |
-| ---------------------- | ----------------------------------------------------------------------------- |
-| `generate()`           | Produce a fresh ID                                                            |
-| `generateAt(date)`     | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
-| `is(value)`            | Strict type guard: `true` only for already-canonical strings                  |
-| `parse(value)`         | Lenient: normalise to canonical, or throw                                     |
-| `safeParse(value)`     | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
-| `extractTimestamp(id)` | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
-| `minIdForTime(date)`   | Tight lower bound for any ID generated at `date` (for range queries)          |
-| `maxIdForTime(date)`   | Tight upper bound for any ID generated at `date` (for range queries)          |
-| `toJsonSchema()`       | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
+| Method                 | `Codec<Brand>` | `OpaqueCodec<Brand>` | Description                                                                   |
+| ---------------------- | -------------- | -------------------- | ----------------------------------------------------------------------------- |
+| `generate()`           | sync           | async                | Produce a fresh ID                                                            |
+| `generateAt(date)`     | sync           | async                | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
+| `is(value)`            | sync           | sync                 | Strict type guard: `true` only for already-canonical strings                  |
+| `parse(value)`         | sync           | sync                 | Lenient: normalise to canonical, or throw                                     |
+| `safeParse(value)`     | sync           | sync                 | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
+| `extractTimestamp(id)` | sync           | async                | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
+| `minIdForTime(date)`   | sync           | —                    | Tight lower bound for any ID generated at `date` (for range queries)          |
+| `maxIdForTime(date)`   | sync           | —                    | Tight upper bound for any ID generated at `date` (for range queries)          |
+| `toJsonSchema()`       | sync           | sync                 | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
 
 ## 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
@@ -209,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-BlQPohZp.mjs";
+import { i as encodeOpaqueKey, n as importOpaqueKey, r as decodeOpaqueKey, t as createOpaqueId } from "./opaque-ChnxvPm5.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/{id-B4GiFKYV.mjs → id-BlQPohZp.mjs}

@@ -21,6 +21,12 @@ const defaultOptions = {
 };
 const randomByteLength = 10;
 const timestampBase32Length = Math.ceil(48 / 5);
+/**
+* Creates a codec for `brand` (three lowercase a–z characters).
+*
+* @param brand - Entity type brand validated once at construction.
+* @param opts - Optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+*/
 function createId(brand, opts = {}) {
 	validateBrand(brand);
 	registerBrand(brand, opts.allowDuplicateBrand);
@@ -73,4 +79,4 @@ function extractTimestamp(prefix, id) {
 //#endregion
 export { createId as t };
 
-//# sourceMappingURL=id-B4GiFKYV.mjs.map
+//# sourceMappingURL=id-BlQPohZp.mjs.map

package/dist/id-BlQPohZp.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-BlQPohZp.mjs","names":[],"sources":["../src/id.ts"],"sourcesContent":["import { decodeBase32, encodeBase32 } from \"./base32.js\";\nimport { registerBrand, validateBrand } from \"./registry.js\";\nimport {\n  base32CharClass,\n  is,\n  parse,\n  payloadBase32Length,\n  payloadByteLength,\n  readTimestampMs,\n  safeParse,\n  standardValidate,\n  timestampByteLength,\n  writeTimestamp,\n} from \"./shared.js\";\nimport type { Id, JsonSchema, ParseResult, Prefix, StandardSchemaProps } from \"./types.js\";\n\n/**\n * Configuration options for a codec instance.\n */\nexport type Options = {\n  /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */\n  now: () => number;\n  /** Writes random bytes into `target` for ID generation. Defaults to a `crypto.randomUUID` fast path. */\n  rng: (target: Uint8Array) => void;\n  /** If true, silences the duplicate-brand warning in non-production environments. */\n  allowDuplicateBrand?: boolean;\n};\n\n/**\n * A brand-scoped codec for generating and validating public-facing IDs.\n *\n * Wire format: `{brand}_` plus 26 lowercase Crockford base32 characters encoding a\n * 16-byte payload (6-byte ms timestamp + 10 random bytes). IDs sort by creation\n * time in ascending order.\n *\n * For encrypted IDs, use `createOpaqueId` from `@smonn/ids/opaque`.\n */\nexport type Codec<Brand extends string> = {\n  /** Produces a new canonical ID using the codec's `now` and `rng`. */\n  generate(): Id<Brand>;\n  /** Produces a new canonical ID with timestamp bytes from `date` and a fresh random tail. Throws on invalid dates. */\n  generateAt(date: Date): Id<Brand>;\n  /**\n   * Strict type guard: `true` only for already-canonical strings for this brand.\n   * For untrusted input, use `safeParse()` or `parse()` instead. See ADR-0003.\n   */\n  is(value: unknown): value is Id<Brand>;\n  /**\n   * Lenient parse: normalises case and Crockford aliases, returns canonical `Id<Brand>`, or throws.\n   */\n  parse(value: unknown): Id<Brand>;\n  /**\n   * Lenient parse without throwing: normalises to canonical form, or returns `{ ok: false, error }`.\n   */\n  safeParse(value: unknown): ParseResult<Brand>;\n  /**\n   * Decodes the creation `Date` from an `Id<Brand>`. Trusts the type — use `safeParse()` at boundaries first. See ADR-0002.\n   */\n  extractTimestamp(id: Id<Brand>): Date;\n  /** Tight lower bound for any ID generated at `date` (random portion `0x00`). Throws on invalid dates. */\n  minIdForTime(date: Date): Id<Brand>;\n  /** Tight upper bound for any ID generated at `date` (random portion `0xff`). Throws on invalid dates. */\n  maxIdForTime(date: Date): Id<Brand>;\n  /** JSON Schema for the canonical wire form (`pattern` is canonical-only). */\n  toJsonSchema(): JsonSchema;\n  /** Standard Schema validate entry point. */\n  readonly \"~standard\": StandardSchemaProps<Brand>;\n};\n\n// hex charCode → 0–15 nibble, for decoding UUIDv4 strings into bytes.\n// Covers ['0'-'9' = 48–57] and ['a'-'f' = 97–102]; UUIDs are lowercase per spec.\nconst hexCharCodeToNibble = new Uint8Array(128);\nfor (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;\nfor (let i = 0; i < 6; i++) hexCharCodeToNibble[97 + i] = 10 + i;\n\nconst defaultOptions: Options = {\n  now: Date.now,\n  // crypto.randomUUID is ~7× faster than crypto.getRandomValues in Node 24\n  // (~84 ns vs ~610 ns for a 16-byte fill — likely because the UUID path has\n  // a tight fixed-format fast path). We use the 122 random bits of a UUIDv4\n  // string as our entropy source, harvesting 10 fully-random bytes from\n  // positions where no version (hex 12) or variant (hex 16) bits sit.\n  // String layout: \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\" — bytes 0–5 are\n  // string[0..7]+string[9..12], bytes 6–9 are string[24..31].\n  rng: (target) => {\n    const s = crypto.randomUUID();\n    target[0] =\n      (hexCharCodeToNibble[s.charCodeAt(0)]! << 4) | hexCharCodeToNibble[s.charCodeAt(1)]!;\n    target[1] =\n      (hexCharCodeToNibble[s.charCodeAt(2)]! << 4) | hexCharCodeToNibble[s.charCodeAt(3)]!;\n    target[2] =\n      (hexCharCodeToNibble[s.charCodeAt(4)]! << 4) | hexCharCodeToNibble[s.charCodeAt(5)]!;\n    target[3] =\n      (hexCharCodeToNibble[s.charCodeAt(6)]! << 4) | hexCharCodeToNibble[s.charCodeAt(7)]!;\n    target[4] =\n      (hexCharCodeToNibble[s.charCodeAt(9)]! << 4) | hexCharCodeToNibble[s.charCodeAt(10)]!;\n    target[5] =\n      (hexCharCodeToNibble[s.charCodeAt(11)]! << 4) | hexCharCodeToNibble[s.charCodeAt(12)]!;\n    target[6] =\n      (hexCharCodeToNibble[s.charCodeAt(24)]! << 4) | hexCharCodeToNibble[s.charCodeAt(25)]!;\n    target[7] =\n      (hexCharCodeToNibble[s.charCodeAt(26)]! << 4) | hexCharCodeToNibble[s.charCodeAt(27)]!;\n    target[8] =\n      (hexCharCodeToNibble[s.charCodeAt(28)]! << 4) | hexCharCodeToNibble[s.charCodeAt(29)]!;\n    target[9] =\n      (hexCharCodeToNibble[s.charCodeAt(30)]! << 4) | hexCharCodeToNibble[s.charCodeAt(31)]!;\n  },\n};\n\nconst randomByteLength = payloadByteLength - timestampByteLength;\nconst timestampBase32Length = Math.ceil((timestampByteLength * 8) / 5);\n\n/**\n * Creates a codec for `brand` (three lowercase a–z characters).\n *\n * @param brand - Entity type brand validated once at construction.\n * @param opts - Optional `now`, `rng`, and `allowDuplicateBrand` overrides.\n */\nexport function createId<Brand extends string>(\n  brand: Brand,\n  opts: Partial<Options> = {},\n): Codec<Brand> {\n  validateBrand(brand);\n  registerBrand(brand, opts.allowDuplicateBrand);\n\n  const options = {\n    ...defaultOptions,\n    ...opts,\n  } satisfies Options;\n\n  const prefix: Prefix<Brand> = `${brand}_`;\n  // Per-codec scratch buffer. Shared across generate(), generateAt(),\n  // minIdForTime(), and maxIdForTime() — all are synchronous and overwrite both\n  // the timestamp and random slices before encoding, so successive callers see\n  // their own freshly-written bytes. encodeBase32 reads the buffer and\n  // returns an independent string, so the caller never sees the buffer itself.\n  const buffer = new Uint8Array(payloadByteLength);\n  const randomView = new Uint8Array(buffer.buffer, timestampByteLength, randomByteLength);\n\n  return {\n    generate: () => generate(prefix, options, buffer, randomView),\n    generateAt: (date: Date) => generate(prefix, options, buffer, randomView, date.getTime()),\n    is: (value: unknown) => is(prefix, value),\n    parse: (value: unknown) => parse(prefix, value),\n    safeParse: (value: unknown) => safeParse(prefix, value),\n    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, id),\n    minIdForTime: (date: Date) => sentinelIdForTime(prefix, date, 0x00, buffer, randomView),\n    maxIdForTime: (date: Date) => sentinelIdForTime(prefix, date, 0xff, buffer, randomView),\n    toJsonSchema: () => toJsonSchema(brand, prefix, options, buffer, randomView),\n    \"~standard\": {\n      version: 1,\n      vendor: \"@smonn/ids\",\n      validate: (value: unknown) => standardValidate(prefix, value),\n    },\n  };\n}\n\nfunction toJsonSchema<Brand extends string>(\n  brand: Brand,\n  prefix: Prefix<Brand>,\n  options: Options,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n): JsonSchema {\n  return {\n    type: \"string\",\n    pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,\n    description: `Branded ID for '${brand}'`,\n    example: generate(prefix, options, buffer, randomView),\n  };\n}\n\nfunction generate<Brand extends string>(\n  prefix: Prefix<Brand>,\n  options: Options,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n  ms: number = options.now(),\n): Id<Brand> {\n  writeTimestamp(ms, buffer);\n  options.rng(randomView);\n  return (prefix + encodeBase32(buffer)) as Id<Brand>;\n}\n\nfunction sentinelIdForTime<Brand extends string>(\n  prefix: Prefix<Brand>,\n  date: Date,\n  fill: number,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n): Id<Brand> {\n  writeTimestamp(date.getTime(), buffer);\n  randomView.fill(fill);\n  return (prefix + encodeBase32(buffer)) as Id<Brand>;\n}\n\nfunction extractTimestamp<Brand extends string>(prefix: Prefix<Brand>, id: Id<Brand>): Date {\n  const base32 = id.slice(prefix.length, prefix.length + timestampBase32Length);\n  return new Date(readTimestampMs(decodeBase32(base32)));\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,23 +1,54 @@
-import { a as StandardSchemaProps, i as ParseResult, n as JsonSchema, r as ParseError, t as Id } from "./types-Dg2j_zlO.mjs";
+import { a as StandardSchemaProps, i as ParseResult, n as JsonSchema, r as ParseError, t as Id } from "./types-Bv-63YK4.mjs";
 
 //#region src/id.d.ts
+/**
+* Configuration options for a codec instance.
+*/
 type Options = {
-  now: () => number;
-  rng: (target: Uint8Array) => void;
+  /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */now: () => number; /** Writes random bytes into `target` for ID generation. Defaults to a `crypto.randomUUID` fast path. */
+  rng: (target: Uint8Array) => void; /** If true, silences the duplicate-brand warning in non-production environments. */
   allowDuplicateBrand?: boolean;
 };
+/**
+* A brand-scoped codec for generating and validating public-facing IDs.
+*
+* Wire format: `{brand}_` plus 26 lowercase Crockford base32 characters encoding a
+* 16-byte payload (6-byte ms timestamp + 10 random bytes). IDs sort by creation
+* time in ascending order.
+*
+* For encrypted IDs, use `createOpaqueId` from `@smonn/ids/opaque`.
+*/
 type Codec<Brand extends string> = {
-  generate(): Id<Brand>;
+  /** Produces a new canonical ID using the codec's `now` and `rng`. */generate(): Id<Brand>; /** Produces a new canonical ID with timestamp bytes from `date` and a fresh random tail. Throws on invalid dates. */
   generateAt(date: Date): Id<Brand>;
+  /**
+  * Strict type guard: `true` only for already-canonical strings for this brand.
+  * For untrusted input, use `safeParse()` or `parse()` instead. See ADR-0003.
+  */
   is(value: unknown): value is Id<Brand>;
+  /**
+  * Lenient parse: normalises case and Crockford aliases, returns canonical `Id<Brand>`, or throws.
+  */
   parse(value: unknown): Id<Brand>;
+  /**
+  * Lenient parse without throwing: normalises to canonical form, or returns `{ ok: false, error }`.
+  */
   safeParse(value: unknown): ParseResult<Brand>;
-  extractTimestamp(id: Id<Brand>): Date;
-  minIdForTime(date: Date): Id<Brand>;
-  maxIdForTime(date: Date): Id<Brand>;
-  toJsonSchema(): JsonSchema;
+  /**
+  * Decodes the creation `Date` from an `Id<Brand>`. Trusts the type — use `safeParse()` at boundaries first. See ADR-0002.
+  */
+  extractTimestamp(id: Id<Brand>): Date; /** Tight lower bound for any ID generated at `date` (random portion `0x00`). Throws on invalid dates. */
+  minIdForTime(date: Date): Id<Brand>; /** Tight upper bound for any ID generated at `date` (random portion `0xff`). Throws on invalid dates. */
+  maxIdForTime(date: Date): Id<Brand>; /** JSON Schema for the canonical wire form (`pattern` is canonical-only). */
+  toJsonSchema(): JsonSchema; /** Standard Schema validate entry point. */
   readonly "~standard": StandardSchemaProps<Brand>;
 };
+/**
+* Creates a codec for `brand` (three lowercase a–z characters).
+*
+* @param brand - Entity type brand validated once at construction.
+* @param opts - Optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+*/
 declare function createId<Brand extends string>(brand: Brand, opts?: Partial<Options>): Codec<Brand>;
 //#endregion
 export { type Codec, type Id, type JsonSchema, type Options, type ParseError, type ParseResult, createId };

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/id.ts"],"mappings":";;;KAgBY,OAAA;EACV,GAAA;EACA,GAAA,GAAM,MAAA,EAAQ,UAAA;EACd,mBAAA;AAAA;AAAA,KAGU,KAAA;EACV,QAAA,IAAY,EAAA,CAAG,KAAA;EACf,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAC3B,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;EAChC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;EAC1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;EACvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,IAAA;EACjC,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAC7B,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAC7B,YAAA,IAAgB,UAAA;EAAA,SACP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;AAAA,iBA8C5B,QAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,GAAM,OAAA,CAAQ,OAAA,IACb,KAAA,CAAM,KAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/id.ts"],"mappings":";;;;;AAmBA;KAAY,OAAA;+EAEV,GAAA;EAEA,GAAA,GAAM,MAAA,EAAQ,UAAA;EAEd,mBAAA;AAAA;;AAAA;AAYF;;;;;;;KAAY,KAAA;uEAEV,QAAA,IAAY,EAAA,CAAG,KAAA;EAEf,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;;;;;EAK3B,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;EAIhC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;EAI1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;;;;EAIvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,IAAA;EAEjC,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAE7B,YAAA,CAAa,IAAA,EAAM,IAAA,GAAO,EAAA,CAAG,KAAA;EAE7B,YAAA,IAAgB,UAAA;WAEP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;;;;;;;iBAoD5B,QAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA,GAAM,OAAA,CAAQ,OAAA,IACb,KAAA,CAAM,KAAA"}

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { t as createId } from "./id-B4GiFKYV.mjs";
+import { t as createId } from "./id-BlQPohZp.mjs";
 export { createId };

package/dist/opaque-ChnxvPm5.mjs

@@ -0,0 +1,172 @@
+import { a as readTimestampMs, c as writeTimestamp, d as decodeBase32, f as encodeBase32, i as payloadBase32Length, l as registerBrand, n as is, o as safeParse, r as parse, s as standardValidate, t as base32CharClass, u as validateBrand } from "./shared-CmbAeUdM.mjs";
+//#region src/bytes.ts
+const hexDigits = "0123456789abcdef";
+const invalidNibble = 255;
+const hexCharCodeToNibble = new Uint8Array(128).fill(invalidNibble);
+for (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;
+for (let i = 0; i < 6; i++) {
+	hexCharCodeToNibble[97 + i] = 10 + i;
+	hexCharCodeToNibble[65 + i] = 10 + i;
+}
+/** Lowercase hex encoding of raw bytes. */
+function encodeHex(bytes) {
+	const codes = new Array(bytes.length * 2);
+	for (let i = 0; i < bytes.length; i++) {
+		const b = bytes[i];
+		codes[i * 2] = hexDigits.charCodeAt(b >>> 4);
+		codes[i * 2 + 1] = hexDigits.charCodeAt(b & 15);
+	}
+	return String.fromCharCode(...codes);
+}
+/** Decodes a hex string to raw bytes. Throws on non-hex input. */
+function decodeHex(encoded) {
+	if (encoded.length % 2 !== 0) throw new Error("invalid hex");
+	const out = new Uint8Array(encoded.length / 2);
+	for (let i = 0; i < out.length; i++) {
+		const hiCode = encoded.charCodeAt(i * 2);
+		const loCode = encoded.charCodeAt(i * 2 + 1);
+		if (hiCode >= hexCharCodeToNibble.length || loCode >= hexCharCodeToNibble.length) throw new Error("invalid hex");
+		const hi = hexCharCodeToNibble[hiCode];
+		const lo = hexCharCodeToNibble[loCode];
+		if (hi === invalidNibble || lo === invalidNibble) throw new Error("invalid hex");
+		out[i] = hi << 4 | lo;
+	}
+	return out;
+}
+/** Base64url encoding without padding. */
+function encodeBase64Url(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decodes a base64url string to raw bytes. Throws on invalid input. */
+function decodeBase64Url(encoded) {
+	const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+	const pad = (4 - base64.length % 4) % 4;
+	const binary = atob(base64 + "=".repeat(pad));
+	const out = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+	return out;
+}
+//#endregion
+//#region src/opaque-key.ts
+const validAesKeyByteLengths = new Set([
+	16,
+	24,
+	32
+]);
+/**
+* Encodes raw AES key bytes for storage in env vars or secret managers.
+*
+* @param bytes - 16, 24, or 32 raw key bytes (AES-128/192/256).
+* @param format - `hex` (lowercase) or `base64url`.
+*/
+function encodeOpaqueKey(bytes, format) {
+	assertValidAesKeyByteLength(bytes.length);
+	if (format === "hex") return encodeHex(bytes);
+	return encodeBase64Url(bytes);
+}
+/**
+* Decodes key material emitted by `encodeOpaqueKey` (or `ids keygen`) back to raw bytes.
+*
+* @param encoded - Hex or base64url string.
+* @param format - Must match how the string was encoded.
+*/
+function decodeOpaqueKey(encoded, format) {
+	let bytes;
+	if (format === "hex") {
+		if (encoded.length === 0 || encoded.length % 2 !== 0) throw new Error("invalid hex key: length must be a positive even number of characters");
+		if (!/^[0-9a-fA-F]+$/.test(encoded)) throw new Error("invalid hex key: expected [0-9a-fA-F] only");
+		bytes = decodeHex(encoded);
+	} else try {
+		bytes = decodeBase64Url(encoded);
+	} catch {
+		throw new Error("invalid base64url key");
+	}
+	assertValidAesKeyByteLength(bytes.length);
+	return bytes;
+}
+function assertValidAesKeyByteLength(byteLength) {
+	if (!validAesKeyByteLengths.has(byteLength)) throw new Error(`invalid AES key length: expected 16, 24, or 32 bytes, got ${byteLength}`);
+}
+//#endregion
+//#region src/opaque.ts
+const zeroIv = new Uint8Array(16);
+const pkcsPad = 16;
+function defaultRng(target) {
+	crypto.getRandomValues(target);
+}
+/**
+* Imports a raw AES key for use with the Opaque codec.
+*
+* @param bytes - Raw key bytes (16, 24, or 32 bytes for AES-128/192/256).
+*/
+function importOpaqueKey(bytes) {
+	return crypto.subtle.importKey("raw", bytes, "AES-CBC", false, ["encrypt", "decrypt"]);
+}
+/**
+* Creates an Opaque codec for `brand` (three lowercase a–z characters).
+*
+* @param brand - Entity type brand validated once at construction.
+* @param opts - Required `key` plus optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+*/
+function createOpaqueId(brand, opts) {
+	validateBrand(brand);
+	registerBrand(brand, opts.allowDuplicateBrand);
+	const key = opts.key;
+	const now = opts.now ?? Date.now;
+	const rng = opts.rng ?? defaultRng;
+	const prefix = `${brand}_`;
+	return {
+		generate: () => generate(prefix, key, rng, now()),
+		generateAt: (date) => generate(prefix, key, rng, date.getTime()),
+		is: (value) => is(prefix, value),
+		parse: (value) => parse(prefix, value),
+		safeParse: (value) => safeParse(prefix, value),
+		extractTimestamp: (id) => extractTimestamp(prefix, key, id),
+		toJsonSchema: () => toJsonSchema(brand, prefix),
+		"~standard": {
+			version: 1,
+			vendor: "@smonn/ids",
+			validate: (value) => standardValidate(prefix, value)
+		}
+	};
+}
+async function generate(prefix, key, rng, ms) {
+	const plaintext = new Uint8Array(16);
+	writeTimestamp(ms, plaintext);
+	rng(plaintext.subarray(6, 16));
+	return prefix + encodeBase32(new Uint8Array(await crypto.subtle.encrypt({
+		name: "AES-CBC",
+		iv: zeroIv
+	}, key, plaintext)).subarray(0, 16));
+}
+async function extractTimestamp(prefix, key, id) {
+	const c1 = decodeBase32(id.slice(prefix.length));
+	const c2Input = new Uint8Array(16);
+	for (let i = 0; i < 16; i++) c2Input[i] = pkcsPad ^ c1[i];
+	const c2Encrypted = new Uint8Array(await crypto.subtle.encrypt({
+		name: "AES-CBC",
+		iv: zeroIv
+	}, key, c2Input));
+	const ciphertext = new Uint8Array(32);
+	ciphertext.set(c1, 0);
+	ciphertext.set(c2Encrypted.subarray(0, 16), 16);
+	const plaintext = new Uint8Array(await crypto.subtle.decrypt({
+		name: "AES-CBC",
+		iv: zeroIv
+	}, key, ciphertext));
+	return new Date(readTimestampMs(plaintext));
+}
+function toJsonSchema(brand, prefix) {
+	return {
+		type: "string",
+		pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,
+		description: `Branded ID for '${brand}'`,
+		example: prefix + "0".repeat(payloadBase32Length)
+	};
+}
+//#endregion
+export { encodeOpaqueKey as i, importOpaqueKey as n, decodeOpaqueKey as r, createOpaqueId as t };
+
+//# sourceMappingURL=opaque-ChnxvPm5.mjs.map

package/dist/opaque-ChnxvPm5.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"opaque-ChnxvPm5.mjs","names":[],"sources":["../src/bytes.ts","../src/opaque-key.ts","../src/opaque.ts"],"sourcesContent":["const hexDigits = \"0123456789abcdef\";\n\nconst invalidNibble = 0xff;\nconst hexCharCodeToNibble = new Uint8Array(128).fill(invalidNibble);\nfor (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;\nfor (let i = 0; i < 6; i++) {\n  hexCharCodeToNibble[97 + i] = 10 + i;\n  hexCharCodeToNibble[65 + i] = 10 + i;\n}\n\n/** Lowercase hex encoding of raw bytes. */\nexport function encodeHex(bytes: Uint8Array): string {\n  // oxlint-disable-next-line no-new-array\n  const codes = new Array<number>(bytes.length * 2);\n  for (let i = 0; i < bytes.length; i++) {\n    const b = bytes[i]!;\n    codes[i * 2] = hexDigits.charCodeAt(b >>> 4);\n    codes[i * 2 + 1] = hexDigits.charCodeAt(b & 0x0f);\n  }\n  return String.fromCharCode(...codes);\n}\n\n/** Decodes a hex string to raw bytes. Throws on non-hex input. */\nexport function decodeHex(encoded: string): Uint8Array {\n  if (encoded.length % 2 !== 0) throw new Error(\"invalid hex\");\n  const out = new Uint8Array(encoded.length / 2);\n  for (let i = 0; i < out.length; i++) {\n    const hiCode = encoded.charCodeAt(i * 2);\n    const loCode = encoded.charCodeAt(i * 2 + 1);\n    if (hiCode >= hexCharCodeToNibble.length || loCode >= hexCharCodeToNibble.length) {\n      throw new Error(\"invalid hex\");\n    }\n    const hi = hexCharCodeToNibble[hiCode]!;\n    const lo = hexCharCodeToNibble[loCode]!;\n    if (hi === invalidNibble || lo === invalidNibble) {\n      throw new Error(\"invalid hex\");\n    }\n    out[i] = (hi << 4) | lo;\n  }\n  return out;\n}\n\n/** Base64url encoding without padding. */\nexport function encodeBase64Url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Decodes a base64url string to raw bytes. Throws on invalid input. */\nexport function decodeBase64Url(encoded: string): Uint8Array {\n  const base64 = encoded.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const pad = (4 - (base64.length % 4)) % 4;\n  const binary = atob(base64 + \"=\".repeat(pad));\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n","import { decodeBase64Url, decodeHex, encodeBase64Url, encodeHex } from \"./bytes.js\";\n\n/** Wire encoding for opaque AES key material (not Crockford base32). */\nexport type OpaqueKeyFormat = \"hex\" | \"base64url\";\n\nconst validAesKeyByteLengths = new Set([16, 24, 32]);\n\n/**\n * Encodes raw AES key bytes for storage in env vars or secret managers.\n *\n * @param bytes - 16, 24, or 32 raw key bytes (AES-128/192/256).\n * @param format - `hex` (lowercase) or `base64url`.\n */\nexport function encodeOpaqueKey(bytes: Uint8Array, format: OpaqueKeyFormat): string {\n  assertValidAesKeyByteLength(bytes.length);\n  if (format === \"hex\") return encodeHex(bytes);\n  return encodeBase64Url(bytes);\n}\n\n/**\n * Decodes key material emitted by `encodeOpaqueKey` (or `ids keygen`) back to raw bytes.\n *\n * @param encoded - Hex or base64url string.\n * @param format - Must match how the string was encoded.\n */\nexport function decodeOpaqueKey(encoded: string, format: OpaqueKeyFormat): Uint8Array {\n  let bytes: Uint8Array;\n  if (format === \"hex\") {\n    if (encoded.length === 0 || encoded.length % 2 !== 0) {\n      throw new Error(\"invalid hex key: length must be a positive even number of characters\");\n    }\n    if (!/^[0-9a-fA-F]+$/.test(encoded)) {\n      throw new Error(\"invalid hex key: expected [0-9a-fA-F] only\");\n    }\n    bytes = decodeHex(encoded);\n  } else {\n    try {\n      bytes = decodeBase64Url(encoded);\n    } catch {\n      throw new Error(\"invalid base64url key\");\n    }\n  }\n  assertValidAesKeyByteLength(bytes.length);\n  return bytes;\n}\n\nfunction assertValidAesKeyByteLength(byteLength: number): void {\n  if (!validAesKeyByteLengths.has(byteLength)) {\n    throw new Error(`invalid AES key length: expected 16, 24, or 32 bytes, got ${byteLength}`);\n  }\n}\n","import { decodeBase32, encodeBase32 } from \"./base32.js\";\nimport { registerBrand, validateBrand } from \"./registry.js\";\nimport {\n  base32CharClass,\n  is,\n  parse,\n  payloadBase32Length,\n  payloadByteLength,\n  readTimestampMs,\n  safeParse,\n  standardValidate,\n  timestampByteLength,\n  writeTimestamp,\n} from \"./shared.js\";\nimport type { Id, JsonSchema, ParseResult, Prefix, StandardSchemaProps } from \"./types.js\";\n\nexport { decodeOpaqueKey, encodeOpaqueKey, type OpaqueKeyFormat } from \"./opaque-key.js\";\n\n/**\n * Configuration options for an Opaque codec instance.\n */\nexport type OpaqueOptions = {\n  /** AES-CBC key used for encryption and decryption. */\n  key: CryptoKey;\n  /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */\n  now: () => number;\n  /** Writes random bytes into `target` for ID generation. Defaults to `crypto.getRandomValues`. */\n  rng: (target: Uint8Array) => void;\n  /** If true, silences the duplicate-brand warning in non-production environments. */\n  allowDuplicateBrand?: boolean;\n};\n\n/**\n * A brand-scoped codec for generating and validating encrypted (opaque) IDs.\n *\n * Same wire shape as the Timestamp codec (`{brand}_` + 26 base32 chars) but the\n * payload is AES-CBC encrypted. `generate`, `generateAt`, and `extractTimestamp`\n * are async; parsing methods are sync. No `minIdForTime` / `maxIdForTime` —\n * encrypted payloads do not sort by creation time.\n */\nexport type OpaqueCodec<Brand extends string> = {\n  /** Produces a new canonical encrypted ID using the codec's `now` and `rng`. */\n  generate(): Promise<Id<Brand>>;\n  /** Produces a new canonical encrypted ID with timestamp bytes from `date`. Throws on invalid dates. */\n  generateAt(date: Date): Promise<Id<Brand>>;\n  /**\n   * Strict type guard: `true` only for already-canonical strings for this brand.\n   * For untrusted input, use `safeParse()` or `parse()` instead. See ADR-0003.\n   */\n  is(value: unknown): value is Id<Brand>;\n  /**\n   * Lenient parse: normalises case and Crockford aliases, returns canonical `Id<Brand>`, or throws.\n   */\n  parse(value: unknown): Id<Brand>;\n  /**\n   * Lenient parse without throwing: normalises to canonical form, or returns `{ ok: false, error }`.\n   */\n  safeParse(value: unknown): ParseResult<Brand>;\n  /**\n   * Decrypts and decodes the creation `Date` from an `Id<Brand>`. Trusts the type — use `safeParse()` at boundaries first. See ADR-0002.\n   */\n  extractTimestamp(id: Id<Brand>): Promise<Date>;\n  /** JSON Schema for the canonical wire form (`example` is a structural placeholder). */\n  toJsonSchema(): JsonSchema;\n  /** Standard Schema validate entry point. */\n  readonly \"~standard\": StandardSchemaProps<Brand>;\n};\n\nconst zeroIv = new Uint8Array(payloadByteLength);\nconst pkcsPad = 0x10;\n\nfunction defaultRng(target: Uint8Array): void {\n  crypto.getRandomValues(target as Uint8Array<ArrayBuffer>);\n}\n\n/**\n * Imports a raw AES key for use with the Opaque codec.\n *\n * @param bytes - Raw key bytes (16, 24, or 32 bytes for AES-128/192/256).\n */\nexport function importOpaqueKey(bytes: Uint8Array): Promise<CryptoKey> {\n  return crypto.subtle.importKey(\"raw\", bytes as Uint8Array<ArrayBuffer>, \"AES-CBC\", false, [\n    \"encrypt\",\n    \"decrypt\",\n  ]);\n}\n\n/**\n * Creates an Opaque codec for `brand` (three lowercase a–z characters).\n *\n * @param brand - Entity type brand validated once at construction.\n * @param opts - Required `key` plus optional `now`, `rng`, and `allowDuplicateBrand` overrides.\n */\nexport function createOpaqueId<Brand extends string>(\n  brand: Brand,\n  opts: { key: CryptoKey } & Partial<Omit<OpaqueOptions, \"key\">>,\n): OpaqueCodec<Brand> {\n  validateBrand(brand);\n  registerBrand(brand, opts.allowDuplicateBrand);\n\n  const key = opts.key;\n  const now = opts.now ?? Date.now;\n  const rng = opts.rng ?? defaultRng;\n  const prefix: Prefix<Brand> = `${brand}_`;\n\n  return {\n    generate: () => generate(prefix, key, rng, now()),\n    generateAt: (date: Date) => generate(prefix, key, rng, date.getTime()),\n    is: (value: unknown) => is(prefix, value),\n    parse: (value: unknown) => parse(prefix, value),\n    safeParse: (value: unknown) => safeParse(prefix, value),\n    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, key, id),\n    toJsonSchema: () => toJsonSchema(brand, prefix),\n    \"~standard\": {\n      version: 1,\n      vendor: \"@smonn/ids\",\n      validate: (value: unknown) => standardValidate(prefix, value),\n    },\n  };\n}\n\n// Per-call buffers, unlike id.ts's codec-shared scratch. Reuse would be safe\n// (subtle.encrypt/decrypt snapshot inputs synchronously, per WebCrypto step 2\n// before the Promise returns) but subtle dominates this path — the allocation\n// is <1% of total cost, not worth pinning the design to that spec detail.\nasync function generate<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  rng: (target: Uint8Array) => void,\n  ms: number,\n): Promise<Id<Brand>> {\n  const plaintext = new Uint8Array(payloadByteLength);\n  writeTimestamp(ms, plaintext);\n  rng(plaintext.subarray(timestampByteLength, payloadByteLength));\n  const encrypted = new Uint8Array(\n    await crypto.subtle.encrypt({ name: \"AES-CBC\", iv: zeroIv }, key, plaintext),\n  );\n  return (prefix + encodeBase32(encrypted.subarray(0, payloadByteLength))) as Id<Brand>;\n}\n\nasync function extractTimestamp<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  id: Id<Brand>,\n): Promise<Date> {\n  const c1 = decodeBase32(id.slice(prefix.length));\n  // Reconstruct C2 = AES_K(P2 XOR C1) where P2 is the PKCS#7 pad block (0x10×16).\n  // CBC encrypt of (P2 XOR C1) with IV=0 yields AES_K(P2 XOR C1) as the first 16 bytes.\n  const c2Input = new Uint8Array(payloadByteLength);\n  for (let i = 0; i < payloadByteLength; i++) c2Input[i] = pkcsPad ^ c1[i]!;\n  const c2Encrypted = new Uint8Array(\n    await crypto.subtle.encrypt({ name: \"AES-CBC\", iv: zeroIv }, key, c2Input),\n  );\n  const ciphertext = new Uint8Array(payloadByteLength * 2);\n  ciphertext.set(c1, 0);\n  ciphertext.set(c2Encrypted.subarray(0, payloadByteLength), payloadByteLength);\n  const plaintext = new Uint8Array(\n    await crypto.subtle.decrypt({ name: \"AES-CBC\", iv: zeroIv }, key, ciphertext),\n  );\n  return new Date(readTimestampMs(plaintext));\n}\n\nfunction toJsonSchema<Brand extends string>(brand: Brand, prefix: Prefix<Brand>): JsonSchema {\n  return {\n    type: \"string\",\n    pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,\n    description: `Branded ID for '${brand}'`,\n    // The Opaque codec cannot synchronously produce a real example (encrypt is\n    // async). A deterministic structurally-valid placeholder satisfies the\n    // JSON Schema contract without requiring the key at schema time.\n    example: prefix + \"0\".repeat(payloadBase32Length),\n  };\n}\n"],"mappings":"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"}

package/dist/opaque.d.mts

@@ -1,26 +1,79 @@
-import { a as StandardSchemaProps, i as ParseResult, n as JsonSchema, t as Id } from "./types-Dg2j_zlO.mjs";
+import { a as StandardSchemaProps, i as ParseResult, n as JsonSchema, t as Id } from "./types-Bv-63YK4.mjs";
 
+//#region src/opaque-key.d.ts
+/** Wire encoding for opaque AES key material (not Crockford base32). */
+type OpaqueKeyFormat = "hex" | "base64url";
+/**
+* Encodes raw AES key bytes for storage in env vars or secret managers.
+*
+* @param bytes - 16, 24, or 32 raw key bytes (AES-128/192/256).
+* @param format - `hex` (lowercase) or `base64url`.
+*/
+declare function encodeOpaqueKey(bytes: Uint8Array, format: OpaqueKeyFormat): string;
+/**
+* Decodes key material emitted by `encodeOpaqueKey` (or `ids keygen`) back to raw bytes.
+*
+* @param encoded - Hex or base64url string.
+* @param format - Must match how the string was encoded.
+*/
+declare function decodeOpaqueKey(encoded: string, format: OpaqueKeyFormat): Uint8Array;
+//#endregion
 //#region src/opaque.d.ts
+/**
+* Configuration options for an Opaque codec instance.
+*/
 type OpaqueOptions = {
-  key: CryptoKey;
-  now: () => number;
-  rng: (target: Uint8Array) => void;
+  /** AES-CBC key used for encryption and decryption. */key: CryptoKey; /** Returns the current timestamp in milliseconds. Defaults to `Date.now`. */
+  now: () => number; /** Writes random bytes into `target` for ID generation. Defaults to `crypto.getRandomValues`. */
+  rng: (target: Uint8Array) => void; /** If true, silences the duplicate-brand warning in non-production environments. */
   allowDuplicateBrand?: boolean;
 };
+/**
+* A brand-scoped codec for generating and validating encrypted (opaque) IDs.
+*
+* Same wire shape as the Timestamp codec (`{brand}_` + 26 base32 chars) but the
+* payload is AES-CBC encrypted. `generate`, `generateAt`, and `extractTimestamp`
+* are async; parsing methods are sync. No `minIdForTime` / `maxIdForTime` —
+* encrypted payloads do not sort by creation time.
+*/
 type OpaqueCodec<Brand extends string> = {
-  generate(): Promise<Id<Brand>>;
+  /** Produces a new canonical encrypted ID using the codec's `now` and `rng`. */generate(): Promise<Id<Brand>>; /** Produces a new canonical encrypted ID with timestamp bytes from `date`. Throws on invalid dates. */
   generateAt(date: Date): Promise<Id<Brand>>;
+  /**
+  * Strict type guard: `true` only for already-canonical strings for this brand.
+  * For untrusted input, use `safeParse()` or `parse()` instead. See ADR-0003.
+  */
   is(value: unknown): value is Id<Brand>;
+  /**
+  * Lenient parse: normalises case and Crockford aliases, returns canonical `Id<Brand>`, or throws.
+  */
   parse(value: unknown): Id<Brand>;
+  /**
+  * Lenient parse without throwing: normalises to canonical form, or returns `{ ok: false, error }`.
+  */
   safeParse(value: unknown): ParseResult<Brand>;
-  extractTimestamp(id: Id<Brand>): Promise<Date>;
-  toJsonSchema(): JsonSchema;
+  /**
+  * Decrypts and decodes the creation `Date` from an `Id<Brand>`. Trusts the type — use `safeParse()` at boundaries first. See ADR-0002.
+  */
+  extractTimestamp(id: Id<Brand>): Promise<Date>; /** JSON Schema for the canonical wire form (`example` is a structural placeholder). */
+  toJsonSchema(): JsonSchema; /** Standard Schema validate entry point. */
   readonly "~standard": StandardSchemaProps<Brand>;
 };
+/**
+* Imports a raw AES key for use with the Opaque codec.
+*
+* @param bytes - Raw key bytes (16, 24, or 32 bytes for AES-128/192/256).
+*/
 declare function importOpaqueKey(bytes: Uint8Array): Promise<CryptoKey>;
+/**
+* Creates an Opaque codec for `brand` (three lowercase a–z characters).
+*
+* @param brand - Entity type brand validated once at construction.
+* @param opts - Required `key` plus optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+*/
 declare function createOpaqueId<Brand extends string>(brand: Brand, opts: {
   key: CryptoKey;
 } & Partial<Omit<OpaqueOptions, "key">>): OpaqueCodec<Brand>;
 //#endregion
-export { OpaqueCodec, OpaqueOptions, createOpaqueId, importOpaqueKey };
+export { OpaqueCodec, type OpaqueKeyFormat, OpaqueOptions, createOpaqueId, decodeOpaqueKey, encodeOpaqueKey, importOpaqueKey };
 //# sourceMappingURL=opaque.d.mts.map

package/dist/opaque.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"opaque.d.mts","names":[],"sources":["../src/opaque.ts"],"mappings":";;;KAgBY,aAAA;EACV,GAAA,EAAK,SAAA;EACL,GAAA;EACA,GAAA,GAAM,MAAA,EAAQ,UAAA;EACd,mBAAA;AAAA;AAAA,KAGU,WAAA;EACV,QAAA,IAAY,OAAA,CAAQ,EAAA,CAAG,KAAA;EACvB,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,EAAA,CAAG,KAAA;EACnC,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;EAChC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;EAC1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;EACvC,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,OAAA,CAAQ,IAAA;EACzC,YAAA,IAAgB,UAAA;EAAA,SACP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;AAAA,iBAU5B,eAAA,CAAgB,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,SAAA;AAAA,iBAO5C,cAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA;EAAQ,GAAA,EAAK,SAAA;AAAA,IAAc,OAAA,CAAQ,IAAA,CAAK,aAAA,YACvC,WAAA,CAAY,KAAA"}
+{"version":3,"file":"opaque.d.mts","names":[],"sources":["../src/opaque-key.ts","../src/opaque.ts"],"mappings":";;;;KAGY,eAAA;;AAAZ;;;;AAAY;iBAUI,eAAA,CAAgB,KAAA,EAAO,UAAA,EAAY,MAAA,EAAQ,eAAA;;;;;;;iBAY3C,eAAA,CAAgB,OAAA,UAAiB,MAAA,EAAQ,eAAA,GAAkB,UAAA;;;;AAtB3E;;KCkBY,aAAA;EDlBA,sDCoBV,GAAA,EAAK,SAAA,EDVP;ECYE,GAAA;EAEA,GAAA,GAAM,MAAA,EAAQ,UAAA;EAEd,mBAAA;AAAA;;;ADhByD;AAY3D;;;;;KCeY,WAAA;iFAEV,QAAA,IAAY,OAAA,CAAQ,EAAA,CAAG,KAAA,IDjBkD;ECmBzE,UAAA,CAAW,IAAA,EAAM,IAAA,GAAO,OAAA,CAAQ,EAAA,CAAG,KAAA;;;;AAvBrC;EA4BE,EAAA,CAAG,KAAA,YAAiB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;EAIhC,KAAA,CAAM,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;EAI1B,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;;;AA5BvC;EAgCA,gBAAA,CAAiB,EAAA,EAAI,EAAA,CAAG,KAAA,IAAS,OAAA,CAAQ,IAAA,GArB/B;EAuBV,YAAA,IAAgB,UAAA;WAEP,WAAA,EAAa,mBAAA,CAAoB,KAAA;AAAA;;;;;;iBAe5B,eAAA,CAAgB,KAAA,EAAO,UAAA,GAAa,OAAA,CAAQ,SAAA;;;;;;;iBAa5C,cAAA,uBACd,KAAA,EAAO,KAAA,EACP,IAAA;EAAQ,GAAA,EAAK,SAAA;AAAA,IAAc,OAAA,CAAQ,IAAA,CAAK,aAAA,YACvC,WAAA,CAAY,KAAA"}

package/dist/opaque.mjs

@@ -1,70 +1,2 @@
-import { a as readTimestampMs, c as writeTimestamp, d as decodeBase32, f as encodeBase32, i as payloadBase32Length, l as registerBrand, n as is, o as safeParse, r as parse, s as standardValidate, t as base32CharClass, u as validateBrand } from "./shared-CmbAeUdM.mjs";
-//#region src/opaque.ts
-const zeroIv = new Uint8Array(16);
-const pkcsPad = 16;
-function defaultRng(target) {
-	crypto.getRandomValues(target);
-}
-function importOpaqueKey(bytes) {
-	return crypto.subtle.importKey("raw", bytes, "AES-CBC", false, ["encrypt", "decrypt"]);
-}
-function createOpaqueId(brand, opts) {
-	validateBrand(brand);
-	registerBrand(brand, opts.allowDuplicateBrand);
-	const key = opts.key;
-	const now = opts.now ?? Date.now;
-	const rng = opts.rng ?? defaultRng;
-	const prefix = `${brand}_`;
-	return {
-		generate: () => generate(prefix, key, rng, now()),
-		generateAt: (date) => generate(prefix, key, rng, date.getTime()),
-		is: (value) => is(prefix, value),
-		parse: (value) => parse(prefix, value),
-		safeParse: (value) => safeParse(prefix, value),
-		extractTimestamp: (id) => extractTimestamp(prefix, key, id),
-		toJsonSchema: () => toJsonSchema(brand, prefix),
-		"~standard": {
-			version: 1,
-			vendor: "@smonn/ids",
-			validate: (value) => standardValidate(prefix, value)
-		}
-	};
-}
-async function generate(prefix, key, rng, ms) {
-	const plaintext = new Uint8Array(16);
-	writeTimestamp(ms, plaintext);
-	rng(plaintext.subarray(6, 16));
-	return prefix + encodeBase32(new Uint8Array(await crypto.subtle.encrypt({
-		name: "AES-CBC",
-		iv: zeroIv
-	}, key, plaintext)).subarray(0, 16));
-}
-async function extractTimestamp(prefix, key, id) {
-	const c1 = decodeBase32(id.slice(prefix.length));
-	const c2Input = new Uint8Array(16);
-	for (let i = 0; i < 16; i++) c2Input[i] = pkcsPad ^ c1[i];
-	const c2Encrypted = new Uint8Array(await crypto.subtle.encrypt({
-		name: "AES-CBC",
-		iv: zeroIv
-	}, key, c2Input));
-	const ciphertext = new Uint8Array(32);
-	ciphertext.set(c1, 0);
-	ciphertext.set(c2Encrypted.subarray(0, 16), 16);
-	const plaintext = new Uint8Array(await crypto.subtle.decrypt({
-		name: "AES-CBC",
-		iv: zeroIv
-	}, key, ciphertext));
-	return new Date(readTimestampMs(plaintext));
-}
-function toJsonSchema(brand, prefix) {
-	return {
-		type: "string",
-		pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,
-		description: `Branded ID for '${brand}'`,
-		example: prefix + "0".repeat(payloadBase32Length)
-	};
-}
-//#endregion
-export { createOpaqueId, importOpaqueKey };
-
-//# sourceMappingURL=opaque.mjs.map
+import { i as encodeOpaqueKey, n as importOpaqueKey, r as decodeOpaqueKey, t as createOpaqueId } from "./opaque-ChnxvPm5.mjs";
+export { createOpaqueId, decodeOpaqueKey, encodeOpaqueKey, importOpaqueKey };

package/dist/{types-Dg2j_zlO.d.mts → types-Bv-63YK4.d.mts}

@@ -1,9 +1,13 @@
 //#region src/types.d.ts
+/** The brand plus trailing separator — e.g. `usr_` for brand `usr`. */
 type Prefix<Brand extends string> = `${Brand}_`;
+/** A canonical branded ID string for `Brand`. Produced by `generate()` and `safeParse()`. */
 type Id<Brand extends string> = `${Prefix<Brand>}${string}` & {
   readonly __brand: Brand;
 };
+/** Parse failure reason returned by `safeParse()`. */
 type ParseError = "not_string" | "invalid_prefix" | "invalid_base32";
+/** Result of `safeParse()`: canonical `Id<Brand>` or a `ParseError`. */
 type ParseResult<Brand extends string> = {
   ok: true;
   id: Id<Brand>;
@@ -11,12 +15,14 @@ type ParseResult<Brand extends string> = {
   ok: false;
   error: ParseError;
 };
+/** JSON Schema for the canonical wire form returned by `toJsonSchema()`. */
 type JsonSchema = {
   readonly type: "string";
   readonly pattern: string;
   readonly description: string;
   readonly example: string;
 };
+/** Standard Schema validate entry point exposed on `Codec["~standard"]`. */
 type StandardSchemaProps<Brand extends string> = {
   readonly version: 1;
   readonly vendor: "@smonn/ids";
@@ -37,4 +43,4 @@ type StandardSchemaProps<Brand extends string> = {
 };
 //#endregion
 export { StandardSchemaProps as a, ParseResult as i, JsonSchema as n, ParseError as r, Id as t };
-//# sourceMappingURL=types-Dg2j_zlO.d.mts.map
+//# sourceMappingURL=types-Bv-63YK4.d.mts.map

package/dist/types-Bv-63YK4.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-Bv-63YK4.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";;KACY,MAAA,4BAAkC,KAAA;;KAGlC,EAAA,4BAA8B,MAAA,CAAO,KAAA;EAAA,SACtC,OAAA,EAAS,KAAA;AAAA;AADpB;AAAA,KAKY,UAAA;;KAGA,WAAA;EACN,EAAA;EAAU,EAAA,EAAI,EAAA,CAAG,KAAA;AAAA;EACjB,EAAA;EAAW,KAAA,EAAO,UAAA;AAAA;;KAGZ,UAAA;EAAA,SACD,IAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;EAAA,SACA,OAAA;AAAA;;KAIC,mBAAA;EAAA,SACD,OAAA;EAAA,SACA,MAAA;EAAA,SACA,QAAA,GACP,KAAA,WACA,OAAA;IAAA,SAAqB,cAAA,GAAiB,MAAA;EAAA;IAAA,SAEzB,KAAA,EAAO,EAAA,CAAG,KAAA;IAAA,SAAiB,MAAA;EAAA;IAAA,SAC3B,MAAA,EAAQ,aAAA;MAAA,SAAyB,OAAA;IAAA;EAAA;EAAA,SACvC,KAAA;IAAA,SAAmB,KAAA;IAAA,SAAyB,MAAA,EAAQ,EAAA,CAAG,KAAA;EAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smonn/ids",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "MIT",
   "author": "Simon Ingeson (https://github.com/smonn)",
   "repository": {

package/dist/id-B4GiFKYV.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"id-B4GiFKYV.mjs","names":[],"sources":["../src/id.ts"],"sourcesContent":["import { decodeBase32, encodeBase32 } from \"./base32.js\";\nimport { registerBrand, validateBrand } from \"./registry.js\";\nimport {\n  base32CharClass,\n  is,\n  parse,\n  payloadBase32Length,\n  payloadByteLength,\n  readTimestampMs,\n  safeParse,\n  standardValidate,\n  timestampByteLength,\n  writeTimestamp,\n} from \"./shared.js\";\nimport type { Id, JsonSchema, ParseResult, Prefix, StandardSchemaProps } from \"./types.js\";\n\nexport type Options = {\n  now: () => number;\n  rng: (target: Uint8Array) => void;\n  allowDuplicateBrand?: boolean;\n};\n\nexport type Codec<Brand extends string> = {\n  generate(): Id<Brand>;\n  generateAt(date: Date): Id<Brand>;\n  is(value: unknown): value is Id<Brand>;\n  parse(value: unknown): Id<Brand>;\n  safeParse(value: unknown): ParseResult<Brand>;\n  extractTimestamp(id: Id<Brand>): Date;\n  minIdForTime(date: Date): Id<Brand>;\n  maxIdForTime(date: Date): Id<Brand>;\n  toJsonSchema(): JsonSchema;\n  readonly \"~standard\": StandardSchemaProps<Brand>;\n};\n\n// hex charCode → 0–15 nibble, for decoding UUIDv4 strings into bytes.\n// Covers ['0'-'9' = 48–57] and ['a'-'f' = 97–102]; UUIDs are lowercase per spec.\nconst hexCharCodeToNibble = new Uint8Array(128);\nfor (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;\nfor (let i = 0; i < 6; i++) hexCharCodeToNibble[97 + i] = 10 + i;\n\nconst defaultOptions: Options = {\n  now: Date.now,\n  // crypto.randomUUID is ~7× faster than crypto.getRandomValues in Node 24\n  // (~84 ns vs ~610 ns for a 16-byte fill — likely because the UUID path has\n  // a tight fixed-format fast path). We use the 122 random bits of a UUIDv4\n  // string as our entropy source, harvesting 10 fully-random bytes from\n  // positions where no version (hex 12) or variant (hex 16) bits sit.\n  // String layout: \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\" — bytes 0–5 are\n  // string[0..7]+string[9..12], bytes 6–9 are string[24..31].\n  rng: (target) => {\n    const s = crypto.randomUUID();\n    target[0] =\n      (hexCharCodeToNibble[s.charCodeAt(0)]! << 4) | hexCharCodeToNibble[s.charCodeAt(1)]!;\n    target[1] =\n      (hexCharCodeToNibble[s.charCodeAt(2)]! << 4) | hexCharCodeToNibble[s.charCodeAt(3)]!;\n    target[2] =\n      (hexCharCodeToNibble[s.charCodeAt(4)]! << 4) | hexCharCodeToNibble[s.charCodeAt(5)]!;\n    target[3] =\n      (hexCharCodeToNibble[s.charCodeAt(6)]! << 4) | hexCharCodeToNibble[s.charCodeAt(7)]!;\n    target[4] =\n      (hexCharCodeToNibble[s.charCodeAt(9)]! << 4) | hexCharCodeToNibble[s.charCodeAt(10)]!;\n    target[5] =\n      (hexCharCodeToNibble[s.charCodeAt(11)]! << 4) | hexCharCodeToNibble[s.charCodeAt(12)]!;\n    target[6] =\n      (hexCharCodeToNibble[s.charCodeAt(24)]! << 4) | hexCharCodeToNibble[s.charCodeAt(25)]!;\n    target[7] =\n      (hexCharCodeToNibble[s.charCodeAt(26)]! << 4) | hexCharCodeToNibble[s.charCodeAt(27)]!;\n    target[8] =\n      (hexCharCodeToNibble[s.charCodeAt(28)]! << 4) | hexCharCodeToNibble[s.charCodeAt(29)]!;\n    target[9] =\n      (hexCharCodeToNibble[s.charCodeAt(30)]! << 4) | hexCharCodeToNibble[s.charCodeAt(31)]!;\n  },\n};\n\nconst randomByteLength = payloadByteLength - timestampByteLength;\nconst timestampBase32Length = Math.ceil((timestampByteLength * 8) / 5);\n\nexport function createId<Brand extends string>(\n  brand: Brand,\n  opts: Partial<Options> = {},\n): Codec<Brand> {\n  validateBrand(brand);\n  registerBrand(brand, opts.allowDuplicateBrand);\n\n  const options = {\n    ...defaultOptions,\n    ...opts,\n  } satisfies Options;\n\n  const prefix: Prefix<Brand> = `${brand}_`;\n  // Per-codec scratch buffer. Shared across generate(), generateAt(),\n  // minIdForTime(), and maxIdForTime() — all are synchronous and overwrite both\n  // the timestamp and random slices before encoding, so successive callers see\n  // their own freshly-written bytes. encodeBase32 reads the buffer and\n  // returns an independent string, so the caller never sees the buffer itself.\n  const buffer = new Uint8Array(payloadByteLength);\n  const randomView = new Uint8Array(buffer.buffer, timestampByteLength, randomByteLength);\n\n  return {\n    generate: () => generate(prefix, options, buffer, randomView),\n    generateAt: (date: Date) => generate(prefix, options, buffer, randomView, date.getTime()),\n    is: (value: unknown) => is(prefix, value),\n    parse: (value: unknown) => parse(prefix, value),\n    safeParse: (value: unknown) => safeParse(prefix, value),\n    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, id),\n    minIdForTime: (date: Date) => sentinelIdForTime(prefix, date, 0x00, buffer, randomView),\n    maxIdForTime: (date: Date) => sentinelIdForTime(prefix, date, 0xff, buffer, randomView),\n    toJsonSchema: () => toJsonSchema(brand, prefix, options, buffer, randomView),\n    \"~standard\": {\n      version: 1,\n      vendor: \"@smonn/ids\",\n      validate: (value: unknown) => standardValidate(prefix, value),\n    },\n  };\n}\n\nfunction toJsonSchema<Brand extends string>(\n  brand: Brand,\n  prefix: Prefix<Brand>,\n  options: Options,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n): JsonSchema {\n  return {\n    type: \"string\",\n    pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,\n    description: `Branded ID for '${brand}'`,\n    example: generate(prefix, options, buffer, randomView),\n  };\n}\n\nfunction generate<Brand extends string>(\n  prefix: Prefix<Brand>,\n  options: Options,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n  ms: number = options.now(),\n): Id<Brand> {\n  writeTimestamp(ms, buffer);\n  options.rng(randomView);\n  return (prefix + encodeBase32(buffer)) as Id<Brand>;\n}\n\nfunction sentinelIdForTime<Brand extends string>(\n  prefix: Prefix<Brand>,\n  date: Date,\n  fill: number,\n  buffer: Uint8Array,\n  randomView: Uint8Array,\n): Id<Brand> {\n  writeTimestamp(date.getTime(), buffer);\n  randomView.fill(fill);\n  return (prefix + encodeBase32(buffer)) as Id<Brand>;\n}\n\nfunction extractTimestamp<Brand extends string>(prefix: Prefix<Brand>, id: Id<Brand>): Date {\n  const base32 = id.slice(prefix.length, prefix.length + timestampBase32Length);\n  return new Date(readTimestampMs(decodeBase32(base32)));\n}\n"],"mappings":"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"}

package/dist/opaque.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"opaque.mjs","names":[],"sources":["../src/opaque.ts"],"sourcesContent":["import { decodeBase32, encodeBase32 } from \"./base32.js\";\nimport { registerBrand, validateBrand } from \"./registry.js\";\nimport {\n  base32CharClass,\n  is,\n  parse,\n  payloadBase32Length,\n  payloadByteLength,\n  readTimestampMs,\n  safeParse,\n  standardValidate,\n  timestampByteLength,\n  writeTimestamp,\n} from \"./shared.js\";\nimport type { Id, JsonSchema, ParseResult, Prefix, StandardSchemaProps } from \"./types.js\";\n\nexport type OpaqueOptions = {\n  key: CryptoKey;\n  now: () => number;\n  rng: (target: Uint8Array) => void;\n  allowDuplicateBrand?: boolean;\n};\n\nexport type OpaqueCodec<Brand extends string> = {\n  generate(): Promise<Id<Brand>>;\n  generateAt(date: Date): Promise<Id<Brand>>;\n  is(value: unknown): value is Id<Brand>;\n  parse(value: unknown): Id<Brand>;\n  safeParse(value: unknown): ParseResult<Brand>;\n  extractTimestamp(id: Id<Brand>): Promise<Date>;\n  toJsonSchema(): JsonSchema;\n  readonly \"~standard\": StandardSchemaProps<Brand>;\n};\n\nconst zeroIv = new Uint8Array(payloadByteLength);\nconst pkcsPad = 0x10;\n\nfunction defaultRng(target: Uint8Array): void {\n  crypto.getRandomValues(target as Uint8Array<ArrayBuffer>);\n}\n\nexport function importOpaqueKey(bytes: Uint8Array): Promise<CryptoKey> {\n  return crypto.subtle.importKey(\"raw\", bytes as Uint8Array<ArrayBuffer>, \"AES-CBC\", false, [\n    \"encrypt\",\n    \"decrypt\",\n  ]);\n}\n\nexport function createOpaqueId<Brand extends string>(\n  brand: Brand,\n  opts: { key: CryptoKey } & Partial<Omit<OpaqueOptions, \"key\">>,\n): OpaqueCodec<Brand> {\n  validateBrand(brand);\n  registerBrand(brand, opts.allowDuplicateBrand);\n\n  const key = opts.key;\n  const now = opts.now ?? Date.now;\n  const rng = opts.rng ?? defaultRng;\n  const prefix: Prefix<Brand> = `${brand}_`;\n\n  return {\n    generate: () => generate(prefix, key, rng, now()),\n    generateAt: (date: Date) => generate(prefix, key, rng, date.getTime()),\n    is: (value: unknown) => is(prefix, value),\n    parse: (value: unknown) => parse(prefix, value),\n    safeParse: (value: unknown) => safeParse(prefix, value),\n    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, key, id),\n    toJsonSchema: () => toJsonSchema(brand, prefix),\n    \"~standard\": {\n      version: 1,\n      vendor: \"@smonn/ids\",\n      validate: (value: unknown) => standardValidate(prefix, value),\n    },\n  };\n}\n\n// Per-call buffers, unlike id.ts's codec-shared scratch. Reuse would be safe\n// (subtle.encrypt/decrypt snapshot inputs synchronously, per WebCrypto step 2\n// before the Promise returns) but subtle dominates this path — the allocation\n// is <1% of total cost, not worth pinning the design to that spec detail.\nasync function generate<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  rng: (target: Uint8Array) => void,\n  ms: number,\n): Promise<Id<Brand>> {\n  const plaintext = new Uint8Array(payloadByteLength);\n  writeTimestamp(ms, plaintext);\n  rng(plaintext.subarray(timestampByteLength, payloadByteLength));\n  const encrypted = new Uint8Array(\n    await crypto.subtle.encrypt({ name: \"AES-CBC\", iv: zeroIv }, key, plaintext),\n  );\n  return (prefix + encodeBase32(encrypted.subarray(0, payloadByteLength))) as Id<Brand>;\n}\n\nasync function extractTimestamp<Brand extends string>(\n  prefix: Prefix<Brand>,\n  key: CryptoKey,\n  id: Id<Brand>,\n): Promise<Date> {\n  const c1 = decodeBase32(id.slice(prefix.length));\n  // Reconstruct C2 = AES_K(P2 XOR C1) where P2 is the PKCS#7 pad block (0x10×16).\n  // CBC encrypt of (P2 XOR C1) with IV=0 yields AES_K(P2 XOR C1) as the first 16 bytes.\n  const c2Input = new Uint8Array(payloadByteLength);\n  for (let i = 0; i < payloadByteLength; i++) c2Input[i] = pkcsPad ^ c1[i]!;\n  const c2Encrypted = new Uint8Array(\n    await crypto.subtle.encrypt({ name: \"AES-CBC\", iv: zeroIv }, key, c2Input),\n  );\n  const ciphertext = new Uint8Array(payloadByteLength * 2);\n  ciphertext.set(c1, 0);\n  ciphertext.set(c2Encrypted.subarray(0, payloadByteLength), payloadByteLength);\n  const plaintext = new Uint8Array(\n    await crypto.subtle.decrypt({ name: \"AES-CBC\", iv: zeroIv }, key, ciphertext),\n  );\n  return new Date(readTimestampMs(plaintext));\n}\n\nfunction toJsonSchema<Brand extends string>(brand: Brand, prefix: Prefix<Brand>): JsonSchema {\n  return {\n    type: \"string\",\n    pattern: `^${prefix}${base32CharClass}{${payloadBase32Length}}$`,\n    description: `Branded ID for '${brand}'`,\n    // The Opaque codec cannot synchronously produce a real example (encrypt is\n    // async). A deterministic structurally-valid placeholder satisfies the\n    // JSON Schema contract without requiring the key at schema time.\n    example: prefix + \"0\".repeat(payloadBase32Length),\n  };\n}\n"],"mappings":";;AAkCA,MAAM,SAAS,IAAI,WAAA,EAA4B;AAC/C,MAAM,UAAU;AAEhB,SAAS,WAAW,QAA0B;CAC5C,OAAO,gBAAgB,MAAiC;AAC1D;AAEA,SAAgB,gBAAgB,OAAuC;CACrE,OAAO,OAAO,OAAO,UAAU,OAAO,OAAkC,WAAW,OAAO,CACxF,WACA,SACF,CAAC;AACH;AAEA,SAAgB,eACd,OACA,MACoB;CACpB,cAAc,KAAK;CACnB,cAAc,OAAO,KAAK,mBAAmB;CAE7C,MAAM,MAAM,KAAK;CACjB,MAAM,MAAM,KAAK,OAAO,KAAK;CAC7B,MAAM,MAAM,KAAK,OAAO;CACxB,MAAM,SAAwB,GAAG,MAAM;CAEvC,OAAO;EACL,gBAAgB,SAAS,QAAQ,KAAK,KAAK,IAAI,CAAC;EAChD,aAAa,SAAe,SAAS,QAAQ,KAAK,KAAK,KAAK,QAAQ,CAAC;EACrE,KAAK,UAAmB,GAAG,QAAQ,KAAK;EACxC,QAAQ,UAAmB,MAAM,QAAQ,KAAK;EAC9C,YAAY,UAAmB,UAAU,QAAQ,KAAK;EACtD,mBAAmB,OAAkB,iBAAiB,QAAQ,KAAK,EAAE;EACrE,oBAAoB,aAAa,OAAO,MAAM;EAC9C,aAAa;GACX,SAAS;GACT,QAAQ;GACR,WAAW,UAAmB,iBAAiB,QAAQ,KAAK;EAC9D;CACF;AACF;AAMA,eAAe,SACb,QACA,KACA,KACA,IACoB;CACpB,MAAM,YAAY,IAAI,WAAA,EAA4B;CAClD,eAAe,IAAI,SAAS;CAC5B,IAAI,UAAU,SAAA,GAAA,EAA+C,CAAC;CAI9D,OAAQ,SAAS,aAAa,IAHR,WACpB,MAAM,OAAO,OAAO,QAAQ;EAAE,MAAM;EAAW,IAAI;CAAO,GAAG,KAAK,SAAS,CAEvC,EAAE,SAAS,GAAA,EAAoB,CAAC;AACxE;AAEA,eAAe,iBACb,QACA,KACA,IACe;CACf,MAAM,KAAK,aAAa,GAAG,MAAM,OAAO,MAAM,CAAC;CAG/C,MAAM,UAAU,IAAI,WAAA,EAA4B;CAChD,KAAK,IAAI,IAAI,GAAG,IAAA,IAAuB,KAAK,QAAQ,KAAK,UAAU,GAAG;CACtE,MAAM,cAAc,IAAI,WACtB,MAAM,OAAO,OAAO,QAAQ;EAAE,MAAM;EAAW,IAAI;CAAO,GAAG,KAAK,OAAO,CAC3E;CACA,MAAM,aAAa,IAAI,WAAA,EAAgC;CACvD,WAAW,IAAI,IAAI,CAAC;CACpB,WAAW,IAAI,YAAY,SAAS,GAAA,EAAoB,GAAA,EAAoB;CAC5E,MAAM,YAAY,IAAI,WACpB,MAAM,OAAO,OAAO,QAAQ;EAAE,MAAM;EAAW,IAAI;CAAO,GAAG,KAAK,UAAU,CAC9E;CACA,OAAO,IAAI,KAAK,gBAAgB,SAAS,CAAC;AAC5C;AAEA,SAAS,aAAmC,OAAc,QAAmC;CAC3F,OAAO;EACL,MAAM;EACN,SAAS,IAAI,SAAS,gBAAgB,GAAG,oBAAoB;EAC7D,aAAa,mBAAmB,MAAM;EAItC,SAAS,SAAS,IAAI,OAAO,mBAAmB;CAClD;AACF"}

package/dist/types-Dg2j_zlO.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types-Dg2j_zlO.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";KAAY,MAAA,4BAAkC,KAAA;AAAA,KAElC,EAAA,4BAA8B,MAAA,CAAO,KAAA;EAAA,SACtC,OAAA,EAAS,KAAA;AAAA;AAAA,KAGR,UAAA;AAAA,KAEA,WAAA;EACN,EAAA;EAAU,EAAA,EAAI,EAAA,CAAG,KAAA;AAAA;EACjB,EAAA;EAAW,KAAA,EAAO,UAAA;AAAA;AAAA,KAEZ,UAAA;EAAA,SACD,IAAA;EAAA,SACA,OAAA;EAAA,SACA,WAAA;EAAA,SACA,OAAA;AAAA;AAAA,KAGC,mBAAA;EAAA,SACD,OAAA;EAAA,SACA,MAAA;EAAA,SACA,QAAA,GACP,KAAA,WACA,OAAA;IAAA,SAAqB,cAAA,GAAiB,MAAA;EAAA;IAAA,SAEzB,KAAA,EAAO,EAAA,CAAG,KAAA;IAAA,SAAiB,MAAA;EAAA;IAAA,SAC3B,MAAA,EAAQ,aAAA;MAAA,SAAyB,OAAA;IAAA;EAAA;EAAA,SACvC,KAAA;IAAA,SAAmB,KAAA;IAAA,SAAyB,MAAA,EAAQ,EAAA,CAAG,KAAA;EAAA;AAAA"}