@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/src/store/journal.ts

@@ -0,0 +1,104 @@
+// Acked UIDs — durable replay protection.
+//
+// The cursor says what we have *seen*; the journal says what a session has *acked*. A crash
+// between the two is why this file exists.
+//
+// UIDs are only meaningful within one UIDVALIDITY, so the journal stores the one it belongs
+// to. A re-indexed mailbox renumbers from 1, and an old journal then suppresses brand-new
+// mail as "already acked" - so a validity mismatch means the journal is not consulted.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import { statePath } from "./paths.ts"
+import { StateVersionError, checkStateVersion, stamp } from "./schema.ts"
+
+/** Keep the last N acked UIDs. */
+export const JOURNAL_CAP = 5_000
+
+interface JournalFile {
+	v?: number
+	uids: number[]
+	/** The UIDVALIDITY these UIDs were acked under. */
+	uidValidity?: number
+}
+
+function path(env: NodeJS.ProcessEnv): string {
+	return statePath(env, "journal.json")
+}
+
+function loadFile(env: NodeJS.ProcessEnv): JournalFile {
+	const p = path(env)
+	try {
+		if (!existsSync(p)) return { uids: [] }
+		const parsed = JSON.parse(readFileSync(p, "utf8")) as Partial<JournalFile>
+		checkStateVersion("journal.json", parsed)
+		return {
+			uids: Array.isArray(parsed?.uids) ? parsed.uids.filter((n) => typeof n === "number") : [],
+			...(typeof parsed?.uidValidity === "number" ? { uidValidity: parsed.uidValidity } : {}),
+		}
+	} catch (error) {
+		if (error instanceof StateVersionError) throw error
+		return { uids: [] }
+	}
+}
+
+function save(env: NodeJS.ProcessEnv, file: JournalFile): void {
+	const p = path(env)
+	mkdirSync(dirname(p), { recursive: true, mode: 0o700 })
+	const tmp = `${p}.${process.pid}.tmp`
+	const trimmed = file.uids.length > JOURNAL_CAP ? file.uids.slice(file.uids.length - JOURNAL_CAP) : file.uids
+	writeFileSync(tmp, JSON.stringify({ ...stamp(), ...file, uids: trimmed } satisfies JournalFile), { mode: 0o600 })
+	renameSync(tmp, p)
+}
+
+/**
+ * Has this UID been acked?
+ *
+ * When the caller knows the mailbox's UIDVALIDITY and it differs from the journal's, the
+ * answer is "no": those UIDs belonged to a different numbering and say nothing about this one.
+ */
+export function isJournaled(env: NodeJS.ProcessEnv, uid: number, uidValidity?: number): boolean {
+	const file = loadFile(env)
+	if (uidValidity !== undefined) {
+		// The caller knows the live numbering. A journal tagged with a different space cannot
+		// answer for it - and neither can an untagged one, written before the field existed:
+		// after a renumbering its old UIDs are reused, and "already seen" would let the cursor
+		// advance past genuinely new mail.
+		if (file.uidValidity === undefined) return false
+		if (file.uidValidity !== uidValidity) return false
+	}
+	return file.uids.includes(uid)
+}
+
+/** Append `uid` (idempotent). Returns false when it was already journaled. */
+export function journal(env: NodeJS.ProcessEnv, uid: number, uidValidity?: number): boolean {
+	const file = loadFile(env)
+	// A new numbering starts a new journal: keeping old entries would suppress new mail.
+	const sameSpace = uidValidity === undefined || file.uidValidity === undefined || file.uidValidity === uidValidity
+	const uids = sameSpace ? file.uids : []
+	// Never erase a validity we already know: an ack from a caller that could not report one
+	// must not blind the next comparison.
+	// The caller's space wins, because claim/ack refuse a record from another space: an ack
+	// that reaches here is for the live numbering, and the file must adopt it. (Preferring the
+	// file's space made it write-once - after the first renumbering every later ack was
+	// journaled under the dead numbering and dedupe was permanently inert.)
+	const known = uidValidity ?? file.uidValidity
+	const next = { uids, ...(known === undefined ? {} : { uidValidity: known }) }
+	if (uids.includes(uid)) {
+		save(env, next)
+		return false
+	}
+	uids.push(uid)
+	save(env, next)
+	return true
+}
+
+export function journalSize(env: NodeJS.ProcessEnv): number {
+	return loadFile(env).uids.length
+}
+
+/** Test helper: forget every ack. */
+export function resetJournal(env: NodeJS.ProcessEnv): void {
+	save(env, { uids: [] })
+}

