@smonn/ids 0.8.0 → 0.9.0

package/README.md

@@ -391,6 +391,28 @@ Encryption is AES-CBC with a zero IV. That's deliberately safe here because the
 
 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)).
 
+**Rotating the Opaque key.** Rotation is **forward-only and caller-tracked** — the codec deliberately has no key ring. The key feeds only `generate` and `extractTimestamp`; `parse`, `safeParse`, `is`, and `toJsonSchema` work on the wire form and never touch it, so rotating forward is nearly free: point new writes at a new key and keep the old key only to read old IDs' timestamps. Because the payload is unauthenticated ([ADR-0004](./docs/adr/0004-aes-cbc-strip-trick.md)) and carries no key id ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)), the library **cannot** trial a ring to pick the right key for you — a wrong key yields a plausible but wrong timestamp, never an error. You hold one codec per _key epoch_ and select it from your own record of which epoch minted each ID:
+
+```ts
+// One codec instance per key epoch. You — not the library — track which epoch
+// minted each ID (a key-epoch column, tenant→key map, created-at cutover). The
+// epoch CANNOT be read from the ID itself. `allowDuplicateBrand` silences the
+// per-brand registry warning (ADR-0007): multiple instances of one brand is the
+// legitimate case that flag exists for.
+const codecs = new Map([
+  [1, createOpaqueTimestampId("inv", { key: keyV1, allowDuplicateBrand: true })],
+  [2, createOpaqueTimestampId("inv", { key: keyV2, allowDuplicateBrand: true })], // current epoch
+]);
+
+const id = await codecs.get(2)!.generate(); // new IDs use the current epoch's key
+
+// Reading an old ID: look up its epoch from your records, pick that codec.
+const epoch = await db.keyEpochFor(someOldId); // your bookkeeping, not the ID
+await codecs.get(epoch)!.extractTimestamp(someOldId);
+```
+
+If you need transparent, correctness-grade rotation where the library trials a key ring and a wrong key is _rejected_, that's the Signed Timestamp codec's job ([ADR-0012](./docs/adr/0012-signed-timestamp-construction.md)) — its HMAC tag gives a verifiable ring. The Opaque codec trades that away for confidentiality. See [ADR-0013](./docs/adr/0013-opaque-key-rotation.md).
+
 ### "Newest-first IDs for descending range scans"
 
 Most KV stores (DynamoDB, Cloud Datastore, range-scan KV) only support forward lexicographic scans natively — reading the most recent entries first would otherwise require a full reverse scan or a separate sort step. The Reverse Timestamp codec solves this by bitwise-inverting the 48-bit timestamp field before encoding, so newer IDs sort lexicographically before older ones.
@@ -425,12 +447,13 @@ No key material is required. The inversion is a deterministic byte transform; `g
 
 ## Choosing a codec variant
 
-| Codec             | Import               | Sort direction            | Key required       | Timestamp extractable      | Range query support                                            |
-| ----------------- | -------------------- | ------------------------- | ------------------ | -------------------------- | -------------------------------------------------------------- |
-| Timestamp         | `@smonn/ids`         | Ascending (oldest-first)  | No                 | Always                     | `minIdForTime(t_old)` → `maxIdForTime(t_new)`                  |
-| Reverse Timestamp | `@smonn/ids/reverse` | Descending (newest-first) | No                 | Always                     | `minIdForTime(t_new)` → `maxIdForTime(t_old)` (bounds flipped) |
-| Opaque Timestamp  | `@smonn/ids/opaque`  | None (encrypted)          | Yes (AES key)      | With key only              | None — encrypted payloads do not sort by time                  |
-| Wrapped key       | `@smonn/ids/wrapped` | None                      | Yes (wrapping key) | N/A — not timestamp-family | None                                                           |
+| Codec             | Import               | Sort direction            | Key required       | Timestamp extractable      | Range query support                                                          |
+| ----------------- | -------------------- | ------------------------- | ------------------ | -------------------------- | ---------------------------------------------------------------------------- |
+| Timestamp         | `@smonn/ids`         | Ascending (oldest-first)  | No                 | Always (plaintext)         | `minIdForTime(t_old)` → `maxIdForTime(t_new)`                                |
+| Reverse Timestamp | `@smonn/ids/reverse` | Descending (newest-first) | No                 | Always (plaintext)         | `minIdForTime(t_new)` → `maxIdForTime(t_old)` (bounds flipped)               |
+| Signed Timestamp  | `@smonn/ids/signed`  | Ascending (oldest-first)  | Yes (signing key)  | Always (plaintext)         | `minIdForTime(t_old)` → `maxIdForTime(t_new)` (sentinels carry no valid tag) |
+| Opaque Timestamp  | `@smonn/ids/opaque`  | None (encrypted)          | Yes (AES key)      | With key only              | None — encrypted payloads do not sort by time                                |
+| Wrapped key       | `@smonn/ids/wrapped` | None                      | Yes (wrapping key) | N/A — not timestamp-family | None                                                                         |
 
 ## What this is **not** for
 
@@ -553,6 +576,84 @@ import {
 } from "@smonn/ids/fastify";
 ```
 
