Re-review: admin personas + install wizard + mail UI + Network carve

.do/app.yaml

@@ -22,23 +22,35 @@
 name: openpartner
 region: nyc
 
-# Managed Postgres. For production, bump to a paid plan and upgrade the
-# `production` flag. The connection string is injected into services
-# that reference ${openpartner-db.DATABASE_URL}.
-databases:
-  - name: openpartner-db
-    engine: PG
-    version: '16'
-    production: false
-    cluster_name: openpartner-db
-    db_name: openpartner
-    db_user: openpartner
+# Database is provisioned externally (e.g., a separate Coherence cluster
+# with a dedicated `openpartner` database inside it). DATABASE_URL is set
+# as an encrypted secret on each service below. Add this app to the
+# cluster's Trusted Sources after the first deploy so it can reach pg.
+#
+# If you'd rather have App Platform provision a dedicated cluster, paste
+# this block back in:
+#
+#   databases:
+#     - name: openpartner-db
+#       engine: PG
+#       version: '16'
+#       production: true
+#       cluster_name: openpartner-db
+#       db_name: openpartner
+#       db_user: openpartner
+#
+# and change the DATABASE_URL env vars below to:
+#   value: ${openpartner-db.DATABASE_URL}
 
 services:
   # Core API. Runs migrations on first boot via docker-entrypoint.sh.
   - name: api
     dockerfile_path: apps/api/Dockerfile
     source_dir: /
+    github:
+      repo: getcoherence/openpartner
+      branch: main
+      deploy_on_push: true
     http_port: 4601
     instance_count: 1
     instance_size_slug: basic-xs
@@ -54,17 +66,39 @@ services:
       - key: API_PORT
         value: '4601'
       - key: DATABASE_URL
-        value: ${openpartner-db.DATABASE_URL}
+        type: SECRET
+        scope: RUN_TIME
+      # App-pool connection — connects as openpartner_app (a NOLOGIN-by-
+      # default role provisioned by migration 20260507020000_app_role.ts).
+      # Required in multi-tenant deploys for RLS to actually engage at
+      # runtime; in single-tenant self-host you can leave it unset and
+      # let everything run as the migration role.
+      - key: DATABASE_URL_APP
+        type: SECRET
+        scope: RUN_TIME
+      # Password used to provision openpartner_app on migrate. Pair with
+      # DATABASE_URL_APP. Rotation: change here, redeploy to re-run the
+      # idempotent role migration which alters the password in place.
+      - key: OPENPARTNER_APP_DB_PASSWORD
+        type: SECRET
+        scope: RUN_TIME
       - key: OPENPARTNER_MODE
         value: flat
-      - key: MAIL_TRANSPORT
-        value: postmark
+      # single | multi. Hosted deploys default to multi; flip to single
+      # if running a single-tenant fork on App Platform.
+      - key: OPENPARTNER_TENANCY
+        value: multi
       - key: POSTMARK_MESSAGE_STREAM
         value: outbound
+      # Enables the in-process scheduler (usage reporting + payouts).
+      # DO App Platform has no native cron, so the api process runs them
+      # itself. Set to '0' on replica nodes if you ever scale to instance_count > 1.
+      - key: OPENPARTNER_ENABLE_SCHEDULER
+        value: '1'
       - key: ADMIN_API_KEY
         type: SECRET
         scope: RUN_TIME
-      - key: NETWORK_ENCRYPTION_KEY
+      - key: SECRETS_ENCRYPTION_KEY
         type: SECRET
         scope: RUN_TIME
       - key: POSTMARK_SERVER_TOKEN
@@ -76,6 +110,8 @@ services:
       - key: PORTAL_URL
         type: SECRET
         scope: RUN_TIME
+      # Stripe — set as live values when ready to launch. STRIPE_WEBHOOK_SECRET
+      # accepts a comma-separated list (one per Event destination).
       - key: STRIPE_SECRET_KEY
         type: SECRET
         scope: RUN_TIME
