lambder 6.0.1 → 7.0.1

package/dist/session/LambderSessionCrypto.js

@@ -0,0 +1,101 @@
+/**
+ * The cryptography the session model runs on, behind an interface so the
+ * manager itself has no Node dependency: the bearer secrets are hashed at
+ * rest, compared in constant time, and minted from a cryptographic random
+ * source.
+ *
+ * LambderWebCrypto is the default and runs on Node 20+, every browser on a
+ * secure context, and edge runtimes. LambderPlainSessionCrypto is the
+ * stand-in the mock runtime picks on its own where crypto.subtle is missing
+ * (a plain-http page during device testing on a LAN): its memory store is
+ * not a table anybody can leak, so hashing there protects nothing.
+ */
+import { getCrypto } from "../shared/util/LambderNodeModules.js";
+import { bytesToHexString, resolveWebCrypto, sha256HexOf } from "../shared/util/LambderTextDigest.js";
+/** Length-aware, timing-neutral string comparison: no early exit on the first differing character. */
+const constantTimeEqual = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let difference = 0;
+    for (let i = 0; i < a.length; i += 1)
+        difference |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return difference === 0;
+};
+/** True when this runtime offers WebCrypto's subtle API (secure contexts in browsers; Node 20+). */
+export const isWebCryptoAvailable = () => typeof globalThis.crypto?.subtle?.digest === "function" && typeof globalThis.crypto.getRandomValues === "function";
+/** sha256 through crypto.subtle and randomness through getRandomValues: the default. */
+export class LambderWebCrypto {
+    isCryptographic = true;
+    cryptoPromise;
+    /**
+     * Node's crypto where the runtime has it, kept for timingSafeEqual.
+     * Warmed by ready(), because the comparison itself is synchronous and a
+     * session is always hashed before anything is compared against it.
+     */
+    nodeCrypto = null;
+    /**
+     * The runtime's WebCrypto, through the resolver every layer shares, with
+     * Node's crypto warmed alongside it.
+     *
+     * The availability question is asked here, before the shared resolver,
+     * only because of the answer a session has to it: a runtime with neither
+     * a global crypto nor Node's webcrypto can still run sessions over
+     * LambderPlainSessionCrypto and a memory store, which is this layer's own
+     * way out and not something the shared message can know about.
+     */
+    ready() {
+        this.cryptoPromise ??= (async () => {
+            const nodeCrypto = await getCrypto();
+            this.nodeCrypto = nodeCrypto;
+            const nodeWebCrypto = nodeCrypto?.webcrypto;
+            if (!isWebCryptoAvailable() && !nodeWebCrypto?.subtle) {
+                throw new Error("Lambder sessions need WebCrypto (crypto.subtle). In a browser that means a secure context (https or localhost); pass `crypto: new LambderPlainSessionCrypto()` where none is available and the store holds nothing worth hashing.");
+            }
+            return await resolveWebCrypto();
+        })();
+        return this.cryptoPromise;
+    }
+    async sha256Hex(value) {
+        // ready() first, for the message above and for the warmed Node
+        // crypto; the digest itself is the one every layer shares.
+        await this.ready();
+        return await sha256HexOf(value);
+    }
+    async randomHex(bytes) {
+        const webCrypto = await this.ready();
+        return bytesToHexString(webCrypto.getRandomValues(new Uint8Array(bytes)));
+    }
+    constantTimeEqual(a, b) {
+        // node's timingSafeEqual where the runtime has it: a primitive built
+        // for this beats a JS loop the engine is free to optimize. The loop is
+        // the fallback everywhere else, which is every browser.
+        const nodeCrypto = this.nodeCrypto;
+        if (nodeCrypto && a.length === b.length) {
+            const left = Buffer.from(a, "utf8");
+            const right = Buffer.from(b, "utf8");
+            if (left.length === right.length)
+                return nodeCrypto.timingSafeEqual(left, right);
+        }
+        return constantTimeEqual(a, b);
+    }
+}
+/**
+ * No hashing and no cryptographic randomness: values are hex-encoded as
+ * they are and secrets come from Math.random. Only for an in-memory store
+ * in a runtime without WebCrypto; never for anything at rest.
+ */
+export class LambderPlainSessionCrypto {
+    isCryptographic = false;
+    async sha256Hex(value) {
+        return bytesToHexString(new TextEncoder().encode(value));
+    }
+    async randomHex(bytes) {
+        const random = new Uint8Array(bytes);
+        for (let i = 0; i < bytes; i += 1)
+            random[i] = Math.floor(Math.random() * 256);
+        return bytesToHexString(random);
+    }
+    constantTimeEqual(a, b) {
+        return constantTimeEqual(a, b);
+    }
+}