+`@smonn/ids/signed` ships the Signed Timestamp codec — it keeps the 48-bit timestamp **readable and sortable** like the Timestamp codec, but replaces half of the random tail with a truncated HMAC tag, making IDs **tamper-evident and verifiable without a database lookup**. This adds **integrity, not confidentiality** — the opposite security axis from the Opaque Timestamp codec, which hides the timestamp but has no auth tag.
+
+The canonical use case is **share links**: embed a Signed Timestamp ID in a share URL and verify it on receipt without a database roundtrip.
+
+```ts
+import { createSignedTimestampId, importSigningKey } from "@smonn/ids/signed";
+
+const key = await importSigningKey(new Uint8Array(32));
+const shares = createSignedTimestampId("shr", { keys: [key] });
+
+const id = await shares.generate(); // "shr_…", timestamp readable and sortable
+shares.extractTimestamp(id); // Date — sync, timestamp is plaintext
+
+await shares.verify(id); // passes; throws IdsError verification_failed on tamper
+```
+
+The non-throwing `safeVerify` path accepts untrusted input, structurally parses first, then verifies — without throwing:
+
+```ts
+const result = await shares.safeVerify(req.params.shareId);
+
+if (!result.ok) {
+  if (result.error === "verification_failed") return 403; // tampered or wrong key
+  return 400; // malformed ID
+}
+
+const { id } = result; // Id<"shr">, canonical
+```
+
+`safeVerify` returns one of:
+
+```ts
+// Success
+{
+  ok: true;
+  id: Id<Brand>;
+}
+
+// Structural parse failure (wrong brand, invalid base32, etc.)
+{
+  ok: false;
+  error: "not_string" | "invalid_prefix" | "invalid_base32";
+}
+
+// Structurally valid but tag mismatch (tampered, wrong keyring, or revoked key)
+{
+  ok: false;
+  error: "verification_failed";
+}
+```
+
+**False-accept bound.** With a signing keyring of `n` entries, an attacker's per-`verify` success probability is approximately `n / 2⁴⁰`. Verification is online-only — the signing key lives server-side, so offline guessing is not possible.
+
+**Key handling.** Import signing key material via `importSigningKey(bytes)` from raw bytes (16, 24, or 32 bytes). Signing-key material is a **separate secret domain** from Opaque keys and Wrapping keys — same `hex` / `base64url` encoded-format conventions, but a distinct `SigningKey` handle and HKDF label so one raw secret cannot silently serve multiple codecs.
+
+```ts
+import { encodeSigningKey, decodeSigningKey } from "@smonn/ids/signed";
+
+const encoded = encodeSigningKey(rawBytes, "base64url"); // string
+const decoded = decodeSigningKey(encoded, "base64url"); // Uint8Array
+```
+
+**Managing the signing keyring.** Pass a non-empty ordered list of signing keys at construction. The first entry is the _current_ key — the only one `generate` / `generateAt` sign with. `verify` / `safeVerify` trial every entry in order until the tag matches, so IDs signed under any listed key remain verifiable. Removing an entry from the list revokes all IDs signed under it.
+
+```ts
+const oldKey = await importSigningKey(rawOldSecret);
+const newKey = await importSigningKey(rawNewSecret);
+
+// Before rotation: only oldKey in the ring
+const legacy = createSignedTimestampId("shr", { keys: [oldKey] });
+const id = await legacy.generate();
+
+// After rotation: newKey is current; oldKey is still accepted on verify
+const rotated = createSignedTimestampId("shr", { keys: [newKey, oldKey] });
+await rotated.verify(id); // succeeds — tried oldKey and matched
+await rotated.generate(); // signs with newKey
+```
+
 `@smonn/ids/wrapped` ships the Wrapped key codec for `u32`, `i32`, `u64`, and `i64` lookup keys. `wrap(lookupKey)` returns a public ID; `unwrap(id)` verifies the payload and returns the lookup key; `safeUnwrap(input)` is the non-throwing path for untrusted input.
 
 **Integer kinds and value types.** The 32-bit kinds (`u32`, `i32`) use safe JavaScript `number` values in their fixed-width ranges. The 64-bit kinds (`u64`, `i64`) always use `bigint` — even when the magnitude would fit in a `number` — to prevent silent truncation or sign erasure.