package/src/store/mode-store.ts

@@ -0,0 +1,60 @@
+// Global email mode: "am I away from the keyboard?"
+//
+// One human, one mailbox, one switch. It is deliberately global rather than
+// per-session: you are either at the desk or you are not, and pretending
+// otherwise makes the agent guess.
+//
+// Persisted so a daemon restart cannot silently re-enable emailing, and default
+// OFF so installing the package never starts mailing you unprompted.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import { statePath } from "./paths.ts"
+
+export type Mode = "on" | "off"
+
+export const DEFAULT_MODE: Mode = "off"
+
+interface ModeFile {
+	mode: Mode
+	updatedAt: number
+}
+
+function path(env: NodeJS.ProcessEnv): string {
+	return statePath(env, "mode.json")
+}
+
+export function isMode(value: unknown): value is Mode {
+	return value === "on" || value === "off"
+}
+
+/** Current mode; a missing or corrupt file means off. */
+export function readMode(env: NodeJS.ProcessEnv = process.env): Mode {
+	const p = path(env)
+	try {
+		if (!existsSync(p)) return DEFAULT_MODE
+		const parsed = JSON.parse(readFileSync(p, "utf8")) as Partial<ModeFile>
+		return isMode(parsed?.mode) ? parsed.mode : DEFAULT_MODE
+	} catch {
+		return DEFAULT_MODE
+	}
+}
+
+/** Persist the mode. Returns the value actually stored. */
+export function writeMode(env: NodeJS.ProcessEnv, mode: Mode, now: number = Date.now()): Mode {
+	const p = path(env)
+	mkdirSync(dirname(p), { recursive: true, mode: 0o700 })
+	const tmp = `${p}.${process.pid}.tmp`
+	writeFileSync(tmp, JSON.stringify({ mode, updatedAt: now } satisfies ModeFile), { mode: 0o600 })
+	renameSync(tmp, p)
+	return mode
+}
+
+/**
+ * The single rule for whether the daemon may touch the mailbox. `/mailbridge off` is documented as
+ * closing the control channel, so this is the gate that makes that true.
+ */
+export function scanningEnabled(mode: Mode): boolean {
+	return mode === "on"
+}

package/src/store/oauth-store.ts

@@ -0,0 +1,55 @@
+// Persistence for OAuth tokens.
+//
+// Only the refresh token is precious: access tokens are short-lived and cheap to
+// re-mint. The file is 0600 inside the 0700 state dir, and it is never logged.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import { statePath } from "./paths.ts"
+import type { StoredTokens, TokenStore } from "../core/oauth-device.ts"
+
+function path(env: NodeJS.ProcessEnv): string {
+	return statePath(env, "oauth.json")
+}
+
+/** File-backed token store. Atomic replace, mode 0600. */
+export function fileTokenStore(env: NodeJS.ProcessEnv = process.env): TokenStore {
+	const file = path(env)
+	return {
+		read() {
+			try {
+				if (!existsSync(file)) return undefined
+				const parsed = JSON.parse(readFileSync(file, "utf8")) as StoredTokens
+				if (typeof parsed?.refreshToken !== "string" && typeof parsed?.accessToken !== "string") return undefined
+				return parsed
+			} catch {
+				return undefined
+			}
+		},
+
+		write(tokens) {
+			mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+			const tmp = `${file}.${process.pid}.tmp`
+			writeFileSync(tmp, JSON.stringify(tokens), { mode: 0o600 })
+			renameSync(tmp, file)
+		},
+	}
+}
+
+/** In-memory store for tests and for `--auth` dry runs. */
+export function memoryTokenStore(initial?: StoredTokens): TokenStore & { value(): StoredTokens | undefined } {
+	let tokens = initial
+	return {
+		read: () => tokens,
+		write(next) {
+			tokens = next
+		},
+		value: () => tokens,
+	}
+}
+
+/** True when a refresh token is on disk, i.e. login already happened. */
+export function hasStoredRefreshToken(env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(fileTokenStore(env).read()?.refreshToken)
+}

