@prjct.app/pi-team 0.6.1 → 0.7.0

package/src/storage/atomic.ts

@@ -0,0 +1,347 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readdir, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, join, relative, sep } from 'node:path';
+
+export const DEFAULT_MAX_RECORD_BYTES = 256 * 1024;
+const LOCK_ATTEMPTS = Array.from({ length: 200 }, (_, index) => index);
+
+export type RecordValidator<T> = (value: unknown) => asserts value is T;
+export type AtomicWriteOptions = {
+  readonly maxBytes?: number;
+  readonly previous?: boolean;
+};
+export type LockOptions = {
+  readonly staleMs?: number;
+  readonly retryMs?: number;
+};
+
+function storageError(message: string, code: string): Error {
+  return Object.assign(new Error(message), { code });
+}
+
+function assertPrivateMode(path: string, info: { mode: number; uid: number }): void {
+  if ((info.mode & 0o077) !== 0 || (process.getuid && info.uid !== process.getuid())) {
+    throw storageError(`Unsafe storage permissions or owner: ${path}.`, 'UNSAFE_STORAGE');
+  }
+}
+
+async function syncDirectory(path: string): Promise<void> {
+  if (process.platform === 'win32') return;
+  const handle = await open(path, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+  try { await handle.sync(); } finally { await handle.close(); }
+}
+
+async function syncCreatedDirectories(firstCreated: string, target: string): Promise<void> {
+  const suffix = relative(firstCreated, target).split(sep).filter(Boolean);
+  const created = [firstCreated, ...suffix.map((_, index) => join(firstCreated, ...suffix.slice(0, index + 1)))];
+  for (const path of created) await syncDirectory(dirname(path));
+}
+
+// mkdir is not a durable publication by itself. Sync every parent that gained
+// a directory entry, from the first recursively created component to the leaf.
+async function createDirectories(path: string, mode: number): Promise<void> {
+  const firstCreated = await mkdir(path, { recursive: true, mode });
+  if (firstCreated) await syncCreatedDirectories(firstCreated, path);
+}
+
+export async function ensurePrivateDirectory(path: string, create = true): Promise<void> {
+  if (create) await createDirectories(path, 0o700);
+  const info = await lstat(path);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw storageError(`Unsafe storage directory: ${path}.`, 'UNSAFE_STORAGE');
+  }
+  assertPrivateMode(path, info);
+}
+
+async function nearestExistingDirectory(path: string): Promise<string> {
+  const info = await lstat(path).catch(error => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (info) {
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw storageError(`Unsafe storage ancestor: ${path}.`, 'UNSAFE_STORAGE');
+    }
+    return path;
+  }
+  const parent = dirname(path);
+  if (parent === path) throw storageError(`No existing storage ancestor for ${path}.`, 'UNSAFE_STORAGE');
+  return nearestExistingDirectory(parent);
+}
+
+async function ensureRootParent(root: string): Promise<void> {
+  const parent = dirname(root);
+  const existing = await nearestExistingDirectory(parent);
+  await createDirectories(parent, 0o700);
+  const suffix = relative(existing, parent).split(sep).filter(Boolean);
+  const chain = [existing, ...suffix.map((_, index) => join(existing, ...suffix.slice(0, index + 1)))];
+  for (const path of chain) {
+    const info = await lstat(path);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      throw storageError(`Unsafe storage ancestor: ${path}.`, 'UNSAFE_STORAGE');
+    }
+  }
+}
+
+export async function ensurePrivateTree(root: string, ...segments: readonly string[]): Promise<void> {
+  await ensureRootParent(root);
+  await ensurePrivateDirectory(root);
+  const paths = segments.map((_, index) => join(root, ...segments.slice(0, index + 1)));
+  for (const path of paths) await ensurePrivateDirectory(path);
+}
+
+function checkSize(text: string, maxBytes: number): void {
+  if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+    throw storageError(`Record exceeds ${maxBytes} bytes.`, 'RECORD_TOO_LARGE');
+  }
+}
+
+async function readText(path: string, maxBytes: number): Promise<string | undefined> {
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch(error => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (!handle) return undefined;
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw storageError(`Unsafe storage file: ${path}.`, 'UNSAFE_STORAGE');
+    assertPrivateMode(path, info);
+    if (info.size > maxBytes) throw storageError(`Record exceeds ${maxBytes} bytes.`, 'RECORD_TOO_LARGE');
+    return await handle.readFile('utf8');
+  } finally { await handle.close(); }
+}
+
+export async function readJson<T>(path: string, validate: RecordValidator<T>, maxBytes = DEFAULT_MAX_RECORD_BYTES): Promise<T | undefined> {
+  const text = await readText(path, maxBytes);
+  if (text === undefined) return undefined;
+  const parsed = (() => {
+    try { return JSON.parse(text) as unknown; }
+    catch { throw storageError(`Corrupt JSON record preserved at ${path}.`, 'CORRUPT_RECORD'); }
+  })();
+  try { validate(parsed); }
+  catch (error) {
+    throw Object.assign(new Error(`Invalid record preserved at ${path}: ${(error as Error).message}`), { code: 'CORRUPT_RECORD' });
+  }
+  return parsed;
+}
+
+async function writeTemporary(path: string, text: string, maxBytes: number): Promise<string> {
+  checkSize(text, maxBytes);
+  await ensurePrivateDirectory(dirname(path));
+  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+  try {
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+  await handle.close();
+  return temporary;
+}
+
+export async function createAtomicJson(path: string, value: unknown, maxBytes = DEFAULT_MAX_RECORD_BYTES): Promise<void> {
+  const temporary = await writeTemporary(path, `${JSON.stringify(value)}\n`, maxBytes);
+  try {
+    await link(temporary, path);
+    await syncDirectory(dirname(path));
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+
+export async function replaceAtomicJson(path: string, value: unknown, options: AtomicWriteOptions = {}): Promise<void> {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_RECORD_BYTES;
+  const text = `${JSON.stringify(value)}\n`;
+  checkSize(text, maxBytes);
+  if (options.previous) {
+    const current = await readText(path, maxBytes);
+    if (current !== undefined) await replaceAtomicText(`${path}.previous`, current, maxBytes);
+  }
+  await replaceAtomicText(path, text, maxBytes);
+}
+
+async function replaceAtomicText(path: string, text: string, maxBytes: number): Promise<void> {
+  const temporary = await writeTemporary(path, text, maxBytes);
+  try {
+    await rename(temporary, path);
+    await syncDirectory(dirname(path));
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+export async function moveAtomic(from: string, to: string): Promise<void> {
+  await ensurePrivateDirectory(dirname(to));
+  await rename(from, to);
+  await syncDirectory(dirname(to));
+  if (dirname(from) !== dirname(to)) await syncDirectory(dirname(from));
+}
+
+export async function removeAtomic(path: string): Promise<boolean> {
+  const removed = await unlink(path).then(() => true, error => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  });
+  if (removed) await syncDirectory(dirname(path));
+  return removed;
+}
+
+export async function jsonFileNames(path: string, create = true): Promise<string[]> {
+  try { await ensurePrivateDirectory(path, create); }
+  catch (error) {
+    if (!create && (error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const entries = await readdir(path, { withFileTypes: true });
+  return entries
+    .filter(entry => entry.isFile() && !entry.isSymbolicLink() && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.json$/.test(entry.name))
+    .map(entry => entry.name.slice(0, -'.json'.length))
+    .sort();
+}
+
+async function processAlive(pid: number): Promise<boolean> {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code !== 'ESRCH'; }
+}
+
+async function staleLock(path: string, staleMs: number): Promise<boolean> {
+  const info = await lstat(path).catch(error => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (!info) return false;
+  if (!info.isFile() || info.isSymbolicLink()) throw storageError(`Unsafe lock file: ${path}.`, 'UNSAFE_STORAGE');
+  assertPrivateMode(path, info);
+  if (Date.now() - info.mtimeMs <= staleMs) return false;
+  const text = await readText(path, 4096);
+  const pid = (() => {
+    try {
+      const parsed = JSON.parse(text ?? '') as { pid?: unknown };
+      return typeof parsed.pid === 'number' && Number.isSafeInteger(parsed.pid) && parsed.pid > 0 ? parsed.pid : undefined;
+    } catch { return undefined; }
+  })();
+  return pid === undefined || !await processAlive(pid);
+}
+
+async function tryAcquireLock(path: string): Promise<{ readonly handle: Awaited<ReturnType<typeof open>>; readonly token: string } | undefined> {
+  const token = randomUUID();
+  const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600)
+    .catch(error => {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') return undefined;
+      throw error;
+    });
+  if (!handle) return undefined;
+  try {
+    await handle.writeFile(JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() }), 'utf8');
+    return { handle, token };
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await unlink(path).catch(() => {});
+    throw error;
+  }
+}
+
+async function releaseLock(path: string, token: string): Promise<void> {
+  const text = await readText(path, 4096).catch(() => undefined);
+  const currentToken = (() => {
+    try { return (JSON.parse(text ?? '') as { token?: unknown }).token; }
+    catch { return undefined; }
+  })();
+  if (currentToken === token) await unlink(path).catch(() => {});
+}
+
+type GateResult<T> = { readonly entered: false } | { readonly entered: true; readonly value: T };
+
+// Main-lock replacement and release run only while this short-lived gate is
+// owned. Stale gates are reclaimed only for dead holders and only while their
+// inode still matches the inspected handle; a changed pathname is left alone.
+async function reclaimStaleGate(path: string, staleMs: number): Promise<boolean> {
+  const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch(error => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (!handle) return false;
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw storageError(`Unsafe lock gate: ${path}.`, 'UNSAFE_STORAGE');
+    assertPrivateMode(path, info);
+    if (Date.now() - info.mtimeMs <= staleMs) return false;
+    const text = await handle.readFile('utf8');
+    const parsed = (() => {
+      try { return JSON.parse(text) as { pid?: unknown }; }
+      catch { return {} as { pid?: unknown }; }
+    })();
+    const pid = typeof parsed.pid === 'number' && Number.isSafeInteger(parsed.pid) && parsed.pid > 0 ? parsed.pid : undefined;
+    if (pid !== undefined && await processAlive(pid)) return false;
+    const current = await lstat(path).catch(() => undefined);
+    if (!current || current.dev !== info.dev || current.ino !== info.ino) return false;
+    await unlink(path);
+    return true;
+  } finally { await handle.close(); }
+}
+
+async function underLockGate<T>(path: string, staleMs: number, action: () => Promise<T>): Promise<GateResult<T>> {
+  const gatePath = `${path}.gate`;
+  const token = randomUUID();
+  const gate = await open(
+    gatePath,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+    0o600,
+  ).catch(async error => {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    await reclaimStaleGate(gatePath, staleMs);
+    return undefined;
+  });
+  if (!gate) return { entered: false };
+  try {
+    await gate.writeFile(JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() }), 'utf8');
+    return { entered: true, value: await action() };
+  } finally {
+    await gate.close();
+    await releaseLock(gatePath, token);
+  }
+}
+
+async function claimLock(path: string, staleMs: number): Promise<GateResult<Awaited<ReturnType<typeof tryAcquireLock>>>> {
+  return underLockGate(path, staleMs, async () => {
+    const current = await tryAcquireLock(path);
+    if (current) return current;
+    if (!await staleLock(path, staleMs)) return undefined;
+    await unlink(path);
+    return tryAcquireLock(path);
+  });
+}
+
+async function releaseOwnedLock(path: string, token: string, retryMs: number, staleMs: number): Promise<void> {
+  for (const attempt of LOCK_ATTEMPTS) {
+    const released = await underLockGate(path, staleMs, () => releaseLock(path, token));
+    if (released.entered) return;
+    await new Promise(resolve => setTimeout(resolve, retryMs + Math.min(attempt, 20)));
+  }
+  throw storageError(`Storage lock gate is busy: ${path}.`, 'STORAGE_BUSY');
+}
+
+export async function withStorageLock<T>(path: string, action: () => Promise<T>, options: LockOptions = {}): Promise<T> {
+  const staleMs = options.staleMs ?? 30_000;
+  const retryMs = options.retryMs ?? 5;
+  if (!Number.isFinite(staleMs) || staleMs < 0 || !Number.isFinite(retryMs) || retryMs <= 0) {
+    throw new Error('Invalid storage lock timing.');
+  }
+  await ensurePrivateDirectory(dirname(path));
+  for (const attempt of LOCK_ATTEMPTS) {
+    const claim = await claimLock(path, staleMs);
+    const owned = claim.entered ? claim.value : undefined;
+    if (owned) {
+      try { return await action(); }
+      finally {
+        await owned.handle.close();
+        await releaseOwnedLock(path, owned.token, retryMs, staleMs);
+      }
+    }
+    await new Promise(resolve => setTimeout(resolve, retryMs + Math.min(attempt, 20)));
+  }
+  throw storageError(`Storage lock is busy: ${path}.`, 'STORAGE_BUSY');
+}

package/src/storage/inbox-store.ts

@@ -0,0 +1,290 @@
+import { readdir } from 'node:fs/promises';
+import { assertMember, type Member } from '../domain/member.ts';
+import { assertEnvelope, messageExpired, type Envelope } from '../domain/message.ts';
+import { assertTeam, assertEntityId, assertTeamId } from '../domain/team.ts';
+import {
+  createAtomicJson, ensurePrivateDirectory, ensurePrivateTree, jsonFileNames, moveAtomic, readJson, removeAtomic,
+  withStorageLock,
+} from './atomic.ts';
+import { TeamPaths } from './paths.ts';
+
+// JSON escaping can expand a valid 8 KiB control-character body to six bytes
+// per input byte, so the record cap must bound metadata without rejecting it.
+const MESSAGE_MAX_BYTES = 64 * 1024;
+const TEAM_MAX_BYTES = 32 * 1024;
+const MEMBER_MAX_BYTES = 64 * 1024;
+
+export type InboxStoreOptions = {
+  readonly recipientQuota?: number;
+  readonly teamQuota?: number;
+  readonly now?: () => number;
+};
+
+export type InboxPage = {
+  readonly messages: readonly Envelope[];
+  readonly nextCursor?: string;
+};
+
+export class InboxStore {
+  private readonly recipientQuota: number;
+  private readonly teamQuota: number;
+  private readonly now: () => number;
+
+  constructor(readonly paths: TeamPaths, options: InboxStoreOptions = {}) {
+    this.recipientQuota = options.recipientQuota ?? 100;
+    this.teamQuota = options.teamQuota ?? 1_000;
+    this.now = options.now ?? Date.now;
+    if (!Number.isSafeInteger(this.recipientQuota) || this.recipientQuota < 1 ||
+        !Number.isSafeInteger(this.teamQuota) || this.teamQuota < this.recipientQuota) {
+      throw new Error('Invalid inbox quotas.');
+    }
+  }
+
+  private async prepare(): Promise<void> {
+    await ensurePrivateTree(this.paths.root, 'teams');
+    await ensurePrivateTree(this.paths.root, 'control');
+  }
+
+  private async requireTeam(teamId: string, requireOpen = false): Promise<void> {
+    try {
+      await ensurePrivateDirectory(this.paths.team(teamId), false);
+      await ensurePrivateDirectory(this.paths.members(teamId), false);
+      await ensurePrivateDirectory(this.paths.inbox(teamId), false);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw Object.assign(new Error(`Unknown team "${teamId}".`), { code: 'NOT_FOUND' });
+      }
+      throw error;
+    }
+    const team = await readJson(this.paths.teamRecord(teamId), assertTeam, TEAM_MAX_BYTES);
+    if (!team) throw Object.assign(new Error(`Team "${teamId}" is incomplete.`), { code: 'NOT_FOUND' });
+    if (requireOpen && team.state !== 'open') {
+      throw Object.assign(new Error(`Team "${teamId}" is ${team.state}.`), { code: 'TEAM_CLOSED' });
+    }
+  }
+
+  private async member(teamId: string, memberId: string): Promise<Member> {
+    await ensurePrivateDirectory(this.paths.members(teamId), false);
+    const member = await readJson(this.paths.member(teamId, memberId), assertMember, MEMBER_MAX_BYTES);
+    if (!member || member.teamId !== teamId || member.memberId !== memberId) {
+      throw Object.assign(new Error(`Unknown member "${memberId}".`), { code: 'NOT_FOUND' });
+    }
+    return member;
+  }
+
+  private async prepareRecipient(teamId: string, memberId: string, create: boolean): Promise<boolean> {
+    try {
+      await ensurePrivateDirectory(this.paths.inbox(teamId), false);
+      await ensurePrivateDirectory(this.paths.memberInbox(teamId, memberId), create);
+      await ensurePrivateDirectory(this.paths.pending(teamId, memberId), create);
+      await ensurePrivateDirectory(this.paths.claimed(teamId, memberId), create);
+      return true;
+    } catch (error) {
+      if (!create && (error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+      throw error;
+    }
+  }
+
+  private async memberCount(teamId: string, memberId: string): Promise<number> {
+    if (!await this.prepareRecipient(teamId, memberId, false)) return 0;
+    const [pending, claimed] = await Promise.all([
+      jsonFileNames(this.paths.pending(teamId, memberId), false),
+      jsonFileNames(this.paths.claimed(teamId, memberId), false),
+    ]);
+    return pending.length + claimed.length;
+  }
+
+  private async inboxMemberIds(teamId: string): Promise<string[]> {
+    const entries = await readdir(this.paths.inbox(teamId), { withFileTypes: true }).catch(error => {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    });
+    return entries
+      .filter(entry => entry.isDirectory() && !entry.isSymbolicLink())
+      .map(entry => entry.name)
+      .filter(memberId => {
+        try { assertEntityId(memberId, 'member ID'); return true; }
+        catch { return false; }
+      });
+  }
+
+  private async teamCount(teamId: string): Promise<number> {
+    const counts = await Promise.all((await this.inboxMemberIds(teamId)).map(memberId => this.memberCount(teamId, memberId)));
+    return counts.reduce((sum, count) => sum + count, 0);
+  }
+
+  private async teamHasMessage(teamId: string, messageId: string): Promise<boolean> {
+    const matches = await Promise.all((await this.inboxMemberIds(teamId)).map(async memberId => {
+      if (!await this.prepareRecipient(teamId, memberId, false)) return false;
+      const [pending, claimed] = await Promise.all([
+        jsonFileNames(this.paths.pending(teamId, memberId), false),
+        jsonFileNames(this.paths.claimed(teamId, memberId), false),
+      ]);
+      return pending.includes(messageId) || claimed.includes(messageId);
+    }));
+    return matches.some(Boolean);
+  }
+
+  private assertStoredMessage(message: Envelope, teamId: string, recipientId: string, messageId?: string): void {
+    if (message.teamId !== teamId || message.toMemberId !== recipientId || (messageId && message.messageId !== messageId)) {
+      throw Object.assign(new Error('Message identity does not match its storage path.'), { code: 'CORRUPT_RECORD' });
+    }
+  }
+
+  async enqueue(message: Envelope): Promise<void> {
+    assertEnvelope(message);
+    await this.prepare();
+    await withStorageLock(this.paths.inboxLock(message.teamId), async () => {
+      await this.requireTeam(message.teamId, true);
+      if (messageExpired(message, this.now())) throw Object.assign(new Error('Message has already expired.'), { code: 'EXPIRED' });
+      const [sender, recipient] = await Promise.all([
+        this.member(message.teamId, message.fromMemberId),
+        this.member(message.teamId, message.toMemberId),
+      ]);
+      if (sender.generation !== message.senderGeneration ||
+          (message.recipientGeneration !== undefined && recipient.generation !== message.recipientGeneration)) {
+        throw Object.assign(new Error('Message generation has been fenced.'), { code: 'FENCED' });
+      }
+      const [recipientCount, teamCount, duplicate] = await Promise.all([
+        this.memberCount(message.teamId, message.toMemberId),
+        this.teamCount(message.teamId),
+        this.teamHasMessage(message.teamId, message.messageId),
+      ]);
+      if (duplicate) throw Object.assign(new Error(`Message "${message.messageId}" already exists.`), { code: 'ALREADY_EXISTS' });
+      if (recipientCount >= this.recipientQuota) {
+        throw Object.assign(new Error(`Recipient inbox quota reached (${this.recipientQuota}).`), { code: 'QUOTA_EXCEEDED' });
+      }
+      if (teamCount >= this.teamQuota) {
+        throw Object.assign(new Error(`Team inbox quota reached (${this.teamQuota}).`), { code: 'QUOTA_EXCEEDED' });
+      }
+      await this.prepareRecipient(message.teamId, message.toMemberId, true);
+      await createAtomicJson(
+        this.paths.pendingMessage(message.teamId, message.toMemberId, message.messageId),
+        message,
+        MESSAGE_MAX_BYTES,
+      );
+    });
+  }
+
+  async readPending(teamId: string, recipientId: string, messageId: string): Promise<Envelope | undefined> {
+    await this.prepare();
+    await this.requireTeam(teamId);
+    if (!await this.prepareRecipient(teamId, recipientId, false)) return undefined;
+    const message = await readJson(this.paths.pendingMessage(teamId, recipientId, messageId), assertEnvelope, MESSAGE_MAX_BYTES);
+    if (message) this.assertStoredMessage(message, teamId, recipientId, messageId);
+    return message;
+  }
+
+  async readClaimed(teamId: string, recipientId: string, messageId: string): Promise<Envelope | undefined> {
+    await this.prepare();
+    await this.requireTeam(teamId);
+    if (!await this.prepareRecipient(teamId, recipientId, false)) return undefined;
+    const message = await readJson(this.paths.claimedMessage(teamId, recipientId, messageId), assertEnvelope, MESSAGE_MAX_BYTES);
+    if (message) this.assertStoredMessage(message, teamId, recipientId, messageId);
+    return message;
+  }
+
+  async listPending(teamId: string, recipientId: string, limit = 50, cursor?: string): Promise<InboxPage> {
+    assertTeamId(teamId);
+    assertEntityId(recipientId, 'recipient ID');
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('Inbox page limit must be between 1 and 100.');
+    if (cursor !== undefined) assertEntityId(cursor, 'inbox cursor');
+    await this.prepare();
+    await this.requireTeam(teamId);
+    if (!await this.prepareRecipient(teamId, recipientId, false)) return { messages: [] };
+    const ids = await jsonFileNames(this.paths.pending(teamId, recipientId), false);
+    const remaining = cursor === undefined ? ids : ids.filter(id => id > cursor);
+    const pageIds = remaining.slice(0, limit);
+    const records = await Promise.all(pageIds.map(id => this.readPending(teamId, recipientId, id)));
+    const messages = records.filter((message): message is Envelope => message !== undefined);
+    const nextCursor = remaining.length > limit ? pageIds.at(-1) : undefined;
+    return { messages, ...(nextCursor ? { nextCursor } : {}) };
+  }
+
+  async listClaimed(teamId: string, recipientId: string, limit = 50, cursor?: string): Promise<InboxPage> {
+    assertTeamId(teamId);
+    assertEntityId(recipientId, 'recipient ID');
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('Inbox page limit must be between 1 and 100.');
+    if (cursor !== undefined) assertEntityId(cursor, 'inbox cursor');
+    await this.prepare();
+    await this.requireTeam(teamId);
+    if (!await this.prepareRecipient(teamId, recipientId, false)) return { messages: [] };
+    const ids = await jsonFileNames(this.paths.claimed(teamId, recipientId), false);
+    const remaining = cursor === undefined ? ids : ids.filter(id => id > cursor);
+    const pageIds = remaining.slice(0, limit);
+    const records = await Promise.all(pageIds.map(id => this.readClaimed(teamId, recipientId, id)));
+    const messages = records.filter((message): message is Envelope => message !== undefined);
+    const nextCursor = remaining.length > limit ? pageIds.at(-1) : undefined;
+    return { messages, ...(nextCursor ? { nextCursor } : {}) };
+  }
+
+  async claim(teamId: string, recipientId: string, messageId: string): Promise<Envelope> {
+    await this.prepare();
+    return withStorageLock(this.paths.inboxLock(teamId), async () => {
+      await this.requireTeam(teamId, true);
+      const message = await this.readPending(teamId, recipientId, messageId);
+      if (!message) throw Object.assign(new Error(`Unknown pending message "${messageId}".`), { code: 'NOT_FOUND' });
+      if (messageExpired(message, this.now())) throw Object.assign(new Error('Message has expired.'), { code: 'EXPIRED' });
+      await this.prepareRecipient(teamId, recipientId, true);
+      await moveAtomic(
+        this.paths.pendingMessage(teamId, recipientId, messageId),
+        this.paths.claimedMessage(teamId, recipientId, messageId),
+      );
+      return message;
+    });
+  }
+
+  async release(teamId: string, recipientId: string, messageId: string): Promise<void> {
+    await this.prepare();
+    await withStorageLock(this.paths.inboxLock(teamId), async () => {
+      await this.requireTeam(teamId);
+      const message = await readJson(
+        this.paths.claimedMessage(teamId, recipientId, messageId), assertEnvelope, MESSAGE_MAX_BYTES,
+      );
+      if (!message) throw Object.assign(new Error(`Unknown claimed message "${messageId}".`), { code: 'NOT_FOUND' });
+      this.assertStoredMessage(message, teamId, recipientId, messageId);
+      await this.prepareRecipient(teamId, recipientId, true);
+      await moveAtomic(
+        this.paths.claimedMessage(teamId, recipientId, messageId),
+        this.paths.pendingMessage(teamId, recipientId, messageId),
+      );
+    });
+  }
+
+  async removePending(teamId: string, recipientId: string, messageId: string): Promise<boolean> {
+    await this.prepare();
+    return withStorageLock(this.paths.inboxLock(teamId), async () => {
+      await this.requireTeam(teamId);
+      if (!await this.prepareRecipient(teamId, recipientId, false)) return false;
+      return removeAtomic(this.paths.pendingMessage(teamId, recipientId, messageId));
+    });
+  }
+
+  async removeClaimed(teamId: string, recipientId: string, messageId: string): Promise<boolean> {
+    await this.prepare();
+    return withStorageLock(this.paths.inboxLock(teamId), async () => {
+      await this.requireTeam(teamId);
+      if (!await this.prepareRecipient(teamId, recipientId, false)) return false;
+      return removeAtomic(this.paths.claimedMessage(teamId, recipientId, messageId));
+    });
+  }
+
+  async purgeExpired(teamId: string, recipientId: string): Promise<number> {
+    await this.prepare();
+    return withStorageLock(this.paths.inboxLock(teamId), async () => {
+      await this.requireTeam(teamId);
+      if (!await this.prepareRecipient(teamId, recipientId, false)) return 0;
+      const directories = [this.paths.pending(teamId, recipientId), this.paths.claimed(teamId, recipientId)];
+      const idsByDirectory = await Promise.all(directories.map(path => jsonFileNames(path, false)));
+      const candidates = directories.flatMap((path, index) => idsByDirectory[index].map(id => ({ path, id })));
+      const expired = (await Promise.all(candidates.map(async candidate => {
+        const message = await readJson(`${candidate.path}/${candidate.id}.json`, assertEnvelope, MESSAGE_MAX_BYTES);
+        if (!message) return undefined;
+        this.assertStoredMessage(message, teamId, recipientId, candidate.id);
+        return messageExpired(message, this.now()) ? candidate : undefined;
+      }))).filter((candidate): candidate is { path: string; id: string } => candidate !== undefined);
+      await Promise.all(expired.map(candidate => removeAtomic(`${candidate.path}/${candidate.id}.json`)));
+      return expired.length;
+    });
+  }
+}