@proteinjs/user-server 1.7.0 → 1.9.0

package/src/authentication/establishSession.ts

@@ -0,0 +1,33 @@
+/**
+ * The ONE owner of session establishment. Every door that mints a session — login, dev login,
+ * signup auto-login — goes through here; no route calls `request.login` directly.
+ *
+ * The full contract — regenerate → bind → save, all committed before the caller responds — is
+ * passport's own since 0.6 (its CVE-2022-25896 session-fixation fix). `request.login` runs
+ * SessionManager.logIn: `session.regenerate` mints a FRESH session id on the privilege change
+ * (an attacker-planted pre-auth sid never survives authentication), serializeUser binds the
+ * account email onto the fresh session, and `session.save` commits the row before the callback
+ * runs. The save half matters with a DB-backed session store: relying on save-at-response-end
+ * races the client's follow-up navigation — the next request can read the session row before
+ * the write commits and render the login page (observed live on /dev/login; the race class is
+ * identical for every session-minting door).
+ *
+ * Deliberately NO regenerate or save around `request.login`: passport 0.6 offers no way to
+ * disable its internal regenerate (`keepSessionInfo` only merges old session data back in after
+ * regenerating), so a wrapper-level regenerate would mint two ids per login — one owner of the
+ * lifecycle, and it is passport. SignupRoute.test.ts pins the exactly-once ordering against the
+ * real passport machinery.
+ *
+ * COUPLED to the passport 0.6 upgrade in @proteinjs/server (which supplies the runtime passport
+ * middleware): under passport 0.4, `request.login` neither regenerates nor saves — shipping this
+ * package against a pre-0.6 @proteinjs/server would silently reopen both holes.
+ *
+ * `request` is typed loosely because passport augments the express request at runtime; the
+ * routes in this package share that convention. A login failure (regenerate/serialize/save
+ * error) rejects — a door must never answer success for a session that did not commit.
+ */
+export async function establishSession(request: any, email: string): Promise<void> {
+  await new Promise<void>((resolve, reject) =>
+    request.login(email, (error: unknown) => (error ? reject(error) : resolve()))
+  );
+}

package/src/authorization/userCache.ts

