fix(gdpr): PadDeletionManager race + document createPad/deletePad

Qodo review:
- createDeletionTokenIfAbsent() was a non-atomic read-then-write. Two
  concurrent callers for the same pad could both return different
  plaintext tokens while only the later hash was stored, leaving the
  first caller with an unusable recovery token. Serialise per-pad via a
  Promise chain and add a regression test that fires 8 concurrent
  calls and asserts exactly one plaintext is emitted and validates.
- doc/api/http_api.md now documents createPad returning deletionToken
  and deletePad accepting the optional deletionToken parameter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JohnMcLear

doc/api/http_api.md

@@ -519,12 +519,20 @@ Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security
 #### createPad(padID, [text], [authorId])
 * API >= 1
 * `authorId` in API >= 1.3.0
+* returns `deletionToken` once, since the same release that added `allowPadDeletionByAllUsers`
 
 creates a new (non-group) pad.  Note that if you need to create a group Pad, you should call **createGroupPad**.
 You get an error message if you use one of the following characters in the padID: "/", "?", "&" or "#".
 
+`data.deletionToken` is a one-shot recovery token tied to this pad. It is
+returned in plaintext on the first call for a given padID and is `null` on
+subsequent calls (the token itself is stored on the server as a sha256 hash).
+Pass it to **deletePad** (or the socket `PAD_DELETE` message) to delete the
+pad without the creator's author cookie.
+
 *Example returns:*
-* `{code: 0, message:"ok", data: null}`
+* `{code: 0, message:"ok", data: {deletionToken: "…32-char random string…"}}`
+* `{code: 0, message:"ok", data: {deletionToken: null}}` — pad already existed
 * `{code: 1, message:"padID does already exist", data: null}`
 * `{code: 1, message:"malformed padID: Remove special characters", data: null}`
 
@@ -581,14 +589,24 @@ returns the list of users that are currently editing this pad
 * `{code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}`
 * `{code: 0, message:"ok", data: {padUsers: []}}`
 
-#### deletePad(padID)
+#### deletePad(padID, [deletionToken])
 * API >= 1
+* `deletionToken` in the same release as `allowPadDeletionByAllUsers`
+
+deletes a pad.
 
-deletes a pad
+`deletionToken` is the one-shot recovery token returned by `createPad` /
+`createGroupPad`. An apikey-authenticated caller can pass any (or no) token
+and the call still succeeds — trusted admins bypass the check. An
+unauthenticated caller (or a caller that explicitly passes a wrong token)
+is rejected with `invalid deletionToken` unless the operator has set
+`allowPadDeletionByAllUsers: true` in `settings.json`, in which case the
+token is ignored.
 
 *Example returns:*
 * `{code: 0, message:"ok", data: null}`
 * `{code: 1, message:"padID does not exist", data: null}`
+* `{code: 1, message:"invalid deletionToken", data: null}`
 
 #### copyPad(sourceID, destinationID[, force=false])
 * API >= 1.2.8

src/node/db/PadDeletionManager.ts

@@ -10,14 +10,29 @@ const getDeletionTokenKey = (padId: string) => `pad:${padId}:deletionToken`;
 const hashDeletionToken = (deletionToken: string) =>
   crypto.createHash('sha256').update(deletionToken, 'utf8').digest();
 
+// Per-pad serialisation for token creation. Without this, two concurrent
+// `createDeletionTokenIfAbsent()` calls for the same pad can both observe
+// an empty slot, both write a hash, and leave the earlier caller holding a
+// plaintext token that no longer validates. The chain is cleaned up once the
+// outstanding call resolves so this map doesn't grow unbounded.
+const inflightCreate: Map<string, Promise<string | null>> = new Map();
+
 exports.createDeletionTokenIfAbsent = async (padId: string): Promise<string | null> => {
-  if (await DB.db.get(getDeletionTokenKey(padId)) != null) return null;
-  const deletionToken = randomString(32);
-  await DB.db.set(getDeletionTokenKey(padId), {
-    createdAt: Date.now(),
-    hash: hashDeletionToken(deletionToken).toString('hex'),
+  const prior = inflightCreate.get(padId);
+  const next = (prior || Promise.resolve()).then(async () => {
+    if (await DB.db.get(getDeletionTokenKey(padId)) != null) return null;
+    const deletionToken = randomString(32);
+    await DB.db.set(getDeletionTokenKey(padId), {
+      createdAt: Date.now(),
+      hash: hashDeletionToken(deletionToken).toString('hex'),
+    });
+    return deletionToken;
+  });
+  const tracked = next.finally(() => {
+    if (inflightCreate.get(padId) === tracked) inflightCreate.delete(padId);
   });
-  return deletionToken;
+  inflightCreate.set(padId, tracked);
+  return next;
 };
 
 exports.isValidDeletionToken = async (padId: string, deletionToken: string | null | undefined) => {

src/tests/backend/specs/padDeletionManager.ts

@@ -37,6 +37,22 @@ describe(__filename, function () {
       await padDeletionManager.removeDeletionToken(a);
       await padDeletionManager.removeDeletionToken(b);
     });
+
+    it('concurrent calls for the same pad produce a single validating token',
+        async function () {
+          const padId = uniqueId();
+          const results = await Promise.all(
+              Array.from({length: 8},
+                  () => padDeletionManager.createDeletionTokenIfAbsent(padId)));
+          // Exactly one caller should get the plaintext token; the rest see null.
+          const nonNull = results.filter((r) => r != null);
+          assert.equal(nonNull.length, 1, `results: ${JSON.stringify(results)}`);
+          const [token] = nonNull;
+          assert.equal(
+              await padDeletionManager.isValidDeletionToken(padId, token), true,
+              'the one token returned must validate against the stored hash');
+          await padDeletionManager.removeDeletionToken(padId);
+        });
   });
 
   describe('isValidDeletionToken', function () {