@nifrajs/auth 2.2.0 → 2.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @nifrajs/auth
 
-Session primitives for nifra — signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.
+Session primitives for nifra - signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.
 
-Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework — one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework - one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
 
 ## Install
 
@@ -19,7 +19,7 @@ MIT
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/csrf.d.ts

@@ -1,5 +1,5 @@
 /**
- * CSRF protection via an **Origin / Referer check** on state-changing requests — OWASP's recommended
+ * CSRF protection via an **Origin / Referer check** on state-changing requests - OWASP's recommended
  * defense for cookie-authenticated apps. A browser always attaches `Origin` (or at least `Referer`) to
  * a cross-origin or same-origin *unsafe* request; it must match an allowed origin, else `403`. Safe
  * methods (GET/HEAD/OPTIONS) pass. Apply with `app.use(csrf({ origins: ["https://example.com"] }))`.
@@ -7,7 +7,7 @@
 import type { Middleware } from "@nifrajs/core/server";
 export interface CsrfOptions {
     /**
-     * Allowed origins (e.g. `["https://example.com"]`). **Set this in production behind a proxy** — when
+     * Allowed origins (e.g. `["https://example.com"]`). **Set this in production behind a proxy** - when
      * omitted, the check derives same-origin from the request URL, which is correct in dev / when the
      * proxy preserves `Host` but not when the public origin differs from the worker's.
      */

package/dist/csrf.js

