@c9up/ream 0.1.32 → 0.1.33

package/src/session/Session.ts

@@ -19,9 +19,75 @@ export interface SessionDriver {
   touch(sessionId: string, ttl: number): Promise<void>
 }
 
+/** One session belonging to a tagged user (AdonisJS `TaggedSession`). */
+export interface TaggedSession {
+  id: string
+  data: Record<string, unknown>
+}
+
+/**
+ * A driver that can associate a session with a user, so every session a user
+ * holds can be listed or destroyed — "log me out everywhere", and "these are
+ * your active devices" (AdonisJS `SessionStoreWithTaggingContract`).
+ *
+ * Only the drivers that keep a queryable index can answer: memory, redis and
+ * database. The cookie driver holds no server-side state at all, and the file
+ * driver would have to scan the directory on every lookup.
+ */
+export interface SessionDriverWithTagging extends SessionDriver {
+  tag(sessionId: string, userId: string | number): Promise<void>
+  untag(sessionId: string, userId: string | number): Promise<void>
+  /** Every non-expired session tagged with this user. */
+  tagged(userId: string | number): Promise<TaggedSession[]>
+}
+
+/** Whether a driver carries the tagging half of the contract. */
+export function supportsTagging(driver: SessionDriver): driver is SessionDriverWithTagging {
+  return (
+    'tag' in driver &&
+    typeof (driver as SessionDriverWithTagging).tag === 'function' &&
+    'tagged' in driver &&
+    typeof (driver as SessionDriverWithTagging).tagged === 'function'
+  )
+}
+
+/** Where `flashAll` / `flashOnly` / `flashExcept` put the request input. */
+const FLASH_INPUT_KEY = 'input'
+
+/** Where the intended URL is stored, out of the way of app keys. */
+const INTENDED_URL_KEY = '__intended_url'
+
 export interface SessionConfig {
-  driver: string
+  /**
+   * Which store to use. AdonisJS names this key `store`; `driver` is ream's
+   * older spelling and both are accepted, so a migrated `config/session.ts`
+   * runs with its imports rewritten and nothing else.
+   */
+  driver?: string
+  /** AdonisJS spelling of {@link driver}. */
+  store?: string
+  /**
+   * Named stores, AdonisJS-style: `{ store: 'redis', stores: { redis: … } }`.
+   * The selected entry supplies the driver name and its options.
+   */
+  stores?: Record<string, { driver: string } & Record<string, unknown>>
+  /** `file` driver only — the directory session files are written to. */
+  location?: string
+  /** `database` driver only — the connection to store sessions on. */
+  dbConnection?: unknown
+  /** `database` driver only — the table holding them (default `sessions`). */
+  tableName?: string
+  /**
+   * `database` driver only — percent chance that a write also sweeps expired
+   * rows (AdonisJS `gcProbability`, default 2). `0` turns it off.
+   */
+  gcProbability?: number
   cookieName?: string
+  /**
+   * Session lifetime. A bare number is SECONDS; a string carries a unit
+   * (`'2h'`), which is how AdonisJS writes it (`age: string | number`).
+   */
+  age?: number | string
   maxAge?: number // seconds, default 7200 (2h)
   clearWithBrowser?: boolean
   /**
@@ -64,11 +130,18 @@ function generateSessionId(): string {
   return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
 }
 
+/** A non-null, non-array object — the shape flash data must have to be keyed. */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
 export class Session {
   #data: Record<string, unknown> = {}
   #flashData: Record<string, unknown> = {}
   #previousFlash: Record<string, unknown> = {}
   #dirty = false
+  /** Reads the request's original input; absent outside a request. */
+  #readInput?: () => Record<string, unknown>
   #sessionId: string
   /**
    * The session id active when the request arrived, captured at construction.
@@ -78,17 +151,32 @@ export class Session {
    */
   readonly #originalSessionId: string
   #regenerated = false
+  /** Whether this session was created for THIS request (no incoming cookie). */
+  #fresh = false
+  /** The store behind it, when there is one — absent for a bare unit-test session. */
+  #driver?: SessionDriver
+  /** Session lifetime in seconds, used by {@link commit}. */
+  #ttl = 0
+  /** Whether {@link initiate} already ran, so a second call is a no-op. */
+  #initiated = false
 
   constructor(sessionId: string, data: Record<string, unknown> = {}) {
     this.#sessionId = sessionId
     this.#originalSessionId = sessionId
+    this.#hydrate(data)
+  }
+
+  /**
+   * Seat stored data: the payload becomes the session, and the flash bag it
+   * carried becomes THIS request's `old()` / `flashMessages`.
+   *
+   * Shared by the constructor and {@link initiate}, so a session loaded from
+   * the store lands in exactly the same state as one handed its data directly.
+   */
+  #hydrate(data: Record<string, unknown>): void {
     this.#data = { ...data }
     const flash = data.__flash
-    this.#previousFlash =
-      typeof flash === 'object' && flash !== null && !Array.isArray(flash)
-        ? // biome-ignore lint/suspicious/noExplicitAny: flash narrowed to non-null non-array object; branded as Record for key access
-          (flash as any as Record<string, unknown>)
-        : {}
+    this.#previousFlash = isPlainRecord(flash) ? { ...flash } : {}
     delete this.#data.__flash
   }
 
@@ -127,12 +215,11 @@ export class Session {
 
   /** Get a session value. */
   get<T = unknown>(key: string, defaultValue?: T): T {
-    if (key in this.#data) {
-      // biome-ignore lint/suspicious/noExplicitAny: session data stored as unknown; caller brands the value type via T
-      return this.#data[key] as any as T
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: generic default — caller brands the value type via T
-    return defaultValue as any as T
+    // The store is untyped by nature, so `T` is the CALLER's claim about what
+    // it put there — one assertion from `unknown`, which is what `T` means
+    // here. Going through `any` first widened nothing and hid the intent.
+    if (key in this.#data) return this.#data[key] as T
+    return defaultValue as T
   }
 
   /** Set a session value. */
@@ -183,35 +270,152 @@ export class Session {
 
   // ─── Flash data ───────────────────────────────────────────
 
-  /** Set flash data (available only on the next request). */
-  flash(key: string, value: unknown): void {
-    this.#flashData[key] = value
+  /**
+   * @internal Give the session read access to the request's ORIGINAL input.
+   *
+   * AdonisJS's session holds the HTTP context and reads `request.original()`;
+   * ream's Session stays free of it, so the middleware injects a reader. Absent
+   * (a session built outside a request), the input-flashing methods flash
+   * nothing rather than throwing.
+   */
+  setInputReader(read: () => Record<string, unknown>): void {
+    this.#readInput = read
+  }
+
+  /** The request's original input, or nothing when there is no request. */
+  #input(): Record<string, unknown> {
+    return this.#readInput?.() ?? {}
+  }
+
+  /**
+   * Set flash data, available only on the next request.
+   *
+   * Takes a key and a value, or an object of both (AdonisJS accepts either).
+   */
+  flash(key: string | Record<string, unknown>, value?: unknown): void {
+    if (typeof key === 'string') this.#flashData[key] = value
+    else Object.assign(this.#flashData, key)
     this.#dirty = true
   }
 
-  /** Flash all current input. */
-  flashAll(input: Record<string, unknown>): void {
-    for (const [k, v] of Object.entries(input)) {
-      this.#flashData[k] = v
+  /**
+   * Flash the whole request input for the next request (AdonisJS `flashAll`).
+   *
+   * Takes NO argument: it reads the request's original input itself, which is
+   * what makes `session.flashAll()` before a redirect-back repopulate a form.
+   */
+  flashAll(): void {
+    this.flash(FLASH_INPUT_KEY, this.#input())
+  }
+
+  /** Flash only these input keys (AdonisJS `flashOnly`). */
+  flashOnly(keys: string[]): void {
+    const input = this.#input()
+    const picked: Record<string, unknown> = {}
+    for (const key of keys) {
+      if (Object.hasOwn(input, key)) picked[key] = input[key]
     }
-    this.#dirty = true
+    this.flash(FLASH_INPUT_KEY, picked)
   }
 
-  /** Flash only specific keys. */
-  flashOnly(input: Record<string, unknown>, keys: string[]): void {
-    for (const k of keys) {
-      if (k in input) this.#flashData[k] = input[k]
+  /**
+   * Flash the request input except these keys (AdonisJS `flashExcept`).
+   *
+   *   session.flashExcept(['password', '_csrf'])
+   */
+  flashExcept(keys: string[]): void {
+    const omit = new Set(keys)
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(this.#input())) {
+      if (!omit.has(key)) kept[key] = value
     }
-    this.#dirty = true
+    this.flash(FLASH_INPUT_KEY, kept)
   }
 
-  /** Flash all except specific keys. */
-  flashExcept(input: Record<string, unknown>, keys: string[]): void {
-    const keySet = new Set(keys)
-    for (const [k, v] of Object.entries(input)) {
-      if (!keySet.has(k)) this.#flashData[k] = v
+  /**
+   * Flash an error collection under `errorsBag` (AdonisJS `flashErrors`) —
+   * where the `@error` / `@errors` template tags read from.
+   */
+  flashErrors(errors: Record<string, string | string[]>): void {
+    this.flash({ errorsBag: errors })
+  }
+
+  /**
+   * Flash a validation failure the way a form expects it (AdonisJS
+   * `flashValidationErrors`): the per-field messages under `inputErrorsBag`,
+   * a summary under `errorsBag`, and — unless told otherwise — the input, so
+   * the redisplayed form keeps what the user typed.
+   */
+  flashValidationErrors(
+    error: { code?: string; messages?: Array<{ field?: string; message?: string }> },
+    withInput = true,
+  ): void {
+    const bag: Record<string, string[]> = {}
+    for (const message of error.messages ?? []) {
+      if (message.field === undefined || message.message === undefined) continue
+      const existing = bag[message.field] ?? []
+      existing.push(message.message)
+      bag[message.field] = existing
     }
-    this.#dirty = true
+    this.flash('inputErrorsBag', bag)
+    this.flashErrors({
+      [error.code ?? 'E_VALIDATION_ERROR']: Object.values(bag).flat(),
+    })
+    if (withInput) this.flashAll()
+  }
+
+  /**
+   * Keep the PREVIOUS request's flash data for one more request (AdonisJS
+   * `reflash`) — what a redirect chain needs so a message survives the hop.
+   */
+  reflash(): void {
+    this.flash(this.#previousFlash)
+  }
+
+  /** Keep only these keys of the previous flash data (AdonisJS `reflashOnly`). */
+  reflashOnly(keys: string[]): void {
+    for (const key of keys) {
+      if (Object.hasOwn(this.#previousFlash, key)) {
+        this.flash(key, this.#previousFlash[key])
+      }
+    }
+  }
+
+  /** Keep the previous flash data except these keys (AdonisJS `reflashExcept`). */
+  reflashExcept(keys: string[]): void {
+    const omit = new Set(keys)
+    for (const [key, value] of Object.entries(this.#previousFlash)) {
+      if (!omit.has(key)) this.flash(key, value)
+    }
+  }
+
+  // ─── Intended URL ─────────────────────────────────────────
+
+  /**
+   * Remember where the user was heading (AdonisJS `setIntendedUrl`).
+   *
+   * An auth middleware stores it before redirecting to the login page, so the
+   * user lands back on the page they asked for instead of a generic dashboard.
+   */
+  setIntendedUrl(url: string): void {
+    this.put(INTENDED_URL_KEY, url)
+  }
+
+  /** The remembered URL, or null. */
+  getIntendedUrl(): string | null {
+    const url = this.get<string>(INTENDED_URL_KEY)
+    return typeof url === 'string' ? url : null
+  }
+
+  /** Read it and forget it — the usual call right after a successful login. */
+  pullIntendedUrl(): string | null {
+    const url = this.getIntendedUrl()
+    this.clearIntendedUrl()
+    return url
+  }
+
+  clearIntendedUrl(): void {
+    this.forget(INTENDED_URL_KEY)
   }
 
   /** Get a flashed value from the previous request. */
@@ -221,12 +425,10 @@ export class Session {
 
   /** Get a specific flash message from the previous request. */
   old<T = unknown>(key: string, defaultValue?: T): T {
-    if (key in this.#previousFlash) {
-      // biome-ignore lint/suspicious/noExplicitAny: flash data stored as unknown; caller brands the value type via T
-      return this.#previousFlash[key] as any as T
-    }
-    // biome-ignore lint/suspicious/noExplicitAny: generic default — caller brands the value type via T
-    return defaultValue as any as T
+    // Same contract as `get`: `T` is the caller's claim about a store that is
+    // untyped by nature.
+    if (key in this.#previousFlash) return this.#previousFlash[key] as T
+    return defaultValue as T
   }
 
   // ─── Serialization ────────────────────────────────────────
@@ -243,4 +445,129 @@ export class Session {
   isDirty(): boolean {
     return this.#dirty
   }
+
+  /** AdonisJS spelling of {@link isDirty}. */
+  get hasBeenModified(): boolean {
+    return this.#dirty
+  }
+
+  /**
+   * Whether this session was created during THIS request — no session cookie
+   * came in with it (AdonisJS `fresh`).
+   */
+  get fresh(): boolean {
+    return this.#fresh
+  }
+
+  /**
+   * Whether the session holds nothing (AdonisJS `isEmpty`). Flash data counts:
+   * a session carrying only a flash message still has something to write.
+   */
+  get isEmpty(): boolean {
+    return Object.keys(this.#data).length === 0 && Object.keys(this.#flashData).length === 0
+  }
+
+  /**
+   * Whether writes are refused (AdonisJS `readonly`). Always false here: ream
+   * has no read-only session mode, and reporting `true` would tell a caller
+   * its writes were dropped when they were not.
+   */
+  get readonly(): boolean {
+    return false
+  }
+
+  /**
+   * @internal Wire the store this session lives in. Called by
+   * `SessionMiddleware`; a session built by hand in a test has none, and
+   * {@link initiate} / {@link commit} then have nothing to do.
+   */
+  setStore(driver: SessionDriver, options: { fresh: boolean; ttl: number }): void {
+    this.#driver = driver
+    this.#fresh = options.fresh
+    this.#ttl = options.ttl
+  }
+
+  /**
+   * Load the session from its store (AdonisJS `initiate`).
+   *
+   * Idempotent, as upstream: calling it twice is a no-op, so a middleware that
+   * runs on a sub-request cannot wipe what the outer one already read.
+   */
+  async initiate(): Promise<void> {
+    if (this.#initiated || this.#driver === undefined) return
+    this.#initiated = true
+    this.#hydrate(await this.#driver.read(this.#sessionId))
+  }
+
+  /**
+   * Persist the session to its store (AdonisJS `commit`).
+   *
+   * - regenerated: write under the NEW id first, then drop the old entry, so a
+   *   crash between the two leaves the user with a valid session under one id
+   *   rather than none.
+   * - modified: write.
+   * - untouched but pre-existing: touch, to slide the expiry.
+   * - untouched and brand new: nothing. Writing here would hand out a session
+   *   id pointing at a row nobody asked for.
+   */
+  async commit(): Promise<void> {
+    const driver = this.#driver
+    if (driver === undefined) return
+    if (this.#regenerated) {
+      await driver.write(this.#sessionId, this.toJSON(), this.#ttl)
+      try {
+        await driver.destroy(this.#originalSessionId)
+      } catch {
+        // Benign: a stale entry the TTL reclaims. The session is already live
+        // under the new id, and failing the request here would be worse.
+      }
+      return
+    }
+    if (this.#dirty) {
+      await driver.write(this.#sessionId, this.toJSON(), this.#ttl)
+      return
+    }
+    if (!this.#fresh) await driver.touch(this.#sessionId, this.#ttl)
+  }
+
+  /**
+   * Whether the store behind this session can tag sessions with a user
+   * (AdonisJS `supportsTagging`). False under the cookie and file drivers.
+   */
+  supportsTagging(): boolean {
+    return this.#driver !== undefined && supportsTagging(this.#driver)
+  }
+
+  /**
+   * Associate this session with a user, so every session that user holds can
+   * be found later (AdonisJS `tag`) — what "log out from all my devices" and
+   * "your active sessions" are built on. Call it at login.
+   */
+  async tag(userId: string | number): Promise<void> {
+    await this.#taggingDriver('tag').tag(this.#sessionId, userId)
+  }
+
+  /** Drop the association made by {@link tag} (AdonisJS `untag`). Call it at logout. */
+  async untag(userId: string | number): Promise<void> {
+    await this.#taggingDriver('untag').untag(this.#sessionId, userId)
+  }
+
+  /**
+   * The store, asserted to support tagging. Throws naming the method rather
+   * than resolving to a no-op: a login that believes it tagged the session
+   * would leave "log out everywhere" silently doing nothing.
+   */
+  #taggingDriver(method: string): SessionDriverWithTagging {
+    if (this.#driver === undefined) {
+      throw new Error(
+        `session.${method}() needs a session store — this session was built without one.`,
+      )
+    }
+    if (!supportsTagging(this.#driver)) {
+      throw new Error(
+        `session.${method}() is not supported by the configured session store. Use the memory, redis, or database store.`,
+      )
+    }
+    return this.#driver
+  }
 }

package/src/session/SessionMiddleware.ts

@@ -6,11 +6,15 @@
  */
 
 import { randomBytes } from 'node:crypto'
+import { durationToSeconds } from '../helpers/duration.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import { CookieDriver } from './drivers/CookieDriver.js'
+import { DatabaseDriver, type SessionDbConnection } from './drivers/DatabaseDriver.js'
+import { FileDriver } from './drivers/FileDriver.js'
 import { MemoryDriver } from './drivers/MemoryDriver.js'
 import { RedisDriver } from './drivers/RedisDriver.js'
 import { quasarConnection } from './quasar.js'
+import { ReadOnlyValuesStore, type ValuePath } from './ReadOnlyValuesStore.js'
 import type { SessionConfig, SessionDriver } from './Session.js'
 import { Session } from './Session.js'
 
@@ -22,16 +26,35 @@ interface ResolvedSessionConfig {
   rolling: boolean
 }
 
+/** Duck-typed check for a connection the database store can drive. */
+function isSessionDbConnection(value: unknown): value is SessionDbConnection {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'query') === 'function' &&
+    typeof Reflect.get(value, 'execute') === 'function'
+  )
+}
+
 export default class SessionMiddleware {
   #driver: SessionDriver
   #cookieDriver: CookieDriver | null = null
   #config: ResolvedSessionConfig
 
   constructor(config?: SessionConfig & { secret?: string }) {
+    // `store` + `stores` (AdonisJS) and `driver` (ream) name the same thing.
+    // A named store supplies the driver and its own options, so
+    // `{ store: 'redis', stores: { redis: { driver: 'redis' } } }` works.
+    const selected = config?.store ?? config?.driver
+    const named = selected ? config?.stores?.[selected] : undefined
     this.#config = {
-      driver: config?.driver ?? 'memory',
+      driver: named?.driver ?? selected ?? 'memory',
       cookieName: config?.cookieName ?? 'ream_session',
-      maxAge: config?.maxAge ?? 7200,
+      // `age` is the AdonisJS key and accepts a duration string.
+      maxAge:
+        config?.age !== undefined
+          ? durationToSeconds(config.age, 'a session age')
+          : (config?.maxAge ?? 7200),
       clearWithBrowser: config?.clearWithBrowser ?? false,
       rolling: config?.rolling ?? false,
     }
@@ -46,6 +69,26 @@ export default class SessionMiddleware {
       this.#driver = this.#cookieDriver
     } else if (this.#config.driver === 'memory') {
       this.#driver = new MemoryDriver()
+    } else if (this.#config.driver === 'file') {
+      const location = config?.location ?? named?.location
+      if (typeof location !== 'string') {
+        throw new Error(
+          'File session driver requires a `location`. Set session.location (or stores.<name>.location) to a writable directory.',
+        )
+      }
+      this.#driver = new FileDriver({ location })
+    } else if (this.#config.driver === 'database') {
+      const connection = config?.dbConnection ?? named?.connection
+      if (!isSessionDbConnection(connection)) {
+        throw new Error(
+          'Database session driver requires a `connection` exposing query() and execute().',
+        )
+      }
+      this.#driver = new DatabaseDriver({
+        connection,
+        tableName: typeof config?.tableName === 'string' ? config.tableName : undefined,
+        gcProbability: typeof config?.gcProbability === 'number' ? config.gcProbability : undefined,
+      })
     } else if (this.#config.driver === 'redis') {
       // Either the app hands a client in, or it names a quasar connection —
       // the same choice echo, bay and warden offer. Nothing is dialled here:
@@ -64,7 +107,9 @@ export default class SessionMiddleware {
     const isProduction = process.env.NODE_ENV === 'production'
 
     // Read session ID from cookie — pre-parsed by the Rust HyperServer.
-    let sessionId = ctx.request.plainCookie(cookieName)
+    let sessionId = ctx.request.plainCookie<string>(cookieName, undefined, {
+      encoded: false,
+    })
     const hadIncomingCookie = sessionId !== null
 
     // Cookie driver: the cookie value IS the session data (encrypted)
@@ -72,8 +117,16 @@ export default class SessionMiddleware {
       const data = await this.#driver.read(sessionId ?? '')
       sessionId = sessionId ?? generateSessionId()
       const session = new Session(sessionId, data)
+      // No store to commit to: the cookie written below IS the storage, so the
+      // session is seated without one and `commit()` has nothing to do.
+      session.setStore(this.#driver, { fresh: !hadIncomingCookie, ttl: maxAge })
       ctx.store.set('session', session)
       ctx.session = session
+      session.setInputReader(() => ctx.request.original())
+      // Same as the server-side branch below: without it `{{ flashMessages }}`
+      // and the `@error` / `@errors` / `@inputError` tags saw nothing at all
+      // under the cookie driver, so a form silently lost its messages.
+      shareSessionWithView(ctx, session)
 
       await next()
 
@@ -94,6 +147,9 @@ export default class SessionMiddleware {
           )
         }
         ctx.response.plainCookie(cookieName, encoded, {
+          // Already encrypted by the cookie driver; packing it again would
+          // only make the cookie bigger and change nothing.
+          encode: false,
           maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
           path: '/',
           httpOnly: true,
@@ -109,39 +165,23 @@ export default class SessionMiddleware {
       sessionId = generateSessionId()
     }
 
-    const data = await this.#driver.read(sessionId)
-    const session = new Session(sessionId, data)
+    const session = new Session(sessionId)
+    session.setStore(this.#driver, { fresh: !hadIncomingCookie, ttl: maxAge })
+    await session.initiate()
     ctx.store.set('session', session)
     ctx.session = session
+    // `flashAll()` takes no argument (AdonisJS): it reads the request's own
+    // input, which is what repopulates a form after a redirect-back.
+    session.setInputReader(() => ctx.request.original())
+    shareSessionWithView(ctx, session)
 
     await next()
 
-    // Session-fixation mitigation: if the handler called `session.regenerate()`
-    // (typically via Warden's SessionStrategy.login), the session id has been
-    // rotated. Migrate the driver storage atomically — write under the new
-    // id first, then destroy the old entry so a crash between calls leaves
-    // the user with a valid session under one of the two ids rather than
-    // none. The cookie below picks up `session.sessionId` which already
-    // returns the new value.
+    // The store half of the lifecycle — including the session-fixation
+    // migration when the handler called `regenerate()` — belongs to the
+    // session, as it does upstream.
     const regenerated = session.wasRegenerated()
-    const isNew = !hadIncomingCookie
-    if (regenerated) {
-      const originalId = session.originalSessionId()
-      const currentId = session.sessionId
-      await this.#driver.write(currentId, session.toJSON(), maxAge)
-      // Best-effort: a destroy failure leaves a stale entry that TTL will
-      // sweep, but should not crash the request. The new session is already
-      // live under `currentId`.
-      try {
-        await this.#driver.destroy(originalId)
-      } catch {
-        // benign — TTL will reclaim it.
-      }
-    } else if (session.isDirty()) {
-      await this.#driver.write(sessionId, session.toJSON(), maxAge)
-    } else if (!isNew) {
-      await this.#driver.touch(sessionId, maxAge)
-    }
+    await session.commit()
 
     // Emit Set-Cookie only when there is server-side state worth
     // pinning to the browser: the session was modified (isDirty → we
@@ -154,6 +194,9 @@ export default class SessionMiddleware {
     // the cookie-driver path above (which already omits `isNew`).
     if (session.isDirty() || regenerated || (rolling && hadIncomingCookie)) {
       ctx.response.plainCookie(cookieName, session.sessionId, {
+        // An opaque id — packing it would invalidate every session cookie
+        // already in a browser for no gain.
+        encode: false,
         maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
         path: '/',
         httpOnly: true,
@@ -167,3 +210,23 @@ export default class SessionMiddleware {
 function generateSessionId(): string {
   return randomBytes(24).toString('base64url')
 }
+
+/**
+ * Share the session with the request's view, as AdonisJS's session does.
+ *
+ * A migrated template reads `{{ old('email') }}`, `@error('email')` and
+ * `{{ flashMessages.get(...) }}` unchanged, so the three names and their shapes
+ * have to match. Skipped when the app installed no template layer.
+ */
+function shareSessionWithView(ctx: HttpContext, session: Session): void {
+  const view = Reflect.get(Object(ctx), 'view')
+  const share = Reflect.get(Object(view), 'share')
+  if (typeof share !== 'function') return
+  const flashMessages = new ReadOnlyValuesStore(session.flashMessages())
+  share.call(view, {
+    session: new ReadOnlyValuesStore(session.all()),
+    flashMessages,
+    // Adonis exposes the previous request's input under `old`.
+    old: (key: ValuePath, defaultValue?: unknown): unknown => flashMessages.get(key, defaultValue),
+  })
+}