@c9up/ream 0.1.34 → 0.2.0

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
     }

package/src/session/Session.ts

@@ -13,7 +13,16 @@
 import type { SessionRedisClientSource } from './drivers/RedisDriver.js'
 
 export interface SessionDriver {
-  read(sessionId: string): Promise<Record<string, unknown>>
+  /**
+   * The stored session, or `null` when the store has no entry for this id
+   * (AdonisJS `SessionStoreContract.read`).
+   *
+   * `null` and `{}` mean different things: the first is "no session here",
+   * the second "a session that happens to be empty". Without the difference a
+   * cookie whose server-side row has expired looked like a live session, and
+   * `commit()` touched a row that was not there.
+   */
+  read(sessionId: string): Promise<Record<string, unknown> | null>
   write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void>
   destroy(sessionId: string): Promise<void>
   touch(sessionId: string, ttl: number): Promise<void>
@@ -51,6 +60,14 @@ export function supportsTagging(driver: SessionDriver): driver is SessionDriverW
   )
 }
 
+/**
+ * The session key the flash bag travels in.
+ *
+ * One constant rather than three literals: the read, the delete and the write
+ * below all have to agree, and they had to agree by hand.
+ */
+const FLASH_KEY = '__flash'
+
 /** Where `flashAll` / `flashOnly` / `flashExcept` put the request input. */
 const FLASH_INPUT_KEY = 'input'
 
@@ -175,9 +192,9 @@ export class Session {
    */
   #hydrate(data: Record<string, unknown>): void {
     this.#data = { ...data }
-    const flash = data.__flash
+    const flash = data[FLASH_KEY]
     this.#previousFlash = isPlainRecord(flash) ? { ...flash } : {}
-    delete this.#data.__flash
+    delete this.#data[FLASH_KEY]
   }
 
   /** Current session id. Mutated by `regenerate()`. */
@@ -437,7 +454,7 @@ export class Session {
   toJSON(): Record<string, unknown> {
     const result = { ...this.#data }
     if (Object.keys(this.#flashData).length > 0) {
-      result.__flash = this.#flashData
+      result[FLASH_KEY] = this.#flashData
     }
     return result
   }
@@ -472,6 +489,51 @@ export class Session {
    * has no read-only session mode, and reporting `true` would tell a caller
    * its writes were dropped when they were not.
    */
+  /**
+   * The options this session was seated with (AdonisJS `config`).
+   *
+   * What `setStore` was told: whether the session is fresh, and how long it
+   * lives. Read-only — changing it after the fact would not move the entry
+   * already written.
+   */
+  get config(): { fresh: boolean; ttl: number } {
+    return { fresh: this.#fresh, ttl: this.#ttl }
+  }
+
+  /**
+   * The key the flash bag is stored under inside the session (AdonisJS
+   * `flashKey`).
+   *
+   * Exposed so a store that has to reason about the payload — a migration, a
+   * debug screen — does not have to hardcode the string.
+   */
+  get flashKey(): string {
+    return FLASH_KEY
+  }
+
+  /**
+   * What has been flashed for the NEXT request (AdonisJS
+   * `responseFlashMessages`).
+   *
+   * A copy: flashing goes through `flash()`, which is where the value checks
+   * live. `flashMessages` is the other half — what the PREVIOUS request left
+   * for this one.
+   */
+  get responseFlashMessages(): Record<string, unknown> {
+    return { ...this.#flashData }
+  }
+
+  /**
+   * Whether `regenerate()` ran this request (AdonisJS `hasRegeneratedSession`).
+   *
+   * The id changed, so anything holding the old one — a cookie already
+   * written, an external store keyed by session id — is stale. It was tracked
+   * internally and never exposed, so only this class could act on it.
+   */
+  get hasRegeneratedSession(): boolean {
+    return this.#regenerated
+  }
+
   get readonly(): boolean {
     return false
   }
@@ -496,7 +558,11 @@ export class Session {
   async initiate(): Promise<void> {
     if (this.#initiated || this.#driver === undefined) return
     this.#initiated = true
-    this.#hydrate(await this.#driver.read(this.#sessionId))
+    const stored = await this.#driver.read(this.#sessionId)
+    // The store is the authority on existence: a cookie can outlive the row it
+    // points at, and that session is fresh however old its id is.
+    if (stored === null) this.#fresh = true
+    this.#hydrate(stored ?? {})
   }
 
   /**