Replace file-based webhook idempotency storage with a pluggable, multi-instance-safe store

[Lakes41]

Difficulty: Advanced
Type: Refactor

Background
.env.example documents ACTIVITY_STORAGE_MODE (memory default, or file to "persist webhook IDs across local restarts") and ACTIVITY_STORAGE_DIR (default .guildpass-activity), explicitly described as "Webhook activity idempotency storage." This is the mechanism preventing the same incoming webhook (member.joined, pass.activated, etc.) from being processed twice.

Problem
Both memory and file idempotency stores are single-instance by design: memory is lost on restart, and file writes to local disk, which does not work correctly if the dashboard is deployed across multiple server instances or serverless/ephemeral-filesystem environments — a duplicate webhook delivered to a different instance than the one that first processed it would not be recognized as a duplicate, breaking the "idempotency" guarantee the naming implies.

Expected outcome
The webhook idempotency store is defined behind an interface (e.g. IdempotencyStore with hasSeen(id)/markSeen(id, ttl)), with memory and file kept as local-dev implementations, plus a new implementation suitable for multi-instance deployments (e.g. backed by the durable Postgres storage from Issue #6, or a documented Redis-compatible option) selectable via ACTIVITY_STORAGE_MODE.

Suggested implementation

• Extract the current idempotency logic (wherever it lives, e.g. near the webhook handler) into a small interface with pluggable backends.
• Add a durable (or postgres) mode that stores seen webhook IDs with a TTL/expiry column, reusing the Postgres connection if Issue Add a server-wide role sync command for admins #6 is implemented, or with its own minimal table otherwise.
• Ensure TTL-based cleanup doesn't require a background cron — expire lazily on lookup or via a scheduled cleanup query, whichever fits the existing architecture better, and document the choice.
• Update .env.example and CONTRIBUTING.md to describe the new mode and when to use it.

Acceptance criteria

• memory and file modes retain their exact current behavior for local development (no regression).
• A new multi-instance-safe mode correctly rejects a duplicate webhook ID even when the "duplicate" request is simulated as coming from a second, independent process/instance.
• Idempotency records expire (or are cleaned up) after a documented retention window rather than growing unboundedly.
• Tests cover: first-seen acceptance, duplicate rejection, and expiry behavior for each backend.
• pnpm --filter @guildpass/dashboard test and pnpm typecheck pass.

Likely affected files/directories
Webhook handler route (apps/dashboard/app/api/webhook*/), new idempotency-store module (e.g. apps/dashboard/lib/idempotency/), .env.example, CONTRIBUTING.md.

[keljoshX]

Hi maintainer, can i be assigned to this?
I'll submit a pr for it in no time after assignment

[grantfox-oss]

🦊 GrantFox — @keljoshX has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #259)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@keljoshX's PR #284 was approved and merged by @Lakes41.

🏆 @keljoshX: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (239 total points). Track your full progress on GrantFox.

👏 Great work, @keljoshX! Keep contributing to Adamantine-guild.