@nifrajs/auth 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @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.
+
+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
+
+```sh
+bun add @nifrajs/auth
+```
+
+## Docs
+
+- Reference: <https://nifra.dev/docs>
+- AI-readable: <https://nifra.dev/llms.txt>
+
+MIT

package/dist/csrf.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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"] }))`.
+ */
+import type { Middleware } from "@nifrajs/core";
+export interface CsrfOptions {
+    /**
+     * 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.
+     */
+    readonly origins?: readonly string[];
+}
+export declare function csrf(options?: CsrfOptions): Middleware;
+//# sourceMappingURL=csrf.d.ts.map

package/dist/csrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.d.ts","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAI/C,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAKD,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CA2B1D"}

package/dist/csrf.js

@@ -0,0 +1,31 @@
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const forbidden = () => Response.json({ ok: false, error: "csrf_failed" }, { status: 403 });
+export function csrf(options = {}) {
+    const configured = options.origins !== undefined ? new Set(options.origins) : undefined;
+    return {
+        name: "csrf",
+        onRequest(req) {
+            if (SAFE_METHODS.has(req.method))
+                return undefined;
+            const allowed = configured ?? new Set([new URL(req.url).origin]);
+            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.
+            const referer = req.headers.get("referer");
+            if (referer !== null) {
+                let refererOrigin;
+                try {
+                    refererOrigin = new URL(referer).origin;
+                }
+                catch {
+                    return forbidden(); // malformed Referer
+                }
+                return allowed.has(refererOrigin) ? undefined : forbidden();
+            }
+            // A state-changing request with neither header → reject (fail closed; a browser always sends one).
+            return forbidden();
+        },
+    };
+}
+//# sourceMappingURL=csrf.js.map

package/dist/csrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.js","sourceRoot":"","sources":["../src/csrf.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;AAWxD,MAAM,SAAS,GAAG,GAAa,EAAE,CAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;AAErE,MAAM,UAAU,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACvF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,SAAS,CAAC,GAAG;YACX,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,OAAO,SAAS,CAAA;YAClD,MAAM,OAAO,GAAG,UAAU,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;YAEhE,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACxC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAA;YAEzE,iFAAiF;YACjF,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;YAC1C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,IAAI,aAAqB,CAAA;gBACzB,IAAI,CAAC;oBACH,aAAa,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAA;gBACzC,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,SAAS,EAAE,CAAA,CAAC,oBAAoB;gBACzC,CAAC;gBACD,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAA;YAC7D,CAAC;YAED,mGAAmG;YACnG,OAAO,SAAS,EAAE,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/guards.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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
+ * 401 JSON (`{ ok: false, error: "unauthorized" }`). */
+export interface GuardOptions {
+    readonly redirectTo?: string;
+}
+/**
+ * Require a non-empty session. Returns it when present; otherwise throws a `Response` (302/401). Use at
+ * the top of a protected loader:
+ * `const session = requireSession(await sessions.get(c), { redirectTo: "/login" })`.
+ */
+export declare function requireSession<Data extends Record<string, unknown>>(session: Session<Data>, options?: GuardOptions): Session<Data>;
+/**
+ * Require a specific session key (e.g. the `userId` a login set) to be present. Returns its value
+ * (narrowed non-nullish); otherwise throws like {@link requireSession}. The common "who is the user"
+ * guard: `const userId = requireUser(await sessions.get(c), "userId", { redirectTo: "/login" })`.
+ */
+export declare function requireUser<Data extends Record<string, unknown>, K extends keyof Data>(session: Session<Data>, key: K, options?: GuardOptions): NonNullable<Data[K]>;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;wDACwD;AACxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAiBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,EACpF,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,GAAG,EAAE,CAAC,EACN,OAAO,GAAE,YAAiB,GACzB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAKtB"}

package/dist/guards.js