@@ -642,23 +743,27 @@ const { id, lookupKey } = result; // Id<"inv">, number
 
 ### Codec methods
 
-| Method                 | `TimestampCodec<Brand>` | `ReverseTimestampCodec<Brand>` | `OpaqueTimestampCodec<Brand>` | `WrappedKeyCodec<Brand, Kind>` | Description                                                                   |
-| ---------------------- | ----------------------- | ------------------------------ | ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
-| `generate()`           | sync                    | sync                           | async                         | —                              | Produce a fresh ID                                                            |
-| `generateAt(date)`     | sync                    | sync                           | async                         | —                              | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
-| `wrap(lookupKey)`      | —                       | —                              | —                             | async                          | Wrap a lookup key into a public ID using the current wrapping key             |
-| `unwrap(id)`           | —                       | —                              | —                             | async                          | Verify and recover the lookup key; throws on verification failure             |
-| `safeUnwrap(input)`    | —                       | —                              | —                             | async                          | Non-throwing: structurally parse then verify; returns parse or verify error   |
-| `is(value)`            | sync                    | sync                           | sync                          | sync                           | Strict type guard: `true` only for already-canonical strings                  |
-| `parse(value)`         | sync                    | sync                           | sync                          | sync                           | Lenient: normalise to canonical, or throw                                     |
-| `safeParse(value)`     | sync                    | sync                           | sync                          | sync                           | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
-| `extractTimestamp(id)` | sync                    | sync                           | async                         | —                              | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
-| `minIdForTime(date)`   | sync                    | sync †                         | —                             | —                              | Tight lower bound for any ID generated at `date` (for range queries)          |
-| `maxIdForTime(date)`   | sync                    | sync †                         | —                             | —                              | Tight upper bound for any ID generated at `date` (for range queries)          |
-| `toJsonSchema()`       | sync                    | sync                           | sync                          | sync                           | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
+| Method                 | `TimestampCodec<Brand>` | `ReverseTimestampCodec<Brand>` | `OpaqueTimestampCodec<Brand>` | `SignedTimestampCodec<Brand>` | `WrappedKeyCodec<Brand, Kind>` | Description                                                                   |
+| ---------------------- | ----------------------- | ------------------------------ | ----------------------------- | ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `generate()`           | sync                    | sync                           | async                         | async                         | —                              | Produce a fresh ID                                                            |
+| `generateAt(date)`     | sync                    | sync                           | async                         | async                         | —                              | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
+| `verify(id)`           | —                       | —                              | —                             | async                         | —                              | Verify the HMAC tag; throws `IdsError` `verification_failed` on mismatch      |
+| `safeVerify(input)`    | —                       | —                              | —                             | async                         | —                              | Non-throwing: structurally parse then verify; returns parse or verify error   |
+| `wrap(lookupKey)`      | —                       | —                              | —                             | —                             | async                          | Wrap a lookup key into a public ID using the current wrapping key             |
+| `unwrap(id)`           | —                       | —                              | —                             | —                             | async                          | Verify and recover the lookup key; throws on verification failure             |
+| `safeUnwrap(input)`    | —                       | —                              | —                             | —                             | async                          | Non-throwing: structurally parse then verify; returns parse or verify error   |
+| `is(value)`            | sync                    | sync                           | sync                          | sync                          | sync                           | Strict type guard: `true` only for already-canonical strings                  |
+| `parse(value)`         | sync                    | sync                           | sync                          | sync                          | sync                           | Lenient: normalise to canonical, or throw                                     |
+| `safeParse(value)`     | sync                    | sync                           | sync                          | sync                          | sync                           | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
+| `extractTimestamp(id)` | sync                    | sync                           | async                         | sync                          | —                              | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
+| `minIdForTime(date)`   | sync                    | sync †                         | —                             | sync ‡                        | —                              | Tight lower bound for any ID generated at `date` (for range queries)          |
+| `maxIdForTime(date)`   | sync                    | sync †                         | —                             | sync ‡                        | —                              | Tight upper bound for any ID generated at `date` (for range queries)          |
+| `toJsonSchema()`       | sync                    | sync                           | sync                          | sync                          | sync                           | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
 
 † Under the Reverse Timestamp codec, a newer timestamp maps to a lexicographically smaller ID — pass `minIdForTime(t_new)` as the lower bound and `maxIdForTime(t_old)` as the upper bound for a [t_old, t_new] scan.
 