@@ -27,7 +27,15 @@ export const userCache: SessionDataCache<User> = {
         user = adminUser;
       } else {
         const accountUser = await getDbAsSystem().get(tables.User, { email: userEmail.toLowerCase() });
-        if (accountUser) {
+        if (accountUser && accountUser.status === 'deactivated') {
+          // The session half of the deactivation gate (login half in authenticate): the session
+          // cache is rebuilt per request, so a live session stops resolving the moment the
+          // account is deactivated — every request runs as the unauthenticated guest.
+          logger.warn({
+            message: `Session references a deactivated account; resolving as unauthenticated`,
+            obj: { sessionId, userEmail },
+          });
+        } else if (accountUser) {
           delete (accountUser as any)['password'];
           user = accountUser;
         } else {

package/src/emails/AccountDeletionEmailConfigs.ts

@@ -0,0 +1,79 @@
+import { Loadable, SourceRepository } from '@proteinjs/reflection';
+import Mail from 'nodemailer/lib/mailer';
+import { Moment } from 'moment';
+
+/**
+ * Config-factory seams for the two account-deletion emails (the PasswordResetEmailConfig
+ * pattern; the interfaces live here because @proteinjs/email-server is a registry package).
+ * Both emails are self-contained notifications, so each getter carries default content (the
+ * PasswordUpdatedEmailConfig precedent) — an app implements the factory to override.
+ */
+
+export interface AccountDeletionRequestedEmailConfig {
+  /** @see https://nodemailer.com/message/ for all available options */
+  options?: Mail.Options;
+  /** @param purgeAfter when the grace window ends and the account is permanently erased */
+  getEmailContent: (purgeAfter: Moment) => {
+    text: string;
+    html?: string;
+  };
+}
+
+export interface DefaultAccountDeletionRequestedEmailConfigFactory extends Loadable {
+  getConfig(): AccountDeletionRequestedEmailConfig;
+}
+
+export const getDefaultAccountDeletionRequestedEmailConfigFactory =
+  (): DefaultAccountDeletionRequestedEmailConfigFactory => {
+    const defaultFactory: DefaultAccountDeletionRequestedEmailConfigFactory = {
+      getConfig: () => ({
+        options: { subject: 'Your account is scheduled for deletion' },
+        getEmailContent: (purgeAfter: Moment) => ({
+          text:
+            `Your account is scheduled for deletion. Your content is no longer visible to you or to ` +
+            `anyone you shared it with. You can change your mind until ${purgeAfter.format('MMMM D, YYYY')} ` +
+            `by simply logging back in — that restores everything, including shares. After that date, your ` +
+            `account and everything in it are permanently removed from our systems, and we'll email you to ` +
+            `confirm when it's done. If you didn't request this, log back in now to cancel.`,
+        }),
+      }),
+    };
+
+    const retrievedFactory = SourceRepository.get().object<DefaultAccountDeletionRequestedEmailConfigFactory>(
+      '@proteinjs/user-server/DefaultAccountDeletionRequestedEmailConfigFactory'
+    );
+
+    return retrievedFactory || defaultFactory;
+  };
+
+export interface AccountDeletedEmailConfig {
+  /** @see https://nodemailer.com/message/ for all available options */
+  options?: Mail.Options;
+  getEmailContent: () => {
+    text: string;
+    html?: string;
+  };
+}
+
+export interface DefaultAccountDeletedEmailConfigFactory extends Loadable {
+  getConfig(): AccountDeletedEmailConfig;
+}
+
+export const getDefaultAccountDeletedEmailConfigFactory = (): DefaultAccountDeletedEmailConfigFactory => {
+  const defaultFactory: DefaultAccountDeletedEmailConfigFactory = {
+    getConfig: () => ({
+      options: { subject: 'Your account has been deleted' },
+      getEmailContent: () => ({
+        text:
+          `Your account and everything in it have been permanently removed from our systems. ` +
+          `This is the confirmation you were promised when you requested deletion. Goodbye, and thank you.`,
+      }),
+    }),
+  };
+
+  const retrievedFactory = SourceRepository.get().object<DefaultAccountDeletedEmailConfigFactory>(
+    '@proteinjs/user-server/DefaultAccountDeletedEmailConfigFactory'
+  );
+
+  return retrievedFactory || defaultFactory;
+};

package/src/emails/AccountDeletionEmails.ts

@@ -0,0 +1,39 @@
+import { Moment } from 'moment';
+import { EmailSender } from '@proteinjs/email-server';
+import {
+  getDefaultAccountDeletedEmailConfigFactory,
+  getDefaultAccountDeletionRequestedEmailConfigFactory,
+} from './AccountDeletionEmailConfigs';
+
+/**
+ * Thin sender for the two account-deletion emails: deletion-requested (at deactivation — the
+ * only cancel channel an account-takeover victim has) and the store-required completion
+ * confirmation (sent by the purge walker after the user row is gone). Content comes from the
+ * config factories beside this class; transport is the app's DefaultEmailConfigFactory SMTP
+ * config via EmailSender.
+ */
+export class AccountDeletionEmails {
+  async sendDeletionRequested(to: string, purgeAfter: Moment): Promise<void> {
+    const config = getDefaultAccountDeletionRequestedEmailConfigFactory().getConfig();
+    const { text, html } = config.getEmailContent(purgeAfter);
+    await new EmailSender().sendEmail({
+      to,
+      subject: 'Your account is scheduled for deletion',
+      text,
+      html,
+      ...config.options,
+    });
+  }
+
+  async sendAccountDeleted(to: string): Promise<void> {
+    const config = getDefaultAccountDeletedEmailConfigFactory().getConfig();
+    const { text, html } = config.getEmailContent();
+    await new EmailSender().sendEmail({
+      to,
+      subject: 'Your account has been deleted',
+      text,
+      html,
+      ...config.options,
+    });
+  }
+}

package/src/routes/devLogin.ts

@@ -1,5 +1,6 @@
 import { Route } from '@proteinjs/server-api';
 import { Logger } from '@proteinjs/logger';
+import { establishSession } from '../authentication/establishSession';
 import { Signup } from '../services/Signup';
 
 const logger = new Logger({ name: 'devLogin' });
@@ -61,12 +62,9 @@ export const devLogin: Route = {
       logger.info({ message: 'Dev auto-login created missing test account', obj: { email } });
     }
 
-    await new Promise((resolve) => request.login(email, resolve));
-    // Explicit save before redirecting: with a DB-backed session store, save-on-response-end
-    // races the redirected GET / — the follow-up request can read the session row before the
-    // write commits and render the login page (observed: first /dev/login load lands on /login,
-    // second succeeds). Awaiting the store write closes the race.
-    await new Promise((resolve) => request.session.save(resolve));
+    // establishSession commits the session row before the redirect — the redirected GET / must
+    // never read the store ahead of the write (observed: first /dev/login load landed on /login).
+    await establishSession(request, email);
     logger.info({ message: 'Dev auto-login session established', obj: { email } });
     response.redirect('/');
   },

package/src/routes/executePasswordReset.ts

@@ -3,7 +3,7 @@ import { getDbAsSystem } from '@proteinjs/db';
 import { routes, tables } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
 import moment from 'moment';
-import sha256 from 'crypto-js/sha256';
+import { PasswordHasher } from '../authentication/PasswordHasher';
 
 /**
  * Route handler for executing a password reset.
@@ -42,7 +42,7 @@ export const executePasswordReset: Route = {
     }
 
     // Update user's password
-    const hashedPassword = sha256(newPassword).toString();
+    const hashedPassword = await new PasswordHasher().hash(newPassword);
     await db.update(tables.User, {
       id: user.id,
       password: hashedPassword,

package/src/routes/login.ts

@@ -1,6 +1,8 @@
 import { Route } from '@proteinjs/server-api';
 import { routes } from '@proteinjs/user';
 import { authenticate } from '../authentication/authenticate';
+import { establishSession } from '../authentication/establishSession';
+import { AccountDeletion } from '../services/AccountDeletion';
 
 export const login: Route = {
   path: routes.login.path,
@@ -21,9 +23,29 @@ export const login: Route = {
       return;
     }
 
-    await new Promise((resolve, reject) => {
-      request.login(credentials.email, resolve);
-    });
+    // Cancel-by-login: a pending-deletion account's successful authentication IS the cancel
+    // signal. The restore runs synchronously here, BEFORE request.login, so the first
+    // authenticated paint sees the fully restored account (no transient).
+    let outcome: Awaited<ReturnType<AccountDeletion['cancelPendingDeletion']>>;
+    try {
+      outcome = await new AccountDeletion().cancelPendingDeletion(credentials.email);
+    } catch (error) {
+      // Security boundary: the login response never carries internal error detail — an
+      // attacker probing emails must learn nothing from failure shapes (founder ruling
+      // 2026-08-18 after a watcher error surfaced verbatim in the login form). The real
+      // error stays loud in the server log.
+      console.error('cancelPendingDeletion failed during login', error);
+      response.send({ error: 'Unable to log in right now. Please try again.' });
+      return;
+    }
+    if (outcome === 'purging') {
+      const error = 'This account is being deleted and can no longer be restored.';
+      console.error(error);
+      response.send({ error });
+      return;
+    }
+
+    await establishSession(request, credentials.email);
     response.send({});
   },
 };

package/src/routes/logout.ts

@@ -1,28 +1,23 @@
 import { Route } from '@proteinjs/server-api';
 import { routes } from '@proteinjs/user';
-import { destroySession } from '../authentication/destroySession';
 
+/**
+ * Logout rides passport's own `request.logout` (functional for store-backed sessions since
+ * passport 0.6, which added the callback form): it clears the user from the session and SAVES —
+ * a replayed old session id is logged out even before the id rotates — then REGENERATES the
+ * session id (fixation hygiene on the privilege change, mirroring login's rotation). The
+ * regenerate destroys the old session row through the store (`DbSessionStore.destroy`), whose
+ * row delete also disconnects the session's sockets (SocketIOSessionWatcher). The pre-0.6
+ * manual compensation — calling `destroySession` and nulling `session.passport.user` by hand
+ * because `request.logout` was broken — is retired with the workaround era that spawned it.
+ */
 export const logout: Route = {
   path: routes.logout.path,
   method: routes.logout.method,
   onRequest: async (request: any, response): Promise<void> => {
-    // request.logout();
-    // await request.session.destroy();
-    // await new Promise((resolve, reject) => {
-    //     request.session?.destroy((error: any) => {
-    //         if (error) {
-    //             reject(error);
-    //             return;
-    //         }
-
-    //         resolve();
-    //     });
-    // });
-    // delete request._passport?.session?.user;
-    // console.info(`request.sessionID: ${request.sessionID}`);
-    // console.info(`request.session?.id: ${request.session?.id}`);
-    await destroySession(request.sessionID);
-    request.session.passport.user = null;
+    await new Promise<void>((resolve, reject) =>
+      request.logout((error: unknown) => (error ? reject(error) : resolve()))
+    );
     response.redirect('/login');
   },
 };

package/src/routes/signup.ts

@@ -0,0 +1,55 @@
+import { Route } from '@proteinjs/server-api';
+import { Logger } from '@proteinjs/logger';
+import { UserSignup, routes } from '@proteinjs/user';
+import { establishSession } from '../authentication/establishSession';
+import { Signup } from '../services/Signup';
+
+const logger = new Logger({ name: 'signup' });
+
+/**
+ * `POST /user/signup` — create the account AND establish its session in the same request
+ * (auto-login), so a new user lands in the app instead of being bounced to the login form to
+ * re-type the credentials they just submitted. Signup lives at the route layer beside login
+ * because session establishment is a request-level concern services never see; the domain flow
+ * (invite validation, account creation, notification emails) stays owned by `Signup.createUser`.
+ *
+ * Body: `UserSignup` (+ optional invite `token`; the invite carries the email on that path).
+ * Response mirrors the login route's contract: 200 with `{}` on success, `{ error }` with
+ * user-readable copy otherwise.
+ *
+ * When the email is already registered the response is byte-identical to success but NO session
+ * is minted — auto-login must never hand out a session for an account the caller didn't just
+ * create; the caller falls through to the login screen exactly as before. Existence is reported
+ * to the mailbox owner by email, never to the caller.
+ */
+export const signup: Route = {
+  path: routes.signup.path,
+  method: routes.signup.method,
+  onRequest: async (request: any, response): Promise<void> => {
+    const body: Partial<UserSignup> & { token?: string } = request.body ?? {};
+    if (!body.name || !body.password) {
+      response.send({ error: 'Name and password cannot be blank' });
+      return;
+    }
+
+    let result;
+    try {
+      result = await new Signup().createUser(
+        { name: body.name, email: body.email, password: body.password },
+        body.token
+      );
+    } catch (error: any) {
+      // createUser throws plain-words errors deliberately (invite expired / invite required /
+      // email missing); the message is the user-facing contract, same as the RPC layer's.
+      logger.error({ message: 'Signup failed', error });
+      response.send({ error: error instanceof Error ? error.message : 'Sign up failed.' });
+      return;
+    }
+
+    if (result.outcome === 'created') {
+      await establishSession(request, result.email);
+    }
+
+    response.send({});
+  },
+};

package/src/routes/validateResetPasswordToken.ts

@@ -34,6 +34,10 @@ export const validateResetPasswordToken: Route = {
       return;
     }
 
-    response.status(200).send({ isValid: true });
+    // The account email rides the VALID response only: the reset page renders it as the
+    // read-only `autocomplete="username"` field so password managers associate the updated
+    // password with the stored credential. The token was delivered to this very inbox, so a
+    // valid-token holder learns nothing new; invalid/expired verdicts stay email-free.
+    response.status(200).send({ isValid: true, email: user.email });
   },
 };