package/dist/session/LambderSessionManager.d.ts

@@ -1,34 +1,13 @@
-import { type LambderCompressionOption } from "../shared/LambderCompressionOption.js";
-export type LambderSessionContext<SessionData = any> = {
-    [x: string]: any;
-    /**
-     * sha256 of the raw CSRF token. The raw bearer secrets are never stored:
-     * they exist only in the client's cookies (and, at creation, on the
-     * LambderCreatedSession result), so a read of the session table yields
-     * no usable credentials.
-     */
-    csrfTokenHash: string;
-    sessionKey: string;
-    data: SessionData;
-    createdAt: number;
-    expiresAt: number;
-    lastAccessedAt: number;
-    ttlInSeconds: number;
-    /**
-     * When `data` must be renewed via the dataRefresh callback (epoch seconds).
-     * Only present when dataRefresh is configured; independent of the
-     * session's own expiresAt.
-     */
-    dataExpiresAt?: number;
-};
+import type { LambderSessionCrypto } from "./LambderSessionCrypto.js";
+import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
 /**
  * A freshly created (or regenerated) session: the persisted record plus the
  * RAW cookie secrets, which exist only here and in the cookies the caller
  * sets. At rest the record carries hashes of both.
  */
 export type LambderCreatedSession<SessionData = any> = {
-    session: LambderSessionContext<SessionData>;
-    /** Raw bearer token for the session cookie (`pkHash:secret`). */
+    session: LambderSessionRecord<SessionData>;
+    /** Raw bearer token for the session cookie (`sessionKeyHash:secret`). */
     sessionToken: string;
     /** Raw CSRF token for the client-readable csrf cookie. */
     csrfToken: string;
@@ -39,7 +18,7 @@ export type LambderCreatedSession<SessionData = any> = {
  * checks dataExpiresAt and calls `refresh` past it, persisting the result
  * onto the same session record: same tokens, same cookies, the session
  * itself is untouched. The refresh write and the sliding-expiration write
- * share a single DynamoDB put when both are due.
+ * share a single store write when both are due.
  */
 export type LambderSessionDataRefreshConfig<SessionData = any> = {
     /** Seconds session.data stays valid before refresh() runs on read. */
@@ -52,7 +31,7 @@ export type LambderSessionDataRefreshConfig<SessionData = any> = {
      * LambderSessionDataRefreshError and leave the session untouched; catch
      * inside and return session.data to explicitly serve stale instead.
      */
-    refresh: (session: LambderSessionContext<SessionData>) => Promise<SessionData | null>;
+    refresh: (session: LambderSessionRecord<SessionData>) => Promise<SessionData | null>;
 };
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
@@ -64,91 +43,150 @@ export declare class LambderSessionDataRefreshError extends Error {
     constructor(cause: unknown);
 }
 /**
- * Wraps DynamoDB failures during a session read so they stay distinguishable
+ * Wraps store failures during a session read so they stay distinguishable
  * from "no session": fetchSessionIfExists() swallows missing or invalid
- * sessions but rethrows this. Without the distinction a transient DynamoDB
+ * sessions but rethrows this. Without the distinction a transient store
  * error would answer sessionExpired, and the caller would then clear the
  * client's session cookies: an infra blip forcing a real logout.
  */
 export declare class LambderSessionReadError extends Error {
     constructor(cause: unknown);
 }
-export default class LambderSessionManager {
-    private tableName;
-    private sessionSalt;
-    private partitionKey;
-    private sortKey;
-    private tableRegion;
-    /** The document client and the SDK it came from, created the first time the table is touched. */
-    private readyPromise;
-    private enableSlidingExpiration;
-    private slidingWriteIntervalSeconds;
-    private dataRefresh;
-    private compression;
-    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, compression, }: {
-        tableName: string;
-        tableRegion: string;
-        partitionKey: string;
-        sortKey: string;
-        sessionSalt: string;
-        enableSlidingExpiration?: boolean;
-        slidingWriteIntervalSeconds?: number;
-        dataRefresh?: LambderSessionDataRefreshConfig;
-        compression?: LambderCompressionOption;
-    });
-    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
-    private ready;
-    private sessionUserKeyHasher;
+export type LambderSessionManagerOptions<SessionData = any> = {
+    /** Where sessions rest: LambderDdbSessionStore, LambderMemorySessionStore, or your own. */
+    store: LambderSessionStore<SessionData>;
+    /** Salts the sessionKey hash that partitions the store, so a table read does not reveal which subject a session belongs to. */
+    sessionSalt: string;
+    enableSlidingExpiration?: boolean;
+    /** Min seconds between sliding-expiration writes. Default: max(60, 5% of TTL). */
+    slidingWriteIntervalSeconds?: number;
+    dataRefresh?: LambderSessionDataRefreshConfig<SessionData>;
+    /** Hashing and randomness. Default: WebCrypto. */
+    crypto?: LambderSessionCrypto;
+};
+/**
+ * Whether a string has the shape a minted session token has:
+ * `sessionKeyHash:secret`, both hex, neither longer than 1024 characters.
+ *
+ * It lives beside the code that mints and splits that format rather than
+ * beside the cookie reader, so the ceiling is a property of the model and
+ * anyone handing lookupSession a token they did not mint can ask the same
+ * question. The session controller asks it of every candidate cookie before
+ * any store read, so a malformed candidate is "no session" and never a read
+ * error. Nothing a browser legitimately holds fails it, because the only
+ * writer of these cookies is the code that mints them.
+ */
+export declare const isMintedSessionToken: (token: string) => boolean;
+/**
+ * The session model: how a session is minted, what its tokens look like,
+ * how it is found from a presented token, when it expires, when its data is
+ * renewed, and how it is rotated or ended. Storage and cryptography are
+ * injected, so the same class runs on Lambda over DynamoDB, in a test over
+ * a Map, and in a browser under the mock runtime.
+ *
+ * Token format: the session cookie carries `sessionKeyHash:secret`, where
+ * the hash locates the partition and only the secret's hash is stored as
+ * the sort key, so the lookup itself proves possession of the raw secret
+ * and a store read yields no usable token. The CSRF token is a second
+ * random value the client sends back in the request body; its hash is
+ * stored too.
+ */
+export default class LambderSessionManager<SessionData = any> {
+    private readonly store;
+    private readonly sessionSalt;
+    private readonly enableSlidingExpiration;
+    private readonly slidingWriteIntervalSeconds;
+    private readonly dataRefresh;
+    private readonly crypto;
+    constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, crypto, }: LambderSessionManagerOptions<SessionData>);
+    /**
+     * The salted partition hash of a sessionKey: sha256 of the key followed
+     * by the salt, with NO separator between them.
+     *
+     * The missing separator is frozen by the wire guarantee, not chosen
+     * again here: every live session in every deployed table was partitioned
+     * under this exact string, so inserting a separator would relocate every
+     * partition key at once and read to everyone signed in as being logged
+     * out. What it costs is worth naming so nobody reintroduces it by
+     * accident: without a separator the split between key and salt is not
+     * recoverable from the string, so two deployments SHARING one table
+     * collide when the difference between their salts can be absorbed into a
+     * sessionKey ("ab" + "cd" and "a" + "bcd" hash alike). Two deployments
+     * over one table must therefore not stand in a prefix relationship over
+     * their salts. Separate tables, or salts that are independent random
+     * strings, both rule it out.
+     */
+    private sessionKeyHashOf;
     /**
      * At-rest hash for the bearer secrets (session sort-key secret, CSRF
      * token). Fast unsalted sha256 is the right construction here: the
      * inputs are 256-bit random values, so there is nothing to brute-force;
-     * hashing just ensures a leaked table read yields no usable cookies.
+     * hashing just ensures a leaked store read yields no usable cookies.
      */
     private hashToken;
-    private constantTimeCompare;
-    private ddbGetItem;
-    /**
-     * Persists a session record. With compression on, `data` is stored as
-     * Brotli bytes (`dataBr`) beside its JSON byte length (`dataBytes`)
-     * once the JSON reaches minBytes; otherwise it stays a plain attribute.
-     */
-    private ddbPutItem;
-    private ddbDeleteItem;
-    /** Sort keys of every session under a partition (the callers only need the keys). */
-    private ddbQueryAllByPartitionKey;
-    private ddbDeleteAllByPartitionKey;
-    createSession(sessionKey: string, data?: any, ttlInSeconds?: number, options?: {
+    createSession(sessionKey: string, data?: SessionData, ttlInSeconds?: number, options?: {
         /** Carries an existing data freshness stamp over (used by regenerateSession). */
         dataExpiresAt?: number;
-    }): Promise<LambderCreatedSession>;
-    updateSessionData(session: LambderSessionContext, newData?: any): Promise<LambderSessionContext>;
-    getSession(sessionToken: string): Promise<LambderSessionContext | null>;
+    }): Promise<LambderCreatedSession<SessionData>>;
+    updateSessionData(session: LambderSessionRecord<SessionData>, newData: SessionData): Promise<LambderSessionRecord<SessionData>>;
+    /**
+     * The record a token names, read and structurally checked, with nothing
+     * renewed. Split out of getSession so a caller weighing several candidate
+     * cookies can decide which one is this visitor's BEFORE anything is
+     * written on their behalf: renewing slides an expiry and may run the
+     * app's dataRefresh callback, and a cookie a sibling host planted must
+     * not get either from the victim's traffic.
+     */
+    lookupSession(sessionToken: string): Promise<LambderSessionRecord<SessionData> | null>;
+    /**
+     * The renewal half of a session read: the dataRefresh callback once its
+     * shelf life has passed, and the sliding-expiration write. Returns null
+     * when a refresh says the session is over (a deleted or disabled login),
+     * which ends it the same way a missing record does.
+     */
+    renewSession(session: LambderSessionRecord<SessionData>): Promise<LambderSessionRecord<SessionData> | null>;
     /**
      * Runs the dataRefresh callback now, regardless of dataExpiresAt, and
      * persists the result onto the same record. Returns the updated session,
      * or null when the callback ended it (the record is deleted). Requires
      * dataRefresh to be configured.
      */
-    refreshSessionData(session: LambderSessionContext): Promise<LambderSessionContext | null>;
-    isSessionValid(session: any, sessionToken: any, csrfToken: any, skipCsrfTokenCheck?: boolean): boolean;
-    deleteSession(session: Record<string, any>): Promise<boolean>;
-    deleteSessionAll(session: Record<string, any>): Promise<boolean>;
+    refreshSessionData(session: LambderSessionRecord<SessionData>): Promise<LambderSessionRecord<SessionData> | null>;
+    /**
+     * Checks a record against the session token presented with it: the
+     * partition hash and the bearer secret the cookie carries, plus the
+     * structural checks and the expiry. This is the half a route needs, and
+     * the half lookupSession has already proved for a record it just found by
+     * that token's own hash, so the read path does not ask it again.
+     */
+    isSessionTokenValid(session: LambderSessionRecord<SessionData> | null, sessionToken: string | null): Promise<boolean>;
+    /**
+     * Checks a record against the CSRF token the request posted: the other
+     * half, asked of an API call and not of a route. Separate methods rather
+     * than one with a skip flag, because a boolean at the call site says
+     * nothing about which half it turns off, and the two are asked in
+     * different places for different reasons.
+     */
+    isSessionCsrfTokenValid(session: LambderSessionRecord<SessionData> | null, csrfToken: string | null): Promise<boolean>;
+    deleteSession(session: LambderSessionRecord<SessionData>): Promise<boolean>;
+    /** Deletes every session that shares the record's subject: "log this subject out everywhere". */
+    deleteSessionAll(session: LambderSessionRecord<SessionData>): Promise<boolean>;
     /**
      * Deletes every session created for the given sessionKey (e.g. a user
      * id): "log this subject out everywhere", without needing a fetched
      * session record.
      */
     deleteSessionAllByKey(sessionKey: string): Promise<boolean>;
+    private deleteAllUnder;
     /**
      * Marks the data of every session of the given sessionKey stale, so each
      * renews via dataRefresh on its next read: "this subject's roles or
      * permissions changed, apply it now", without logging the subject out
      * (deleteSessionAllByKey) and without waiting for the data TTL. Stamps
-     * dataExpiresAt only, conditionally on the record still existing, so it
-     * neither resurrects a session deleted in between nor overwrites a
-     * concurrent write. Requires dataRefresh to be configured.
+     * dataExpiresAt only, on records that still exist, so it neither
+     * resurrects a session deleted in between nor overwrites a concurrent
+     * write. Requires dataRefresh to be configured.
      */
     expireSessionDataAllByKey(sessionKey: string): Promise<boolean>;
-    regenerateSession(session: LambderSessionContext): Promise<LambderCreatedSession>;
+    regenerateSession(session: LambderSessionRecord<SessionData>): Promise<LambderCreatedSession<SessionData>>;
 }