+‡ Signed Timestamp sentinels carry no valid HMAC tag and are not verifiable — they exist only for indexed range scans, not as real IDs.
+
 ## ORM adapters
 
 ### Drizzle (`@smonn/ids/drizzle`)

package/dist/adapter-types-BY-wrYYB.mjs

@@ -0,0 +1,27 @@
+import { t as IdsError } from "./error-Cp5qYZcv.mjs";
+//#region src/adapter-types.ts
+/** Parses `value` as `Id<Brand>` via `codec.safeParse`; throws `IdsError("invalid_id")` on failure. Shared read helper for ORM adapters. */
+function readIdColumn(codec, value) {
+	const result = codec.safeParse(value);
+	if (!result.ok) throw new IdsError("invalid_id", `invalid ID from database: ${result.error}`, { cause: result.error });
+	return result.id;
+}
+/**
+* Maps a `ParseError` to `{ reason, status }` for web adapter failure handling.
+*
+* - `invalid_prefix` → `brand_mismatch` / default 404
+* - anything else → `malformed` / default 400
+* - `options.status[reason]` overrides the default for that reason
+*/
+function resolveIdParamFailure(error, options) {
+	const reason = error === "invalid_prefix" ? "brand_mismatch" : "malformed";
+	const defaultStatus = reason === "brand_mismatch" ? 404 : 400;
+	return {
+		reason,
+		status: options?.status?.[reason] ?? defaultStatus
+	};
+}
+//#endregion
+export { resolveIdParamFailure as n, readIdColumn as t };
+
+//# sourceMappingURL=adapter-types-BY-wrYYB.mjs.map

