@smonn/ids 0.8.0 → 0.9.1

package/README.md

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

package/dist/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"}