@spine-event-engine/auth 2.0.0-snapshot.25 → 2.0.0-snapshot.28

package/dist/sessions/opaque.js

@@ -11,311 +11,580 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { Time } from "@spine-event-engine/core/time";
 import { create } from "@bufbuild/protobuf";
 import { TimestampSchema } from "@bufbuild/protobuf/wkt";
 import { randomBytes as nodeRandomBytes } from "node:crypto";
+import { sealData, unsealData } from "iron-session";
+import { OpaqueSessionRecordSchema, } from "@spine-event-engine/proto/auth";
+import { MemoryOpaqueSessionStore } from "./opaque-session-store.js";
+import { SessionRecords } from "./session-record.js";
+import { SessionLifetimes } from "./session-lifetime.js";
 /**
- * A bounded, terminal in-memory store of random opaque application sessions.
- *
- * It is intentionally process-local: applications needing durable or shared
- * sessions provide another `SessionResolver` implementation.
+ * Sealed opaque credentials backed by atomic stable-reference transitions.
  */
 export class OpaqueSessions {
-    records = new Map();
-    clock;
-    random;
-    ttlMilliseconds;
-    maxSessions;
-    collisionAttempts;
-    closed = false;
+    #store;
+    #internalStore;
+    #scope;
+    #password;
+    #clock;
+    #ttlMilliseconds;
+    #sealTtl;
+    #random;
+    #collisionAttempts;
+    #lifetimes = new SessionLifetimes(() => this.#now());
+    #closed = false;
+    #active = 0;
+    #drained;
+    #closing;
     /**
-     * Creates a bounded in-memory session store.
-     * @param options The optional clock, entropy, lifetime, and capacity settings.
+     * Binds already validated policy and an authoritative store.
+     *
+     * @param options Validated session policy.
+     * @param store Selected atomic store.
+     * @param internalStore Process-local store created by this strategy, if any.
      */
-    constructor(options = {}) {
-        this.clock = options.clock ?? { now: () => Time.currentTimeMillis() };
-        this.random = options.randomBytes ?? nodeRandomBytes;
-        this.ttlMilliseconds = OpaqueSessionValues.positiveSafeInteger(options.ttlMilliseconds ?? 8 * 60 * 60 * 1_000, "ttlMilliseconds");
-        this.maxSessions = OpaqueSessionValues.positiveSafeInteger(options.maxSessions ?? 10_000, "maxSessions");
-        this.collisionAttempts = OpaqueSessionValues.positiveSafeInteger(options.collisionAttempts ?? 3, "collisionAttempts");
+    constructor(options, store, internalStore) {
+        this.#store = store;
+        this.#internalStore = internalStore;
+        this.#scope = options.scope;
+        this.#password = SessionPolicy.password(options.password);
+        this.#clock = options.clock;
+        this.#ttlMilliseconds = options.ttlMilliseconds;
+        this.#sealTtl = Math.ceil(options.ttlMilliseconds / 1_000);
+        this.#random = options.randomBytes ?? nodeRandomBytes;
+        this.#collisionAttempts = options.collisionAttempts ?? 3;
     }
     /**
-     * Creates a new session unless the terminal or bounded store state rejects it.
-     * @param principal The authenticated principal to retain.
-     * @returns The creation outcome and, when accepted, credential and session.
+     * Validates sealing and lifetime policy before exposing a usable strategy.
+     *
+     * @param options Required application policy and optional store.
+     * @returns Initialized opaque-session strategy.
      */
-    create(principal) {
-        if (this.isClosed())
-            return Promise.resolve({ kind: "rejected", reason: "closed" });
-        const now = this.now();
-        if (now === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "clock-failure" });
-        this.sweepExpired(now);
-        if (this.records.size >= this.maxSessions)
-            return Promise.resolve({ kind: "rejected", reason: "capacity-exceeded" });
-        const id = this.nextId();
-        if (id === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "entropy-exhausted" });
-        const current = this.now();
-        if (current === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "clock-failure" });
-        this.sweepExpired(current);
-        if (this.isClosed())
-            return Promise.resolve({ kind: "rejected", reason: "closed" });
-        if (this.records.size >= this.maxSessions) {
-            return Promise.resolve({ kind: "rejected", reason: "capacity-exceeded" });
-        }
-        if (this.records.has(id))
-            return Promise.resolve({ kind: "rejected", reason: "entropy-exhausted" });
-        const record = this.record(principal, current);
-        if (record === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "clock-failure" });
-        if (this.isClosed())
-            return Promise.resolve({ kind: "rejected", reason: "closed" });
-        this.records.set(id, record);
-        return Promise.resolve({
-            kind: "created",
-            credential: OpaqueSessionValues.credential(id),
-            session: OpaqueSessionValues.resolved(record),
+    static create(options) {
+        return Promise.resolve().then(() => {
+            if (typeof options.scope !== "string" || options.scope.length === 0)
+                throw new TypeError("Opaque session scope must be nonempty.");
+            SessionPolicy.password(options.password);
+            SessionPolicy.positive(options.ttlMilliseconds, "ttlMilliseconds");
+            SessionPolicy.positive(options.collisionAttempts ?? 3, "collisionAttempts");
+            SessionPolicy.positive(options.maxSessions ?? 10_000, "maxSessions");
+            if (options.store !== undefined && options.maxSessions !== undefined)
+                throw new TypeError("maxSessions applies only when the memory store is selected.");
+            const clock = options.clock;
+            if (typeof clock !== "object" ||
+                clock === null ||
+                typeof Reflect.get(clock, "now") !== "function")
+                throw new TypeError("Session clock is required.");
+            if (options.store !== undefined)
+                return new OpaqueSessions(options, options.store);
+            const memory = new MemoryOpaqueSessionStore(() => SessionPolicy.timestamp(options.clock.now()), options.maxSessions ?? 10_000);
+            return new OpaqueSessions(options, memory, memory);
         });
     }
     /**
-     * Resolves one currently live cookie credential as a defensive copy.
-     * @param credentialInput The credential to resolve.
-     * @returns The live session, or undefined when it is invalid or expired.
+     * Creates one sealed credential after an atomic absent insertion.
+     *
+     * @param principal Complete authenticated identity.
+     * @param signal Optional cancellation.
+     * @returns Issuance result; cancellation never returns a credential.
      */
-    resolve(credentialInput) {
-        if (this.closed || credentialInput.kind !== "cookie")
-            return Promise.resolve(undefined);
-        const now = this.now();
-        if (now === undefined)
+    issue(principal, signal) {
+        if (this.#closed)
+            return Promise.resolve({ kind: "rejected", reason: "closed" });
+        return this.#run(() => this.#issue(principal, signal));
+    }
+    /**
+     * Resolves only the current generation before its exact deadline.
+     *
+     * @param credentialInput Cookie credential to validate.
+     * @param signal Optional cancellation.
+     * @returns Detached session, or undefined for invalid or expired credentials.
+     */
+    resolve(credentialInput, signal) {
+        if (this.#closed || credentialInput.kind !== "cookie")
             return Promise.resolve(undefined);
-        const record = this.live(credentialInput.value, now);
-        return Promise.resolve(record === undefined ? undefined : OpaqueSessionValues.resolved(record));
+        return this.#run(async () => {
+            signal?.throwIfAborted();
+            const seal = await this.#unseal(credentialInput.value);
+            signal?.throwIfAborted();
+            if (this.#closed)
+                return undefined;
+            if (seal === undefined || this.#expired(seal.expires))
+                return undefined;
+            const monitor = signal === undefined ? undefined : this.#lifetimes.register(seal.id, signal);
+            let retained = false;
+            try {
+                const record = await this.#store.read(seal.id, signal);
+                signal?.throwIfAborted();
+                if (this.#isClosed() || monitor?.signal.aborted)
+                    return undefined;
+                if (record === undefined ||
+                    !this.#matches(record, seal) ||
+                    this.#expired(SessionRecords.expiry(record)))
+                    return undefined;
+                const resolved = this.#resolved(record);
+                if (monitor === undefined)
+                    return resolved;
+                if (!monitor.ready(resolved.expiresAt))
+                    return undefined;
+                retained = true;
+                return { ...resolved, invalidated: monitor.signal };
+            }
+            finally {
+                if (!retained)
+                    monitor?.release();
+            }
+        });
     }
     /**
-     * Updates a live opaque credential without ever retaining both values.
-     * @param credentialInput The credential to replace.
-     * @returns The rotation outcome and, when accepted, the replacement values.
+     * Creates a new generation before atomically replacing the current record.
+     *
+     * @param credentialInput Current cookie credential.
+     * @param signal Optional cancellation.
+     * @returns One winning replacement or a rejection.
      */
-    rotate(credentialInput) {
-        if (this.isClosed())
+    rotate(credentialInput, signal) {
+        if (this.#closed)
             return Promise.resolve({ kind: "rejected", reason: "closed" });
         if (credentialInput.kind !== "cookie")
             return Promise.resolve({ kind: "rejected", reason: "unsupported-credential" });
-        const now = this.now();
-        if (now === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "clock-failure" });
-        const previous = this.records.get(credentialInput.value);
-        if (previous === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "not-found" });
-        if (this.expired(previous, now)) {
-            this.records.delete(credentialInput.value);
-            return Promise.resolve({ kind: "rejected", reason: "expired" });
-        }
-        const id = this.nextId();
-        if (id === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "entropy-exhausted" });
-        const current = this.now();
-        if (current === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "clock-failure" });
-        if (this.isClosed())
-            return Promise.resolve({ kind: "rejected", reason: "closed" });
-        if (this.records.get(credentialInput.value) !== previous) {
-            return Promise.resolve({ kind: "rejected", reason: "not-found" });
-        }
-        if (this.expired(previous, current)) {
-            this.records.delete(credentialInput.value);
-            return Promise.resolve({ kind: "rejected", reason: "expired" });
-        }
-        if (this.records.has(id))
-            return Promise.resolve({ kind: "rejected", reason: "entropy-exhausted" });
-        const record = this.record(previous.principal, current);
-        if (record === undefined)
-            return Promise.resolve({ kind: "rejected", reason: "clock-failure" });
-        this.records.delete(credentialInput.value);
-        this.records.set(id, record);
-        return Promise.resolve({
-            kind: "rotated",
-            credential: OpaqueSessionValues.credential(id),
-            session: OpaqueSessionValues.resolved(record),
+        return this.#run(() => this.#rotate(credentialInput.value, signal));
+    }
+    /**
+     * Removes the stable reference when the supplied seal is still live.
+     *
+     * @param credentialInput Cookie credential to revoke.
+     * @param signal Optional cancellation.
+     * @returns Enumeration-safe acknowledgement.
+     */
+    logout(credentialInput, signal) {
+        if (this.#closed || credentialInput.kind !== "cookie")
+            return Promise.resolve({ kind: "logged-out" });
+        return this.#run(async () => {
+            signal?.throwIfAborted();
+            const seal = await this.#unseal(credentialInput.value);
+            signal?.throwIfAborted();
+            if (seal !== undefined && !this.#expired(seal.expires)) {
+                try {
+                    await this.#store.revoke(seal.id, signal);
+                    signal?.throwIfAborted();
+                }
+                finally {
+                    this.#lifetimes.invalidate(seal.id);
+                }
+            }
+            return { kind: "logged-out" };
         });
     }
     /**
-     * Deletes a cookie session when present without revealing whether it existed.
-     * @param credentialInput The credential to invalidate.
-     * @returns An enumeration-safe logout acknowledgement.
+     * Removes records at or before a trusted maintenance cutoff.
+     *
+     * @param cutoff Current-or-earlier exact deadline.
+     * @param signal Optional maintenance cancellation.
+     * @returns Number of conditionally removed records.
      */
-    logout(credentialInput) {
-        if (!this.closed && credentialInput.kind === "cookie")
-            this.records.delete(credentialInput.value);
-        return Promise.resolve({ kind: "logged-out" });
+    purgeExpired(cutoff, signal) {
+        if (this.#closed)
+            return Promise.reject(new Error("Session strategy is closed."));
+        return this.#run(() => this.#store.purgeExpired(cutoff, signal));
     }
     /**
-     * Closes the store and drops retained session identity and record references.
-     * @returns Completes after retained records are dropped.
+     * Closes new work and drains admitted work and compensation.
+     *
+     * @returns Repeatable close completion; injected stores remain open.
      */
     close() {
-        if (this.closed)
-            return Promise.resolve();
-        this.closed = true;
-        this.records.clear();
-        return Promise.resolve();
+        if (this.#closing !== undefined)
+            return this.#closing;
+        this.#closed = true;
+        this.#lifetimes.close();
+        this.#closing = this.#finishClose();
+        return this.#closing;
     }
     /**
-     * Checks whether the session store has been closed.
-     * @returns Whether further session operations must be rejected.
+     * Waits for admitted work and closes only internally created memory.
+     *
+     * @returns Completion after local resources are released.
      */
-    isClosed() {
-        return this.closed;
+    async #finishClose() {
+        if (this.#active > 0)
+            await new Promise((resolve) => (this.#drained = resolve));
+        await this.#internalStore?.close();
     }
     /**
-     * Creates a bounded session record for an authenticated principal.
-     * @param principal The identity to store in the session.
-     * @param now The validated issuance time in milliseconds.
-     * @returns The record, or undefined if expiry cannot be represented.
+     * Keeps asynchronous work admitted through all awaited transitions.
+     *
+     * @typeParam T Result produced by the admitted operation.
+     * @param work Operation body.
+     * @returns Operation outcome.
      */
-    record(principal, now) {
-        const expiresAt = now + this.ttlMilliseconds;
-        if (!Number.isSafeInteger(expiresAt) || !OpaqueSessionValues.timestampValid(expiresAt)) {
-            this.failClosed();
-            return undefined;
+    async #run(work) {
+        this.#active += 1;
+        try {
+            return await work();
+        }
+        finally {
+            this.#active -= 1;
+            if (this.#active === 0)
+                this.#drained?.();
         }
-        return { principal: OpaqueSessionValues.copyPrincipal(principal), expiresAt };
     }
     /**
-     * Creates an unused opaque credential identifier within the retry limit.
-     * @returns The identifier, or undefined after entropy failures or collisions.
+     * Tries random stable references until an absent insert wins.
+     *
+     * @param principal Complete identity.
+     * @param signal Optional cancellation.
+     * @returns Issuance outcome.
      */
-    nextId() {
-        for (let attempt = 0; attempt < this.collisionAttempts; attempt += 1) {
-            let bytes;
+    async #issue(principal, signal) {
+        for (let attempt = 0; attempt < this.#collisionAttempts; attempt += 1) {
+            signal?.throwIfAborted();
+            if (this.#internalStore?.atCapacity())
+                return { kind: "rejected", reason: "capacity-exceeded" };
+            const candidate = this.#newRecord(principal);
+            if (typeof candidate === "string")
+                return { kind: "rejected", reason: candidate };
+            const seal = await this.#seal(candidate);
+            signal?.throwIfAborted();
+            if (this.#closed)
+                throw new Error("Session strategy closed.");
+            let inserted = false;
             try {
-                bytes = this.random(32);
-            }
-            catch {
-                continue;
+                inserted = await this.#store.insert(candidate);
+                if (signal?.aborted || this.#isClosed())
+                    throw signal?.reason ?? new Error("Session strategy closed.");
             }
-            try {
-                if (bytes.byteLength !== 32)
-                    continue;
-                const id = Buffer.from(bytes).toString("base64url");
-                if (!this.records.has(id))
-                    return id;
-            }
-            finally {
-                bytes.fill(0);
+            catch (error) {
+                if (inserted && (signal?.aborted || this.#isClosed()))
+                    await this.#compensate(candidate, error);
+                throw error;
             }
+            if (inserted)
+                return {
+                    kind: "created",
+                    credential: SessionPolicy.credential(seal),
+                    session: this.#resolved(candidate),
+                };
         }
-        return undefined;
+        return {
+            kind: "rejected",
+            reason: this.#internalStore?.atCapacity() ? "capacity-exceeded" : "entropy-exhausted",
+        };
+    }
+    /**
+     * Creates one complete candidate from trusted time and cryptographic bytes.
+     *
+     * @param principal Complete authenticated identity.
+     * @returns Candidate record or a policy failure reason.
+     */
+    #newRecord(principal) {
+        const now = this.#now();
+        if (now === undefined)
+            return "clock-failure";
+        const expires = this.#deadline(now);
+        if (expires === undefined)
+            return "clock-failure";
+        const id = this.#randomValue();
+        const generation = this.#randomValue();
+        if (id === undefined || generation === undefined)
+            return "entropy-exhausted";
+        return create(OpaqueSessionRecordSchema, {
+            id,
+            generation,
+            principal: SessionRecords.principal(principal),
+            whenExpires: expires,
+        });
     }
     /**
-     * Returns a live session record and removes it when expired.
-     * @param id The opaque credential identifier.
-     * @param now The validated lookup time in milliseconds.
-     * @returns The live record, or undefined if absent or expired.
+     * Removes only a newly issued expected record after late cancellation.
+     *
+     * @param record Candidate inserted session.
+     * @param cause Cancellation or close failure.
      */
-    live(id, now) {
-        const record = this.records.get(id);
-        if (record === undefined)
+    async #compensate(record, cause) {
+        try {
+            await this.#store.remove(record);
+        }
+        catch (error) {
+            throw new AggregateError([cause, error], "Session issuance compensation failed.");
+        }
+    }
+    /**
+     * Validates a current generation then performs one conditional replacement.
+     *
+     * @param credential Sealed cookie value.
+     * @param signal Optional cancellation.
+     * @returns Rotation outcome.
+     */
+    async #rotate(credential, signal) {
+        signal?.throwIfAborted();
+        const seal = await this.#unseal(credential);
+        signal?.throwIfAborted();
+        if (this.#closed)
+            return { kind: "rejected", reason: "closed" };
+        if (seal === undefined)
+            return { kind: "rejected", reason: "not-found" };
+        if (this.#expired(seal.expires))
+            return { kind: "rejected", reason: "expired" };
+        const previous = await this.#store.read(seal.id, signal);
+        signal?.throwIfAborted();
+        if (this.#isClosed())
+            return { kind: "rejected", reason: "closed" };
+        if (previous === undefined || !this.#matches(previous, seal))
+            return { kind: "rejected", reason: "not-found" };
+        if (this.#expired(SessionRecords.expiry(previous)))
+            return { kind: "rejected", reason: "expired" };
+        return this.#replace(previous, signal);
+    }
+    /**
+     * Creates a new generation before the authoritative conditional update.
+     *
+     * @param previous Complete expected record.
+     * @param signal Optional cancellation.
+     * @returns Rotation outcome.
+     */
+    async #replace(previous, signal) {
+        const candidate = this.#replacement(previous);
+        if (typeof candidate === "string")
+            return { kind: "rejected", reason: candidate };
+        const next = candidate;
+        const seal = await this.#seal(next);
+        signal?.throwIfAborted();
+        if (this.#closed)
+            return { kind: "rejected", reason: "closed" };
+        let replaced = false;
+        try {
+            replaced = await this.#store.replace(previous, next);
+            if (signal?.aborted || this.#isClosed())
+                throw signal?.reason ?? new Error("Session strategy closed.");
+        }
+        catch (error) {
+            if (replaced && (signal?.aborted || this.#isClosed()))
+                await this.#compensate(next, error);
+            throw error;
+        }
+        return replaced
+            ? {
+                kind: "rotated",
+                credential: SessionPolicy.credential(seal),
+                session: this.#resolved(next),
+            }
+            : { kind: "rejected", reason: "not-found" };
+    }
+    /**
+     * Creates a distinct generation with its exact replacement deadline.
+     *
+     * @param previous Current complete record.
+     * @returns Replacement record or a policy failure reason.
+     */
+    #replacement(previous) {
+        const now = this.#now();
+        if (now === undefined)
+            return "clock-failure";
+        const expires = this.#deadline(now);
+        if (expires === undefined)
+            return "clock-failure";
+        const generation = this.#randomValue();
+        if (generation === undefined || generation === previous.generation)
+            return "entropy-exhausted";
+        return create(OpaqueSessionRecordSchema, { ...previous, generation, whenExpires: expires });
+    }
+    /**
+     * Creates JSON-safe authenticated reference, generation, scope and deadline.
+     *
+     * @param record Complete record to bind.
+     * @returns Iron-session seal.
+     */
+    #seal(record) {
+        const expiry = SessionRecords.expiry(record);
+        return sealData({
+            id: record.id,
+            generation: record.generation,
+            scope: this.#scope,
+            seconds: expiry.seconds.toString(),
+            nanos: expiry.nanos,
+        }, { password: this.#password, ttl: this.#sealTtl });
+    }
+    /**
+     * Unseals and validates a scoped JSON-safe payload.
+     *
+     * @param credential Candidate cookie value.
+     * @returns Authenticated payload, if valid.
+     */
+    async #unseal(credential) {
+        const value = await unsealData(credential, {
+            password: this.#password,
+            ttl: this.#sealTtl,
+        });
+        if (typeof value !== "object" || value === null)
             return undefined;
-        if (!this.expired(record, now))
-            return record;
-        this.records.delete(id);
-        return undefined;
+        const fields = value;
+        if (fields.scope !== this.#scope ||
+            typeof fields.id !== "string" ||
+            typeof fields.generation !== "string" ||
+            typeof fields.seconds !== "string" ||
+            typeof fields.nanos !== "number" ||
+            !/^-?\d+$/.test(fields.seconds))
+            return undefined;
+        try {
+            return {
+                id: fields.id,
+                generation: fields.generation,
+                expires: SessionRecords.deadline(create(TimestampSchema, {
+                    seconds: BigInt(fields.seconds),
+                    nanos: fields.nanos,
+                })),
+            };
+        }
+        catch {
+            return undefined;
+        }
     }
     /**
-     * Removes every session that has expired by the supplied time.
-     * @param now The validated sweep time in milliseconds.
+     * Matches a seal to the current stored generation and exact expiry.
+     *
+     * @param record Current record.
+     * @param seal Authenticated payload.
+     * @returns Whether the payload still identifies this generation.
      */
-    sweepExpired(now) {
-        for (const [id, record] of this.records)
-            if (this.expired(record, now))
-                this.records.delete(id);
+    #matches(record, seal) {
+        return (record.generation === seal.generation &&
+            SessionRecords.compare(SessionRecords.expiry(record), seal.expires) === 0);
     }
     /**
-     * Compares a session expiry with the current millisecond reading.
-     * @param record The session record to inspect.
-     * @param now The validated current time.
-     * @returns Whether the record has expired.
+     * Checks exact application expiry against the trusted clock.
+     *
+     * @param expires Exact authenticated deadline.
+     * @returns Whether the deadline has arrived or clock failed.
      */
-    expired(record, now) {
-        return now >= record.expiresAt;
+    #expired(expires) {
+        const now = this.#now();
+        return now === undefined || SessionRecords.compare(expires, SessionPolicy.timestamp(now)) <= 0;
     }
     /**
-     * Reads a safe clock value and closes the store on clock failure.
-     * @returns Current epoch milliseconds, or undefined after failure.
+     * Reads and validates a trusted clock value.
+     *
+     * @returns Safe milliseconds, if valid.
      */
-    now() {
+    #now() {
         try {
-            const value = this.clock.now();
-            if (!Number.isSafeInteger(value) || !OpaqueSessionValues.timestampValid(value))
-                throw new Error("invalid clock");
+            const value = this.#clock.now();
+            if (!Number.isSafeInteger(value))
+                throw new Error("Invalid session clock.");
+            SessionRecords.deadline(SessionPolicy.timestamp(value));
             return value;
         }
         catch {
-            this.failClosed();
+            this.#closed = true;
+            this.#lifetimes.close();
+            return undefined;
+        }
+    }
+    /**
+     * Reads closure after callbacks that can change lifecycle state.
+     *
+     * @returns Whether the strategy has closed.
+     */
+    #isClosed() {
+        return this.#closed;
+    }
+    /**
+     * Calculates one exact millisecond deadline without overflow.
+     *
+     * @param now Valid current milliseconds.
+     * @returns Exact deadline if representable.
+     */
+    #deadline(now) {
+        const value = now + this.#ttlMilliseconds;
+        if (!Number.isSafeInteger(value))
+            return undefined;
+        try {
+            return SessionRecords.deadline(SessionPolicy.timestamp(value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Generates and clears cryptographic bytes for an opaque reference.
+     *
+     * @returns Base64url random value when the source succeeds.
+     */
+    #randomValue() {
+        let bytes;
+        try {
+            bytes = this.#random(32);
+        }
+        catch {
             return undefined;
         }
+        try {
+            return bytes.byteLength === 32 ? Buffer.from(bytes).toString("base64url") : undefined;
+        }
+        finally {
+            bytes.fill(0);
+        }
     }
     /**
-     * Closes the store and clears session records after a clock fault.
+     * Copies authoritative stored identity and deadline for a caller.
+     *
+     * @param record Complete stored record.
+     * @returns Detached resolved session.
      */
-    failClosed() {
-        this.closed = true;
-        this.records.clear();
+    #resolved(record) {
+        return Object.freeze({
+            principal: SessionRecords.publicPrincipal(record),
+            expiresAt: SessionRecords.expiry(record),
+        });
     }
 }
 /**
- * Validates opaque-session values and creates immutable credential data.
+ * Validates session configuration and builds exact public values.
  */
-const OpaqueSessionValues = Object.freeze({
+const SessionPolicy = Object.freeze({
     /**
-     * Validates a positive safe integer for a session limit.
-     * @param value The candidate limit.
-     * @param name The option named in an error.
-     * @returns The accepted limit.
+     * Validates a positive safe policy integer.
+     *
+     * @param value Candidate number.
+     * @param name Option named in an error.
+     * @returns Accepted number.
      */
-    positiveSafeInteger(value, name) {
+    positive(value, name) {
         if (!Number.isSafeInteger(value) || value <= 0)
-            throw new Error(`${name} must be a positive safe integer`);
+            throw new RangeError(`${name} must be a positive safe integer.`);
         return value;
     },
     /**
-     * Wraps an opaque identifier in an immutable cookie credential.
-     * @param value The opaque identifier.
-     * @returns The cookie credential.
+     * Validates and snapshots every configured iron-session secret.
+     *
+     * @param value Secret or numeric version map.
+     * @returns Detached validated configuration.
      */
-    credential(value) {
-        return Object.freeze({ kind: "cookie", value });
-    },
-    /**
-     * Copies a principal and freezes its attributes before retention.
-     * @param principal The authenticated identity to copy.
-     * @returns An immutable principal snapshot.
-     */
-    copyPrincipal(principal) {
-        if (typeof principal.id !== "string")
-            throw new Error("principal.id must be a string");
-        const attributes = principal.attributes === undefined ? undefined : Object.freeze({ ...principal.attributes });
-        return Object.freeze(attributes === undefined ? { id: principal.id } : { id: principal.id, attributes });
-    },
-    /**
-     * Builds a detached resolved session from a retained record.
-     * @param record The live session record.
-     * @returns The resolved principal and precise expiry.
-     */
-    resolved(record) {
-        return Object.freeze({
-            principal: OpaqueSessionValues.copyPrincipal(record.principal),
-            expiresAt: OpaqueSessionValues.timestamp(record.expiresAt),
-        });
+    password(value) {
+        if (typeof value === "string") {
+            if (value.length < 32)
+                throw new RangeError("Session password must have at least 32 characters.");
+            return value;
+        }
+        const candidate = value;
+        if (typeof candidate !== "object" || candidate === null || Object.keys(candidate).length === 0)
+            throw new TypeError("Session password map must be nonempty.");
+        const copy = {};
+        for (const [key, secret] of Object.entries(candidate)) {
+            if (!/^\d+$/.test(key) || !Number.isSafeInteger(Number(key)) || Number(key) <= 0)
+                throw new TypeError("Session password IDs must be positive numeric integers.");
+            if (typeof secret !== "string" || secret.length < 32)
+                throw new RangeError("Every session password must have at least 32 characters.");
+            copy[key] = secret;
+        }
+        return copy;
     },
     /**
-     * Converts epoch milliseconds to a Protobuf expiry timestamp.
-     * @param milliseconds The expiry time to encode.
-     * @returns The normalized Protobuf timestamp.
+     * Converts safe epoch milliseconds without losing subsecond precision.
+     *
+     * @param milliseconds Safe epoch millisecond value.
+     * @returns Protobuf timestamp.
      */
     timestamp(milliseconds) {
         const seconds = Math.floor(milliseconds / 1_000);
@@ -325,13 +594,13 @@ const OpaqueSessionValues = Object.freeze({
         });
     },
     /**
-     * Checks whether epoch milliseconds fit the Protobuf timestamp range.
-     * @param milliseconds The candidate expiry time.
-     * @returns Whether it fits the supported range.
+     * Wraps a sealed value in an immutable cookie credential.
+     *
+     * @param value Iron-session seal.
+     * @returns Cookie credential.
      */
-    timestampValid(milliseconds) {
-        const seconds = Math.floor(milliseconds / 1_000);
-        return seconds >= -62_135_596_800 && seconds <= 253_402_300_799;
+    credential(value) {
+        return Object.freeze({ kind: "cookie", value });
     },
 });
 //# sourceMappingURL=opaque.js.map