/**
 * GDPR Art. 17: anonymise an author. Zeroes the display identity on
 * globalAuthor:<authorID>, deletes the token/mapper bindings that link a
 * person to this authorID, and nulls authorship on chat messages they
 * posted. Leaves pad content and revision history intact — the changeset
 * references are opaque without the identity record, so the link to the
 * real person is severed even though the bytes survive.
 *
 * Idempotent: once `erased: true` is set on the author record, subsequent
 * calls short-circuit and return zero counters.
 */
exports.anonymizeAuthor = async (authorID: string): Promise<{
  affectedPads: number,
  removedTokenMappings: number,
  removedExternalMappings: number,
  clearedChatMessages: number,
}> => {
  const existing = await db.get(`globalAuthor:${authorID}`);
  if (existing == null || existing.erased) {
    return {
      affectedPads: 0,
      removedTokenMappings: 0,
      removedExternalMappings: 0,
      clearedChatMessages: 0,
    };
  }

  // Drop the token/mapper mappings first, before zeroing the display
  // record, so a concurrent getAuthorId() can no longer resolve this
  // author through its old bindings mid-erasure.
  let removedTokenMappings = 0;
  const tokenKeys = await db.findKeys('token2author:*', null);
  for (const key of tokenKeys) {
    if (await db.get(key) === authorID) {
      await db.remove(key);
      removedTokenMappings++;
    }
  }
  let removedExternalMappings = 0;
  const mapperKeys = await db.findKeys('mapper2author:*', null);
  for (const key of mapperKeys) {
    if (await db.get(key) === authorID) {
      await db.remove(key);
      removedExternalMappings++;
    }
  }

  // Zero the display identity but keep padIDs so future maintenance (or a
  // pad-delete batch) can still find the set of pads this authorID touched.
  await db.set(`globalAuthor:${authorID}`, {
    colorId: 0,
    name: null,
    timestamp: Date.now(),
    padIDs: existing.padIDs || {},
    erased: true,
    erasedAt: new Date().toISOString(),
  });

  // Null authorship on chat messages the author posted.
  const padIDs = Object.keys(existing.padIDs || {});
  let clearedChatMessages = 0;
  for (const padID of padIDs) {
    if (!await padManager.doesPadExist(padID)) continue;
    const pad = await padManager.getPad(padID);
    const chatHead = pad.chatHead;
    if (typeof chatHead !== 'number' || chatHead < 0) continue;
    for (let i = 0; i <= chatHead; i++) {
      const chatKey = `pad:${padID}:chat:${i}`;
      const msg = await db.get(chatKey);
      if (msg != null && msg.authorId === authorID) {
        msg.authorId = null;
        await db.set(chatKey, msg);
        clearedChatMessages++;
      }
    }
  }

  return {
    affectedPads: padIDs.length,
    removedTokenMappings,
    removedExternalMappings,
    clearedChatMessages,
  };
};

git add src/node/db/AuthorManager.ts
git commit -m "feat(gdpr): AuthorManager.anonymizeAuthor — Art. 17 erasure"

'use strict';

import {strict as assert} from 'assert';

const common = require('../common');
const authorManager = require('../../../node/db/AuthorManager');
const db = require('../../../node/db/DB');