@@ -85,13 +121,35 @@ services:
       - key: STRIPE_FLAT_PRICE_ID
         type: SECRET
         scope: RUN_TIME
+      # Metered usage prices — created by `setup-stripe.mjs` against the
+      # live key. Optional in self-host but required for the percentage
+      # portion of Flex/Revshare/Network billing to actually fire.
+      - key: STRIPE_FLAT_USAGE_PRICE_ID
+        type: SECRET
+        scope: RUN_TIME
+      - key: STRIPE_REVSHARE_USAGE_PRICE_ID
+        type: SECRET
+        scope: RUN_TIME
+      - key: STRIPE_NETWORK_PRICE_ID
+        type: SECRET
+        scope: RUN_TIME
+      - key: STRIPE_NETWORK_USAGE_PRICE_ID
+        type: SECRET
+        scope: RUN_TIME
+      - key: METRICS_TOKEN
+        type: SECRET
+        scope: RUN_TIME
 
   # Click router. Separate component so we can point a marketing apex
   # (go.yourdomain.com) at it without routing through the portal's
   # ingress.
   - name: router
     dockerfile_path: apps/router/Dockerfile
     source_dir: /
+    github:
+      repo: getcoherence/openpartner
+      branch: main
+      deploy_on_push: true
     http_port: 4701
     instance_count: 1
     instance_size_slug: basic-xxs
@@ -107,7 +165,8 @@ services:
       - key: ROUTER_PORT
         value: '4701'
       - key: DATABASE_URL
-        value: ${openpartner-db.DATABASE_URL}
+        type: SECRET
+        scope: RUN_TIME
       - key: COOKIE_DOMAIN
         type: SECRET
         scope: RUN_TIME
@@ -122,21 +181,43 @@ services:
 static_sites:
   - name: portal
     source_dir: /
+    github:
+      repo: getcoherence/openpartner
+      branch: main
+      deploy_on_push: true
+    # Force devDependencies (tsc, vite) during build — App Platform sets
+    # NODE_ENV=production by default which would have pnpm skip them.
+    # NODE_ENV stays unset on this static site at runtime; nothing executes.
     build_command: |
       corepack enable
       corepack prepare pnpm@9.11.0 --activate
-      pnpm install --frozen-lockfile
+      NPM_CONFIG_PRODUCTION=false pnpm install --frozen-lockfile
       pnpm --filter @openpartner/db build
       pnpm --filter @openpartner/portal build
     output_dir: apps/portal/dist
     catchall_document: index.html
     envs:
-      - key: NODE_ENV
-        value: production
+      # PostHog product analytics. VITE_-prefixed so Vite inlines the
+      # value into the static bundle at build time. BUILD_TIME scope is
+      # required: the static site has no run-time process to read env
+      # vars from. Without this declaration the values you set in the
+      # DO UI may not flow into the build (depending on App Platform
+      # version). Same project key as studio-website for unified
+      # dashboards.
+      - key: VITE_POSTHOG_KEY
+        type: SECRET
+        scope: BUILD_TIME
+      - key: VITE_POSTHOG_HOST
+        scope: BUILD_TIME
+        value: https://us.i.posthog.com
 
-# App-level routing. /api/* goes to the api service; everything else
-# falls through to the static portal. The router is addressed by its
-# own subdomain — see `domains` below.
+# App-level routing.
+#   /api/* → api (path stripped before forward)
+#   /r/*   → router (path preserved — router serves /r/:linkKey directly)
+#   /      → portal (App Platform's static-site default)
+#
+# Once you wire `r.openpartner.dev` to the router component via the
+# `domains` block, you can remove the /r rule — the subdomain handles it.
 ingress:
   rules:
     - match:
@@ -147,9 +228,9 @@ ingress:
         preserve_path_prefix: false
     - match:
         path:
-          prefix: /
+          prefix: /r
       component:
