feat(api): per-map edit permissions + protected maps + attribution (#4)

[Aduersarius]

Summary

Resolves #4 — Etapa 0 permissions and attribution for map editing.

What landed

• requireMapEditSession: same GAME_DATA_ADMIN_PROXY_TOKEN gate; superadmin via email/account; collaborators via game_map_permissions (map_num or 0 = all non-protected).
• Protected cities {1, 34, 59, 150}: rejected for everyone unless superadmin sends x-protected-map-override: true.
• Attribution: game_map_mutation_log records who/what/when on paint, clear, entities, publish, discard, revert, grant/revoke (complements updated_by_account_id on row writes).
• Admin APIs: grant/revoke/list map permissions.
• Docs: GAME_DATA_ADMIN_* in api/.env.example.
• Tests: npx tsx --test src/tests/mapEditPermissions.test.ts → 6/6 covering all four acceptance cases as pure decision logic.

Differentiation vs open PRs

PR	Gap
#110	Always passes isSuperAdmin: true — collaborators never work; no DB grants table; contaminated with graceful-shutdown unrelated files
#129	Close, but override via body/query is inconsistent; no dedicated mutation audit log; decision logic not unit-tested in isolation
#47	Parallel services/map-permissions.ts with fictional assignedMaps; not wired to real admin/session or map routes

This PR keeps permission decision pure (mapEditPermissions.ts), persists grants + audit in schema, and wires every map mutation route consistently via one header.

Test plan

• cd api && npx tsx --test src/tests/mapEditPermissions.test.ts (6/6)
• Apply api/schema.sql (game_map_permissions, game_map_mutation_log)
• Session without grant → PUT .../maps/50/tiles → 403
• Grant map 50 only → can edit 50, cannot edit 1 or 2
• Superadmin without override on map 1 → 403; with x-protected-map-override: true → ok
• After paint/publish, row appears in game_map_mutation_log

[gitar-bot]

Important

You are using the Gitar free plan. Upgrade to unlock code review, CI analysis, auto-apply, custom automations, and more.

_Gitar

[gilmarGNJ]

Hi @Aduersarius — I checked head 7d5dd10 using the repository's Vitest runner and found a small integration issue:

cd api
pnpm exec vitest run src/tests/mapEditPermissions.test.ts
Error: No test suite found in file .../mapEditPermissions.test.ts

The six assertions run through node:test, but Vitest does not register them, so the command exits 1. Changing only import test from "node:test" to import { test } from "vitest" gives 6 passed, exit 0 locally (Node 22.17.1, Vitest 4.1.6). This is a focused test run, not a claim that the full CI passes.

I could help with a complementary follow-up in api/src/tests/world-builder.integration.test.ts: exercise the real HTTP/PostgreSQL path for no grant, grant limited to map 50, protected-map override, and persisted mutation attribution. I would also test what happens when audit insertion fails, since the route currently awaits it after the map write has completed.

Would this separate integration-test scope be useful to you, and can a maintainer point me to an assignable campaign task if it is eligible? I will wait for assignment before opening a PR and follow the campaign platform's reward process; I am not claiming the implementation already in this PR.

Disclosure: this review and proposed contribution are AI-assisted, performed on behalf of gilmarGNJ; the commands and results above were actually run locally.