lambder 7.3.1 → 8.0.2

package/dist/session/LambderSessionCrypto.js

@@ -2,7 +2,7 @@
  * 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.
+ * source, and the sessionKey is hashed under the salt as its key.
  *
  * LambderWebCrypto is the default and runs on Node 20+, every browser on a
  * secure context, and edge runtimes. LambderPlainSessionCrypto is the
@@ -23,7 +23,7 @@ const constantTimeEqual = (a, b) => {
 };
 /** 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. */
+/** sha256 and HMAC through crypto.subtle and randomness through getRandomValues: the default. */
 export class LambderWebCrypto {
     isCryptographic = true;
     cryptoPromise;
@@ -37,11 +37,11 @@ export class LambderWebCrypto {
      * 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.
+     * Availability is checked here, before the shared resolver, so the error
+     * can name this layer's own way out: a runtime with neither a global
+     * crypto nor Node's webcrypto can still run sessions over
+     * LambderPlainSessionCrypto and a memory store, which the shared
+     * resolver's message cannot know about.
      */
     ready() {
         this.cryptoPromise ??= (async () => {
@@ -56,19 +56,25 @@ export class LambderWebCrypto {
         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.
+        // ready() first, for its error message and the warmed Node crypto;
+        // the digest itself is the one every layer shares.
         await this.ready();
         return await sha256HexOf(value);
     }
+    async hmacSha256Hex(key, value) {
+        const webCrypto = await this.ready();
+        const encoder = new TextEncoder();
+        const hmacKey = await webCrypto.subtle.importKey("raw", encoder.encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        return bytesToHexString(new Uint8Array(await webCrypto.subtle.sign("HMAC", hmacKey, encoder.encode(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.
+        // Node's timingSafeEqual where the runtime has it: a primitive built
+        // for this beats a JS loop the engine is free to optimize. Browsers
+        // fall back to the loop.
         const nodeCrypto = this.nodeCrypto;
         if (nodeCrypto && a.length === b.length) {
             const left = Buffer.from(a, "utf8");
@@ -89,6 +95,14 @@ export class LambderPlainSessionCrypto {
     async sha256Hex(value) {
         return bytesToHexString(new TextEncoder().encode(value));
     }
+    /**
+     * The key and the value hex-encoded as a JSON pair rather than run
+     * together, so the pair stays unambiguous the way a keyed hash keeps it:
+     * no key and value can pass for another split of the same text.
+     */
+    async hmacSha256Hex(key, value) {
+        return bytesToHexString(new TextEncoder().encode(JSON.stringify([key, value])));
+    }
     async randomHex(bytes) {
         const random = new Uint8Array(bytes);
         for (let i = 0; i < bytes; i += 1)

package/dist/session/LambderSessionManager.d.ts

@@ -20,13 +20,20 @@ export type LambderCreatedSession<SessionData = any> = {
  * 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 store write when both are due.
+ *
+ * A refresh result is written only over the data it was computed from: if
+ * the record's dataVersion moved in between (another request refreshed or
+ * wrote the data, or expireSessionDataAllByKey marked it stale), the result
+ * still serves this request but the newer write stands, and a marked record
+ * renews again on its next read.
  */
 export type LambderSessionDataRefreshConfig<SessionData = any> = {
     /** Seconds session.data stays valid before refresh() runs on read. */
     ttlSeconds: number;
     /**
      * Rebuild session.data from its source of truth. Must be a pure
-     * derivation (concurrent reads may run it in parallel; last write wins).
+     * derivation (concurrent reads may run it in parallel; the first result
+     * written stands, since each is written only over the data it read).
      * Return null to end the session: the record is deleted and the read
      * reports no session. Thrown errors fail the read as a
      * LambderSessionDataRefreshError and leave the session untouched; catch
@@ -56,7 +63,7 @@ export declare class LambderSessionReadError extends Error {
 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. */
+    /** The HMAC key that turns a sessionKey into the store's partition key, 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). */
@@ -69,13 +76,12 @@ export type LambderSessionManagerOptions<SessionData = any> = {
  * 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.
+ * It lives beside the code that mints and splits the format, not the cookie
+ * reader, so the ceiling belongs to the model and anyone handing
+ * lookupSession a token they did not mint can ask it too. The session
+ * controller checks every candidate cookie with it before any store read, so
+ * a malformed one is "no session", never a read error. No legitimate cookie
+ * fails it, since only the minting code writes them.
  */
 export declare const isMintedSessionToken: (token: string) => boolean;
 /**
@@ -111,21 +117,16 @@ export default class LambderSessionManager<SessionData = any> {
      */
     [LAMBDER_BACKEND_SWAP](store: LambderSessionStore<SessionData>): void;
     /**
-     * The salted partition hash of a sessionKey: sha256 of the key followed
-     * by the salt, with NO separator between them.
+     * The salted partition hash of a sessionKey: HMAC-SHA256 with the salt
+     * as the key and the sessionKey as the message.
      *
-     * 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.
+     * Keyed rather than hashed over the two run together, because a plain
+     * concatenation cannot tell where the sessionKey ends and the salt
+     * begins: "ab" + "cd" and "a" + "bcd" would hash alike, so two
+     * deployments sharing one table could collide whenever the difference
+     * between their salts fits into a sessionKey. With the salt as the HMAC
+     * key the two inputs never meet in one string, so no choice of salts
+     * lets one deployment's subject land in another's partition.
      */
     private sessionKeyHashOf;
     /**
@@ -136,68 +137,145 @@ export default class LambderSessionManager<SessionData = any> {
      */
     private hashToken;
     createSession(sessionKey: string, data?: SessionData, ttlInSeconds?: number, options?: {
-        /** Carries an existing data freshness stamp over (used by regenerateSession). */
+        /** The data refresh deadline to start with (regenerateSession starts its data due). */
         dataExpiresAt?: number;
     }): Promise<LambderCreatedSession<SessionData>>;
-    updateSessionData(session: LambderSessionRecord<SessionData>, newData: SessionData): Promise<LambderSessionRecord<SessionData>>;
+    /**
+     * Writes new session data onto the record, and nothing else: the expiry
+     * slides only in renewSession, which also re-issues the cookies, so a
+     * data write never moves the record's expiry away from the browser's.
+     * Returns the updated record, or null when the session was ended in
+     * between (the write does not bring it back).
+     *
+     * With dataRefresh, the write leaves dataExpiresAt where it is: only the
+     * dataRefresh callback's output is stamped fresh. The data an app writes
+     * is almost always the session's own with a field changed, still carrying
+     * whatever the callback derived last, so a write that pushed the deadline
+     * would let an app writing more often than ttlSeconds never refresh at
+     * all, and would cancel the due start regenerateSession gives a rotated
+     * session. The write is still conditioned on the dataVersion this record
+     * was read with. If that moved in between (expireSessionDataAllByKey
+     * marked the data stale, or another request refreshed it, possibly
+     * applying a revocation already), the data is written and marked due, so
+     * a revocation that landed during this request is not undone by data
+     * derived before it.
+     *
+     * The returned record carries the dataVersion this write produced only
+     * when a conditioned write applied, which is then exactly one past the
+     * version it named. Otherwise it keeps the version it was read with,
+     * which the store has already passed, so a later conditioned write from
+     * the same request answers "stale" and lands marked due: the safe side.
+     */
+    updateSessionData(session: LambderSessionRecord<SessionData>, newData: SessionData): Promise<LambderSessionRecord<SessionData> | null>;
     /**
      * 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
+     * renewed. Kept apart from renewSession so a caller weighing several
+     * candidate cookies can decide which 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.
+     * get neither 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.
+     * when the session is over: a refresh said so (a deleted or disabled
+     * login), or the record was deleted while this request read it (a
+     * logout, a password change), which a renewal must not undo.
      */
     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.
+     * Runs the dataRefresh callback immediately, regardless of
+     * dataExpiresAt, and persists the result onto the same record, over the
+     * data it was computed from only (see LambderSessionDataRefreshConfig).
+     * Returns the refreshed session, or null when the callback ended it (the
+     * record is deleted) or the session is gone. The expiry does not slide
+     * here; renewSession slides it. Requires dataRefresh to be configured.
      */
     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.
+     * structural checks and the expiry. This is the half a route needs; a
+     * record lookupSession just found by that token's own hash has already
+     * passed it, so the read path does not ask 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.
+     * than one with a skip flag, because a boolean at the call site does not
+     * say which half it turns off.
      */
     isSessionCsrfTokenValid(session: LambderSessionRecord<SessionData> | null, csrfToken: string | null): Promise<boolean>;
+    /** Deletes the session; false when there was none left to delete. */
     deleteSession(session: LambderSessionRecord<SessionData>): Promise<boolean>;
-    /** Deletes every session that shares the record's subject: "log this subject out everywhere". */
+    /**
+     * Deletes every session that shares the record's subject: "log this
+     * subject out everywhere". False when a rotation racing it may have left
+     * a session behind (see deleteAllUnder).
+     */
     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.
+     * session record. False when a rotation racing it may have left a
+     * session behind (see deleteAllUnder).
      */
     deleteSessionAllByKey(sessionKey: string): Promise<boolean>;
+    /**
+     * Deletes every session of a subject, and answers whether it is sure
+     * none is left. A pass that finds a record it listed already gone lists
+     * again: a rotation writes its new record before deleting the old one
+     * (see regenerateSession), so the old one vanishing between this listing
+     * and this delete means a new record may have appeared after the
+     * listing. When the last pass the bound allows still finds one gone,
+     * such a record may be standing, so the call is logged and answers
+     * false: a caller ending a subject's sessions after a password change
+     * can run it again.
+     */
     private deleteAllUnder;
+    /**
+     * One write per session of a subject, a bounded number at a time: a
+     * subject with hundreds of sessions is not hundreds of round trips in a
+     * row, and not hundreds at once either.
+     */
+    private forEachSessionOf;
     /**
      * 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
+     * permissions changed, apply that right away", without logging them out
+     * (deleteSessionAllByKey) and without waiting for the data TTL. Writes
      * 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.
+     * write. The write moves each record's dataVersion, even when the
+     * deadline already reads this second, so a refresh or data write in
+     * flight, conditioned on the version it read, answers "stale" rather
+     * than landing data derived before the change. Requires dataRefresh to
+     * be configured.
      */
     expireSessionDataAllByKey(sessionKey: string): Promise<boolean>;
-    regenerateSession(session: LambderSessionRecord<SessionData>): Promise<LambderCreatedSession<SessionData>>;
+    /**
+     * Replaces the session with a new one under new tokens, carrying over
+     * the data as the delete removed it rather than as this request read
+     * it, so data another request wrote meanwhile stays. Returns null, and
+     * leaves no new session behind, when the record was already gone or
+     * over: a logout, "log out everywhere" or a password change that landed
+     * during this request stays in force.
+     *
+     * The new record is written before the old one is deleted. The other
+     * way round, a subject-wide delete that listed the subject's sessions
+     * between the two would find neither, and the new session would outlive
+     * the password change it was racing. Written first, the new record is in
+     * that listing, or the old one still is: then either the subject-wide
+     * delete removes the old one before this delete does, and this delete
+     * takes the new one back out, or this delete removes it first, and the
+     * subject-wide delete, finding it gone, lists again (deleteAllUnder).
+     *
+     * With dataRefresh, the new session's data is due at once: a revocation
+     * marked by expireSessionDataAllByKey while the new record was being
+     * written may have passed it by, and due, its next read renews the data
+     * from the source of truth either way.
+     */
+    regenerateSession(session: LambderSessionRecord<SessionData>): Promise<LambderCreatedSession<SessionData> | null>;
 }