package/src/store/paths.ts

@@ -0,0 +1,38 @@
+// State + config locations. Everything the package writes lives under one
+// directory so a user can inspect or delete it in one step.
+//
+//   $XDG_STATE_HOME/pi-mailbridge/   (default ~/.local/state/pi-mailbridge)
+//     secret.key        shared HMAC + daemon bearer key, mode 0600
+//     uid-cursor.json   IMAP UID cursor + the mailbox UIDVALIDITY it belongs to
+//     pending.json      durable pending deliveries
+//     journal.json      UIDs already acked (replay protection)
+//     mode.json         global on/off
+//     routes.json       short routing ids (TTL-bounded)
+//     threads.json      outbound Message-IDs: threading + reply chain
+//     oauth.json        refresh token, 0600
+//
+// Config is read from, in order, each deep-merged over the previous:
+//   1. built-in defaults
+//   2. $XDG_CONFIG_HOME/pi-mailbridge/config.json
+//   3. PI_MAILBRIDGE_* environment variables
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export function stateDir(env: NodeJS.ProcessEnv = process.env): string {
+	const base = env.XDG_STATE_HOME || join(homedir(), ".local", "state")
+	return join(base, "pi-mailbridge")
+}
+
+export function configDir(env: NodeJS.ProcessEnv = process.env): string {
+	const base = env.XDG_CONFIG_HOME || join(homedir(), ".config")
+	return join(base, "pi-mailbridge")
+}
+
+export function statePath(env: NodeJS.ProcessEnv, ...parts: string[]): string {
+	return join(stateDir(env), ...parts)
+}
+
+export function configPath(env: NodeJS.ProcessEnv = process.env): string {
+	return join(configDir(env), "config.json")
+}

package/src/store/pending-store.ts