-        name: portal
+        name: router
 
 # Wire custom domains once the app is up. Set these in the App Platform
 # UI, or uncomment + fill below and `doctl apps update`.

.env.example

@@ -5,9 +5,30 @@
 # Values: selfhost | flat | revshare
 OPENPARTNER_MODE=selfhost
 
-# Database
+# Tenancy mode — single tenant (self-host bootstrap) vs multi-tenant
+# (hosted, /t/<slug>/... URL routing). Values: single | multi
+# Self-host customers leave this at 'single'. Hosted operators set
+# 'multi' and use POST /signup to provision tenants.
+OPENPARTNER_TENANCY=single
+
+# Database — privileged connection used by migrations, signup, the
+# Stripe webhook handler, and the in-process scheduler. Bypasses RLS.
 DATABASE_URL=postgres://openpartner:openpartner@localhost:5433/openpartner
 
+# Optional: app-role connection string used by every tenant-scoped
+# request. Run as a non-superuser without BYPASSRLS so RLS engages as
+# defense-in-depth alongside the per-request app.tenant_id filter.
+# When unset, tenant-scoped requests fall back to DATABASE_URL and RLS
+# is bypassed (app-level filtering still applies). Self-hosters opt in
+# by setting both this and OPENPARTNER_APP_DB_PASSWORD.
+DATABASE_URL_APP=
+
+# Password used to provision the openpartner_app role on migrate. The
+# 20260507020000_app_role.ts migration creates the role with this
+# password (rotates it if the role already exists). Skipped with a
+# notice if unset. Pair with DATABASE_URL_APP pointing at this role.
+OPENPARTNER_APP_DB_PASSWORD=
+
 # Service ports
 ROUTER_PORT=4701
 API_PORT=4601
@@ -17,10 +38,9 @@ PORTAL_PORT=5673
 # In production: set to your marketing apex (e.g. .yourdomain.com)
 COOKIE_DOMAIN=localhost
 
-# Session secret — generate a random 32+ char string for prod
-SESSION_SECRET=dev-only-replace-in-prod
-
-# Admin API key for bootstrap (curl/CI). Rotate via POST /api-keys once live.
+# Bootstrap / headless admin bearer. Human admins sign in via the /install
+# wizard (first run) or by receiving an emailed magic link. Keep this set
+# for CI, scripts, and emergency access; rotate once human admins exist.
 # Generate: node -e "console.log('op_' + require('crypto').randomBytes(24).toString('hex'))"
 ADMIN_API_KEY=op_devonly_replace_me_with_64_hex_chars_before_any_real_use_xxxx
 
@@ -35,30 +55,55 @@ STRIPE_FLAT_PRICE_ID=
 VELOCITY_MAX=20
 VELOCITY_WINDOW_MS=60000
 
-# Network federation — AES-256-GCM master key (32 raw bytes, either hex
-# (64 chars) or base64 (44 chars)). REQUIRED in production; dev uses a
-# weak fallback and logs a warning.
+# Public portal URL. Required in production so CORS has an explicit
+# origin allowlist (we refuse to boot with it empty). Defaults to
+# localhost:5673 in dev.
+PORTAL_URL=http://localhost:5673
+
+# Optional: extra CORS origins beyond PORTAL_URL, comma-separated.
+CORS_EXTRA_ORIGINS=
+
+# -- Secret encryption at rest --
+# 32-byte master key (hex or base64) used to encrypt SMTP passwords /
+# Postmark tokens / future Config secrets. REQUIRED in production; dev
+# uses a fixed fallback with a warning so restarts keep decrypting.
 # Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-NETWORK_ENCRYPTION_KEY=