describe(__filename, function () {
  before(async function () {
    this.timeout(60000);
    await common.init();
  });

  it('zeroes the display identity on globalAuthor:<id>', async function () {
    const {authorID} = await authorManager.createAuthorIfNotExistsFor(
        `mapper-${Date.now()}-${Math.random()}`, 'Alice');
    assert.equal(await authorManager.getAuthorName(authorID), 'Alice');

    const res = await authorManager.anonymizeAuthor(authorID);
    assert.ok(res.removedExternalMappings >= 1);

    const record = await db.db.get(`globalAuthor:${authorID}`);
    assert.equal(record.name, null);
    assert.equal(record.colorId, 0);
    assert.equal(record.erased, true);
    assert.ok(typeof record.erasedAt === 'string');
  });

  it('drops token2author and mapper2author mappings pointing at the author',
      async function () {
        const mapper = `mapper-${Date.now()}-${Math.random()}`;
        const {authorID} = await authorManager.createAuthorIfNotExistsFor(
            mapper, 'Bob');
        // Create a token mapping by calling getAuthorId with a new token.
        const token = `t.${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
        // getAuthorId takes (token, user); first call seeds token2author:<token>.
        await authorManager.getAuthorId(token, {});
        // We need a token that resolves to *this* authorID. Do it by making
        // the token's first use deterministic: set token2author:<token> ourselves.
        await db.db.set(`token2author:${token}`, authorID);

        assert.equal(await db.db.get(`token2author:${token}`), authorID);
        assert.equal(await db.db.get(`mapper2author:${mapper}`), authorID);

        const res = await authorManager.anonymizeAuthor(authorID);
        assert.ok(res.removedTokenMappings >= 1);
        assert.ok(res.removedExternalMappings >= 1);
        assert.equal(await db.db.get(`token2author:${token}`), null);
        assert.equal(await db.db.get(`mapper2author:${mapper}`), null);
      });

  it('is idempotent — second call returns zero counters', async function () {
    const {authorID} = await authorManager.createAuthorIfNotExistsFor(
        `mapper-${Date.now()}-${Math.random()}`, 'Carol');
    await authorManager.anonymizeAuthor(authorID);
    const second = await authorManager.anonymizeAuthor(authorID);
    assert.deepEqual(second, {
      affectedPads: 0,
      removedTokenMappings: 0,
      removedExternalMappings: 0,
      clearedChatMessages: 0,
    });
  });

  it('returns zero counters for an unknown authorID', async function () {
    const res = await authorManager.anonymizeAuthor('a.does-not-exist');
    assert.deepEqual(res, {
      affectedPads: 0,
      removedTokenMappings: 0,
      removedExternalMappings: 0,
      clearedChatMessages: 0,
    });
  });
});

git add src/tests/backend/specs/anonymizeAuthor.ts
git commit -m "test(gdpr): AuthorManager.anonymizeAuthor — identity + mappings + idempotence"

/**
 * anonymizeAuthor(authorID) — GDPR Art. 17 erasure. See doc/privacy.md.
 *
 * @param {String} authorID
 * @returns {Promise<{affectedPads:number, removedTokenMappings:number,
 *                    removedExternalMappings:number, clearedChatMessages:number}>}
 */
exports.anonymizeAuthor = async (authorID: string) => {
  if (!authorID || typeof authorID !== 'string') {
    throw new CustomError('authorID is required', 'apierror');
  }
  return await authorManager.anonymizeAuthor(authorID);
};

version['1.3.1'] = {
  ...version['1.3.0'],
  anonymizeAuthor: ['authorID'],
};

// set the latest available API version here
exports.latestApiVersion = '1.3.1';

git add src/node/db/API.ts src/node/handler/APIHandler.ts
git commit -m "feat(gdpr): REST anonymizeAuthor on API version 1.3.1"

'use strict';

import {strict as assert} from 'assert';

const common = require('../../common');

let agent: any;
let apiVersion = '1.3.1';
const endPoint = (point: string) => `/api/${apiVersion}/${point}`;

const callApi = async (point: string, query: Record<string, string> = {}) => {
  const qs = new URLSearchParams(query).toString();
  const path = qs ? `${endPoint(point)}?${qs}` : endPoint(point);
  return await agent.get(path)
      .set('authorization', await common.generateJWTToken())
      .expect(200)
      .expect('Content-Type', /json/);
};

describe(__filename, function () {
  before(async function () {
    this.timeout(60000);
    agent = await common.init();
    const res = await agent.get('/api/').expect(200);
    apiVersion = res.body.currentVersion;
  });

  it('anonymizeAuthor zeroes the author and returns counters', async function () {
    const create = await callApi('createAuthor', {name: 'Alice'});
    assert.equal(create.body.code, 0);
    const authorID = create.body.data.authorID;

    const res = await callApi('anonymizeAuthor', {authorID});
    assert.equal(res.body.code, 0, JSON.stringify(res.body));
    assert.ok(res.body.data.affectedPads >= 0);

    const name = await callApi('getAuthorName', {authorID});
    assert.equal(name.body.data.authorName, null);
  });

  it('anonymizeAuthor with missing authorID returns an error', async function () {
    const res = await agent.get(`${endPoint('anonymizeAuthor')}?authorID=`)
        .set('authorization', await common.generateJWTToken())
        .expect(200)
        .expect('Content-Type', /json/);
    assert.equal(res.body.code, 1);
    assert.match(res.body.message, /authorID is required/);
  });
});

git add src/tests/backend/specs/api/anonymizeAuthor.ts
git commit -m "test(gdpr): REST anonymizeAuthor end-to-end"

ls doc/privacy.md || cat > doc/privacy.md <<'EOF'
# Privacy

See [cookies.md](cookies.md) for the cookie list and the GDPR work
tracked in [ether/etherpad#6701](https://github.com/ether/etherpad/issues/6701).
EOF

## Right to erasure (GDPR Art. 17)

Etherpad anonymises an author rather than deleting their changesets
(deletion would corrupt every pad they contributed to). Operators
trigger erasure via the admin REST API:

```bash
curl -X POST \
  -H "Authorization: Bearer <admin JWT / apikey>" \
  "https://<instance>/api/1.3.1/anonymizeAuthor?authorID=a.XXXXXXXXXXXXXX"

- [ ] **Step 3: Commit**

```bash
git add doc/privacy.md
git commit -m "docs(gdpr): right-to-erasure section + anonymizeAuthor example"

cd src && NODE_ENV=production pnpm exec mocha --require tsx/cjs \
  tests/backend/specs/anonymizeAuthor.ts \
  tests/backend/specs/api/anonymizeAuthor.ts \
  tests/backend/specs/api/api.ts --timeout 60000

git push origin feat-gdpr-author-erasure
gh pr create --repo ether/etherpad --base develop --head feat-gdpr-author-erasure \
  --title "feat(gdpr): author erasure (PR5 of #6701)" --body "$(cat <<'EOF'
## Summary
- New `authorManager.anonymizeAuthor(authorID)` zeroes the display identity on `globalAuthor:<id>`, deletes every `token2author:*` and `mapper2author:*` binding that points at the author, and nulls `authorId` on chat messages they posted. Pad content, revisions, and attribute pool are intact.
- New REST endpoint `POST /api/1.3.1/anonymizeAuthor?authorID=…` — admin-auth via the existing apikey/JWT pipeline.
- Idempotent. Zero counters on second call.
- `doc/privacy.md` explains what the call does and does not do.

Final PR of the #6701 GDPR work. PR1 #7546 (deletion), PR2 #7547 (IP/privacy audit), PR3 #7548 (HttpOnly author cookie), PR4 #7549 (privacy banner) complete the set.

Design: `docs/superpowers/specs/2026-04-19-gdpr-pr5-author-erasure-design.md`
Plan: `docs/superpowers/plans/2026-04-19-gdpr-pr5-author-erasure.md`

## Test plan
- [x] ts-check
- [x] AuthorManager unit — identity zeroing, mappings removal, idempotence, unknown authorID
- [x] REST — successful erasure + missing-authorID error path
EOF
)"