@@ -0,0 +1,282 @@
+// Durable pending deliveries.
+//
+// Written by the daemon immediately after a message is parsed and authorized —
+// *before* any session is told about it. That ordering is the whole point: a
+// crash after this write still leaves the reply available for redelivery, while
+// the mail stays unseen on the server.
+//
+// Single-writer model: only the daemon mutates this file, so no inter-process
+// lock is required. Atomic rename protects against torn reads.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import { statePath } from "./paths.ts"
+import { StateVersionError, checkStateVersion, stamp } from "./schema.ts"
+
+/** Bound the store so a stuck mailbox cannot grow it without limit. */
+export const PENDING_CAP = 1_000
+/** A claim older than this is considered abandoned and may be re-taken. */
+export const CLAIM_TTL_MS = 120_000
+
+export interface PendingRecord {
+	uid: number
+	sessionId: string
+	from: string
+	subject: string
+	body: string
+	/** Already allowlisted and capped by core/attachments before persisting. */
+	attachments?: { name: string; mimeType: string; size: number; data: string }[]
+	receivedAt: number
+	/** The UIDVALIDITY this UID belongs to, when known. */
+	uidValidity?: number
+	/**
+	 * The device that scanned it. Two machines sharing one state directory (or one device.name)
+	 * must not deliver each other's replies, so /pending filters and /claim refuses on this.
+	 */
+	device?: string
+	claimedBy?: string
+	claimedAt?: number
+}
+
+interface PendingFile {
+	v?: number
+	items: PendingRecord[]
+}
+
+export type ClaimResult =
+	| { ok: true }
+	| { ok: false; reason: "not-found" | "claimed-by-other" | "stale-space" | "foreign-device" }
+
+function path(env: NodeJS.ProcessEnv): string {
+	return statePath(env, "pending.json")
+}
+
+/**
+ * Parsed-file cache, keyed by the file's mtime+size.
+ *
+ * /health is unauthenticated and reads the queue length on every request; every poll tick
+ * and every claim/ack re-reads it too. Without a cache, one large queued reply is re-parsed
+ * (and re-serialised to JSON) many times a minute.
+ */
+let cached: { path: string; stamp: string; items: PendingRecord[] } | undefined
+
+function load(env: NodeJS.ProcessEnv): PendingRecord[] {
+	const p = path(env)
+	try {
+		if (!existsSync(p)) return []
+		const stat = statSync(p)
+		const stamp = `${stat.mtimeMs}:${stat.size}`
+		if (cached && cached.path === p && cached.stamp === stamp) return cached.items
+		const parsed = JSON.parse(readFileSync(p, "utf8")) as Partial<PendingFile>
+		// Refuses a file from a newer schema rather than filtering records it cannot read.
+		checkStateVersion("pending.json", parsed)
+		if (!Array.isArray(parsed?.items)) return []
+		const items = parsed.items.filter(
+			(r): r is PendingRecord =>
+				typeof r?.uid === "number" && typeof r?.sessionId === "string" && typeof r?.body === "string",
+		)
+		cached = { path: p, stamp, items }
+		return items
+	} catch (error) {
+		if (error instanceof StateVersionError) throw error
+		// Unparsable is not empty. Returning [] lets the next addPending rewrite the file with a
+		// single record, discarding a queue whose replies the cursor has already passed. Keep the
+		// bytes where a human can recover them and start clean.
+		try {
+			renameSync(p, `${p}.corrupt-${Date.now()}`)
+		} catch {
+			/* if it cannot be moved, the caller still gets an empty queue rather than a crash */
+		}
+		return []
+	}
+}
+
+function save(env: NodeJS.ProcessEnv, items: PendingRecord[]): void {
+	const p = path(env)
+	mkdirSync(dirname(p), { recursive: true, mode: 0o700 })
+	const tmp = `${p}.${process.pid}.tmp`
+	// Never trim here. These records were accepted and the cursor has already moved past
+	// them, so dropping one is silent, unrecoverable mail loss. The cap is enforced at
+	// insertion instead, where the caller can refuse and leave the cursor alone.
+	writeFileSync(tmp, JSON.stringify({ ...stamp(), items } satisfies PendingFile), { mode: 0o600 })
+	renameSync(tmp, p)
+	// The process that wrote knows the truth; an mtime+size stamp can collide when two writes
+	// land in the same millisecond with the same length (measured on ext4).
+	try {
+		const stat = statSync(p)
+		cached = { path: p, stamp: `${stat.mtimeMs}:${stat.size}`, items }
+	} catch {
+		cached = undefined
+	}
+}
+
+export function listPending(env: NodeJS.ProcessEnv = process.env): PendingRecord[] {
+	return load(env)
+}
+
+/** Only the records this device scanned; absent device means "from before the field". */
+export function listPendingForDevice(env: NodeJS.ProcessEnv, device: string): PendingRecord[] {
+	return load(env).filter((r) => r.device === undefined || r.device === device)
+}
+
+export function listPendingForSession(env: NodeJS.ProcessEnv, sessionId: string): PendingRecord[] {
+	return load(env).filter((r) => r.sessionId === sessionId)
+}
+
+export function getPending(env: NodeJS.ProcessEnv, uid: number): PendingRecord | undefined {
+	return load(env).find((r) => r.uid === uid)
+}
+
+export type AddResult = { ok: true; record: PendingRecord } | { ok: false; reason: "full" }
+
+/**
+ * Add or replace the record for `uid`. Idempotent on replay.
+ *
+ * Refuses a NEW record once the store is full rather than making room by discarding an
+ * older one: every record here was already accepted, and the caller's cursor is about to
+ * move past it. Replacing an existing uid (replay) is always allowed.
+ */
+export function addPending(env: NodeJS.ProcessEnv, record: PendingRecord): AddResult {
+	const existing = load(env)
+	const without = existing.filter((r) => r.uid !== record.uid)
+	if (without.length >= PENDING_CAP) return { ok: false, reason: "full" }
+	without.push(record)
+	save(env, without)
+	return { ok: true, record }
+}
+
+/**
+ * Claim a delivery for `instanceId`.
+ *
+ * Succeeds when the record is unclaimed, already claimed by this same instance,
+ * or its claim has expired (abandoned instance).
+ */
+export function claimPending(
+	env: NodeJS.ProcessEnv,
+	uid: number,
+	instanceId: string,
+	now: number = Date.now(),
+	uidValidity?: number,
+	liveValidity?: number,
+	device?: string,
+): ClaimResult {
+	const items = load(env)
+	const record = items.find((r) => r.uid === uid)
+	if (!record) return { ok: false, reason: "not-found" }
+	// Defence in depth for a shared state directory: /pending already filters by device, but a
+	// caller that names a uid it should not have (an older client, or a direct POST) is refused.
+	if (record.device !== undefined && device !== undefined && record.device !== device) {
+		return { ok: false, reason: "foreign-device" }
+	}
+	// A caller holding a record from a previous UID numbering must not act on whatever now
+	// occupies that UID: after a renumbering it is a different message.
+	if (record.uidValidity !== undefined && uidValidity !== undefined && record.uidValidity !== uidValidity) {
+		return { ok: false, reason: "stale-space" }
+	}
+	// Also compare against the mailbox itself: a caller and a record can agree with each other
+	// while both belong to a numbering the mailbox has already left.
+	if (record.uidValidity !== undefined && liveValidity !== undefined && record.uidValidity !== liveValidity) {
+		return { ok: false, reason: "stale-space" }
+	}
+	if (record.claimedBy && record.claimedBy !== instanceId) {
+		const age = now - (record.claimedAt ?? 0)
+		if (age < CLAIM_TTL_MS) return { ok: false, reason: "claimed-by-other" }
+	}
+	record.claimedBy = instanceId
+	record.claimedAt = now
+	save(env, items)
+	return { ok: true }
+}
+
+/**
+ * Remove a delivery. Only the claimant may ack.
+ *
+ * An unclaimed record must NOT be ackable: with two sessions on one machine, any
+ * authenticated client could otherwise delete, journal and mark `\Seen` another
+ * session's reply - and nothing would re-read it, because the cursor has already moved.
+ * Returns the record's session so the caller releases the right decision slot instead of
+ * trusting whatever session id the request body carried.
+ */
+export type AckResult =
+	| { ok: true; sessionId: string; uidValidity?: number }
+	| { ok: false; reason: "not-found" | "not-claimed" | "stale-space" }
+
+export function ackPending(
+	env: NodeJS.ProcessEnv,
+	uid: number,
+	instanceId: string,
+	uidValidity?: number,
+	liveValidity?: number,
+): AckResult {
+	const items = load(env)
+	const record = items.find((r) => r.uid === uid)
+	if (!record) return { ok: false, reason: "not-found" }
+	// Same rule as claim: an ack from another UID space would journal a UID that now means
+	// something else.
+	if (record.uidValidity !== undefined && uidValidity !== undefined && record.uidValidity !== uidValidity) {
+		return { ok: false, reason: "stale-space" }
+	}
+	if (record.uidValidity !== undefined && liveValidity !== undefined && record.uidValidity !== liveValidity) {
+		return { ok: false, reason: "stale-space" }
+	}
+	if (record.claimedBy !== instanceId) return { ok: false, reason: "not-claimed" }
+	save(env, items.filter((r) => r.uid !== uid))
+	return { ok: true, sessionId: record.sessionId, ...(record.uidValidity === undefined ? {} : { uidValidity: record.uidValidity }) }
+}
+
+/**
+ * Drop queued records that belong to a different UID numbering.
+ *
+ * A re-indexed mailbox renumbers from 1, so an old UID can collide with a new one and
+ * `addPending` would silently replace a queued reply. The dropped mail is *not* lost: it was
+ * never acked, so it is still unread in the mailbox, and the cursor reset that accompanies
+ * this re-reads it.
+ *
+ * @returns how many records were dropped.
+ */
+export function dropPendingFromOtherSpaces(
+	env: NodeJS.ProcessEnv,
+	uidValidity: number,
+	options: { includeUnknown?: boolean } = {},
+): PendingRecord[] {
+	const items = load(env)
+	// On a detected renumbering, a record that carries no space cannot be shown to belong to the
+	// new numbering - and a live review caught one being claimed there and injecting a different
+	// message's body. Its mail is unread and the reset cursor re-reads it.
+	const keep = (r: PendingRecord): boolean =>
+		r.uidValidity === uidValidity || (r.uidValidity === undefined && !options.includeUnknown)
+	const kept = items.filter(keep)
+	const dropped = items.filter((r) => !keep(r))
+	if (dropped.length > 0) save(env, kept)
+	// Returned, not just counted: the caller releases exactly these sessions' decision slots,
+	// and a second pass over the file could disagree with what was actually removed.
+	return dropped
+}
+
+/** Records older than this, for sessions that are gone, are expired under queue pressure only
+ * (see `process.ts`): never on connect, where a `/mailbridge off` plus a holiday would delete replies. */
+export const PENDING_MAX_AGE_MS = 7 * 24 * 3600_000
+
+/**
+ * Drop records nothing can deliver any more.
+ *
+ * A record whose session never comes back is refused by every runner (`foreign-session`) and
+ * removed by nothing else, so a handful of them can fill `PENDING_CAP` - and at the cap the
+ * scanner stops advancing the cursor, which stalls *all* inbound mail. Expiring them is a
+ * deliberate, bounded loss: their mail stays unread in the mailbox, but the cursor has moved
+ * past it, so it will not be re-read.
+ *
+ * @returns the dropped records, so the caller can release their decision slots.
+ */
+export function expirePending(env: NodeJS.ProcessEnv, maxAgeMs = PENDING_MAX_AGE_MS, now = Date.now()): PendingRecord[] {
+	const items = load(env)
+	const expired = items.filter((r) => now - r.receivedAt > maxAgeMs)
+	if (expired.length === 0) return []
+	save(env, items.filter((r) => now - r.receivedAt <= maxAgeMs))
+	return expired
+}
+
+export function pendingSize(env: NodeJS.ProcessEnv): number {
+	return load(env).length
+}

