create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/deploy/first-party-plugins.md

@@ -0,0 +1,219 @@
+# First-party plugins
+
+Gift registries, community spaces, voice/video and marketplace channel
+sync are first-party plugins (MASTER.md §36, C3.13). They install with
+the instance; disable one from Admin → Plugins if the business does not use it.
+
+**These are not complete products.** Community, voice/video and marketplace
+channel sync have landed as first-party plugins. Shopify and Daily have real
+HTTP adapters; the Daily adapter remains in-tree as optional non-first-party
+code — the de-facto first-party voice/video provider is paradisemodern's
+Paradise Comms (owner decision 2026-09-27). Print-on-demand's Printify
+adapter likewise remains in-tree as working optional code, but the
+print-on-demand product is **deferred to v2** (MASTER.md §43.18, owner
+decision 2026-09-27).
+Gift registries raise ordinary invoices. Missing live providers fail explicitly; no
+channel connection or call is reported as successful. Live acceptance and
+remaining product depth stay open under C3.13.
+
+## Gift registries
+
+Admin → Gift registries opens a list attached to a contact. Items raise
+invoices through the existing invoicing module — there is no second checkout.
+The public page `/gifts/<slug>` lets a visitor contribute; that path calls
+`contacts.resolve` and `invoicing.createDraft`. A duplicate slug is a conflict.
+Retry an item that failed to invoice from the same screen.
+
+## Print on demand
+
+> **Deferred to v2** (MASTER.md §43.18, owner decision 2026-09-27: "we'll get
+> back to printify later"). Print-on-demand leaves the v1 plan; the adapter
+> documented below remains in-tree as working optional code, and re-entry
+> into the plan happens only by owner decision.
+
+Admin → Print on demand maps a catalog SKU to a Printify product and numeric
+variant ID. Set `PRINTIFY_API_TOKEN` and `PRINTIFY_SHOP_ID` in the deployment
+environment and restart Freeholder. Obtain the token and shop ID using the
+[Printify API guide](https://developers.printify.com/). The screen reports local
+configuration; it does not claim the credentials have been verified.
+
+A paid mapped catalog line opens an ordinary catalog fulfillment and submits
+its product, quantity, contact email and shipping address to Printify. A complete
+name, street, city, postal code and two-letter country are required. Each line
+is a separate Printify order with standard shipping. Merchant approval and
+production settings in Printify govern when it enters production; Freeholder
+does not call the separate send-to-production endpoint.
+
+Acceptance marks the print job submitted and leaves fulfillment pending.
+Scheduled checks and **Refresh tracking** apply verified carrier evidence.
+All tracking numbers appear on the print job; the first is the catalog
+fulfillment's primary tracking number. Fulfilled provider orders with tracking
+become shipped. Delivery is recorded only when all returned shipments carry
+valid past delivery timestamps. Automatic checks stop after shipment; refresh
+manually to check later delivery.
+
+Queued, failed and expired submissions retry twice hourly, in batches of 50.
+The original catalog line identity survives timeouts; Printify's documented
+matching duplicate response recovers the same vendor order. A ten-minute lease
+rejects stale workers. Existing jobs retain their original product/address and
+merchant shop binding; changing mappings affects newly queued lines only.
+Restore the original shop configuration before retrying a job from another shop.
+Review rejected address/product details before retrying: editing an existing
+job's snapshot is not currently supported. No live merchant acceptance test
+has been performed; mocked HTTP and database tests are not that evidence.
+
+## Community
+
+Admin → Community creates open or gated spaces, rooms inside a space, and a
+moderation queue of hidden or reported posts. Open spaces accept a public join
+at `/community/<slug>` and show a chronological feed. Gated spaces show a join
+request instead of the feed until staff add the person; members must sign in through the existing customer account to read and post.
+An email in a form or URL never grants membership or moderator rights. Joining the same person
+twice is a conflict, not a second membership. A signed-in moderator (or staff through admin) can hide
+or remove a post; hidden posts leave the public feed and stay on the admin
+queue. Member posts are rate-limited by signed-in account, stored as plain text, and
+land on the session-linked contact timeline.
+
+## Voice and video
+
+The de-facto first-party provider is paradisemodern's Paradise Comms
+(owner decision 2026-09-27): prod `https://paradisemodern.com/v1`, staging
+`https://comms-staging.paradisemodern.com/v1`; auth is a per-site
+`x-api-key` (carrying comms scopes) or a legacy portfolio bearer token;
+capabilities `comms.calls/rooms/streams/conversations` per
+`/api/integration/capabilities`. Admin → Voice and video opens a private
+room attached to the canonical contact. Rooms are created with policy
+(open/moderated/invite_only), participant and publisher caps and recording
+options plus retention; credentials are TTL JWTs with TURN.
+
+**Open as host** issues an owner token for that room. **Create guest link**
+returns a non-owner invitation to copy and share with the contact; Freeholder
+does not send it. Treat these links as private credentials. **Record
+attendance** is a manual attendance entry, not evidence that the invited
+person joined.
+
+**Stop** asks Paradise Comms to end the room: PM persists the terminal
+state, then awaits LiveKit `DeleteRoom` and returns `media_ended`; a 503
+`media_termination_pending` is retryable. Freeholder does not claim that
+deleting a room proves its call ended. **Missed call** performs that
+shutdown before writing the timeline event. Recording start/stop rides the
+room's recording options; recordings land in DigitalOcean Spaces.
+
+Transcripts are unavailable until PM ships them; a missing transcript stays
+absent, never a placeholder. Paradise Comms webhooks are HMAC-SHA256 signed
+(`Webhook-Signature: t=<ts>,v1=<hmac>` over `"<ts>.<body>"`) and posted to
+`/api/plugins/voice-video/webhooks/paradise`, which verifies the signature
+and a five-minute timestamp window, de-duplicates on the envelope id, and
+maps room-ended to closing the local room and `recording.deleted`/
+`recording.expired` to dropping local provider references. The
+prepaid-budget 402 gate applies to site-key callers on cost-starting calls
+(create, credentials, recording start): Freeholder surfaces the balance and
+top-up URL on the room row and the setup screen's verify probe, and never
+treats a 402 as a transport error.
+
+A verified recording is copied automatically into the owner's configured
+storage (the same S3-compatible adapter as media). The copy uses content-
+addressed keys and a SHA-256 checksum, so retries never duplicate objects; a
+failed copy stays visible on the recording with **Copy to storage** to retry
+it. Recordings above 512 MiB are not imported; the recording row reports the
+failure instead of exhausting the worker. The recording list shows the copy
+state per recording. Contact erasure deletes imported owner-storage copies
+through the same durable job receipt as provider copies; retention holds keep
+them exactly like the provider originals.
+
+**Honesty notes for the PM path.** PM shipped the recording lifecycle
+(contract `2026-09-28.comms-recording-lifecycle`): Freeholder lists a room's
+recordings, reads one (playback URL only when `status=available`), imports
+the verified recording into owner storage, and erases provider-side through
+`DELETE /v1/recordings/:id` — retryable 503 keeps the PM row and the privacy
+receipt pending, 409 mid-egress defers to the durable job. One caveat: PM
+playback URLs are **public unsigned Spaces URLs** — anyone holding one can
+download until PM ships signed playback, so Freeholder treats them as
+short-lived access windows and never displays them as shareable links. See
+[provider erasure and recovery](provider-recording-erasure.md). The adapter
+(`plugins/voice-video/paradise.ts`, `paradise-provider.ts`, `settings.ts`,
+`webhook.ts`) is covered by mocked-HTTP and database tests; live
+paradisemodern acceptance against a real site key remains open C3.13 work.
+
+The Daily adapter remains in-tree as optional non-first-party code: set
+`DAILY_API_KEY` and `DAILY_DOMAIN` (for example `your-business.daily.co`)
+in the deployment environment to use it. It provides private expiring rooms,
+separate host/guest tokens expiring within 30 minutes, recording and
+transcript handling, and durable erasure as documented in
+[provider erasure and recovery](provider-recording-erasure.md); its Daily
+references ([room configuration](https://docs.daily.co/reference/rest-api/rooms/create-room),
+[meeting tokens](https://docs.daily.co/reference/rest-api/meeting-tokens/create-meeting-token))
+remain the authority for that optional path. HTTP and database tests do not
+establish a live call or device compatibility on either provider.
+
+## Marketplace channels
+
+Admin → Marketplace channels connects the configured Shopify store and keeps
+failed handshakes available for retry. Etsy, Amazon and eBay remain unimplemented
+provider seams. The production adapter imports verified paid Shopify orders
+through the canonical contact and draft invoice services, as described below.
+Only tests use staged in-memory orders. The Shopify connection is a
+**migration bridge** — import your Shopify history into the native
+Freeholder store, which is the product (owner decision 2026-09-27, C3.24) —
+not an ongoing dependency.
+
+### Sync ownership and retries (C3.13)
+
+Print and voice/video retries exclusively claim existing jobs or artifacts.
+Marketplace sync claims an expiring lease, renews it after each page, and
+checks its ownership before importing or checkpointing. An expired worker
+cannot overwrite a recovered sync. Each imported order resolves its contact,
+creates its invoice and records the channel order in one transaction.
+Print and call adapters recover documented idempotent operations, but HTTP
+fixtures do not prove live merchant or call-provider acceptance.
+
+### Shopify own-store setup (C3.13)
+
+This connection exists to migrate your Shopify history into the native
+store; it is not an ongoing dependency (owner decision 2026-09-27, C3.24).
+
+Create and install an app for a store in your Shopify organization using the
+[client credentials grant guide](https://shopify.dev/docs/apps/build/authentication-authorization/client-credentials-grant).
+Set `SHOPIFY_SHOP` to its `your-store.myshopify.com` domain, and set
+`SHOPIFY_CLIENT_ID` and `SHOPIFY_CLIENT_SECRET` in your deployment environment.
+Restart Freeholder, then connect Shopify in Admin → Marketplace. Local
+configuration is distinct from the verified channel connection. Tokens stay
+in process memory and renew before expiry; credentials never appear in channel
+reads, generated API results or stored provider errors.
+
+The app needs `read_orders`, `read_customers` and access to protected customer
+email/name fields. The [Customer API](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer)
+requires the customer scope used to resolve the buyer’s name. Shopify normally
+limits history to 60 days; older orders need additional approved access
+([Order API](https://shopify.dev/docs/api/admin-graphql/latest/objects/order)).
+A missing email stops the page with an actionable error rather than creating
+a fabricated contact. Fix permissions or the source order, then retry.
+
+Sync reads up to 50 orders per page using GraphQL Admin API `2026-07`. Only
+paid, non-test, non-cancelled orders are imported. Each produces a draft
+invoice for the gross shop-currency amount, linked to the resolved contact.
+Review channel tax details before issuing anything; Freeholder does not send
+an invoice, charge the customer, or assert a local settlement during import.
+Later source edits and cancellations do not update previous imports.
+
+After the order pass, the same sync reconciles refunds. Orders with a refunded
+or partially-refunded financial status return their refund list; each refund
+is recorded once, keyed by its provider refund id. When the imported invoice
+has been issued, the refund becomes an issued credit note through the
+invoicing module — never a direct money mutation — bounded by the original
+invoice total like any other credit note. Multiple refunds on one order
+produce separate credit notes. A refund whose order has not imported yet, or
+whose invoice is still a reviewable draft, stays listed as pending and
+reconciles on a later sync; the admin screen shows the state per refund. No
+live store acceptance has been performed; HTTP fixtures and database
+integration tests establish local behavior only.
+
+Connected channels sync twice hourly; active leases are left to their owner.
+Completed scans start from the beginning on the next run; existing imports
+are skipped by channel/order identity. Interrupted scans retain the last
+completed page. A sync stops after 500 pages, so large histories need a future
+incremental history workflow. Shop identity must match the connected channel
+on every page. Restore the original configuration if it changes. Connection
+and sync leases reject competing or expired workers. No live store acceptance
+has been performed; HTTP fixtures and database integration tests establish
+local behavior only.

package/dist/template/deploy/fork-lane.md

@@ -0,0 +1,93 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# The fork lane
+
+*MASTER.md §39.7, checklist item C10.09.*
+
+Most instances update by swapping an image. An owner who has modified core
+cannot: an image swap would throw their changes away. For them an update is a
+**merge**, and this is how it works.
+
+You are on the fork lane if this instance is a git checkout of your own
+repository. You are on the image lane otherwise, and nothing here applies —
+`freeholder doctor` says which one you are on under `update.fork`.
+
+## What it does
+
+1. **Fetches upstream** into a throwaway worktree in the system temp
+   directory. Not the tree serving traffic. Never the tree serving traffic.
+2. **Merges** with `--no-commit --no-ff`, then **aborts** — whether it
+   succeeded or not. The question being asked is "would this merge, and what
+   would fight", not "please merge it".
+3. **Classifies every conflict** through the customization seams (§39.1):
+   - a conflict in **core** goes to the pull request, where you resolve it;
+   - a conflict in a **seam** — `plugins/`, `freeholder.config.ts`, `.env` —
+     stops the lane. Upstream has reached into a file the contract says is
+     yours, and resolving it automatically is exactly the overwrite this lane
+     exists to prevent.
+4. **Opens a pull request in your own fork**, if the merge is clean. GitHub
+   performs the merge onto a fresh branch; your CI is the review. Nothing is
+   ever pushed to your base branch, whatever your branch protection allows.
+
+The running instance never holds push credentials for your code and never
+writes a file outside the temp worktree. If step 4 cannot run — no repository
+connected — steps 1 to 3 still tell you the truth.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `FREEHOLDER_UPSTREAM_REMOTE` | `https://github.com/CampDenman/freeholder.git` | Upstream to merge from. Must be `https`. |
+| `FREEHOLDER_UPSTREAM_REF` | `main` | The upstream branch. |
+| `BUILDER_CODE_REPOSITORY` | — | `owner/repo`: where the pull request is opened. Shared with §37's builder lane. |
+| `BUILDER_CODE_TOKEN` | — | A token that may open a pull request and needs no other authority. |
+| `BUILDER_CODE_BASE_BRANCH` | `main` | Your fork's base branch. |
+
+A ref is validated before it reaches git. `--upload-pack=…`, `a/../b` and
+anything with a shell metacharacter are refused rather than passed along, and
+git is spawned with `shell: false` and no terminal prompt.
+
+## Drift, stated honestly
+
+`platform.forkStatus` answers in security terms, not commit counts. "Fourteen
+commits behind" tells you nothing about whether you are exposed:
+
+```
+2 security releases behind — CVSS 8.1; this fork carries 3 commits of its own
+```
+
+Channel filtering happens before the count, so an instance on the `security`
+channel is not reported as behind because a feature release exists. A release
+with no CVSS score is news, not exposure, and is never counted as a security
+release. "Up to date with upstream" is only ever said when it is true of
+security too — silence must not be indistinguishable from safety.
+
+The same call reports which of your diverging files are **yours**
+(`ownedByYou`) and which are **replaceable core** (`replaceableCore`), because
+the second list is what will conflict on the next merge and the first list
+never should.
+
+## Services
+
+| Service | Does |
+|---|---|
+| `platform.forkStatus` | Drift, missing releases, missing security releases, and which diverging files are yours. Read-only. |
+| `platform.openForkUpdate` | Runs the worktree merge, then opens the pull request. Refuses rather than resolving a seam conflict. |
+
+Both are orchestrated services: they cross a process and provider boundary, so
+they hold no database transaction while doing it (§2).
+
+## Honest limits
+
+- **A clean local merge is not a passing build.** The worktree proves the
+  trees combine; it does not run your tests. That is what the pull request and
+  your CI are for.
+- **A conflicted merge leaves the branch behind.** It is your starting point
+  for resolving by hand, and deleting it would throw away the only thing the
+  attempt produced.
+- **Drift is only as fresh as the feed.** If update checks are off, or the
+  feed cannot be verified, the lane still reports commit drift but will not
+  claim you are up to date on security.

package/dist/template/deploy/host-updater.example.json

@@ -0,0 +1,23 @@
+{
+  "state_directory": "/var/lib/freeholder-host-updater",
+  "socket": "/run/freeholder-host-updater/updater.sock",
+  "app_gid": 1001,
+  "backup_produces": "/backups/freeholder-pre-update.dump",
+  "health_timeout_seconds": 180,
+  "artifact": {
+    "url": "https://releases.example.com/freeholder/freeholder-0.1.0.tar.gz",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "cosign_identity": "https://github.com/CampDenman/freeholder/.github/workflows/publish-host-artifact.yml@refs/heads/main",
+    "signature_url": "https://releases.example.com/freeholder/freeholder-0.1.0.tar.gz.sig"
+  },
+  "hooks": {
+    "backup": "systemctl stop freeholder && pg_dump --format=custom freeholder > /backups/freeholder-pre-update.dump && systemctl start freeholder",
+    "maintenance_on": "touch /var/www/maintenance.on",
+    "apply": "tar -C /opt/freeholder -xzf \"$FH_ARTIFACT\" && systemctl restart freeholder",
+    "health": "curl -fsS http://127.0.0.1:3000/api/health | grep -q '\"ok\":true'",
+    "rollback": "/opt/freeholder/bin/restore-previous && systemctl restart freeholder",
+    "maintenance_off": "rm -f /var/www/maintenance.on"
+  },
+  "automatic": false,
+  "utc_hour": 10
+}

package/dist/template/deploy/host-updater.md

@@ -0,0 +1,107 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Host updates on non-Docker targets (C10.06)
+
+`docker-updater.py` covers the standard Compose recipe. This executor covers
+the remaining hosting targets — source-pull containers (Replit), systemd or
+plain-binary hosts, and platform deploy hooks (Render, Railway, DigitalOcean
+App Platform) — with the same discipline the readiness audit demanded: no
+success is recorded unless the backup and the health check both proved, and
+every refusal is durable.
+
+The operator declares an **immutable, digest-pinned artifact** and the commands
+their target's tooling runs. The executor downloads the artifact, verifies its
+sha256 (and optionally the publisher's cosign signature), refuses to continue
+unless the backup hook produced a real non-empty file at the declared path,
+applies, health-checks, and — on failure — rolls back and independently
+re-runs the health check before it will say `rolled_back`.
+
+## Install
+
+Copy `scripts/host-updater.py` to `/usr/local/lib/freeholder/host-updater.py`
+and a root-owned, mode-600 `/etc/freeholder/host-updater.json` adapted from
+`deploy/host-updater.example.json`:
+
+```json
+{
+  "state_directory": "/var/lib/freeholder-host-updater",
+  "socket": "/run/freeholder-host-updater/updater.sock",
+  "app_gid": 1001,
+  "backup_produces": "/backups/freeholder-pre-update.dump",
+  "health_timeout_seconds": 180,
+  "artifact": {
+    "url": "https://releases.example.com/freeholder/freeholder-0.1.0.tar.gz",
+    "sha256": "<64 hex chars pinned at release time>",
+    "cosign_identity": "https://github.com/CampDenman/freeholder/.github/workflows/publish-host-artifact.yml@refs/heads/main",
+    "signature_url": "https://releases.example.com/freeholder/freeholder-0.1.0.tar.gz.sig"
+  },
+  "hooks": {
+    "backup": "systemctl stop freeholder && pg_dump --format=custom freeholder > /backups/freeholder-pre-update.dump && systemctl start freeholder",
+    "maintenance_on": "touch /var/www/maintenance.on",
+    "apply": "tar -C /opt/freeholder -xzf \"$FH_ARTIFACT\" && systemctl restart freeholder",
+    "health": "curl -fsS http://127.0.0.1:3000/api/health | grep -q '\"ok\":true'",
+    "rollback": "/opt/freeholder/bin/restore-previous && systemctl restart freeholder",
+    "maintenance_off": "rm -f /var/www/maintenance.on"
+  },
+  "automatic": false,
+  "utc_hour": 10
+}
+```
+
+Rules the executor enforces before any hook runs:
+
+- The configuration is root-owned and not writable by group/other; every path
+  is absolute; the artifact URL is `https`; the digest is an immutable
+  sha256; `backup`, `apply`, `health` and `rollback` are non-empty commands.
+- When `cosign_identity` is set, `signature_url` must be `https` and `cosign
+  verify-blob` must validate the artifact against that exact identity and the
+  GitHub OIDC issuer before anything else happens.
+- The `backup` hook must leave a non-empty file at `backup_produces`. A
+  fingerprint, a log line or a missing file is not a backup: the run refuses
+  and nothing else runs.
+- Hooks run as root with `FH_ARTIFACT` pointing at the verified artifact.
+
+## Run
+
+```sh
+python3 /usr/local/lib/freeholder/host-updater.py apply --config /etc/freeholder/host-updater.json
+python3 /usr/local/lib/freeholder/host-updater.py status --config /etc/freeholder/host-updater.json
+```
+
+The state machine is the Docker executor's: verify artifact → verified backup
+→ maintenance on → apply → health → maintenance off → `completed`. On a
+health failure after apply, rollback runs and the health hook must pass again
+before the run records `rolled_back`; a rollback that cannot verify itself
+records `recovery_required`, leaves maintenance on, and blocks every later
+run. A run interrupted mid-state blocks the next run until an operator
+inspects the host, archives `status.json`, and clears the state deliberately.
+A failure before the apply hook ran records `failed` and never runs rollback,
+because the deployment it would roll back was never touched.
+
+`maintenance_on`/`maintenance_off` are optional; when present they bracket the
+candidate window exactly as Caddy does on the Docker lane. Keep their effect
+write-blocking: the rollback guarantee is that no accepted write lands between
+the backup and the verified rollback.
+
+## Schedule
+
+The same operator discipline as the Docker lane: start with `automatic:
+false`, prove refusal and recovery on your installation, then set `automatic:
+true` and `utc_hour` (0–23) and drive `scheduled` from an hourly systemd
+timer. Disable the timer or set `automatic: false` to pause unattended
+changes.
+
+## Target mapping
+
+| Target family | `apply` hook is | `rollback` hook restores |
+|---|---|---|
+| Replit (source-pull) | fetch + install the pinned artifact commit and restart | the previous artifact |
+| systemd / bare host | unpack the pinned artifact and restart the unit | the previous artifact |
+| Render / Railway / DO App Platform (deploy hook) | hand the pinned artifact to the platform deploy API | the previous deploy spec |
+
+On every target the artifact stays immutable and digest-pinned, so rollback is
+always to exactly what ran before. Host tests: `python3 -m unittest discover
+-s tests/host -v`.

package/dist/template/deploy/mail-delivery.md

@@ -0,0 +1,205 @@
+# Mail delivery and feedback
+
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+
+Freeholder has two deliberately separate routes:
+
+- **Account mail** sends password resets, portal links, staff invitations,
+  security notices and form notifications through Gmail, Microsoft Outlook or
+  SMTP.
+- **Broadcast mail** sends campaigns through Resend, Postmark or Amazon SES.
+  It never falls back to Gmail, Outlook or SMTP because broadcasts require
+  authenticated bounce/complaint feedback and local suppression state.
+
+The database keeps sender state, recipient, subject, provider reference,
+timestamps and normalized delivery status. It never keeps message bodies or
+raw webhook payloads. Raw provider payloads are authenticated in memory and
+represented only by a SHA-256 digest.
+
+## Account mail
+
+### Google delegated Gmail
+
+1. Create an OAuth web application in the Google project you already control.
+2. Add this exact redirect URI:
+
+   ```text
+   ${APP_URL}/api/mail/oauth/google/callback
+   ```
+
+3. Set `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET` and
+   `CREDENTIAL_KEY`.
+4. Restart Freeholder. Open **Admin → Settings → Mail**, choose **Connect
+   Google**, approve only the displayed identity and `gmail.send` scopes, then
+   choose the connected sender as default.
+
+Freeholder requests offline access so it can send account mail after the
+interactive session ends. Access and refresh tokens are encrypted with
+`CREDENTIAL_KEY`. Losing that key means reconnecting the mailbox; include it
+in the same protected backup set as the database.
+
+### Microsoft delegated Outlook
+
+1. Create an Entra ID application for the tenant policy you use.
+2. Add this exact redirect URI:
+
+   ```text
+   ${APP_URL}/api/mail/oauth/microsoft/callback
+   ```
+
+3. Grant delegated `Mail.Send` plus the identity/offline scopes shown during
+   consent. Freeholder does not request mailbox read access.
+4. Set `MICROSOFT_OAUTH_CLIENT_ID`, `MICROSOFT_OAUTH_CLIENT_SECRET`, optional
+   `MICROSOFT_OAUTH_TENANT` (default `common`) and `CREDENTIAL_KEY`.
+5. Restart, connect from **Admin → Settings → Mail**, and choose the sender as
+   default.
+
+An `invalid_grant` refresh response marks the account for reconnection in an
+independent transaction, so that evidence survives the failed send. Network,
+429 and 5xx failures keep the account active for retry.
+
+### SMTP
+
+Set:
+
+```dotenv
+MAIL_ADAPTER=smtp
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=
+SMTP_PASSWORD=
+MAIL_FROM="Business name <hello@example.com>"
+```
+
+Restart, then register the exact normalized `MAIL_FROM` address in **Admin →
+Settings → Mail**. SMTP configuration proves only that a transport is
+configured. It does not prove domain ownership, SPF, DKIM, DMARC or inbox
+placement; use **Send test** to your own account and confirm those records with
+the mailbox provider.
+
+## Broadcast carriers
+
+Set `MAIL_BULK_ADAPTER` to `resend`, `postmark` or `ses`, set
+`MAIL_BULK_FROM`, and provide the selected carrier's existing credentials from
+`.env.example`. Restart, register the exact `MAIL_BULK_FROM`, run provider
+verification, and choose the verified sender as the bulk default. Freeholder
+does not provision a paid account or make a billable campaign send during
+setup or doctor.
+
+### Resend feedback
+
+Set `RESEND_WEBHOOK_SECRET` and point the Resend webhook at:
+
+```text
+${APP_URL}/api/mail/webhooks/resend
+```
+
+Freeholder checks the Svix message id, timestamp (five-minute tolerance) and
+every `v1` signature in the rotation header against the unmodified bounded
+request body. The stable Svix id makes replay idempotent.
+
+### Postmark feedback
+
+Generate a dedicated high-entropy Basic Auth username and password, set
+`POSTMARK_WEBHOOK_USER` and `POSTMARK_WEBHOOK_PASSWORD`, and configure each
+Postmark delivery/bounce/complaint/subscription webhook to:
+
+```text
+${APP_URL}/api/mail/webhooks/postmark
+```
+
+The credential comparison is constant-size and timing-safe. Postmark provider
+reactivation is recorded but never silently releases Freeholder's local
+suppression; an authorized person must type the exact address to release it.
+
+### Amazon SES through SNS
+
+1. Configure the SES configuration set named by `SES_CONFIGURATION_SET` to
+   publish send, delivery, delay, bounce, complaint, reject and rendering
+   events to one SNS topic.
+2. Set the topic's exact ARN in `SES_SNS_TOPIC_ARN`.
+3. Subscribe this HTTPS endpoint:
+
+   ```text
+   ${APP_URL}/api/mail/webhooks/ses
+   ```
+
+4. Allow Freeholder to confirm the signed subscription request.
+
+Only the exact topic is accepted. Header and payload topic/type must agree.
+Signing and confirmation URLs must be HTTPS SNS hosts with no credentials,
+nonstandard port or redirect. Signing certificates are bounded, cached for at
+most 24 hours, valid for `sns.amazonaws.com`, Amazon-labelled, current and RSA
+2048-bit or stronger. Only SNS `SignatureVersion` **2** with RSA-SHA256 is
+accepted; SHA-1/Version 1 is refused. HTTPS verifies the AWS server chain
+before the message-supplied signing certificate is read from the strict AWS
+hostname/path.
+
+## Suppression and operations
+
+Permanent bounces, complaints and provider suppressions activate an exact,
+lowercase address suppression before another send can reach a provider. Soft
+bounces do not. Provider events use provider occurrence time and a
+non-regressive transition graph, so a late submitted/failed/delivery message
+cannot undo a complaint or suppression.
+
+Use **Admin → Settings → Mail** to inspect senders, recent delivery evidence
+and suppressions. Release only after correcting or independently verifying the
+address, and type the exact address into the release form. A provider saying
+it reactivated an address is evidence, not authority to bypass this check.
+
+Run `pnpm doctor` after every setup or credential rotation. It reports
+configured, pending, missing and reconnect states, the exact authenticated
+feedback URL, and remediation variable names without rendering secret values
+or sending mail.
+
+## Campaign consent and unsubscribe links
+
+Every campaign recipient receives an opaque opt-out capability in both message
+bodies and the `List-Unsubscribe` / `List-Unsubscribe-Post` headers. Resend,
+Postmark and SES carry these through their supported header fields. An opt-out
+withdraws this business's marketing-email consent on the shared contact record;
+transactional receipts and essential account messages remain separate.
+Provider one-click POSTs are repeatable. A browser GET only displays a translated
+confirmation form, so a mail scanner cannot withdraw consent or confirm a
+newsletter subscription merely by fetching its link.
+
+Campaign batches serialize against the campaign row and use a stable
+per-recipient delivery key. Queued campaign messages check consent again just
+before provider delivery; a withdrawal suppresses them and updates the owner's
+recipient outcomes. A provider request that has already started cannot be
+recalled. No unsubscribe capability appears in owner recipient listings or
+contact exports.
+
+Migration `0024_broadcast_unsubscribe.sql` adds a private UUID token and unique
+index to existing recipient rows. It preserves campaign history. Actual inbox
+delivery, header signing (including DKIM coverage), and provider one-click
+behavior still require the production acceptance checks below. This repair does
+not claim legal compliance or replace an independent review.
+
+## Threat model and verification
+
+The relevant threats are replayed/forged feedback, SSRF through SNS URLs,
+unbounded bodies/certificates/provider responses, OAuth state theft or replay,
+provider-account reassignment, credential leakage, out-of-order events,
+accidental personal-mailbox broadcasts, and unsafe suppression release. The
+implementation closes these at the HTTP, transaction and schema boundaries.
+
+Before relying on mail in production:
+
+1. Run `pnpm doctor` and resolve every mail failure.
+2. Send one account-mail test to the signed-in administrator and verify its
+   inbox and headers.
+3. Verify the broadcast identity with the provider, then use the single-recipient
+   test control. Do not use a campaign list for setup validation.
+4. Trigger provider sandbox/test delivery feedback where available and confirm
+   the ledger updates. Never use a real customer address for a bounce test.
+5. Confirm an intentionally malformed or replayed provider payload is refused
+   without raw detail in the response or database.
+
+Migration `0031_lucky_maria_hill.sql` is additive: it creates only the five
+mail tables, constraints, indexes and foreign keys. Release N-1 does not know
+about them and remains read/write compatible after the forward migration, so
+rollback is an image swap. Do not drop the tables to disable mail; set the
+adapters to `console`/`none` and pause registered senders instead.