package/dist/adapter-types-BY-wrYYB.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-types-BY-wrYYB.mjs","names":[],"sources":["../src/adapter-types.ts"],"sourcesContent":["import { IdsError } from \"./error.js\";\nimport type { Id, ParseError, ParseResult } from \"./types.js\";\n\n/** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */\nexport type IdParamFailure =\n  | { readonly reason: \"brand_mismatch\"; readonly status: number }\n  | { readonly reason: \"malformed\"; readonly status: number };\n\n/** Minimum structural type required by web and ORM adapters. Any codec variant satisfies this — all expose `safeParse`. Adapters only ever call `safeParse` — never key-dependent methods like `extractTimestamp`, `wrap`, or `unwrap`. */\nexport type IdCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/** Re-exported from ORM adapter subpaths (`@smonn/ids/drizzle`, `@smonn/ids/prisma`, `@smonn/ids/kysely`) under the public name; structurally identical to {@link IdCodec}. */\nexport type IdColumnCodec<Brand extends string> = IdCodec<Brand>;\n\n/** Parses `value` as `Id<Brand>` via `codec.safeParse`; throws `IdsError(\"invalid_id\")` on failure. Shared read helper for ORM adapters. */\nexport function readIdColumn<Brand extends string>(\n  codec: IdCodec<Brand>,\n  value: unknown,\n): Id<Brand> {\n  const result = codec.safeParse(value);\n  if (!result.ok) {\n    throw new IdsError(\"invalid_id\", `invalid ID from database: ${result.error}`, {\n      cause: result.error,\n    });\n  }\n  return result.id;\n}\n\n/**\n * Maps a `ParseError` to `{ reason, status }` for web adapter failure handling.\n *\n * - `invalid_prefix` → `brand_mismatch` / default 404\n * - anything else → `malformed` / default 400\n * - `options.status[reason]` overrides the default for that reason\n */\nexport function resolveIdParamFailure(\n  error: ParseError,\n  options?: { status?: { brand_mismatch?: number; malformed?: number } },\n): IdParamFailure {\n  const reason = error === \"invalid_prefix\" ? (\"brand_mismatch\" as const) : (\"malformed\" as const);\n  const defaultStatus = reason === \"brand_mismatch\" ? 404 : 400;\n  const status = options?.status?.[reason] ?? defaultStatus;\n  return { reason, status };\n}\n"],"mappings":";;;AAiBA,SAAgB,aACd,OACA,OACW;CACX,MAAM,SAAS,MAAM,UAAU,KAAK;CACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,SAAS,cAAc,6BAA6B,OAAO,SAAS,EAC5E,OAAO,OAAO,MAChB,CAAC;CAEH,OAAO,OAAO;AAChB;;;;;;;;AASA,SAAgB,sBACd,OACA,SACgB;CAChB,MAAM,SAAS,UAAU,mBAAoB,mBAA8B;CAC3E,MAAM,gBAAgB,WAAW,mBAAmB,MAAM;CAE1D,OAAO;EAAE;EAAQ,QADF,SAAS,SAAS,WAAW;CACpB;AAC1B"}

package/dist/adapter-types-unUcmMXC.d.mts

@@ -0,0 +1,20 @@
+import { i as ParseResult } from "./types-g7CiQDyE.mjs";
+
+//#region src/adapter-types.d.ts
+/** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */
+type IdParamFailure = {
+  readonly reason: "brand_mismatch";
+  readonly status: number;
+} | {
+  readonly reason: "malformed";
+  readonly status: number;
+};
+/** Minimum structural type required by web and ORM adapters. Any codec variant satisfies this — all expose `safeParse`. Adapters only ever call `safeParse` — never key-dependent methods like `extractTimestamp`, `wrap`, or `unwrap`. */
+type IdCodec<Brand extends string> = {
+  safeParse(value: unknown): ParseResult<Brand>;
+};
+/** Re-exported from ORM adapter subpaths (`@smonn/ids/drizzle`, `@smonn/ids/prisma`, `@smonn/ids/kysely`) under the public name; structurally identical to {@link IdCodec}. */
+type IdColumnCodec<Brand extends string> = IdCodec<Brand>;
+//#endregion
+export { IdColumnCodec as n, IdParamFailure as r, IdCodec as t };
+//# sourceMappingURL=adapter-types-unUcmMXC.d.mts.map

package/dist/adapter-types-unUcmMXC.d.mts.map

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