@@ -0,0 +1,35 @@
+const rejection = (options) => {
+    const to = options.redirectTo;
+    if (to === undefined) {
+        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.
+    if (!to.startsWith("/") || to.startsWith("//")) {
+        throw new Error(`[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`);
+    }
+    return new Response(null, { status: 302, headers: { location: to } });
+};
+/**
+ * Require a non-empty session. Returns it when present; otherwise throws a `Response` (302/401). Use at
+ * the top of a protected loader:
+ * `const session = requireSession(await sessions.get(c), { redirectTo: "/login" })`.
+ */
+export function requireSession(session, options = {}) {
+    if (!session.isEmpty)
+        return session;
+    throw rejection(options);
+}
+/**
+ * Require a specific session key (e.g. the `userId` a login set) to be present. Returns its value
+ * (narrowed non-nullish); otherwise throws like {@link requireSession}. The common "who is the user"
+ * guard: `const userId = requireUser(await sessions.get(c), "userId", { redirectTo: "/login" })`.
+ */
+export function requireUser(session, key, options = {}) {
+    const value = session.get(key);
+    // Narrowed by the runtime check; the generic `Data[K] | undefined` doesn't auto-narrow to NonNullable.
+    if (value !== undefined && value !== null)
+        return value;
+    throw rejection(options);
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAcA,MAAM,SAAS,GAAG,CAAC,OAAqB,EAAY,EAAE;IACpD,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAA;IAC7B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7E,CAAC;IACD,kGAAkG;IAClG,+FAA+F;IAC/F,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,oFAAoF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAC1G,CAAA;IACH,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;AACvE,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsB,EACtB,UAAwB,EAAE;IAE1B,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,OAAO,CAAA;IACpC,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,OAAsB,EACtB,GAAM,EACN,UAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,uGAAuG;IACvG,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAA6B,CAAA;IAC/E,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@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.
+ */
+export { type CsrfOptions, csrf } from "./csrf.js";
+export { type GuardOptions, requireSession, requireUser } from "./guards.js";
+export { createSessions, type Session, type SessionContext, type SessionCookieOptions, type SessionManager, type SessionOptions, } from "./session.js";
+export { type KVNamespaceLike, KVSessionStore, MemorySessionStore, type MemorySessionStoreOptions, type SessionRecord, type SessionStore, } from "./store.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,cAAc,EACd,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,eAAe,EACpB,cAAc,EACd,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@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.
+ */
+export { csrf } from "./csrf.js";
+export { requireSession, requireUser } from "./guards.js";
+export { createSessions, } from "./session.js";
+export { KVSessionStore, MemorySessionStore, } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAoB,IAAI,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAqB,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,cAAc,GAMf,MAAM,cAAc,CAAA;AACrB,OAAO,EAEL,cAAc,EACd,kBAAkB,GAInB,MAAM,YAAY,CAAA"}

package/dist/session.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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
+ * anonymous session, never an error.
+ */
+import { type CookieOptions } from "@nifrajs/core";
+import type { SessionStore } from "./store.js";
+/** 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>>;
+    readonly set: {
+        cookie(name: string, value: string, options?: CookieOptions): void;
+        deleteCookie(name: string, options?: {
+            readonly path?: string;
+            readonly domain?: string;
+        }): void;
+    };
+}
+/** 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;
+    unset(key: keyof Data): void;
+    has(key: keyof Data): boolean;
+    /** Wipe all data (the session id is kept). To end the session entirely, call `manager.destroy`. */
+    clear(): void;
+    /** A snapshot of the current data. */
+    readonly data: Readonly<Partial<Data>>;
+    readonly isEmpty: boolean;
+}
+/** 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 {
+    /** Signing secret (≥ 16 chars). Rotating it invalidates all existing sessions. */
+    readonly secret: string;
+    /** Provide a store for **store mode**; omit for **cookie mode** (stateless). */
+    readonly store?: SessionStore;
+    /** Cookie name. Default `nifra_session`. */
+    readonly cookieName?: string;
+    /** Session lifetime in **seconds**. Default 7 days. */
+    readonly maxAge?: number;
+    /** Slide the expiry forward on every commit (default `true`); `false` = fixed absolute expiry. */
+    readonly rolling?: boolean;
+    /** 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). */
+    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
+     * 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
+     * session fixation). Data is preserved; the old store record is dropped. */
+    regenerate(session: Session<Data>): void;
+}
+export declare function createSessions<Data extends Record<string, unknown> = Record<string, unknown>>(options: SessionOptions): SessionManager<Data>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -0,0 +1,164 @@
+/**
+ * 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
+ * anonymous session, never an error.
+ */
+import { parseCookies, signValue, unsignValue } from "@nifrajs/core";
+const DAY_SECONDS = 86_400;
+// 256-bit floor, matching @nifrajs/core's signed-cookie/webhook guard. Sessions sign via core's
+// signValue (which enforces the same bar); this early check gives an auth-specific message before
+// delegating. Measured in UTF-8 bytes, not characters.
+const MIN_SECRET_BYTES = 32;
+const SECRET_ENCODER = new TextEncoder();
+const encodeBase64Url = (bytes) => {
+    let bin = "";
+    for (const b of 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. */
+const randomId = () => encodeBase64Url(crypto.getRandomValues(new Uint8Array(32)));
+/** Validate a cookie-mode payload at the trust boundary — malformed JSON / shape → `null` (no session). */
+const parsePayload = (json) => {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null)
+        return null;
+    const obj = value;
+    if (typeof obj.expiresAt !== "number" || !Number.isFinite(obj.expiresAt))
+        return null;
+    if (typeof obj.data !== "object" || obj.data === null)
+        return null;
+    return { data: obj.data, expiresAt: obj.expiresAt };
+};
+export function createSessions(options) {
+    const { secret, store } = options;
+    if (SECRET_ENCODER.encode(secret).length < MIN_SECRET_BYTES) {
+        throw new Error(`[nifra/auth] session secret must be at least ${MIN_SECRET_BYTES} bytes (256-bit). Generate one with: openssl rand -base64 32`);
+    }
+    const cookieName = options.cookieName ?? "nifra_session";
+    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
+    // 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
+    // the manager that created it.
+    const states = new WeakMap();
+    const make = (init) => {
+        const state = {
+            id: init.id,
+            // The Map erases per-key value types; the public generic signatures restore them at the edge.
+            data: new Map(Object.entries(init.data ?? {})),
+            expiresAt: init.expiresAt,
+            regenerate: false,
+        };
+        const session = {
+            get: (key) => state.data.get(key),
+            set: (key, value) => {
+                state.data.set(key, value);
+            },
+            unset: (key) => {
+                state.data.delete(key);
+            },
+            has: (key) => state.data.has(key),
+            clear: () => {
+                state.data.clear();
+            },
+            get data() {
+                return Object.fromEntries(state.data);
+            },
+            get isEmpty() {
+                return state.data.size === 0;
+            },
+        };
+        states.set(session, state);
+        return session;
+    };
+    const stateOf = (session, op) => {
+        const state = states.get(session);
+        if (state === undefined) {
+            throw new Error(`[nifra/auth] ${op}: session was not created by this manager`);
+        }
+        return state;
+    };
+    const loadFromRaw = async (raw) => {
+        if (raw === undefined || raw === "")
+            return make({});
+        const unsigned = await unsignValue(raw, secret);
+        if (unsigned === null)
+            return make({}); // tampered / wrong secret → fail closed (anonymous)
+        if (store !== undefined) {
+            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
+                return make({});
+            }
+            return make({ id: unsigned, data: record.data, expiresAt: record.expiresAt });
+        }
+        const payload = parsePayload(unsigned);
+        if (payload === null || payload.expiresAt <= now())
+            return make({});
+        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
+    // 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) => {
+        const maxAgeSeconds = Math.max(0, Math.floor((expiresAt - now()) / 1000));
+        c.set.cookie(cookieName, value, { ...cookieOpts, maxAge: maxAgeSeconds });
+    };
+    const commit = async (c, session) => {
+        const state = stateOf(session, "commit");
+        // Rolling → slide the expiry; absolute → keep the original (set on the first commit).
+        const expiresAt = rolling || state.expiresAt === undefined ? now() + maxAge * 1000 : state.expiresAt;
+        state.expiresAt = expiresAt;
+        const data = Object.fromEntries(state.data);
+        if (store !== undefined) {
+            if (state.regenerate) {
+                if (state.id !== undefined)
+                    await store.delete(state.id); // drop the pre-rotation session
+                state.id = undefined;
+                state.regenerate = false;
+            }
+            if (state.id === undefined)
+                state.id = randomId();
+            await store.set(state.id, { data, expiresAt });
+            writeCookie(c, await signValue(state.id, secret), expiresAt);
+            return;
+        }
+        // Cookie mode: the (signed) payload IS the cookie. serializeCookie enforces the 4 KB cap.
+        writeCookie(c, await signValue(JSON.stringify({ data, expiresAt }), secret), expiresAt);
+    };
+    const destroy = async (c, session) => {
+        if (store !== undefined && session !== undefined) {
+            const state = states.get(session);
+            if (state?.id !== undefined)
+                await store.delete(state.id);
+        }
+        c.set.deleteCookie(cookieName, {
+            path: cookieOpts.path ?? "/",
+            ...(cookieOpts.domain !== undefined ? { domain: cookieOpts.domain } : {}),
+        });
+    };
+    const regenerate = (session) => {
+        stateOf(session, "regenerate").regenerate = true;
+    };
+    return { get, read, commit, destroy, regenerate };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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). */
+export interface SessionRecord {
+    readonly data: Record<string, unknown>;
+    /** Absolute expiry (ms epoch). The manager treats `expiresAt <= now` as no session. */
+    readonly expiresAt: number;
+}
+/**
+ * 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}
+ * prod-guards against the per-instance footgun.
+ */
+export interface SessionStore {
+    /** The record for `id`, or `undefined` on a miss. */
+    get(id: string): Promise<SessionRecord | undefined>;
+    /** Store (or overwrite) the record for `id`. */
+    set(id: string, record: SessionRecord): Promise<void>;
+    /** Drop `id` (logout / regeneration). A no-op if absent. */
+    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
+     * instances and are lost on restart. */
+    readonly allowInProduction?: boolean;
+    /** Hard cap on stored sessions; the oldest-inserted is evicted past it (default 10_000). */
+    readonly max?: number;
+}
+/**
+ * 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).
+ * Bounded: oldest-inserted entries evict past `max`.
+ */
+export declare class MemorySessionStore implements SessionStore {
+    private readonly sessions;
+    private readonly max;
+    constructor(options?: MemorySessionStoreOptions);
+    get(id: string): Promise<SessionRecord | undefined>;
+    set(id: string, record: SessionRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * 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.
+ */
+export interface KVNamespaceLike {
+    get(key: string): Promise<string | null>;
+    /** `expiration` is an absolute unix-seconds timestamp (Cloudflare KV auto-evicts past it). */
+    put(key: string, value: string, options?: {
+        readonly expiration?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * 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.
+ * 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).
+ * Every read is validated, so a corrupt/skewed entry reads as no session.
+ */
+export declare class KVSessionStore implements SessionStore {
+    private readonly kv;
+    constructor(kv: KVNamespaceLike);
+    get(id: string): Promise<SessionRecord | undefined>;
+    set(id: string, record: SessionRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAA;IACnD,gDAAgD;IAChD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD,4DAA4D;IAC5D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC;4CACwC;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;gBAEhB,OAAO,GAAE,yBAA8B;IAYnD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAInD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIlC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,8FAA8F;IAC9F,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1F,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAgBD;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;gBAExB,EAAE,EAAE,eAAe;IAIzB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAYnD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IASrD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/store.js

@@ -0,0 +1,92 @@
+/**
+ * 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).
+ * Bounded: oldest-inserted entries evict past `max`.
+ */
+export class MemorySessionStore {
+    sessions = new Map();
+    max;
+    constructor(options = {}) {
+        const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+        if (options.allowInProduction !== true && isProd) {
+            throw new Error("[nifra/auth] MemorySessionStore is per-instance and unsafe in production (sessions don't hold " +
+                "across instances and are lost on restart). Use a shared store (KVSessionStore, Redis), or " +
+                "pass { allowInProduction: true } for a single-instance deploy.");
+        }
+        this.max = options.max ?? 10_000;
+    }
+    get(id) {
+        return Promise.resolve(this.sessions.get(id));
+    }
+    set(id, record) {
+        this.sessions.delete(id); // re-insert at the tail so Map order tracks recency for the bounded evict
+        this.sessions.set(id, record);
+        while (this.sessions.size > this.max) {
+            const oldest = this.sessions.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.sessions.delete(oldest);
+        }
+        return Promise.resolve();
+    }
+    delete(id) {
+        this.sessions.delete(id);
+        return Promise.resolve();
+    }
+}
+/** Structural validation of a KV-read value before it's trusted as a {@link SessionRecord}. The store
+ * is a trust boundary (corruption, version skew, tampering), so a malformed entry reads as a miss
+ * (no session) rather than a thrown error or a half-valid record. */
+const isSessionRecord = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.expiresAt === "number" &&
+        Number.isFinite(v.expiresAt) &&
+        typeof v.data === "object" &&
+        v.data !== null);
+};
+/**
+ * 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.
+ * 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).
+ * Every read is validated, so a corrupt/skewed entry reads as no session.
+ */
+export class KVSessionStore {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    async get(id) {
+        const raw = await this.kv.get(id);
+        if (raw === null)
+            return undefined;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined; // corrupt entry → no session (the next set overwrites it)
+        }
+        return isSessionRecord(parsed) ? parsed : undefined;
+    }
+    async set(id, record) {
+        // Absolute KV expiry (unix seconds) as a GC backstop. Cloudflare requires it be ≥ 60s out; session
+        // `maxAge` is realistically minutes+, so a real deploy satisfies that (the manager enforces the
+        // exact expiry regardless).
+        await this.kv.put(id, JSON.stringify(record), {
+            expiration: Math.floor(record.expiresAt / 1000),
+        });
+    }
+    async delete(id) {
+        await this.kv.delete(id);
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nifrajs/auth",
+  "version": "0.1.0-alpha.1",
+  "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",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/csrf.ts

@@ -0,0 +1,50 @@
+/**
+ * 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"] }))`.
+ */
+import type { Middleware } from "@nifrajs/core"
+
+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
+   * 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.
+   */
+  readonly origins?: readonly string[]
+}
+
+const forbidden = (): Response =>
+  Response.json({ ok: false, error: "csrf_failed" }, { status: 403 })
+
+export function csrf(options: CsrfOptions = {}): Middleware {
+  const configured = options.origins !== undefined ? new Set(options.origins) : undefined
+  return {
+    name: "csrf",
+    onRequest(req) {
+      if (SAFE_METHODS.has(req.method)) return undefined
+      const allowed = configured ?? new Set([new URL(req.url).origin])
+
+      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.
+      const referer = req.headers.get("referer")
+      if (referer !== null) {
+        let refererOrigin: string
+        try {
+          refererOrigin = new URL(referer).origin
+        } catch {
+          return forbidden() // malformed Referer
+        }
+        return allowed.has(refererOrigin) ? undefined : forbidden()
+      }
+
+      // A state-changing request with neither header → reject (fail closed; a browser always sends one).
+      return forbidden()
+    },
+  }
+}

package/src/guards.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ * 401 JSON (`{ ok: false, error: "unauthorized" }`). */
+export interface GuardOptions {
+  readonly redirectTo?: string
+}
+
+const rejection = (options: GuardOptions): Response => {
+  const to = options.redirectTo
+  if (to === undefined) {
+    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.
+  if (!to.startsWith("/") || to.startsWith("//")) {
+    throw new Error(
+      `[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`,
+    )
+  }
+  return new Response(null, { status: 302, headers: { location: to } })
+}
+
+/**
+ * Require a non-empty session. Returns it when present; otherwise throws a `Response` (302/401). Use at
+ * the top of a protected loader:
+ * `const session = requireSession(await sessions.get(c), { redirectTo: "/login" })`.
+ */
+export function requireSession<Data extends Record<string, unknown>>(
+  session: Session<Data>,
+  options: GuardOptions = {},
+): Session<Data> {
+  if (!session.isEmpty) return session
+  throw rejection(options)
+}
+
+/**
+ * Require a specific session key (e.g. the `userId` a login set) to be present. Returns its value
+ * (narrowed non-nullish); otherwise throws like {@link requireSession}. The common "who is the user"
+ * guard: `const userId = requireUser(await sessions.get(c), "userId", { redirectTo: "/login" })`.
+ */
+export function requireUser<Data extends Record<string, unknown>, K extends keyof Data>(
+  session: Session<Data>,
+  key: K,
+  options: GuardOptions = {},
+): NonNullable<Data[K]> {
+  const value = session.get(key)
+  // Narrowed by the runtime check; the generic `Data[K] | undefined` doesn't auto-narrow to NonNullable.
+  if (value !== undefined && value !== null) return value as NonNullable<Data[K]>
+  throw rejection(options)
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `@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.
+ */
+export { type CsrfOptions, csrf } from "./csrf.ts"
+export { type GuardOptions, requireSession, requireUser } from "./guards.ts"
+export {
+  createSessions,
+  type Session,
+  type SessionContext,
+  type SessionCookieOptions,
+  type SessionManager,
+  type SessionOptions,
+} from "./session.ts"
+export {
+  type KVNamespaceLike,
+  KVSessionStore,
+  MemorySessionStore,
+  type MemorySessionStoreOptions,
+  type SessionRecord,
+  type SessionStore,
+} from "./store.ts"

package/src/session.ts

@@ -0,0 +1,256 @@
+/**
+ * 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
+ * anonymous session, never an error.
+ */
+import { type CookieOptions, parseCookies, signValue, unsignValue } from "@nifrajs/core"
+import type { SessionRecord, SessionStore } from "./store.ts"
+
+/** 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>>
+  readonly set: {
+    cookie(name: string, value: string, options?: CookieOptions): void
+    deleteCookie(name: string, options?: { readonly path?: string; readonly domain?: string }): void
+  }
+}
+
+/** 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
+  unset(key: keyof Data): void
+  has(key: keyof Data): boolean
+  /** Wipe all data (the session id is kept). To end the session entirely, call `manager.destroy`. */
+  clear(): void
+  /** A snapshot of the current data. */
+  readonly data: Readonly<Partial<Data>>
+  readonly isEmpty: boolean
+}
+
+/** 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 {
+  /** Signing secret (≥ 16 chars). Rotating it invalidates all existing sessions. */
+  readonly secret: string
+  /** Provide a store for **store mode**; omit for **cookie mode** (stateless). */
+  readonly store?: SessionStore
+  /** Cookie name. Default `nifra_session`. */
+  readonly cookieName?: string
+  /** Session lifetime in **seconds**. Default 7 days. */
+  readonly maxAge?: number
+  /** Slide the expiry forward on every commit (default `true`); `false` = fixed absolute expiry. */
+  readonly rolling?: boolean
+  /** 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). */
+  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
+   * 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
+   * session fixation). Data is preserved; the old store record is dropped. */
+  regenerate(session: Session<Data>): void
+}
+
+const DAY_SECONDS = 86_400
+// 256-bit floor, matching @nifrajs/core's signed-cookie/webhook guard. Sessions sign via core's
+// signValue (which enforces the same bar); this early check gives an auth-specific message before
+// delegating. Measured in UTF-8 bytes, not characters.
+const MIN_SECRET_BYTES = 32
+const SECRET_ENCODER = new TextEncoder()
+
+const encodeBase64Url = (bytes: Uint8Array): string => {
+  let bin = ""
+  for (const b of 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. */
+const randomId = (): string => encodeBase64Url(crypto.getRandomValues(new Uint8Array(32)))
+
+interface Payload {
+  data: Record<string, unknown>
+  expiresAt: number
+}
+
+/** 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 {
+    value = JSON.parse(json)
+  } catch {
+    return null
+  }
+  if (typeof value !== "object" || value === null) return null
+  const obj = value as Record<string, unknown>
+  if (typeof obj.expiresAt !== "number" || !Number.isFinite(obj.expiresAt)) return null
+  if (typeof obj.data !== "object" || obj.data === null) return null
+  return { data: obj.data as Record<string, unknown>, expiresAt: obj.expiresAt }
+}
+
+export function createSessions<Data extends Record<string, unknown> = Record<string, unknown>>(
+  options: SessionOptions,
+): SessionManager<Data> {
+  const { secret, store } = options
+  if (SECRET_ENCODER.encode(secret).length < MIN_SECRET_BYTES) {
+    throw new Error(
+      `[nifra/auth] session secret must be at least ${MIN_SECRET_BYTES} bytes (256-bit). Generate one with: openssl rand -base64 32`,
+    )
+  }
+  const cookieName = options.cookieName ?? "nifra_session"
+  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
+  // type to include the empty-object literal, which the package's build tsconfig rejects on access.
+  const cookieOpts: SessionCookieOptions = options.cookie ?? {}
+
+  interface State {
+    id: string | undefined
+    readonly data: Map<keyof Data, Data[keyof Data]>
+    expiresAt: number | undefined
+    regenerate: boolean
+  }
+  // Per-manager so the WeakMap is typed to this `Data` (no `any`); a session can only be committed by
+  // the manager that created it.
+  const states = new WeakMap<Session<Data>, State>()
+
+  const make = (init: {
+    id?: string
+    data?: Record<string, unknown>
+    expiresAt?: number
+  }): Session<Data> => {
+    const state: State = {
+      id: init.id,
+      // The Map erases per-key value types; the public generic signatures restore them at the edge.
+      data: new Map(Object.entries(init.data ?? {}) as [keyof Data, Data[keyof Data]][]),
+      expiresAt: init.expiresAt,
+      regenerate: false,
+    }
+    const session: Session<Data> = {
+      get: <K extends keyof Data>(key: K) => state.data.get(key) as Data[K] | undefined,
+      set: (key, value) => {
+        state.data.set(key, value)
+      },
+      unset: (key) => {
+        state.data.delete(key)
+      },
+      has: (key) => state.data.has(key),
+      clear: () => {
+        state.data.clear()
+      },
+      get data() {
+        return Object.fromEntries(state.data) as Partial<Data>
+      },
+      get isEmpty() {
+        return state.data.size === 0
+      },
+    }
+    states.set(session, state)
+    return session
+  }
+
+  const stateOf = (session: Session<Data>, op: string): State => {
+    const state = states.get(session)
+    if (state === undefined) {
+      throw new Error(`[nifra/auth] ${op}: session was not created by this manager`)
+    }
+    return state
+  }
+
+  const loadFromRaw = async (raw: string | undefined): Promise<Session<Data>> => {
+    if (raw === undefined || raw === "") return make({})
+    const unsigned = await unsignValue(raw, secret)
+    if (unsigned === null) return make({}) // tampered / wrong secret → fail closed (anonymous)
+
+    if (store !== undefined) {
+      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
+        return make({})
+      }
+      return make({ id: unsigned, data: record.data, expiresAt: record.expiresAt })
+    }
+
+    const payload = parsePayload(unsigned)
+    if (payload === null || payload.expiresAt <= now()) return make({})
+    return make({ data: payload.data, expiresAt: payload.expiresAt })
+  }
+
+  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
+  // 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])
+
+  const writeCookie = (c: SessionContext, value: string, expiresAt: number): void => {
+    const maxAgeSeconds = Math.max(0, Math.floor((expiresAt - now()) / 1000))
+    c.set.cookie(cookieName, value, { ...cookieOpts, maxAge: maxAgeSeconds })
+  }
+
+  const commit = async (c: SessionContext, session: Session<Data>): Promise<void> => {
+    const state = stateOf(session, "commit")
+    // Rolling → slide the expiry; absolute → keep the original (set on the first commit).
+    const expiresAt =
+      rolling || state.expiresAt === undefined ? now() + maxAge * 1000 : state.expiresAt
+    state.expiresAt = expiresAt
+    const data = Object.fromEntries(state.data) as Record<string, unknown>
+
+    if (store !== undefined) {
+      if (state.regenerate) {
+        if (state.id !== undefined) await store.delete(state.id) // drop the pre-rotation session
+        state.id = undefined
+        state.regenerate = false
+      }
+      if (state.id === undefined) state.id = randomId()
+      await store.set(state.id, { data, expiresAt } satisfies SessionRecord)
+      writeCookie(c, await signValue(state.id, secret), expiresAt)
+      return
+    }
+    // Cookie mode: the (signed) payload IS the cookie. serializeCookie enforces the 4 KB cap.
+    writeCookie(
+      c,
+      await signValue(JSON.stringify({ data, expiresAt } satisfies Payload), secret),
+      expiresAt,
+    )
+  }
+
+  const destroy = async (c: SessionContext, session?: Session<Data>): Promise<void> => {
+    if (store !== undefined && session !== undefined) {
+      const state = states.get(session)
+      if (state?.id !== undefined) await store.delete(state.id)
+    }
+    c.set.deleteCookie(cookieName, {
+      path: cookieOpts.path ?? "/",
+      ...(cookieOpts.domain !== undefined ? { domain: cookieOpts.domain } : {}),
+    })
+  }
+
+  const regenerate = (session: Session<Data>): void => {
+    stateOf(session, "regenerate").regenerate = true
+  }
+
+  return { get, read, commit, destroy, regenerate }
+}

package/src/store.ts

@@ -0,0 +1,143 @@
+/**
+ * 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). */
+export interface SessionRecord {
+  readonly data: Record<string, unknown>
+  /** Absolute expiry (ms epoch). The manager treats `expiresAt <= now` as no session. */
+  readonly expiresAt: number
+}
+
+/**
+ * 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}
+ * prod-guards against the per-instance footgun.
+ */
+export interface SessionStore {
+  /** The record for `id`, or `undefined` on a miss. */
+  get(id: string): Promise<SessionRecord | undefined>
+  /** Store (or overwrite) the record for `id`. */
+  set(id: string, record: SessionRecord): Promise<void>
+  /** Drop `id` (logout / regeneration). A no-op if absent. */
+  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
+   * instances and are lost on restart. */
+  readonly allowInProduction?: boolean
+  /** Hard cap on stored sessions; the oldest-inserted is evicted past it (default 10_000). */
+  readonly max?: number
+}
+
+/**
+ * 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).
+ * Bounded: oldest-inserted entries evict past `max`.
+ */
+export class MemorySessionStore implements SessionStore {
+  private readonly sessions = new Map<string, SessionRecord>()
+  private readonly max: number
+
+  constructor(options: MemorySessionStoreOptions = {}) {
+    const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production"
+    if (options.allowInProduction !== true && isProd) {
+      throw new Error(
+        "[nifra/auth] MemorySessionStore is per-instance and unsafe in production (sessions don't hold " +
+          "across instances and are lost on restart). Use a shared store (KVSessionStore, Redis), or " +
+          "pass { allowInProduction: true } for a single-instance deploy.",
+      )
+    }
+    this.max = options.max ?? 10_000
+  }
+
+  get(id: string): Promise<SessionRecord | undefined> {
+    return Promise.resolve(this.sessions.get(id))
+  }
+
+  set(id: string, record: SessionRecord): Promise<void> {
+    this.sessions.delete(id) // re-insert at the tail so Map order tracks recency for the bounded evict
+    this.sessions.set(id, record)
+    while (this.sessions.size > this.max) {
+      const oldest = this.sessions.keys().next().value
+      if (oldest === undefined) break
+      this.sessions.delete(oldest)
+    }
+    return Promise.resolve()
+  }
+
+  delete(id: string): Promise<void> {
+    this.sessions.delete(id)
+    return Promise.resolve()
+  }
+}
+
+/**
+ * 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.
+ */
+export interface KVNamespaceLike {
+  get(key: string): Promise<string | null>
+  /** `expiration` is an absolute unix-seconds timestamp (Cloudflare KV auto-evicts past it). */
+  put(key: string, value: string, options?: { readonly expiration?: number }): Promise<void>
+  delete(key: string): Promise<void>
+}
+
+/** Structural validation of a KV-read value before it's trusted as a {@link SessionRecord}. The store
+ * is a trust boundary (corruption, version skew, tampering), so a malformed entry reads as a miss
+ * (no session) rather than a thrown error or a half-valid record. */
+const isSessionRecord = (value: unknown): value is SessionRecord => {
+  if (typeof value !== "object" || value === null) return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.expiresAt === "number" &&
+    Number.isFinite(v.expiresAt) &&
+    typeof v.data === "object" &&
+    v.data !== null
+  )
+}
+
+/**
+ * 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.
+ * 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).
+ * Every read is validated, so a corrupt/skewed entry reads as no session.
+ */
+export class KVSessionStore implements SessionStore {
+  private readonly kv: KVNamespaceLike
+
+  constructor(kv: KVNamespaceLike) {
+    this.kv = kv
+  }
+
+  async get(id: string): Promise<SessionRecord | undefined> {
+    const raw = await this.kv.get(id)
+    if (raw === null) return undefined
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch {
+      return undefined // corrupt entry → no session (the next set overwrites it)
+    }
+    return isSessionRecord(parsed) ? parsed : undefined
+  }
+
+  async set(id: string, record: SessionRecord): Promise<void> {
+    // Absolute KV expiry (unix seconds) as a GC backstop. Cloudflare requires it be ≥ 60s out; session
+    // `maxAge` is realistically minutes+, so a real deploy satisfies that (the manager enforces the
+    // exact expiry regardless).
+    await this.kv.put(id, JSON.stringify(record), {
+      expiration: Math.floor(record.expiresAt / 1000),
+    })
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.kv.delete(id)
+  }
+}