package/src/store/registry.ts

@@ -0,0 +1,91 @@
+// One-outstanding-decision registry.
+//
+// Why this exists: `request_decision` emails the human and ends the turn. If the
+// agent calls it twice for the same session, the human gets two emails for one
+// decision and can only answer one of them. The registry reserves a slot per
+// session so the second call is refused before any mail is sent.
+//
+// Scope note: this is intentionally **in memory**, owned by the daemon. A daemon
+// restart drops reservations — that is acceptable, because a reply is keyed by
+// its own UID in the pending store, not by a reservation. A dropped reservation
+// can therefore never lose a reply; it can only allow a duplicate *question*.
+//
+// Bounds: entries expire by TTL and the map has a hard cap, because the
+// /register endpoint is reachable by any local session.
+
+export const REGISTRY_TTL_MS = 24 * 60 * 60 * 1000
+export const DEFAULT_MAX_ENTRIES = 10_000
+
+export interface RegisterResult {
+	/** The session already had an outstanding decision. */
+	alreadyPending: boolean
+	/** The cap was hit; the new entry was NOT admitted. */
+	full: boolean
+}
+
+export interface Registry {
+	register(sessionId: string): RegisterResult
+	release(sessionId: string): void
+	has(sessionId: string): boolean
+	size(): number
+	/** Live session ids, for `/mailbridge` output. */
+	list(): string[]
+}
+
+export interface RegistryOptions {
+	ttlMs?: number
+	maxEntries?: number
+	now?: () => number
+}
+
+export function createRegistry(options: RegistryOptions = {}): Registry {
+	const ttlMs = options.ttlMs ?? REGISTRY_TTL_MS
+	const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES
+	const now = options.now ?? (() => Date.now())
+
+	/** sessionId -> last refresh time */
+	const entries = new Map<string, number>()
+
+	/** Lazy prune: a dead entry can never be served after its TTL. */
+	function prune(): void {
+		const cutoff = now() - ttlMs
+		for (const [id, at] of entries) {
+			if (at < cutoff) entries.delete(id)
+		}
+	}
+
+	return {
+		register(sessionId) {
+			prune()
+			const existing = entries.get(sessionId)
+			if (existing !== undefined) {
+				entries.set(sessionId, now()) // refresh TTL
+				return { alreadyPending: true, full: false }
+			}
+			if (entries.size >= maxEntries) {
+				return { alreadyPending: false, full: true }
+			}
+			entries.set(sessionId, now())
+			return { alreadyPending: false, full: false }
+		},
+
+		release(sessionId) {
+			entries.delete(sessionId)
+		},
+
+		has(sessionId) {
+			prune()
+			return entries.has(sessionId)
+		},
+
+		size() {
+			prune()
+			return entries.size
+		},
+
+		list() {
+			prune()
+			return [...entries.keys()]
+		},
+	}
+}