@c9up/ream 0.1.33 → 0.2.0

package/src/migrations/MigrationRegistry.ts

@@ -0,0 +1,49 @@
+import type { RegisteredMigrationSource } from './types.js'
+
+/**
+ * Where every store's migration runner registers itself.
+ *
+ * Bound in the container as `migrations`, always — an app with no data package
+ * gets an EMPTY registry, never a missing binding. That distinction is what
+ * lets the CLI tell "this app has no migrations" from "this app predates the
+ * registry", and say something useful in each case instead of failing the same
+ * way twice.
+ */
+export class MigrationRegistry {
+  readonly #sources = new Map<string, RegisteredMigrationSource>()
+
+  /**
+   * Register a store's runner. Registering the same name twice is refused:
+   * silently replacing it would mean one of two providers migrates nothing,
+   * and the run would still report success.
+   */
+  register(source: RegisteredMigrationSource): this {
+    if (this.#sources.has(source.name)) {
+      throw new Error(
+        `A migration source named '${source.name}' is already registered. Two providers cannot claim one name — one of them would migrate nothing while the run still reported success.`,
+      )
+    }
+    this.#sources.set(source.name, source)
+    return this
+  }
+
+  /** Every registered store, in registration order. */
+  all(): RegisteredMigrationSource[] {
+    return [...this.#sources.values()]
+  }
+
+  /** One store by name, or `undefined`. */
+  get(name: string): RegisteredMigrationSource | undefined {
+    return this.#sources.get(name)
+  }
+
+  /** The registered names, for an error message that lists what IS available. */
+  names(): string[] {
+    return [...this.#sources.keys()]
+  }
+
+  /** Whether anything registered. */
+  get isEmpty(): boolean {
+    return this.#sources.size === 0
+  }
+}

package/src/migrations/types.ts

@@ -0,0 +1,68 @@
+/**
+ * The contract a data package implements so `ream migrate` can drive it.
+ *
+ * REAM PARTICULARITY, deliberate — AdonisJS has no equivalent, because Lucid is
+ * its only migration source: `node ace migration:run` can name it directly.
+ * Ream expects several stores in one app (a relational one, a time-series one,
+ * whatever comes next), so the CLI must not name any of them. A store registers
+ * itself and the CLI stays generic for good.
+ *
+ * The vocabulary is Adonis' where Adonis has one: a status node is
+ * `{ name, status, batch? }`, spelled `status` as Lucid's `MigrationListNode`
+ * spells it.
+ */
+
+/** Whether a migration has run. */
+export type MigrationState = 'applied' | 'pending'
+
+/** One migration's position, as `ream migrate:status` prints it. */
+export interface MigrationStatusNode {
+  /** The migration's name, without extension. */
+  name: string
+  status: MigrationState
+  /** The batch it was applied in, when it has been. */
+  batch?: number
+}
+
+/**
+ * What a store's migration runner must provide.
+ *
+ * Only three methods are REQUIRED — the three `ream migrate`,
+ * `migrate:rollback` and `migrate:status` call. Everything else is optional on
+ * purpose: a new store must be able to register with a runner that only knows
+ * how to go forward, rather than stub methods it cannot honour. A caller that
+ * needs an optional one checks for it and says so, instead of crashing.
+ */
+export interface MigrationRunnerContract {
+  /** Apply every pending migration. Resolves to the names applied, in order. */
+  migrate(): Promise<string[]>
+  /** Undo the last batch. Resolves to the names rolled back. */
+  rollback(): Promise<string[]>
+  /** Every known migration and whether it has run. */
+  status(): Promise<MigrationStatusNode[]>
+
+  /** Undo every migration. */
+  reset?(): Promise<string[]>
+  /** Reset, then migrate. */
+  refresh?(): Promise<unknown>
+  /** Drop everything, then migrate. */
+  fresh?(): Promise<unknown>
+  /** What `migrate()` would do, without doing it. */
+  dryRun?(): Promise<unknown>
+  /** Release a lock a crashed run left behind. */
+  forceUnlock?(): Promise<boolean>
+}
+
+/** A registered store, as the CLI sees it. */
+export interface RegisteredMigrationSource {
+  /**
+   * How the store is named on the command line — `atlas`, `eon`, …
+   *
+   * It is what `ream migrate --only <name>` matches and what prefixes the
+   * output, so it belongs to the store, not to the app.
+   */
+  name: string
+  /** Where its migration files live, for the message when there are none. */
+  directory?: string
+  runner: MigrationRunnerContract
+}

package/src/router/Router.ts

@@ -57,8 +57,24 @@ export type LazyControllerAction = [loader: LazyControllerImport, method: string
  */
 export type RouteHandler = RouteHandlerFunction | ControllerAction | LazyControllerAction | string
 
-/** Param matcher — regex or predefined matcher. */
-export type ParamMatcher = RegExp | { pattern: RegExp }
+/**
+ * Param matcher — a bare RegExp, or the AdonisJS `{ match, cast }` shape.
+ *
+ * `cast` turns the captured string into the value the handler wants, so
+ * `where('id', matchers.number())` gives `params.id` as a NUMBER. Ream carried
+ * only the pattern, so a matched param stayed a string and every controller
+ * re-parsed it. `pattern` is ream's older spelling of `match`, still accepted.
+ */
+export type ParamMatcher =
+  | RegExp
+  | {
+      /** AdonisJS spelling. */
+      match?: RegExp
+      /** Ream's older spelling of {@link match}. */
+      pattern?: RegExp
+      /** Casts the captured segment before it reaches `ctx.params`. */
+      cast?: (value: string) => unknown
+    }
 
 export interface RouteDefinition {
   method: string
@@ -166,17 +182,22 @@ export interface MatchResult {
 // ─── Matchers ───────────────────────────────────────────────
 
 export const matchers = {
-  /** Match numeric params only. */
+  /** Match numeric params only, and hand the handler a number. */
   number(): ParamMatcher {
-    return { pattern: /^\d+$/ }
+    return { match: /^\d+$/, cast: (value) => Number(value) }
   },
   /** Match UUID v4 params only. */
   uuid(): ParamMatcher {
-    return { pattern: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i }
+    return {
+      match: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+      // AdonisJS lowercases it, so a route keyed on the param is stable
+      // whatever case the client sent.
+      cast: (value) => value.toLowerCase(),
+    }
   },
   /** Match slug params only (lowercase alphanumeric + hyphens). */
   slug(): ParamMatcher {
-    return { pattern: /^[a-z0-9]+(?:-[a-z0-9]+)*$/ }
+    return { match: /^[a-z0-9]+(?:-[a-z0-9]+)*$/ }
   },
 }
 
@@ -190,15 +211,43 @@ export const matchers = {
  * anchoring here reproduces AdonisJS's *effective* full-segment semantics.
  */
 function compileMatcher(matcher: ParamMatcher | RegExp | string): ParamMatcher {
-  if (typeof matcher === 'string') return { pattern: new RegExp(`^(?:${matcher})$`) }
-  return matcher instanceof RegExp ? { pattern: matcher } : matcher
+  if (typeof matcher === 'string') return { match: new RegExp(`^(?:${matcher})$`) }
+  return matcher instanceof RegExp ? { match: matcher } : matcher
+}
+
+/**
+ * Run each matcher's `cast` over the params it matched.
+ *
+ * The wildcard holds several segments, so the cast applies to each of them.
+ * A matcher without a cast leaves its param untouched.
+ */
+function applyCasts(params: MatchedParams, matchers: Record<string, ParamMatcher>): MatchedParams {
+  let out: MatchedParams | undefined
+  for (const [param, value] of Object.entries(params)) {
+    const matcher = matchers[param]
+    const cast = matcher instanceof RegExp ? undefined : matcher?.cast
+    if (!cast) continue
+    out ??= { ...params }
+    // The cast's return is the caller's claim about its own param; the router
+    // only carries it.
+    out[param] = (
+      Array.isArray(value) ? value.map((v) => cast(v)) : cast(value)
+    ) as MatchedParams[string]
+  }
+  return out ?? params
+}
+
+/** The RegExp a matcher tests with, whichever spelling it used. */
+function matcherPattern(matcher: ParamMatcher): RegExp | undefined {
+  if (matcher instanceof RegExp) return matcher
+  return matcher.match ?? matcher.pattern
 }
 
 // ─── RouteBuilder ───────────────────────────────────────────
 
 /**
  * Fluent route builder — mutates the already-registered route definition(s).
- * Backed by an array so a multi-verb `router.route(['GET','POST'], …)` returns
+ * Backed by an array so a multi-verb `router.route(pattern, ['GET','POST'], …)` returns
  * ONE builder that fans every mutation across all its verbs; the single-verb
  * helpers (`get`/`post`/…) back it with a one-element array.
  */
@@ -808,14 +857,16 @@ export class Router extends Macroable {
   // ─── Route registration ───────────────────────────────────
 
   /**
-   * Register a route for one verb or several (AdonisJS `route(pattern, methods)`
-   * accepts an array). A multi-verb call returns a single builder that
-   * configures every verb at once.
+   * Register a route for one verb or several — `route(pattern, methods,
+   * handler)`, the AdonisJS argument order. Ream took `(method, path)`, so a
+   * call copied from an AdonisJS app registered the pattern as the verb.
+   *
+   * A multi-verb call returns a single builder that configures every verb.
    */
-  route(method: string | string[], path: string, handler: RouteHandler): RouteBuilder {
-    const methods = Array.isArray(method) ? method : [method]
-    const defs = methods.map((verb) => {
-      const def = this.#createDefinition(verb, path, handler)
+  route(pattern: string, methods: string | string[], handler: RouteHandler): RouteBuilder {
+    const verbs = Array.isArray(methods) ? methods : [methods]
+    const defs = verbs.map((verb) => {
+      const def = this.#createDefinition(verb, pattern, handler)
       this.#routes.push(def)
       return def
     })
@@ -824,36 +875,36 @@ export class Router extends Macroable {
   }
 
   get(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('GET', path, handler)
+    return this.route(path, 'GET', handler)
   }
 
   post(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('POST', path, handler)
+    return this.route(path, 'POST', handler)
   }
 
   put(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('PUT', path, handler)
+    return this.route(path, 'PUT', handler)
   }
 
   patch(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('PATCH', path, handler)
+    return this.route(path, 'PATCH', handler)
   }
 
   delete(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('DELETE', path, handler)
+    return this.route(path, 'DELETE', handler)
   }
 
   head(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('HEAD', path, handler)
+    return this.route(path, 'HEAD', handler)
   }
 
   options(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('OPTIONS', path, handler)
+    return this.route(path, 'OPTIONS', handler)
   }
 
   /** Register a route for all HTTP methods. */
   any(path: string, handler: RouteHandler): RouteBuilder {
-    return this.route('*', path, handler)
+    return this.route(path, '*', handler)
   }
 
   // ─── Resource routes ──────────────────────────────────────
@@ -1096,16 +1147,16 @@ export class Router extends Macroable {
         // separate gates meant the global always had the final say, so a route
         // could never loosen it — a global `id: /^[0-9]+$/` plus a route-level
         // slug matcher 404'd instead of matching.
-        if (
-          !this.#validateMatchers(params, {
-            ...this.#globalMatchers,
-            ...route.matchers,
-          })
-        ) {
+        const effective = { ...this.#globalMatchers, ...route.matchers }
+        if (!this.#validateMatchers(params, effective)) {
           continue
         }
 
-        return { route, params }
+        // A matcher's `cast` turns the captured segment into the value the
+        // handler wants — `where('id', matchers.number())` hands `params.id`
+        // a NUMBER, as in AdonisJS. Ream carried only the pattern, so every
+        // controller re-parsed a string the router had already validated.
+        return { route, params: applyCasts(params, effective) }
       }
     }
 
@@ -1270,6 +1321,96 @@ export class Router extends Macroable {
     return this.#routes.filter((route) => !route.deleted)
   }
 
+  /**
+   * A fluent URL builder (AdonisJS `router.builder()` / `urlBuilder`).
+   *
+   * `urlFor` takes everything at once; this is the form upstream gives you
+   * when the pieces arrive separately — params here, query string there, a
+   * prefix from config:
+   *
+   * ```ts
+   * router.builder().params({ id: '1' }).qs({ tab: 'posts' }).make('users.show')
+   * router.builder().prefixUrl('https://acme.test').makeSigned('invite', { expiresIn: '1h' })
+   * ```
+   */
+  builder(): UrlBuilder {
+    return new UrlBuilder(this)
+  }
+
+  /** AdonisJS' property name for {@link builder}. */
+  get urlBuilder(): UrlBuilder {
+    return this.builder()
+  }
+
+  /**
+   * A builder that prefixes every URL with `domain` (AdonisJS
+   * `builderForDomain`).
+   *
+   * The domain is a prefix here, not a lookup key: routes are matched by host
+   * at request time, and a named route is unique across the table.
+   */
+  builderForDomain(domain: string): UrlBuilder {
+    return this.builder().prefixUrl(domain)
+  }
+
+  /**
+   * The parameter names a route pattern declares, in order (AdonisJS
+   * `parsePattern`).
+   *
+   * `:id` and `:slug?` both count; the optional marker is reported rather than
+   * being part of the name.
+   */
+  parsePattern(pattern: string): Array<{ name: string; optional: boolean }> {
+    const tokens: Array<{ name: string; optional: boolean }> = []
+    for (const match of pattern.matchAll(/:([A-Za-z_][\w]*)(\?)?/g)) {
+      tokens.push({ name: match[1] ?? '', optional: match[2] === '?' })
+    }
+    return tokens
+  }
+
+  /**
+   * Every route, grouped by the domain it answers on (AdonisJS `toJSON`).
+   *
+   * Routes registered without a domain land under `root`, as upstream keys
+   * them. This is what a route list — `ream inspect`, an OpenAPI generator, a
+   * debug screen — reads.
+   */
+  toJSON(): Record<string, RouteDefinition[]> {
+    const byDomain: Record<string, RouteDefinition[]> = {}
+    for (const route of this.getRoutes()) {
+      const key = route.domain ?? 'root'
+      const bucket = byDomain[key] ?? []
+      bucket.push(route)
+      byDomain[key] = bucket
+    }
+    return byDomain
+  }
+
+  /**
+   * Whether any route is scoped to a domain (AdonisJS `usingDomains`).
+   *
+   * Lets the matcher skip host resolution entirely when nothing asked for it.
+   */
+  get usingDomains(): boolean {
+    return this.getRoutes().some((route) => route.domain !== undefined)
+  }
+
+  /**
+   * Freeze the route table and build the lookup index (AdonisJS `commit`).
+   *
+   * The index is built lazily on the first `match()`, so this is only needed
+   * to pay that cost up front — at the end of boot rather than inside the
+   * first request.
+   */
+  commit(): void {
+    this.#buildIndex()
+  }
+
+  /** Whether the lookup index has been built (AdonisJS `commited`). */
+  get commited(): boolean {
+    return !this.#indexDirty
+  }
+
   /**
    * Clear all registered routes AND registries (used by hot-reload). Router
    * middleware, named middleware, and global matchers are reset too — the
@@ -1302,7 +1443,8 @@ export class Router extends Macroable {
       // The wildcard holds several segments; every one has to satisfy the
       // matcher, or a `/assets/*` guard would pass on its first segment alone.
       const values = Array.isArray(value) ? value : [value]
-      const regex = matcher instanceof RegExp ? matcher : matcher.pattern
+      const regex = matcherPattern(matcher)
+      if (!regex) continue
       // A user-supplied /g or /y regex is stateful (`lastIndex` advances on
       // match) — without a reset, the same URL alternates match/no-match
       // across requests. Reset before every test.
@@ -1387,3 +1529,70 @@ function matchDomain(pattern: string, host: string): boolean {
   }
   return false
 }
+
+/**
+ * Builds a URL for a named route, one piece at a time (AdonisJS `UrlBuilder`).
+ *
+ * Every method returns the builder, and `make` / `makeSigned` are the two ways
+ * out. It defers to {@link Router.urlFor} and {@link Router.makeSignedUrl}, so
+ * a missing param fails the same way whichever spelling you used.
+ */
+export class UrlBuilder {
+  readonly #router: Router
+  #params: Record<string, string> = {}
+  #qs: Record<string, string> = {}
+  #prefix = ''
+  #lookup = true
+
+  constructor(router: Router) {
+    this.#router = router
+  }
+
+  /** Route params, by name. */
+  params(params: Record<string, string>): this {
+    this.#params = { ...this.#params, ...params }
+    return this
+  }
+
+  /** Query-string params appended to the built URL. */
+  qs(qs: Record<string, string>): this {
+    this.#qs = { ...this.#qs, ...qs }
+    return this
+  }
+
+  /** A prefix — a domain, a base path — put in front of the result. */
+  prefixUrl(prefix: string): this {
+    this.#prefix = prefix.replace(/\/$/, '')
+    return this
+  }
+
+  /**
+   * Treat what `make()` receives as a literal path instead of a route name
+   * (AdonisJS `disableRouteLookup`).
+   */
+  disableRouteLookup(): this {
+    this.#lookup = false
+    return this
+  }
+
+  /** The URL. */
+  make(identifier: string): string {
+    const path = this.#lookup ? this.#router.urlFor(identifier, this.#params) : identifier
+    const query = new URLSearchParams(this.#qs).toString()
+    return `${this.#prefix}${path}${query ? `?${query}` : ''}`
+  }
+
+  /**
+   * The URL with an HMAC signature (AdonisJS `makeSigned`).
+   *
+   * The query string is folded into the signature, so a link cannot be
+   * re-pointed by editing it.
+   */
+  makeSigned(identifier: string, options?: SignedUrlOptions): string {
+    const signed = this.#router.makeSignedUrl(identifier, this.#params, {
+      ...options,
+      qs: { ...this.#qs, ...options?.qs },
+    })
+    return `${this.#prefix}${signed}`
+  }
+}

package/src/security/CookieSigner.ts

@@ -40,8 +40,12 @@ export class E_INSECURE_APP_KEY extends Error {
 
 /** The envelope carried inside an encrypted or signed value. */
 interface Envelope {
-  /** The payload. */
-  m: string
+  /**
+   * The payload. Any JSON value, not just a string: AdonisJS' verifier signs
+   * whatever you hand it, and a caller signing `{ id: 1 }` should not have to
+   * stringify it first.
+   */
+  m: unknown
   /** Epoch-ms expiry, when one was given. */
   e?: number
   /** The purpose it was sealed for, when one was given. */
@@ -69,25 +73,36 @@ export class CookieSigner {
    * another — a password-reset token presented as a session cookie fails here
    * rather than being honoured.
    */
-  #seal(value: string, expiresIn?: number, purpose?: string): string {
+  #seal(value: unknown, expiresIn?: number, purpose?: string): string {
     const envelope: Envelope = { m: value }
     if (expiresIn !== undefined) envelope.e = Date.now() + expiresIn
     if (purpose !== undefined) envelope.p = purpose
     return JSON.stringify(envelope)
   }
 
-  /** Unwrap a sealed payload, refusing an expired one or the wrong purpose. */
-  #open(raw: string, purpose?: string): string | null {
-    let envelope: Envelope
+  /**
+   * Unwrap a sealed payload, refusing an expired one or the wrong purpose.
+   *
+   * Anything that is not an envelope is refused rather than handed back.
+   * `#seal` only ever produces one, so a non-envelope did not come from this
+   * class — and returning it would skip the expiry and purpose checks below,
+   * which is precisely the downgrade those checks exist to prevent. Failing
+   * closed costs a value nothing here produced; failing open costs the
+   * guarantee that a token sealed for one use cannot be replayed into another.
+   */
+  #open(raw: string, purpose?: string): unknown {
+    let parsed: unknown
     try {
-      const parsed: unknown = JSON.parse(raw)
-      if (typeof parsed !== 'object' || parsed === null) return null
-      envelope = parsed as Envelope
+      parsed = JSON.parse(raw)
     } catch {
-      // Not an envelope — a value sealed before this format existed.
-      return raw
+      return null
     }
-    if (typeof envelope.m !== 'string') return raw
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const envelope = parsed as Envelope
+    // The KEY must be there, whatever it holds — that is what distinguishes an
+    // envelope from an arbitrary JSON document, and a signed `null` or `0` is a
+    // legitimate payload.
+    if (!('m' in envelope)) return null
     if (envelope.e !== undefined && envelope.e < Date.now()) return null
     if ((envelope.p ?? undefined) !== purpose) return null
     return envelope.m
@@ -99,27 +114,86 @@ export class CookieSigner {
    * `expiresIn` is in milliseconds; `purpose` scopes the signature so it cannot
    * be replayed somewhere else.
    */
-  sign(value: string, expiresIn?: number, purpose?: string): string {
+  sign(value: unknown, expiresIn?: number, purpose?: string): string {
     const sealed = Buffer.from(this.#seal(value, expiresIn, purpose)).toString('base64url')
     const sig = hmacSign(sealed, this.#secret)
     return `${sealed}.${sig}`
   }
 
   /** Verify and unwrap, returning null when tampered, expired, or mis-purposed. */
-  unsign(signed: string, purpose?: string): string | null {
+  unsign<T = string>(signed: string, purpose?: string): T | null {
     const lastDot = signed.lastIndexOf('.')
     if (lastDot === -1) return null
     const sealed = signed.slice(0, lastDot)
     const sig = signed.slice(lastDot + 1)
     if (!hmacVerify(sealed, sig, this.#secret)) return null
     try {
-      return this.#open(Buffer.from(sealed, 'base64url').toString('utf8'), purpose)
+      return this.#open(Buffer.from(sealed, 'base64url').toString('utf8'), purpose) as T | null
     } catch {
       return null
     }
   }
 
-  encrypt(value: string, expiresIn?: number, purpose?: string): string {
+  /**
+   * The cipher in use (AdonisJS `Encryption.algorithm`).
+   *
+   * `aes-256-gcm`, not upstream's `aes-256-cbc` — see the deviation at the top
+   * of this file.
+   */
+  get algorithm(): 'aes-256-gcm' {
+    return 'aes-256-gcm'
+  }
+
+  /**
+   * base64url helpers (AdonisJS `Encryption.base64`).
+   *
+   * url-safe and unpadded, which is what every value this class produces uses
+   * — a signed or encrypted payload travels in a cookie or a URL, where `+`,
+   * `/` and `=` do not survive. `decode` answers `null` on anything that does
+   * not round-trip rather than handing back mangled bytes.
+   */
+  get base64(): {
+    encode(value: string): string
+    decode(value: string): string | null
+    urlEncode(value: string): string
+    urlDecode(value: string): string | null
+  } {
+    const encode = (value: string) => Buffer.from(value, 'utf8').toString('base64url')
+    const decode = (value: string): string | null => {
+      const out = Buffer.from(value, 'base64url').toString('utf8')
+      return Buffer.from(out, 'utf8').toString('base64url') === value ? out : null
+    }
+    return { encode, decode, urlEncode: encode, urlDecode: decode }
+  }
+
+  /**
+   * Sign and verify WITHOUT encrypting (AdonisJS `Encryption.verifier`).
+   *
+   * The same `sign` / `unsign` this class already exposes, under the name and
+   * shape upstream puts them: an app calling `encryption.verifier.sign(...)`
+   * found nothing here.
+   */
+  get verifier(): {
+    sign(payload: unknown, expiresIn?: number, purpose?: string): string
+    unsign<T = string>(payload: string, purpose?: string): T | null
+  } {
+    return {
+      sign: (payload, expiresIn, purpose) => this.sign(payload, expiresIn, purpose),
+      unsign: <T>(payload: string, purpose?: string) => this.unsign<T>(payload, purpose),
+    }
+  }
+
+  /**
+   * Another signer on a different secret (AdonisJS `Encryption.child`).
+   *
+   * What key rotation is built on: keep the old secret's signer around to read
+   * values already in the wild while the new one writes.
+   */
+  child(secret?: string): CookieSigner {
+    return new CookieSigner(secret ?? this.#secret)
+  }
+
+  encrypt(value: unknown, expiresIn?: number, purpose?: string): string {
     const iv = randomBytes(12)
     const cipher = createCipheriv('aes-256-gcm', this.#keyBuffer, iv)
     const sealed = this.#seal(value, expiresIn, purpose)
@@ -128,7 +202,7 @@ export class CookieSigner {
     return `${iv.toString('base64url')}.${encrypted.toString('base64url')}.${tag.toString('base64url')}`
   }
 
-  decrypt(encrypted: string, purpose?: string): string | null {
+  decrypt<T = string>(encrypted: string, purpose?: string): T | null {
     const parts = encrypted.split('.')
     if (parts.length !== 3) return null
     try {
@@ -138,7 +212,7 @@ export class CookieSigner {
       const decipher = createDecipheriv('aes-256-gcm', this.#keyBuffer, iv)
       decipher.setAuthTag(tag)
       const raw = Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8')
-      return this.#open(raw, purpose)
+      return this.#open(raw, purpose) as T | null
     } catch {
       return null
     }