@c9up/warden 0.1.16 → 0.1.18

package/dist/strategies/SessionStrategy.js

@@ -7,6 +7,9 @@
  * @implements MISS-7
  */
 import { WardenError } from "../errors.js";
+import { decodeTokenValue, mintRememberMeToken, verifyAndRecycleRememberMeToken, } from "../RememberMeToken.js";
+/** Two years, Adonis' `rememberMeTokensAge` default. */
+const DEFAULT_REMEMBER_AGE_SECONDS = 63_072_000;
 export class SessionStrategy {
     name = "session";
     #config;
@@ -15,6 +18,62 @@ export class SessionStrategy {
         this.#config = config;
         this.#sessionKey = config.sessionKey ?? "auth_user_id";
     }
+    /** The cookie the remember-me token travels in. */
+    get rememberMeCookieName() {
+        return this.#config.rememberMeCookieName ?? "remember_web";
+    }
+    /** Whether "keep me signed in" is wired at all. */
+    get usesRememberMeTokens() {
+        return this.#config.rememberMeTokens !== undefined;
+    }
+    #rememberMeAge() {
+        return this.#config.rememberMeAge ?? DEFAULT_REMEMBER_AGE_SECONDS;
+    }
+    /**
+     * Mint a remember-me token for `user` and return the cookie value the caller
+     * must set. `null` when the feature is not wired.
+     */
+    async issueRememberMeToken(user) {
+        const driver = this.#config.rememberMeTokens;
+        if (!driver)
+            return null;
+        const minted = mintRememberMeToken(user.id, this.#rememberMeAge());
+        await driver.create(minted.stored);
+        return minted.value;
+    }
+    /**
+     * Authenticate from a remember-me cookie, and RECYCLE it: the returned
+     * `cookieValue` must replace the one the browser holds.
+     *
+     * The user is re-read through `findUser`, never trusted from the token — a
+     * token outlives the row it points at, and a deleted or disabled account
+     * must not walk back in through a cookie.
+     */
+    async authenticateViaRememberMeToken(cookieValue) {
+        const driver = this.#config.rememberMeTokens;
+        if (!driver)
+            return null;
+        const recycled = await verifyAndRecycleRememberMeToken(driver, cookieValue, this.#rememberMeAge());
+        if (!recycled)
+            return null;
+        const user = await this.#config.findUser(recycled.userId);
+        if (!user)
+            return null;
+        return { user, cookieValue: recycled.value };
+    }
+    /**
+     * Drop the token behind `cookieValue`. Called on logout so the persistent
+     * credential dies with the session — Adonis deletes the row too.
+     */
+    async revokeRememberMeToken(cookieValue) {
+        const driver = this.#config.rememberMeTokens;
+        if (!driver)
+            return;
+        const decoded = decodeTokenValue(cookieValue);
+        if (!decoded)
+            return;
+        await driver.delete(decoded.identifier);
+    }
     /** Authenticate via email/password — stores user ID in session. */
     async authenticate(_credentials, _context) {
         // Session strategy doesn't handle password verification — that's done
@@ -62,7 +121,22 @@ export class SessionStrategy {
         session.regenerate();
         session.put(this.#sessionKey, user.id);
     }
-    /** Logout — remove user ID from session. */
+    /**
+     * The session entry a test client needs to be `user` (AdonisJS
+     * `authenticateAsClient`).
+     *
+     * Returns the same key `login()` writes, so the request is authenticated by
+     * the guard's own logic rather than by the test knowing where the id lives.
+     */
+    authenticateAsClient(user) {
+        return { session: { [this.#sessionKey]: user.id } };
+    }
+    /**
+     * Logout — remove the user id from the session.
+     *
+     * The remember-me token is revoked separately through
+     * {@link revokeRememberMeToken}, because only the caller holds the cookie.
+     */
     async logout(session) {
         session.forget(this.#sessionKey);
     }

package/dist/strategies/SessionStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"SessionStrategy.js","sourceRoot":"","sources":["../../src/strategies/SessionStrategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AA2B3C,MAAM,OAAO,eAAe;IAC3B,IAAI,GAAG,SAAS,CAAC;IACjB,OAAO,CAAwB;IAC/B,WAAW,CAAS;IAEpB,YAAY,MAA6B;QACxC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,UAAU,IAAI,cAAc,CAAC;IACxD,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,YAAY,CACjB,YAAiD,EACjD,QAAqC;QAErC,sEAAsE;QACtE,wEAAwE;QACxE,mEAAmE;QACnE,sEAAsE;QACtE,kEAAkE;QAClE,sCAAsC;QACtC,MAAM,IAAI,WAAW,CACpB,WAAW,EACX,6KAA6K,EAC7K;YACC,IAAI,EAAE,yKAAyK;SAC/K,CACD,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,KAAK,CAAC,MAAM,CAAC,MAAc;QAC1B,OAAO;YACN,aAAa,EAAE,KAAK;YACpB,KAAK,EACJ,qEAAqE;SACtE,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,iBAAiB,CACtB,MAAc,EACd,OAAoC;QAEpC,IAAI,CAAC,OAAO,EAAE,OAAO;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC;QACvE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK,QAAQ;YAC3D,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;QACpE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,IAAiB,EAAE,OAAqB;QACnD,OAAO,CAAC,UAAU,EAAE,CAAC;QACrB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,MAAM,CAAC,OAAqB;QACjC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAClC,CAAC;CACD"}
+{"version":3,"file":"SessionStrategy.js","sourceRoot":"","sources":["../../src/strategies/SessionStrategy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/warden",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Warden — Authentication & authorization for the Ream framework",
   "license": "MIT",
   "type": "module",
@@ -49,15 +49,20 @@
     }
   },
   "peerDependencies": {
-    "@c9up/ream": "^0.1.10"
+    "@c9up/ream": "^0.1.10",
+    "@c9up/quasar": "^0.1.0"
   },
   "peerDependenciesMeta": {
     "@c9up/ream": {
       "optional": true
+    },
+    "@c9up/quasar": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
+    "@c9up/quasar": "^0.1.0",
     "@types/node": "^22.19.15",
     "reflect-metadata": "^0.2.2",
     "typescript": "^6.0.2",
@@ -81,6 +86,7 @@
     "test:rust": "cargo test -p warden-engine",
     "lint": "biome check src/",
     "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:integration": "vitest run -c vitest.integration.config.ts"
   }
 }

package/src/AuthManager.ts

@@ -31,10 +31,34 @@ export interface AuthResult {
 	strategyCrash?: true;
 }
 
+/**
+ * What a test client must send to act as a user (AdonisJS `AuthClientResponse`).
+ *
+ * Each guard answers in its own currency — a header for a token guard, a
+ * session entry for a session guard — so the test harness applies whichever
+ * fields come back instead of knowing how each guard authenticates.
+ */
+export interface AuthClientResponse {
+	/** Headers to set on the request. */
+	headers?: Record<string, string>;
+	/** Session values to seed before the request. */
+	session?: Record<string, unknown>;
+	/** Cookies to send. */
+	cookies?: Record<string, string>;
+}
+
 export interface AuthStrategy {
 	name: string;
 	authenticate(credentials: Record<string, unknown>): Promise<AuthResult>;
 	verify(token: string, context?: Record<string, unknown>): Promise<AuthResult>;
+	/**
+	 * Build what a test client sends to be this user (AdonisJS
+	 * `authenticateAsClient`). Optional: a guard with no test seam simply has
+	 * none, and the harness says so instead of forging one.
+	 */
+	authenticateAsClient?(
+		...args: never[]
+	): Promise<AuthClientResponse> | AuthClientResponse;
 }
 
 /**
@@ -86,6 +110,14 @@ function isTokenIssuer(
 /**
  * Manages authentication strategies and provides guard/permission checks.
  */
+/**
+ * The slice of an event emitter warden publishes through — `emit(name, data)`,
+ * which is what both `@c9up/ream`'s Emitter and Adonis' expose.
+ */
+export interface WardenEmitter {
+	emit(event: string, data: unknown): unknown;
+}
+
 export class AuthManager {
 	// AdonisJS names: `guards` (name → strategy) and `default` (the guard used
 	// when none is named). Renamed from the previous `strategies`/`defaultStrategy`.
@@ -93,6 +125,40 @@ export class AuthManager {
 	private default: string;
 	private readonly rights: RightsResolver;
 
+	/**
+	 * Where auth events go. Structural and optional: warden is a leaf and must
+	 * not import an emitter — a host wires its own through `setEmitter`, and one
+	 * that wires none simply gets no events.
+	 */
+	#emitter: WardenEmitter | undefined;
+
+	/**
+	 * Publish auth events on `emitter`. AdonisJS emits six of them from its
+	 * session guard, and an app that audits logins reads exactly those.
+	 */
+	setEmitter(emitter: WardenEmitter): this {
+		this.#emitter = emitter;
+		return this;
+	}
+
+	/**
+	 * Publish one auth event. Public so the per-request `Authenticator` can
+	 * report what it observed — it holds the guard chain, the manager holds the
+	 * emitter.
+	 */
+	emitAuthEvent(event: string, payload: Record<string, unknown>): void {
+		this.#emit(event, payload);
+	}
+
+	/** Fire-and-forget: an event listener must never break authentication. */
+	#emit(event: string, payload: Record<string, unknown>): void {
+		try {
+			void this.#emitter?.emit(event, payload);
+		} catch {
+			// A throwing listener is the listener's problem, not the login's.
+		}
+	}
+
 	constructor(config: AuthConfig) {
 		// Normalise the two accepted forms — AdonisJS `{ default, guards }` and
 		// the legacy `{ defaultStrategy, strategies }` — to the AdonisJS names.
@@ -316,7 +382,16 @@ export class AuthManager {
 				},
 			);
 		}
+		this.#emit("session_auth:login_attempted", {
+			guardName: strategyName ?? this.default,
+			user,
+		});
 		await strategy.login(user, session);
+		this.#emit("session_auth:login_succeeded", {
+			guardName: strategyName ?? this.default,
+			user,
+			sessionId: undefined,
+		});
 	}
 
 	/**
@@ -333,6 +408,11 @@ export class AuthManager {
 			);
 		}
 		await strategy.logout(session);
+		this.#emit("session_auth:logged_out", {
+			guardName: strategyName ?? this.default,
+			user: null,
+			error: null,
+		});
 	}
 }
 

package/src/Authenticator.ts

@@ -321,6 +321,12 @@ export class Authenticator {
 		this.#attempted = true;
 		const names =
 			guards && guards.length > 0 ? guards : [this.#auth.defaultStrategyName];
+		const guardName = names[0] ?? this.#auth.defaultStrategyName;
+		// The four authentication events AdonisJS' session guard emits. An app
+		// auditing logins subscribes to exactly these names.
+		this.#auth.emitAuthEvent("session_auth:authentication_attempted", {
+			guardName,
+		});
 		const creds = extractCredentials(this.#ctx, this.#auth);
 		const hasSessionStrategy = names.includes("session");
 		const { result, viaGuard, attemptCount, crashCount } =
@@ -332,6 +338,11 @@ export class Authenticator {
 		if (result?.authenticated && result.user) {
 			this.#user = result.user;
 			this.#viaGuard = viaGuard;
+			this.#auth.emitAuthEvent("session_auth:authentication_succeeded", {
+				guardName: viaGuard ?? guardName,
+				user: result.user,
+				sessionId: undefined,
+			});
 			return;
 		}
 		// Every attempted guard crashed → a server-side incident, not a
@@ -343,10 +354,18 @@ export class Authenticator {
 				{ status: 500 },
 			);
 		}
-		throw new E_UNAUTHORIZED_ACCESS(result?.error ?? "Unauthorized access", {
-			guardDriverName: names[0] ?? this.#auth.defaultStrategyName,
-			redirectTo: hasSessionStrategy ? options?.loginRoute : undefined,
+		const failure = new E_UNAUTHORIZED_ACCESS(
+			result?.error ?? "Unauthorized access",
+			{
+				guardDriverName: guardName,
+				redirectTo: hasSessionStrategy ? options?.loginRoute : undefined,
+			},
+		);
+		this.#auth.emitAuthEvent("session_auth:authentication_failed", {
+			guardName,
+			error: failure,
 		});
+		throw failure;
 	}
 
 	/** Return the authenticated user or throw `E_UNAUTHORIZED_ACCESS`. */

package/src/RedisBlacklistDriver.ts

@@ -26,15 +26,47 @@ export interface RedisBlacklistConfig {
 	prefix?: string;
 }
 
+/**
+ * Where the client comes from. A resolver is what lets the blacklist name its
+ * connection instead of being handed a client: config is read synchronously,
+ * the first revocation check is not.
+ */
+export type RedisClientSource =
+	| RedisLikeClient
+	| (() => RedisLikeClient | Promise<RedisLikeClient>);
+
 export class RedisBlacklistDriver implements BlacklistDriver {
-	readonly #client: RedisLikeClient;
+	readonly #source: RedisClientSource;
+	#resolved: RedisLikeClient | undefined;
+	#pending: Promise<RedisLikeClient> | undefined;
 	readonly #prefix: string;
 
-	constructor(client: RedisLikeClient, config: RedisBlacklistConfig = {}) {
-		this.#client = client;
+	constructor(source: RedisClientSource, config: RedisBlacklistConfig = {}) {
+		this.#source = source;
 		this.#prefix = config.prefix ?? "warden:blacklist:";
 	}
 
+	/**
+	 * The client, resolved once. Two requests racing on a cold start must not
+	 * each open their own connection, so the in-flight promise is shared.
+	 */
+	async #client(): Promise<RedisLikeClient> {
+		if (this.#resolved) return this.#resolved;
+		if (typeof this.#source !== "function") {
+			this.#resolved = this.#source;
+			return this.#resolved;
+		}
+		if (!this.#pending) {
+			const resolver = this.#source;
+			this.#pending = Promise.resolve(resolver()).then((client) => {
+				this.#resolved = client;
+				this.#pending = undefined;
+				return client;
+			});
+		}
+		return this.#pending;
+	}
+
 	/**
 	 * Blacklist a JTI until its natural expiry. Tokens already past `expiresAt`
 	 * are skipped — there is nothing left to revoke.
@@ -44,11 +76,13 @@ export class RedisBlacklistDriver implements BlacklistDriver {
 		if (ttlSeconds <= 0) {
 			return;
 		}
-		await this.#client.set(this.#key(jti), "1", "EX", ttlSeconds);
+		const client = await this.#client();
+		await client.set(this.#key(jti), "1", "EX", ttlSeconds);
 	}
 
 	async has(jti: string): Promise<boolean> {
-		return (await this.#client.exists(this.#key(jti))) > 0;
+		const client = await this.#client();
+		return (await client.exists(this.#key(jti))) > 0;
 	}
 
 	/** No-op: Redis/KeyDB evicts expired keys on its own. */

package/src/RememberMeToken.ts

@@ -0,0 +1,223 @@
+/**
+ * Remember-me tokens — "keep me signed in" that survives the session cookie.
+ *
+ * Modelled on `@adonisjs/auth`'s `RememberMeToken`
+ * (modules/session_guard/remember_me_token.ts), because an app moving over
+ * carries the same table and the same cookie:
+ *
+ *   value  = base64url(identifier) + "." + base64url(secret)
+ *   stored = sha256(secret), never the secret itself
+ *
+ * The three properties that make this safe, all taken from upstream:
+ *
+ *  1. **Only a hash is stored.** A dump of the tokens table does not let anyone
+ *     log in — the secret exists solely in the user's cookie.
+ *  2. **The comparison is constant-time.** Comparing hashes with `===` leaks
+ *     how many leading bytes matched, which is enough to forge one byte at a
+ *     time.
+ *  3. **A used token is recycled.** Authenticating rotates the secret and
+ *     invalidates the old one, so a stolen cookie stops working the moment the
+ *     legitimate user comes back.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+/** Bytes of entropy in a token secret. Adonis defaults to 40. */
+export const DEFAULT_SECRET_LENGTH = 40;
+
+/** A token as persisted. The secret is NOT here — only its hash. */
+export interface StoredRememberMeToken {
+	/** Unique id of the row; the public half of the token value. */
+	identifier: string;
+	/** Whose token this is. */
+	tokenableId: string | number;
+	/** `sha256(secret)`, hex. */
+	hash: string;
+	createdAt: number;
+	updatedAt: number;
+	expiresAt: number;
+}
+
+/** What a store must implement. Structural: warden owns no database. */
+export interface RememberMeTokenDriver {
+	create(token: StoredRememberMeToken): Promise<void>;
+	find(identifier: string): Promise<StoredRememberMeToken | null>;
+	/** Replace the hash + expiry of an existing row (recycling). */
+	update(identifier: string, hash: string, expiresAt: number): Promise<void>;
+	delete(identifier: string): Promise<void>;
+	deleteAllForUser(userId: string | number): Promise<void>;
+}
+
+/** Base64url without padding — the encoding Adonis uses for the token halves. */
+function base64UrlEncode(value: string): string {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function base64UrlDecode(value: string): string | null {
+	try {
+		const decoded = Buffer.from(value, "base64url").toString("utf8");
+		// A non-base64url character decodes to something that does not round-trip;
+		// reject rather than authenticate against a mangled identifier.
+		return Buffer.from(decoded, "utf8").toString("base64url") === value
+			? decoded
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/** `sha256(secret)` as hex — what gets stored. */
+export function hashSecret(secret: string): string {
+	return createHash("sha256").update(secret).digest("hex");
+}
+
+/**
+ * Compare two hex hashes without leaking where they diverge. Length is checked
+ * first because `timingSafeEqual` throws on a mismatch — and the length of a
+ * sha256 hex digest is public anyway.
+ */
+export function safeCompareHashes(a: string, b: string): boolean {
+	const left = Buffer.from(a, "utf8");
+	const right = Buffer.from(b, "utf8");
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+}
+
+/** Split a cookie value into its identifier and secret, or `null` if malformed. */
+export function decodeTokenValue(
+	value: unknown,
+): { identifier: string; secret: string } | null {
+	if (typeof value !== "string" || value.length === 0) return null;
+	const [encodedIdentifier, ...rest] = value.split(".");
+	if (!encodedIdentifier || rest.length === 0) return null;
+	const identifier = base64UrlDecode(encodedIdentifier);
+	const secret = base64UrlDecode(rest.join("."));
+	if (identifier === null || secret === null) return null;
+	if (identifier === "" || secret === "") return null;
+	return { identifier, secret };
+}
+
+/** Build the cookie value from its two halves. */
+export function encodeTokenValue(identifier: string, secret: string): string {
+	return `${base64UrlEncode(identifier)}.${base64UrlEncode(secret)}`;
+}
+
+/** A freshly minted token: what to store, and what to hand the browser. */
+export interface MintedRememberMeToken {
+	stored: StoredRememberMeToken;
+	/** Goes in the cookie. Never persisted. */
+	value: string;
+}
+
+/**
+ * Mint a token for `userId`, valid for `ageSeconds`.
+ *
+ * `identifier` is random too, not a counter: a guessable identifier would let
+ * an attacker enumerate rows and target a specific user's token.
+ */
+export function mintRememberMeToken(
+	userId: string | number,
+	ageSeconds: number,
+	secretLength = DEFAULT_SECRET_LENGTH,
+): MintedRememberMeToken {
+	const identifier = randomBytes(16).toString("hex");
+	const secret = randomBytes(secretLength).toString("base64url");
+	const now = Date.now();
+	return {
+		stored: {
+			identifier,
+			tokenableId: userId,
+			hash: hashSecret(secret),
+			createdAt: now,
+			updatedAt: now,
+			expiresAt: now + ageSeconds * 1000,
+		},
+		value: encodeTokenValue(identifier, secret),
+	};
+}
+
+/**
+ * Verify a cookie value against the store, and RECYCLE the token on success:
+ * the row keeps its identifier but gets a fresh secret and expiry, and the
+ * caller must send the returned value back as the new cookie.
+ *
+ * Recycling is what limits the damage of a stolen cookie — the thief's copy
+ * dies as soon as the real user authenticates again.
+ *
+ * Returns `null` for anything wrong: malformed value, unknown identifier,
+ * expired row, or a secret that does not match. The caller cannot tell these
+ * apart, which is deliberate — a distinguishable "unknown identifier" tells an
+ * attacker which identifiers exist.
+ */
+export async function verifyAndRecycleRememberMeToken(
+	driver: RememberMeTokenDriver,
+	cookieValue: unknown,
+	ageSeconds: number,
+	secretLength = DEFAULT_SECRET_LENGTH,
+): Promise<{ userId: string | number; value: string } | null> {
+	const decoded = decodeTokenValue(cookieValue);
+	if (!decoded) return null;
+
+	const stored = await driver.find(decoded.identifier);
+	if (!stored) return null;
+
+	if (stored.expiresAt <= Date.now()) {
+		// Expired rows are removed on sight rather than left to a cleanup job.
+		await driver.delete(stored.identifier);
+		return null;
+	}
+
+	if (!safeCompareHashes(stored.hash, hashSecret(decoded.secret))) {
+		return null;
+	}
+
+	const secret = randomBytes(secretLength).toString("base64url");
+	const expiresAt = Date.now() + ageSeconds * 1000;
+	await driver.update(stored.identifier, hashSecret(secret), expiresAt);
+
+	return {
+		userId: stored.tokenableId,
+		value: encodeTokenValue(stored.identifier, secret),
+	};
+}
+
+/** In-memory store — for tests and single-process apps. Not for a cluster. */
+export class MemoryRememberMeTokenDriver implements RememberMeTokenDriver {
+	readonly #rows = new Map<string, StoredRememberMeToken>();
+
+	async create(token: StoredRememberMeToken): Promise<void> {
+		this.#rows.set(token.identifier, { ...token });
+	}
+
+	async find(identifier: string): Promise<StoredRememberMeToken | null> {
+		const row = this.#rows.get(identifier);
+		return row ? { ...row } : null;
+	}
+
+	async update(
+		identifier: string,
+		hash: string,
+		expiresAt: number,
+	): Promise<void> {
+		const row = this.#rows.get(identifier);
+		if (!row) return;
+		this.#rows.set(identifier, {
+			...row,
+			hash,
+			expiresAt,
+			updatedAt: Date.now(),
+		});
+	}
+
+	async delete(identifier: string): Promise<void> {
+		this.#rows.delete(identifier);
+	}
+
+	async deleteAllForUser(userId: string | number): Promise<void> {
+		for (const [identifier, row] of this.#rows) {
+			if (String(row.tokenableId) === String(userId)) {
+				this.#rows.delete(identifier);
+			}
+		}
+	}
+}