+SECRETS_ENCRYPTION_KEY=
+
+# Mail for admin + partner invite / signin links.
+#
+# Preferred: configure from the admin Settings → Email delivery page
+# (stored encrypted at rest in Config). The env vars below are
+# fallbacks used only when UI config is empty — useful for hosted /
+# managed tiers where the operator wants to force the transport.
+#
+#   SMTP_HOST + MAIL_FROM    → nodemailer SMTP (Gmail, SES, Mailgun,
+#                              SendGrid, Postmark SMTP, Postfix, …)
+#   POSTMARK_SERVER_TOKEN + MAIL_FROM → Postmark HTTP API
+#   neither                  → stdout (dev only)
+#
+# MAIL_FROM must be quoted if it contains a display name, e.g.
+#   MAIL_FROM="Acme Partners <partners@acme.com>"
+MAIL_FROM=
 
-# Router URL override used when federating Network partnerships. If unset,
-# we infer from the vendor's instance URL by swapping API port 4601 → 4701.
-NETWORK_ROUTER_URL=
+# -- SMTP fallback --
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_SECURE=
+SMTP_USER=
+SMTP_PASSWORD=
 
-# Mail delivery for magic-link auth.
-#   dev       → writes to the DevMessage table; admins read at /admin/dev-mailbox.
-#   postmark  → POSTs to api.postmarkapp.com/email (requires the vars below).
-MAIL_TRANSPORT=dev
-MAIL_FROM=OpenPartner <no-reply@example.com>
+# -- Postmark (alternative) --
 POSTMARK_SERVER_TOKEN=
-# Optional — defaults to the "outbound" transactional stream.
 POSTMARK_MESSAGE_STREAM=outbound
 
-# Public portal URL that magic links point at. Defaults to localhost:5673
-# for dev. Set this in prod so emails link to your real hostname.
-PORTAL_URL=http://localhost:5673
-
 # Optional: bearer token required to scrape /metrics. Leave blank and
 # /metrics is open (fine on internal networks). Set it when /metrics is
 # reachable from the public internet.
 METRICS_TOKEN=
+
+# Optional: URL of the OpenPartner Network coordinator. When set, hosted
+# multi-tenant signups auto-register with the Network (admin still
+# confirms via the magic link); self-host installs see a "Connect to
+# Network" button under Settings → Network. Leave empty to opt out.
+NETWORK_URL=

.github/CODEOWNERS

@@ -0,0 +1,41 @@
+# GitHub CODEOWNERS file.
+#
+# Lines map a path glob to a GitHub user / team. The last matching line
+# wins. When a PR touches a path, GitHub auto-requests review from the
+# matching owner(s); when the protected-branch rule "Require review from
+# Code Owners" is on, the PR can't merge without their approval.
+#
+# Keep this list short and meaningful — every entry is a hard
+# review-block. Default reviewer covers everything; specific paths
+# below add no extra owners (yet) but reserve the slots for when a
+# team forms around the repo.
+
+# Default reviewer for everything not matched below.
+*  @keithfawcett
+
+# Build, deploy, and CI configuration. Changes here affect the release
+# pipeline and supply chain — surface them clearly.
+/.github/                          @keithfawcett
+/.do/                              @keithfawcett
+/Dockerfile                        @keithfawcett
+/docker-compose*.yml               @keithfawcett
+/apps/api/Dockerfile               @keithfawcett
+/apps/portal/Dockerfile            @keithfawcett
+/apps/router/Dockerfile            @keithfawcett
+
+# Cryptography + auth + storage of secrets. Anything under here gets
+# extra eyes because a regression is hard to catch in review.
+/apps/api/src/crypto.ts            @keithfawcett
+/apps/api/src/auth.ts              @keithfawcett
+/apps/api/src/db.ts                @keithfawcett
+/apps/api/src/tenancy.ts           @keithfawcett
+/packages/db/src/ssl.ts            @keithfawcett
+
+# Database migrations. Bad migrations are the most expensive class of
+# mistake — explicitly route to the maintainer even when they're small.
+/packages/db/migrations/           @keithfawcett
+
+# Network-protocol contract. Any wire-shape change must go through the
+# maintainer because it's the federation API openpartner-network builds
+# against.
+/docs/network-protocol.md          @keithfawcett

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+buy_me_a_coffee: keithf