@@ -11,7 +11,7 @@ export function csrf(options = {}) {
             const origin = req.headers.get("origin");
             if (origin !== null)
                 return allowed.has(origin) ? undefined : forbidden();
-            // Some same-origin requests omit `Origin` — fall back to the `Referer`'s origin.
+            // Some same-origin requests omit `Origin` - fall back to the `Referer`'s origin.
             const referer = req.headers.get("referer");
             if (referer !== null) {
                 let refererOrigin;

package/dist/guards.d.ts

@@ -1,11 +1,11 @@
 /**
- * Route guards — run at the top of a protected loader/action/handler. On a missing session they
+ * Route guards - run at the top of a protected loader/action/handler. On a missing session they
  * **throw a `Response`** (a 302 to your login path, or a 401); nifra returns a thrown Response as-is, so
  * the guard short-circuits the rest of the handler. Pairs with `@nifrajs/auth` sessions but only needs the
  * `Session` shape, so it's framework-agnostic.
  */
 import type { Session } from "./session.js";
-/** What a guard does when the check fails: 302 to `redirectTo` (a same-origin path), or — omitted — a
+/** What a guard does when the check fails: 302 to `redirectTo` (a same-origin path), or - omitted - a
  * 401 JSON (`{ ok: false, error: "unauthorized" }`). */
 export interface GuardOptions {
     readonly redirectTo?: string;

package/dist/guards.js

@@ -4,7 +4,7 @@ const rejection = (options) => {
         return Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
     }
     // Same-origin guard (mirrors @nifrajs/web `redirect`): a single leading "/", never "//host" or an
-    // absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug — fail loud here.
+    // absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug - fail loud here.
     if (!to.startsWith("/") || to.startsWith("//")) {
         throw new Error(`[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`);
     }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/auth` — session primitives for nifra. Signed-cookie + server-store sessions, with the same
+ * `@nifrajs/auth` - session primitives for nifra. Signed-cookie + server-store sessions, with the same
  * pluggable-store + prod-guard discipline as the ISR cache. **Bring your own identity** (Better Auth,
  * Lucia, your own OAuth/password logic); nifra owns the session cookie, store, CSRF, and route guards.
  */

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/auth` — session primitives for nifra. Signed-cookie + server-store sessions, with the same
+ * `@nifrajs/auth` - session primitives for nifra. Signed-cookie + server-store sessions, with the same
  * pluggable-store + prod-guard discipline as the ISR cache. **Bring your own identity** (Better Auth,
  * Lucia, your own OAuth/password logic); nifra owns the session cookie, store, CSRF, and route guards.
  */

package/dist/session.d.ts

@@ -1,17 +1,17 @@
 /**
- * The session manager — `createSessions<Data>()` returns get/commit/destroy/regenerate bound to a
+ * The session manager - `createSessions<Data>()` returns get/commit/destroy/regenerate bound to a
  * signing secret + cookie config. Two modes:
  *   • **store mode** (a {@link SessionStore} is given): a random session id rides a signed cookie; the
  *     data lives in the store. Big/sensitive data, server-side revocation.
  *   • **cookie mode** (no store): the data itself is signed into the cookie (stateless, edge-friendly,
  *     ≤4 KB). No server state.
  * The cookie value is **always HMAC-signed** (tamper-evident; verified constant-time) and the session
- * cookie is always `HttpOnly`. Reads **fail closed** — a tampered/missing/expired cookie yields a fresh
+ * cookie is always `HttpOnly`. Reads **fail closed** - a tampered/missing/expired cookie yields a fresh
  * anonymous session, never an error.
  */
 import { type CookieOptions } from "@nifrajs/core/cookies";
 import type { SessionStore } from "./store.js";
-/** The cookie + response surface the manager needs — a structural subset of nifra's `Context`, so any
+/** The cookie + response surface the manager needs - a structural subset of nifra's `Context`, so any
  * `c` satisfies it and it's testable with a stub. */
 export interface SessionContext {
     readonly cookies: Readonly<Record<string, string>>;
@@ -23,7 +23,7 @@ export interface SessionContext {
         }): void;
     };
 }
-/** A typed session handle. Every key is optional — a fresh session is empty. */
+/** A typed session handle. Every key is optional - a fresh session is empty. */
 export interface Session<Data extends Record<string, unknown> = Record<string, unknown>> {
     get<K extends keyof Data>(key: K): Data[K] | undefined;
     set<K extends keyof Data>(key: K, value: Data[K]): void;
@@ -35,7 +35,7 @@ export interface Session<Data extends Record<string, unknown> = Record<string, u
     readonly data: Readonly<Partial<Data>>;
     readonly isEmpty: boolean;
 }
-/** Cookie attributes a session may tune. `httpOnly` is **not** offered — a session cookie is always
+/** Cookie attributes a session may tune. `httpOnly` is **not** offered - a session cookie is always
  * HttpOnly; `maxAge`/`expires` are derived from the session's lifetime. */
 export type SessionCookieOptions = Pick<CookieOptions, "secure" | "sameSite" | "path" | "domain">;
 export interface SessionOptions {
@@ -52,20 +52,20 @@ export interface SessionOptions {
     /** Extra cookie attributes (the session cookie is always HttpOnly; `Secure`/`SameSite=Lax`/`Path=/`
      * default via `c.set.cookie`). Pass `{ secure: false }` for local http dev. */
     readonly cookie?: SessionCookieOptions;
-    /** Clock (ms) — injected for testability; production passes `() => Date.now()` (the default). */
+    /** Clock (ms) - injected for testability; production passes `() => Date.now()` (the default). */
     readonly now?: () => number;
 }
 export interface SessionManager<Data extends Record<string, unknown> = Record<string, unknown>> {
     /** Load the session from the request cookie (verified + un-expired), or a fresh anonymous one. */
     get(c: SessionContext): Promise<Session<Data>>;
-    /** Read-only load from a raw `Request` — for `@nifrajs/web` loaders (which can read the request but not
+    /** Read-only load from a raw `Request` - for `@nifrajs/web` loaders (which can read the request but not
      * write cookies). Identical verify/expiry to {@link get}; commit/destroy in a route or action. */
     read(request: Request): Promise<Session<Data>>;
     /** Persist the session: write the store (store mode) + the signed cookie. */
     commit(c: SessionContext, session: Session<Data>): Promise<void>;
     /** End the session: drop the store record (store mode) + clear the cookie. */
     destroy(c: SessionContext, session?: Session<Data>): Promise<void>;
-    /** Rotate the session id on the next commit (call on privilege change — login — to defend against
+    /** Rotate the session id on the next commit (call on privilege change - login - to defend against
      * session fixation). Data is preserved; the old store record is dropped. */
     regenerate(session: Session<Data>): void;
 }

package/dist/session.js

@@ -1,12 +1,12 @@
 /**
- * The session manager — `createSessions<Data>()` returns get/commit/destroy/regenerate bound to a
+ * The session manager - `createSessions<Data>()` returns get/commit/destroy/regenerate bound to a
  * signing secret + cookie config. Two modes:
  *   • **store mode** (a {@link SessionStore} is given): a random session id rides a signed cookie; the
  *     data lives in the store. Big/sensitive data, server-side revocation.
  *   • **cookie mode** (no store): the data itself is signed into the cookie (stateless, edge-friendly,
  *     ≤4 KB). No server state.
  * The cookie value is **always HMAC-signed** (tamper-evident; verified constant-time) and the session
- * cookie is always `HttpOnly`. Reads **fail closed** — a tampered/missing/expired cookie yields a fresh
+ * cookie is always `HttpOnly`. Reads **fail closed** - a tampered/missing/expired cookie yields a fresh
  * anonymous session, never an error.
  */
 import { parseCookies, signValue, unsignValue } from "@nifrajs/core/cookies";
@@ -22,9 +22,9 @@ const encodeBase64Url = (bytes) => {
         bin += String.fromCharCode(b);
     return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 };
-/** A 256-bit random session id (base64url). High-entropy + unguessable — the cookie also signs it. */
+/** A 256-bit random session id (base64url). High-entropy + unguessable - the cookie also signs it. */
 const randomId = () => encodeBase64Url(crypto.getRandomValues(new Uint8Array(32)));
-/** Validate a cookie-mode payload at the trust boundary — malformed JSON / shape → `null` (no session). */
+/** Validate a cookie-mode payload at the trust boundary - malformed JSON / shape → `null` (no session). */
 const parsePayload = (json) => {
     let value;
     try {
@@ -51,7 +51,7 @@ export function createSessions(options) {
     const maxAge = options.maxAge ?? 7 * DAY_SECONDS;
     const rolling = options.rolling ?? true;
     const now = options.now ?? (() => Date.now());
-    // Annotated (not just `?? {}`) so `cookieOpts.path`/`.domain` stay typed — `?? {}` alone widens the
+    // Annotated (not just `?? {}`) so `cookieOpts.path`/`.domain` stay typed - `?? {}` alone widens the
     // type to include the empty-object literal, which the package's build tsconfig rejects on access.
     const cookieOpts = options.cookie ?? {};
     // Per-manager so the WeakMap is typed to this `Data` (no `any`); a session can only be committed by
@@ -105,7 +105,7 @@ export function createSessions(options) {
             if (record === undefined)
                 return make({});
             if (record.expiresAt <= now()) {
-                await store.delete(unsigned); // expired — evict + treat as no session
+                await store.delete(unsigned); // expired - evict + treat as no session
                 return make({});
             }
             return make({ id: unsigned, data: record.data, expiresAt: record.expiresAt });
@@ -116,7 +116,7 @@ export function createSessions(options) {
         return make({ data: payload.data, expiresAt: payload.expiresAt });
     };
     const get = (c) => loadFromRaw(c.cookies[cookieName]);
-    // Read-only load from a raw Request — for @nifrajs/web loaders, which have the request but can't write
+    // Read-only load from a raw Request - for @nifrajs/web loaders, which have the request but can't write
     // cookies (commit/destroy belong in a route/action with the full Context). Same verify + expiry.
     const read = (request) => loadFromRaw(parseCookies(request.headers.get("cookie"))[cookieName]);
     const writeCookie = (c, value, expiresAt) => {

package/dist/store.d.ts

@@ -1,10 +1,10 @@
 /**
- * Session stores (the **store mode** backend) — a pluggable `SessionStore` plus an in-memory
+ * Session stores (the **store mode** backend) - a pluggable `SessionStore` plus an in-memory
  * implementation (dev / single-instance, prod-guarded) and a Cloudflare Workers KV implementation
  * (the durable, shared production path). The store is dumb persistence: the session *manager* owns the
  * clock and authoritatively enforces expiry, so the store stays clock-free and trivially testable.
  */
-/** A persisted session — its data plus an absolute expiry (ms epoch). */
+/** A persisted session - its data plus an absolute expiry (ms epoch). */
 export interface SessionRecord {
     readonly data: Record<string, unknown>;
     /** Absolute expiry (ms epoch). The manager treats `expiresAt <= now` as no session. */
@@ -12,7 +12,7 @@ export interface SessionRecord {
 }
 /**
  * Pluggable session backend (store mode). Async so a network store (KV/Redis) fits the same shape.
- * **Production needs a shared/durable store** so sessions hold across instances — {@link MemorySessionStore}
+ * **Production needs a shared/durable store** so sessions hold across instances - {@link MemorySessionStore}
  * prod-guards against the per-instance footgun.
  */
 export interface SessionStore {
@@ -24,7 +24,7 @@ export interface SessionStore {
     delete(id: string): Promise<void>;
 }
 export interface MemorySessionStoreOptions {
-    /** Allow the in-memory store in production. Off by default — per-instance sessions don't hold across
+    /** Allow the in-memory store in production. Off by default - per-instance sessions don't hold across
      * instances and are lost on restart. */
     readonly allowInProduction?: boolean;
     /** Hard cap on stored sessions; the oldest-inserted is evicted past it (default 10_000). */
@@ -32,7 +32,7 @@ export interface MemorySessionStoreOptions {
 }
 /**
  * In-process session store. Refuses to run in production unless explicitly allowed (mirrors the ISR
- * `MemoryCacheStore` + the rate-limit `MemoryStore` — a per-instance store is unsafe across instances).
+ * `MemoryCacheStore` + the rate-limit `MemoryStore` - a per-instance store is unsafe across instances).
  * Bounded: oldest-inserted entries evict past `max`.
  */
 export declare class MemorySessionStore implements SessionStore {
@@ -44,7 +44,7 @@ export declare class MemorySessionStore implements SessionStore {
     delete(id: string): Promise<void>;
 }
 /**
- * Minimal structural shape of a Cloudflare Workers **KV namespace** binding — just the three methods
+ * Minimal structural shape of a Cloudflare Workers **KV namespace** binding - just the three methods
  * {@link KVSessionStore} uses. Structural (no `@cloudflare/workers-types` dependency) so any KV-like
  * binding satisfies it and tests can pass an in-memory double.
  */
@@ -58,9 +58,9 @@ export interface KVNamespaceLike {
 }
 /**
  * A {@link SessionStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike})
- * — the durable, shared production store: sessions hold across worker instances and survive restarts.
+ * - the durable, shared production store: sessions hold across worker instances and survive restarts.
  * Records serialize to JSON; the entry's KV `expiration` is set from the record's `expiresAt` so KV
- * auto-evicts the session (a GC backstop — the manager still authoritatively checks expiry on read).
+ * auto-evicts the session (a GC backstop - the manager still authoritatively checks expiry on read).
  * Every read is validated, so a corrupt/skewed entry reads as no session.
  */
 export declare class KVSessionStore implements SessionStore {

package/dist/store.js

@@ -1,12 +1,12 @@
 /**
- * Session stores (the **store mode** backend) — a pluggable `SessionStore` plus an in-memory
+ * Session stores (the **store mode** backend) - a pluggable `SessionStore` plus an in-memory
  * implementation (dev / single-instance, prod-guarded) and a Cloudflare Workers KV implementation
  * (the durable, shared production path). The store is dumb persistence: the session *manager* owns the
  * clock and authoritatively enforces expiry, so the store stays clock-free and trivially testable.
  */
 /**
  * In-process session store. Refuses to run in production unless explicitly allowed (mirrors the ISR
- * `MemoryCacheStore` + the rate-limit `MemoryStore` — a per-instance store is unsafe across instances).
+ * `MemoryCacheStore` + the rate-limit `MemoryStore` - a per-instance store is unsafe across instances).
  * Bounded: oldest-inserted entries evict past `max`.
  */
 export class MemorySessionStore {
@@ -54,9 +54,9 @@ const isSessionRecord = (value) => {
 };
 /**
  * A {@link SessionStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike})
- * — the durable, shared production store: sessions hold across worker instances and survive restarts.
+ * - the durable, shared production store: sessions hold across worker instances and survive restarts.
  * Records serialize to JSON; the entry's KV `expiration` is set from the record's `expiresAt` so KV
- * auto-evicts the session (a GC backstop — the manager still authoritatively checks expiry on read).
+ * auto-evicts the session (a GC backstop - the manager still authoritatively checks expiry on read).
  * Every read is validated, so a corrupt/skewed entry reads as no session.
  */
 export class KVSessionStore {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/auth",
-  "version": "2.2.0",
-  "description": "Session primitives for nifra — signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.",
+  "version": "2.4.0",
+  "description": "Session primitives for nifra - signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.",
   "keywords": [
     "bun",
     "typescript",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.2.0"
+    "@nifrajs/core": "^2.4.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/csrf.ts

@@ -1,5 +1,5 @@
 /**
- * CSRF protection via an **Origin / Referer check** on state-changing requests — OWASP's recommended
+ * CSRF protection via an **Origin / Referer check** on state-changing requests - OWASP's recommended
  * defense for cookie-authenticated apps. A browser always attaches `Origin` (or at least `Referer`) to
  * a cross-origin or same-origin *unsafe* request; it must match an allowed origin, else `403`. Safe
  * methods (GET/HEAD/OPTIONS) pass. Apply with `app.use(csrf({ origins: ["https://example.com"] }))`.
@@ -10,7 +10,7 @@ const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"])
 
 export interface CsrfOptions {
   /**
-   * Allowed origins (e.g. `["https://example.com"]`). **Set this in production behind a proxy** — when
+   * Allowed origins (e.g. `["https://example.com"]`). **Set this in production behind a proxy** - when
    * omitted, the check derives same-origin from the request URL, which is correct in dev / when the
    * proxy preserves `Host` but not when the public origin differs from the worker's.
    */
@@ -31,7 +31,7 @@ export function csrf(options: CsrfOptions = {}): Middleware {
       const origin = req.headers.get("origin")
       if (origin !== null) return allowed.has(origin) ? undefined : forbidden()
 
-      // Some same-origin requests omit `Origin` — fall back to the `Referer`'s origin.
+      // Some same-origin requests omit `Origin` - fall back to the `Referer`'s origin.
       const referer = req.headers.get("referer")
       if (referer !== null) {
         let refererOrigin: string

package/src/guards.ts

@@ -1,12 +1,12 @@
 /**
- * Route guards — run at the top of a protected loader/action/handler. On a missing session they
+ * Route guards - run at the top of a protected loader/action/handler. On a missing session they
  * **throw a `Response`** (a 302 to your login path, or a 401); nifra returns a thrown Response as-is, so
  * the guard short-circuits the rest of the handler. Pairs with `@nifrajs/auth` sessions but only needs the
  * `Session` shape, so it's framework-agnostic.
  */
 import type { Session } from "./session.ts"
 
-/** What a guard does when the check fails: 302 to `redirectTo` (a same-origin path), or — omitted — a
+/** What a guard does when the check fails: 302 to `redirectTo` (a same-origin path), or - omitted - a
  * 401 JSON (`{ ok: false, error: "unauthorized" }`). */
 export interface GuardOptions {
   readonly redirectTo?: string
@@ -18,7 +18,7 @@ const rejection = (options: GuardOptions): Response => {
     return Response.json({ ok: false, error: "unauthorized" }, { status: 401 })
   }
   // Same-origin guard (mirrors @nifrajs/web `redirect`): a single leading "/", never "//host" or an
-  // absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug — fail loud here.
+  // absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug - fail loud here.
   if (!to.startsWith("/") || to.startsWith("//")) {
     throw new Error(
       `[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`,

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * `@nifrajs/auth` — session primitives for nifra. Signed-cookie + server-store sessions, with the same
+ * `@nifrajs/auth` - session primitives for nifra. Signed-cookie + server-store sessions, with the same
  * pluggable-store + prod-guard discipline as the ISR cache. **Bring your own identity** (Better Auth,
  * Lucia, your own OAuth/password logic); nifra owns the session cookie, store, CSRF, and route guards.
  */

package/src/session.ts

@@ -1,18 +1,18 @@
 /**
- * The session manager — `createSessions<Data>()` returns get/commit/destroy/regenerate bound to a
+ * The session manager - `createSessions<Data>()` returns get/commit/destroy/regenerate bound to a
  * signing secret + cookie config. Two modes:
  *   • **store mode** (a {@link SessionStore} is given): a random session id rides a signed cookie; the
  *     data lives in the store. Big/sensitive data, server-side revocation.
  *   • **cookie mode** (no store): the data itself is signed into the cookie (stateless, edge-friendly,
  *     ≤4 KB). No server state.
  * The cookie value is **always HMAC-signed** (tamper-evident; verified constant-time) and the session
- * cookie is always `HttpOnly`. Reads **fail closed** — a tampered/missing/expired cookie yields a fresh
+ * cookie is always `HttpOnly`. Reads **fail closed** - a tampered/missing/expired cookie yields a fresh
  * anonymous session, never an error.
  */
 import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core/cookies"
 import type { SessionRecord, SessionStore } from "./store.ts"
 
-/** The cookie + response surface the manager needs — a structural subset of nifra's `Context`, so any
+/** The cookie + response surface the manager needs - a structural subset of nifra's `Context`, so any
  * `c` satisfies it and it's testable with a stub. */
 export interface SessionContext {
   readonly cookies: Readonly<Record<string, string>>
@@ -22,7 +22,7 @@ export interface SessionContext {
   }
 }
 
-/** A typed session handle. Every key is optional — a fresh session is empty. */
+/** A typed session handle. Every key is optional - a fresh session is empty. */
 export interface Session<Data extends Record<string, unknown> = Record<string, unknown>> {
   get<K extends keyof Data>(key: K): Data[K] | undefined
   set<K extends keyof Data>(key: K, value: Data[K]): void
@@ -35,7 +35,7 @@ export interface Session<Data extends Record<string, unknown> = Record<string, u
   readonly isEmpty: boolean
 }
 
-/** Cookie attributes a session may tune. `httpOnly` is **not** offered — a session cookie is always
+/** Cookie attributes a session may tune. `httpOnly` is **not** offered - a session cookie is always
  * HttpOnly; `maxAge`/`expires` are derived from the session's lifetime. */
 export type SessionCookieOptions = Pick<CookieOptions, "secure" | "sameSite" | "path" | "domain">
 
@@ -53,21 +53,21 @@ export interface SessionOptions {
   /** Extra cookie attributes (the session cookie is always HttpOnly; `Secure`/`SameSite=Lax`/`Path=/`
    * default via `c.set.cookie`). Pass `{ secure: false }` for local http dev. */
   readonly cookie?: SessionCookieOptions
-  /** Clock (ms) — injected for testability; production passes `() => Date.now()` (the default). */
+  /** Clock (ms) - injected for testability; production passes `() => Date.now()` (the default). */
   readonly now?: () => number
 }
 
 export interface SessionManager<Data extends Record<string, unknown> = Record<string, unknown>> {
   /** Load the session from the request cookie (verified + un-expired), or a fresh anonymous one. */
   get(c: SessionContext): Promise<Session<Data>>
-  /** Read-only load from a raw `Request` — for `@nifrajs/web` loaders (which can read the request but not
+  /** Read-only load from a raw `Request` - for `@nifrajs/web` loaders (which can read the request but not
    * write cookies). Identical verify/expiry to {@link get}; commit/destroy in a route or action. */
   read(request: Request): Promise<Session<Data>>
   /** Persist the session: write the store (store mode) + the signed cookie. */
   commit(c: SessionContext, session: Session<Data>): Promise<void>
   /** End the session: drop the store record (store mode) + clear the cookie. */
   destroy(c: SessionContext, session?: Session<Data>): Promise<void>
-  /** Rotate the session id on the next commit (call on privilege change — login — to defend against
+  /** Rotate the session id on the next commit (call on privilege change - login - to defend against
    * session fixation). Data is preserved; the old store record is dropped. */
   regenerate(session: Session<Data>): void
 }
@@ -85,7 +85,7 @@ const encodeBase64Url = (bytes: Uint8Array): string => {
   return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
 }
 
-/** A 256-bit random session id (base64url). High-entropy + unguessable — the cookie also signs it. */
+/** A 256-bit random session id (base64url). High-entropy + unguessable - the cookie also signs it. */
 const randomId = (): string => encodeBase64Url(crypto.getRandomValues(new Uint8Array(32)))
 
 interface Payload {
@@ -93,7 +93,7 @@ interface Payload {
   expiresAt: number
 }
 
-/** Validate a cookie-mode payload at the trust boundary — malformed JSON / shape → `null` (no session). */
+/** Validate a cookie-mode payload at the trust boundary - malformed JSON / shape → `null` (no session). */
 const parsePayload = (json: string): Payload | null => {
   let value: unknown
   try {
@@ -121,7 +121,7 @@ export function createSessions<Data extends Record<string, unknown> = Record<str
   const maxAge = options.maxAge ?? 7 * DAY_SECONDS
   const rolling = options.rolling ?? true
   const now = options.now ?? (() => Date.now())
-  // Annotated (not just `?? {}`) so `cookieOpts.path`/`.domain` stay typed — `?? {}` alone widens the
+  // Annotated (not just `?? {}`) so `cookieOpts.path`/`.domain` stay typed - `?? {}` alone widens the
   // type to include the empty-object literal, which the package's build tsconfig rejects on access.
   const cookieOpts: SessionCookieOptions = options.cookie ?? {}
 
@@ -187,7 +187,7 @@ export function createSessions<Data extends Record<string, unknown> = Record<str
       const record = await store.get(unsigned)
       if (record === undefined) return make({})
       if (record.expiresAt <= now()) {
-        await store.delete(unsigned) // expired — evict + treat as no session
+        await store.delete(unsigned) // expired - evict + treat as no session
         return make({})
       }
       return make({ id: unsigned, data: record.data, expiresAt: record.expiresAt })
@@ -200,7 +200,7 @@ export function createSessions<Data extends Record<string, unknown> = Record<str
 
   const get = (c: SessionContext): Promise<Session<Data>> => loadFromRaw(c.cookies[cookieName])
 
-  // Read-only load from a raw Request — for @nifrajs/web loaders, which have the request but can't write
+  // Read-only load from a raw Request - for @nifrajs/web loaders, which have the request but can't write
   // cookies (commit/destroy belong in a route/action with the full Context). Same verify + expiry.
   const read = (request: Request): Promise<Session<Data>> =>
     loadFromRaw(parseCookies(request.headers.get("cookie"))[cookieName])

package/src/store.ts

@@ -1,11 +1,11 @@
 /**
- * Session stores (the **store mode** backend) — a pluggable `SessionStore` plus an in-memory
+ * Session stores (the **store mode** backend) - a pluggable `SessionStore` plus an in-memory
  * implementation (dev / single-instance, prod-guarded) and a Cloudflare Workers KV implementation
  * (the durable, shared production path). The store is dumb persistence: the session *manager* owns the
  * clock and authoritatively enforces expiry, so the store stays clock-free and trivially testable.
  */
 
-/** A persisted session — its data plus an absolute expiry (ms epoch). */
+/** A persisted session - its data plus an absolute expiry (ms epoch). */
 export interface SessionRecord {
   readonly data: Record<string, unknown>
   /** Absolute expiry (ms epoch). The manager treats `expiresAt <= now` as no session. */
@@ -14,7 +14,7 @@ export interface SessionRecord {
 
 /**
  * Pluggable session backend (store mode). Async so a network store (KV/Redis) fits the same shape.
- * **Production needs a shared/durable store** so sessions hold across instances — {@link MemorySessionStore}
+ * **Production needs a shared/durable store** so sessions hold across instances - {@link MemorySessionStore}
  * prod-guards against the per-instance footgun.
  */
 export interface SessionStore {
@@ -27,7 +27,7 @@ export interface SessionStore {
 }
 
 export interface MemorySessionStoreOptions {
-  /** Allow the in-memory store in production. Off by default — per-instance sessions don't hold across
+  /** Allow the in-memory store in production. Off by default - per-instance sessions don't hold across
    * instances and are lost on restart. */
   readonly allowInProduction?: boolean
   /** Hard cap on stored sessions; the oldest-inserted is evicted past it (default 10_000). */
@@ -36,7 +36,7 @@ export interface MemorySessionStoreOptions {
 
 /**
  * In-process session store. Refuses to run in production unless explicitly allowed (mirrors the ISR
- * `MemoryCacheStore` + the rate-limit `MemoryStore` — a per-instance store is unsafe across instances).
+ * `MemoryCacheStore` + the rate-limit `MemoryStore` - a per-instance store is unsafe across instances).
  * Bounded: oldest-inserted entries evict past `max`.
  */
 export class MemorySessionStore implements SessionStore {
@@ -77,7 +77,7 @@ export class MemorySessionStore implements SessionStore {
 }
 
 /**
- * Minimal structural shape of a Cloudflare Workers **KV namespace** binding — just the three methods
+ * Minimal structural shape of a Cloudflare Workers **KV namespace** binding - just the three methods
  * {@link KVSessionStore} uses. Structural (no `@cloudflare/workers-types` dependency) so any KV-like
  * binding satisfies it and tests can pass an in-memory double.
  */
@@ -104,9 +104,9 @@ const isSessionRecord = (value: unknown): value is SessionRecord => {
 
 /**
  * A {@link SessionStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike})
- * — the durable, shared production store: sessions hold across worker instances and survive restarts.
+ * - the durable, shared production store: sessions hold across worker instances and survive restarts.
  * Records serialize to JSON; the entry's KV `expiration` is set from the record's `expiresAt` so KV
- * auto-evicts the session (a GC backstop — the manager still authoritatively checks expiry on read).
+ * auto-evicts the session (a GC backstop - the manager still authoritatively checks expiry on read).
  * Every read is validated, so a corrupt/skewed entry reads as no session.
  */
 export class KVSessionStore implements SessionStore {