package/src/services/AccountDeletion.ts

@@ -0,0 +1,291 @@
+import moment, { Moment } from 'moment';
+import { Db, QueryBuilderFactory, Reference, getDbAsSystem } from '@proteinjs/db';
+import { Logger } from '@proteinjs/logger';
+import { Service } from '@proteinjs/service';
+import {
+  AccessGrant,
+  AccountDeletion as AccountDeletionRecord,
+  AccountDeletionService,
+  ManifestGrant,
+  User,
+  UserRepo,
+  tables,
+} from '@proteinjs/user';
+import { DefaultAdminCredentials } from '../authentication/DefaultAdminCredentials';
+import { PasswordHasher } from '../authentication/PasswordHasher';
+import { AccountDeletionEmails } from '../emails/AccountDeletionEmails';
+import { SetUserStatus } from './SetUserStatus';
+
+/** IN-list chunk size for grant enumeration/revocation (the Db.ts IN-chunk precedent). */
+const GRANT_CHUNK_SIZE = 100;
+
+/**
+ * Deactivation ("gone right away") + cancel-by-login — the synchronous half of archive-then-purge.
+ * The purge walker (flow-server) owns erasure after the grace window; this service owns entering
+ * and leaving the deactivated state, driven by the `account_deletion` manifest row.
+ *
+ * Deliberately NOT deactivation's job: the user's own content_reference/content_seen/pins/
+ * notifications — all scoped to the locked-out user, invisible behind the auth gate, purged by
+ * the walker. Leaving them preserves watermarks and pins exactly for cancel-restore.
+ */
+export class AccountDeletion implements AccountDeletionService {
+  /** Any authenticated user — the call acts only on the session user (re-auth inside). */
+  public serviceMetadata: Service['serviceMetadata'] = {
+    auth: {
+      allUsers: true,
+    },
+  };
+  private logger = new Logger({ name: this.constructor.name });
+
+  /**
+   * §3.3 — seven steps, each idempotent; a re-call after a partial failure resumes from the
+   * stored manifest. The caller's sessions die last, so the response is the last authenticated
+   * exchange.
+   */
+  async requestDeletion(password: string): Promise<{ purgeAfter: Moment }> {
+    // 1. Re-auth — a miss throws with nothing written.
+    const user = await this.reauthenticateSessionUser(password);
+    const db = getDbAsSystem();
+
+    // 2. Resume check: an existing row means a prior call crashed mid-flight — resume with the
+    // STORED manifest, never re-enumerate (after a partial revocation the live grants
+    // under-count; rebuilding would clobber the manifest with the shrunken set).
+    let deletion = await db.get(tables.AccountDeletion, { userId: user.id });
+
+    // 3. Enumerate + persist — the manifest is durable BEFORE any mutation.
+    if (!deletion) {
+      deletion = await this.createDeletionManifest(db, user);
+    }
+
+    // 4. Revoke. Watchers fire per Db.delete: the grant watcher removes grantee-side cards for
+    // my content AND my cards for others' content — the synchronous "gone right away" contract.
+    // Already-deleted ids no-op (resume-safe).
+    await this.deleteGrantsById(
+      db,
+      deletion.manifestGrants.map((grant) => grant.id)
+    );
+
+    // 5. Flip the user row through the ONE standing write path (audited), then stamp the
+    // deletion columns. deleteRequestedAt = the manifest row's own creation time, so a resumed
+    // call re-writes identical values.
+    await new SetUserStatus().setUserStatus(user.id, 'deactivated');
+    await db.update(tables.User, {
+      id: user.id,
+      deleteRequestedAt: deletion.created,
+      purgeAfter: deletion.purgeAfter,
+    });
+
+    // Deletion-requested email (§9.4-1) — the only cancel channel an account-takeover victim
+    // has. The deletion state is already durable, so a mail-transport failure logs loudly
+    // instead of misreporting the committed deactivation as failed.
+    try {
+      await new AccountDeletionEmails().sendDeletionRequested(user.email, deletion.purgeAfter);
+    } catch (error: any) {
+      this.logger.error({
+        message: 'Failed to send the deletion-requested email',
+        obj: { userId: user.id },
+        error,
+      });
+    }
+
+    // 6. Kill sessions last — SocketIOSessionWatcher disconnects every live socket, including
+    // the caller's own.
+    await db.delete(tables.Session, { userEmail: user.email });
+
+    // 7. The UI's confirmation copy renders from this.
+    return { purgeAfter: deletion.purgeAfter };
+  }
+
+  /**
+   * §3.4 — logging back in IS the cancel (called by the login route after `authenticate`
+   * passes, BEFORE `request.login`). Not RPC-reachable: it is deliberately absent from the
+   * AccountDeletionService interface, so the service router never exposes it.
+   */
+  async cancelPendingDeletion(email: string): Promise<'not-pending' | 'restored' | 'purging'> {
+    const db = getDbAsSystem();
+    const deletion = await db.get(tables.AccountDeletion, { userEmail: email.toLowerCase() });
+    if (!deletion) {
+      return 'not-pending';
+    }
+
+    // CAS claim (RoutineTicker shape): one winner across this login, concurrent logins, and the
+    // purge walker. 'restoring' re-entry covers a crashed prior cancel. No purgeAfter check —
+    // this CAS is the arbiter, so a user beating the walker to a just-expired window wins
+    // honestly.
+    const claimSeq = (deletion.leaseSeq ?? 0) + 1;
+    const claimQb = new QueryBuilderFactory()
+      .createQueryBuilder(tables.AccountDeletion)
+      .condition({ field: 'userId', operator: '=', value: deletion.userId })
+      .condition({ field: 'phase', operator: 'IN', value: ['grace', 'restoring'] })
+      .condition({ field: 'leaseSeq', operator: '=', value: deletion.leaseSeq ?? 0 });
+    const claimed = await db.update(tables.AccountDeletion, { phase: 'restoring', leaseSeq: claimSeq }, claimQb);
+    if (claimed !== 1) {
+      const current = await db.get(tables.AccountDeletion, { userId: deletion.userId });
+      if (!current) {
+        return 'not-pending'; // a concurrent cancel finished the restore — normal login proceeds
+      }
+      if (current.phase === 'purging' || current.phase === 'purged') {
+        return 'purging'; // the walker won — no longer restorable
+      }
+      throw new Error(`A concurrent restore is in flight for account ${deletion.userId} — retry login.`);
+    }
+
+    // Re-insert manifest grants idempotently (fresh ids). The grant watcher's afterInsert
+    // rebuilds content_reference cards through the normal path — grantees' cards for my content
+    // AND my cards for inbound shares — synchronously, before the login response.
+    await this.restoreManifestGrants(db, deletion.manifestGrants);
+
+    // User row back to standing through the audited path; deletion stamps nulled.
+    await new SetUserStatus().setUserStatus(deletion.userId, 'active');
+    await db.update(tables.User, { id: deletion.userId, deleteRequestedAt: null, purgeAfter: null });
+
+    await db.delete(tables.AccountDeletion, { id: deletion.id });
+    return 'restored';
+  }
+
+  /** Verify the caller's password against their own account row; throws with nothing written. */
+  private async reauthenticateSessionUser(password: string): Promise<User> {
+    const sessionUser = new UserRepo().getUser();
+    const adminCredentials = DefaultAdminCredentials.getCredentials();
+    if (adminCredentials && sessionUser.email === adminCredentials.username) {
+      throw new Error('The default admin session has no account row to delete.');
+    }
+    if (!sessionUser.id || !sessionUser.email) {
+      throw new Error('Account deletion requires a signed-in account.');
+    }
+
+    // Fetch by email only and verify in code (both stored formats). No rehash here — this
+    // method's contract is "throws with nothing written"; legacy rows migrate at login.
+    const user = await getDbAsSystem().get(tables.User, { email: sessionUser.email.toLowerCase() });
+    if (!user || !(await new PasswordHasher().verify(user.password, password))) {
+      throw new Error('Password incorrect');
+    }
+
+    return user;
+  }
+
+  /**
+   * §3.3 step 3: enumerate grants in both directions and persist the manifest row — phase
+   * 'grace', full grant set, owned-resource snapshot — before any mutation.
+   */
+  private async createDeletionManifest(db: Db, user: User): Promise<AccountDeletionRecord> {
+    const qbf = new QueryBuilderFactory();
+
+    // Owner grants are the authoritative ownership signal (backed by
+    // idx_ag_principal_table_level_resource). They are NOT revoked at deactivation — the purge
+    // walker deletes them terminally after the walk that enumerates from this snapshot.
+    const ownerQb = qbf
+      .createQueryBuilder(tables.AccessGrant)
+      .condition({ field: 'principal', operator: '=', value: user.id })
+      .condition({ field: 'accessLevel', operator: '=', value: 'owner' });
+    const ownerGrants = await db.query(tables.AccessGrant, ownerQb);
+    const ownedResourceIds = Array.from(
+      new Set(ownerGrants.map((grant) => this.referenceId(grant.resource, grant.id)))
+    );
+
+    // Inbound: my non-owner grants on other people's content.
+    const inboundQb = qbf
+      .createQueryBuilder(tables.AccessGrant)
+      .condition({ field: 'principal', operator: '=', value: user.id })
+      .condition({ field: 'accessLevel', operator: 'IN', value: ['read', 'write', 'admin'] });
+    const inbound = await db.query(tables.AccessGrant, inboundQb);
+
+    // Outbound: grants on my content held by anyone else (no resource-side index — chunked
+    // IN-list enumeration, acceptable at MVP scale).
+    const outbound: AccessGrant[] = [];
+    for (const idsChunk of this.chunk(ownedResourceIds, GRANT_CHUNK_SIZE)) {
+      const outboundQb = qbf
+        .createQueryBuilder(tables.AccessGrant)
+        .condition({ field: 'resource', operator: 'IN', value: idsChunk });
+      const grants = await db.query(tables.AccessGrant, outboundQb);
+      outbound.push(...grants.filter((grant) => this.referenceId(grant.principal, grant.id) !== user.id));
+    }
+
+    const graceDays = this.gracePeriodDays();
+    return await db.insert(tables.AccountDeletion, {
+      userId: user.id,
+      userEmail: user.email,
+      phase: 'grace',
+      purgeAfter: moment().add(Math.round(graceDays * 24 * 60 * 60 * 1000), 'milliseconds'),
+      manifestGrants: [...inbound, ...outbound].map((grant) => this.toManifestGrant(grant)),
+      ownedResourceIds,
+      leaseSeq: 0,
+    });
+  }
+
+  /** Revoke grants by manifest id, in chunks of 100. Already-deleted ids no-op. */
+  private async deleteGrantsById(db: Db, grantIds: string[]): Promise<void> {
+    for (const idsChunk of this.chunk(grantIds, GRANT_CHUNK_SIZE)) {
+      const qb = new QueryBuilderFactory()
+        .createQueryBuilder(tables.AccessGrant)
+        .condition({ field: 'id', operator: 'IN', value: idsChunk });
+      await db.delete(tables.AccessGrant, qb);
+    }
+  }
+
+  /** §3.4 step 3: per entry, get by (principal, resource, accessLevel) → insert if missing. */
+  private async restoreManifestGrants(db: Db, manifestGrants: ManifestGrant[]): Promise<void> {
+    for (const grant of manifestGrants) {
+      const existingQb = new QueryBuilderFactory()
+        .createQueryBuilder(tables.AccessGrant)
+        .condition({ field: 'principal', operator: '=', value: grant.principal })
+        .condition({ field: 'resource', operator: '=', value: grant.resource })
+        .condition({ field: 'accessLevel', operator: '=', value: grant.accessLevel });
+      const existing = await db.query(tables.AccessGrant, existingQb);
+      if (existing.length > 0) {
+        continue;
+      }
+
+      await db.insert(tables.AccessGrant, {
+        principal: new Reference(tables.User.name, grant.principal),
+        // Serialization fails loudly on a missing table name — a table-less grant is corrupt.
+        resource: new Reference(grant.resourceTable ?? '', grant.resource),
+        resourceTable: grant.resourceTable,
+        accessLevel: grant.accessLevel,
+      });
+    }
+  }
+
+  private toManifestGrant(grant: AccessGrant): ManifestGrant {
+    return {
+      id: grant.id,
+      principal: this.referenceId(grant.principal, grant.id),
+      resource: this.referenceId(grant.resource, grant.id),
+      resourceTable: grant.resourceTable,
+      accessLevel: grant.accessLevel,
+    };
+  }
+
+  /** A grant reference's id, loudly — the manifest must never be built from corrupt grants. */
+  private referenceId(reference: Reference<any>, grantId: string): string {
+    if (!reference?._id) {
+      throw new Error(`access_grant ${grantId} has a reference with no id — refusing to build a deletion manifest.`);
+    }
+    return reference._id;
+  }
+
+  /**
+   * Grace window in days (ACCOUNT_DELETION_GRACE_DAYS, default 30). Fractional values are
+   * honored so dev verification can shorten the window to minutes.
+   */
+  private gracePeriodDays(): number {
+    const raw = process.env.ACCOUNT_DELETION_GRACE_DAYS;
+    if (raw === undefined || raw === '') {
+      return 30;
+    }
+
+    const days = Number(raw);
+    if (!Number.isFinite(days) || days < 0) {
+      throw new Error(`ACCOUNT_DELETION_GRACE_DAYS must be a non-negative number of days, got '${raw}'`);
+    }
+    return days;
+  }
+
+  private chunk<T>(items: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < items.length; i += size) {
+      chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+  }
+}