polar: build /api/polar/webhook handler

Standalone router for inbound Polar (merchant-of-record) deliveries.
No bearer-token dep — authenticity comes from the Standard Webhooks
HMAC instead. Wired up so it's safe to deploy dark: empty
POLAR_WEBHOOK_SECRET makes the endpoint return 503 (loud) rather than
accept unsigned events.

Behaviour
- Standard Webhooks signature verification: HMAC-SHA256 over
  `{webhook-id}.{webhook-timestamp}.{body}`, base64 secret prefixed
  whsec_, ±5min replay window, constant-time compare against any of
  the space-separated v1 tokens.
- Idempotency via UNIQUE on polar_events.event_id — a replayed
  webhook-id short-circuits to 200 "duplicate" without re-running.
- Event dispatch table covers the 10 events we subscribed to:
  subscription.{created,active,updated,uncanceled} -> tier=paid +
  persist polar_customer_id / polar_subscription_id.
  subscription.revoked -> tier=free (customer id kept so a resub
  matches the same User row).
  canceled / past_due / order.* / refund.created -> audit only.
- Unknown event types are acked 200 + recorded; we don't want to 4xx
  on something Polar adds in the future and trigger their retry loop.

Schema (migration 0018)
- users.polar_customer_id, users.polar_subscription_id (both nullable
  String(64)); UNIQUE on polar_customer_id so two users can't claim
  the same Polar identity.
- polar_events table: event_id (unique), event_type, received_at,
  processed_at, error, raw payload (truncated to 16 KiB).

Tests
- 7 in tests/test_polar_webhook.py: bad signature -> 401, stale
  timestamp -> 401, missing headers -> 400, subscription.active flips
  tier to paid + stores IDs, subscription.revoked drops to free while
  keeping customer link, replayed webhook-id is no-op, unknown event
  is acked.
- Full suite: 212 passed, 5 skipped.

Operator next steps before saving the webhook in Polar
1. Pull this branch to prod and apply migration 0018.
2. Save the webhook in Polar pointing at
   https://read.markets/api/polar/webhook — Polar will accept the
   save even though our endpoint still 503s (no secret yet).
3. Copy the secret Polar reveals into the prod .env as
   POLAR_WEBHOOK_SECRET=whsec_... and restart the app.
4. Trigger a test event from Polar's dashboard to confirm 200 OK.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

alembic/versions/0018_polar_webhook.py

@@ -0,0 +1,55 @@
+"""polar webhook: User.polar_customer_id/subscription_id, polar_events table.
+
+Revision ID: 0018
+Revises: 0017
+Create Date: 2026-05-26
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "0018"
+down_revision: Union[str, None] = "0017"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("polar_customer_id", sa.String(length=64), nullable=True),
+    )
+    op.add_column(
+        "users",
+        sa.Column("polar_subscription_id", sa.String(length=64), nullable=True),
+    )
+    op.create_unique_constraint(
+        "uq_users_polar_customer", "users", ["polar_customer_id"],
+    )
+
+    op.create_table(
+        "polar_events",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, primary_key=True),
+        sa.Column("event_id", sa.String(length=128), nullable=False),
+        sa.Column("event_type", sa.String(length=64), nullable=False),
+        sa.Column("received_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("processed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("error", sa.Text(), nullable=True),
+        sa.Column("payload", sa.Text(), nullable=False),
+        sa.UniqueConstraint("event_id", name="uq_polar_events_event_id"),
+    )
+    op.create_index(
+        "ix_polar_events_type_received",
+        "polar_events",
+        ["event_type", "received_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_polar_events_type_received", table_name="polar_events")
+    op.drop_table("polar_events")
+    op.drop_constraint("uq_users_polar_customer", "users", type_="unique")
+    op.drop_column("users", "polar_subscription_id")
+    op.drop_column("users", "polar_customer_id")