feat(infra): move app secrets to sst.Secret, Cloudflare creds to SSM

7 app secrets (OIDC client id, OIDC management id/secret, PostHog, Svix, SSH host/private keys) now resolve from the SST secret store per-stage instead of the gitignored .env. Cloudflare provider creds cannot be sst.Secret because the provider initializes in app() before run() exists, so scripts/sst-with-cloudflare.mjs loads them from AWS SSM SecureString and exports them before invoking sst; the dev/deploy/remove/sst npm scripts route through it. README gains a Secrets and credentials section and the commands now use npm run. Also fixes a non-ASCII em-dash in the RunnerSecurityGroup description that EC2 rejects.

Author: DorianZheng

apps/infra/README.md

@@ -24,18 +24,63 @@ EC2 runner with nested KVM, RDS Postgres, ElastiCache Redis, S3, CloudFront.
 
 ```bash
 cd apps/infra
-cp .env.example .env
-# Fill in STACK_DOMAIN, CLOUDFLARE_*, OIDC_* (see .env.example comments)
 npm install
-npx sst deploy --stage dev
+cp .env.example .env        # non-secret config: STACK_DOMAIN, OIDC_ISSUER_BASE_URL, OIDC_AUDIENCE
+
+# Cloudflare provider credentials live in SSM (per stage) — see "Secrets & credentials":
+aws ssm put-parameter --region ap-southeast-1 --type SecureString \
+  --name /boxlite/dev/cloudflare-api-token  --value "<token>"
+aws ssm put-parameter --region ap-southeast-1 --type SecureString \
+  --name /boxlite/dev/cloudflare-account-id --value "<account-id>"
+
+npm run deploy -- --stage dev   # the wrapper loads the Cloudflare creds, then runs sst deploy
 ```
 
+App secrets (SSH keys, Auth0 Management API, Svix, PostHog) are optional and set
+per-stage in the SST secret store — see [Secrets & credentials](#secrets--credentials).
+
 First deploy: 10–15 minutes. Output prints service URLs + CloudFront domain.
 
 If the build fails with a transient `auth.docker.io` EOF or Debian mirror
-`502 Bad Gateway`, just rerun `npx sst deploy --stage dev` — SST resumes
+`502 Bad Gateway`, just rerun `npm run deploy -- --stage dev` — SST resumes
 from the failed step.
 
+## Secrets & credentials
+
+Three homes, one access gate — **AWS IAM**. Nothing secret lives in git or a
+single laptop's `.env`:
+
+| What | Where | Set with |
+|---|---|---|
+| **App secrets** — SSH host/private keys, Auth0 Management API id + secret, `SVIX_AUTH_TOKEN`, `POSTHOG_API_KEY`, `OIDC_CLIENT_ID` | SST secret store (encrypted in SST state, per stage) | `sst secret set <NAME> "<value>" --stage <stage>` |
+| **Cloudflare provider creds** — `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_DEFAULT_ACCOUNT_ID` | AWS SSM (`SecureString`, per stage) | `aws ssm put-parameter --type SecureString --name /boxlite/<stage>/cloudflare-…` |
+| **Non-secret config** — `STACK_DOMAIN`, `OIDC_ISSUER_BASE_URL`, `OIDC_AUDIENCE`, toggles | local `.env` (gitignored) | edit `.env` |
+
+The Cloudflare creds can't be `sst.Secret`: the provider initializes in `app()`
+before `run()` (where secrets exist), so it reads them from the environment.
+`scripts/sst-with-cloudflare.mjs` — wired into `npm run dev`/`deploy`/`remove`
+and `npm run sst` — fetches them from SSM and exports them before invoking sst.
+**Run sst through these npm scripts**, not bare `npx sst`, so the creds load.
+
+### App secrets
+
+```bash
+sst secret set SVIX_AUTH_TOKEN "<value>" --stage dev   # set one
+sst secret load .env --stage dev                       # bulk-load a dotenv (names match 1:1)
+npm run secrets -- --stage dev                          # list what's set
+```
+
+Secret names match the env keys the services expect. Unset optional secrets
+resolve to empty (feature off); `OIDC_CLIENT_ID` defaults to `boxlite`. A changed
+value takes effect on the next `npm run deploy`.
+
+### Onboarding / offboarding
+
+Access is **AWS IAM only**: anyone who can deploy (read SST state + SSM, run
+`sst deploy`) can read every secret. Onboard by granting that AWS access;
+offboard by revoking it. There's no secret file or vault to hand over. Secret
+values and the SSM params are **per-stage** — seed each stage you run.
+
 ## After first deploy
 
 Nothing needs to be fed back into `.env`. The runner EC2 self-registers with the
@@ -50,7 +95,7 @@ count and redeploy:
 
 ```bash
 echo "RUNNERS=3" >> .env     # default runner (#1) + runner-2 + runner-3
-npx sst deploy --stage dev
+npm run deploy -- --stage dev
 ```
 
 Each extra runner gets its own EC2 + minted token. Because the API only
@@ -192,20 +237,23 @@ For Auth0 specifically:
 | **ClickHouse Cloud** | Managed OTel storage                 | external service; configured by env         |
 | **ClickStack**      | Logs/traces/metrics explorer         | external ClickHouse Cloud UI                |
 
-Run `npx sst deploy --stage dev` without changes to reprint all URLs. See
+Run `npm run deploy -- --stage dev` without changes to reprint all URLs. See
 [Public hostnames](#public-hostnames) below for the rationale behind the
 dashboard-vs-API split.
 
 ## Common commands
 
 ```bash
-npx sst deploy --stage dev       # deploy / update
-npx sst diff   --stage dev       # preview changes
-npx sst unlock --stage dev       # recover from "concurrent update detected"
-npx sst shell  --stage dev       # open shell with SST-linked env vars
-npx sst remove --stage dev       # destroy everything
+npm run deploy -- --stage dev       # deploy / update
+npm run sst -- diff --stage dev     # preview changes
+npm run sst -- unlock --stage dev   # recover from "concurrent update detected"
+npm run sst -- shell --stage dev    # open shell with SST-linked env vars
+npm run remove -- --stage dev       # destroy everything
 ```
 
+> These route through `scripts/sst-with-cloudflare.mjs` so the Cloudflare provider
+> creds load from SSM. Bare `npx sst …` skips that and can't reach Cloudflare.
+
 ## Runner lifecycle
 
 The Runner EC2 instance (`tag:Name=boxlite-runner`) holds load-bearing state:
@@ -247,7 +295,7 @@ operation by design:
 1. Verify no `running` boxes are pinned to this Runner (DB query against
    `box.runnerId`).
 2. Edit `sst.config.ts`: change `protect: true` to `protect: false` on the
-   Runner resource. Run `npx sst deploy --stage <stage>`. This only updates
+   Runner resource. Run `npm run deploy -- --stage <stage>`. This only updates
    the resource metadata; the EC2 is not yet touched.
 3. Destroy the EC2:
 
@@ -256,7 +304,7 @@ operation by design:
    ```
 
 4. Edit `sst.config.ts`: change `protect: false` back to `protect: true`. Run
-   `npx sst deploy` again — a new Runner is created with fresh state.
+   `npm run deploy` again — a new Runner is created with fresh state.
 
 This is deliberate by construction: three code edits across two deploys. If
 you find yourself doing this often, look at the future drain API (tracked
@@ -307,7 +355,7 @@ Auth: OIDC provider (Auth0/Okta/Keycloak/Dex/…) ← Api validates JWT via JWKS
 
 ## Troubleshooting
 
-**"concurrent update detected"** — run `npx sst unlock --stage dev` and retry.
+**"concurrent update detected"** — run `npm run sst -- unlock --stage dev` and retry.
 
 **Service stuck at `rolloutState: FAILED` with 1 running task** — stale event
 from an earlier failed deploy. If `runningCount == desiredCount` the service
@@ -375,6 +423,5 @@ initial setup: `aws ecs update-service --force-new-deployment --service Proxy`.
 | **Total**                             | **~$570** |
 
 Figures are approximate (ap-southeast-1 on-demand). The **Runner and the load
-balancers dominate** — the NAT is ~$16, not a headline cost. `npx sst remove
---stage dev` tears it all down; S3 buckets and RDS snapshots are retained in
+balancers dominate** — the NAT is ~$16, not a headline cost. `npm run remove -- --stage dev` tears it all down; S3 buckets and RDS snapshots are retained in
 production stage (`--stage production`) per SST's default.

apps/infra/package.json

@@ -4,9 +4,11 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "sst dev",
-    "deploy": "sst deploy",
-    "remove": "sst remove"
+    "dev": "node scripts/sst-with-cloudflare.mjs dev",
+    "deploy": "node scripts/sst-with-cloudflare.mjs deploy",
+    "remove": "node scripts/sst-with-cloudflare.mjs remove",
+    "sst": "node scripts/sst-with-cloudflare.mjs",
+    "secrets": "sst secret list"
   },
   "devDependencies": {
     "@pulumi/aws": "^7.24.0",

apps/infra/scripts/sst-with-cloudflare.mjs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 BoxLite AI
+
+/*
+ * Run an `sst` command with the Cloudflare provider credentials loaded.
+ *
+ * The Cloudflare provider initializes inside `app()` (sst.config.ts), before
+ * `run()` exists — so its credentials can't be `sst.Secret` like the app
+ * secrets. They live in AWS SSM Parameter Store (SecureString) instead, keyed
+ * per stage, and this wrapper fetches + exports them just before invoking sst.
+ * App secrets are NOT handled here; sst resolves those from its own store.
+ *
+ * Wired into the dev/deploy/remove npm scripts, plus a passthrough:
+ *   npm run deploy -- --stage dev      → node sst-with-cloudflare.mjs deploy --stage dev
+ *   npm run sst -- diff --stage dev     → any other subcommand
+ *
+ * One access gate: a deployer already needs AWS credentials to deploy, so the
+ * same credentials fetch the Cloudflare token from SSM — nothing extra to share.
+ *
+ * Seed the parameters once per stage:
+ *   aws ssm put-parameter --region ap-southeast-1 --type SecureString \
+ *     --name /boxlite/<stage>/cloudflare-api-token   --value "<token>"
+ *   aws ssm put-parameter --region ap-southeast-1 --type SecureString \
+ *     --name /boxlite/<stage>/cloudflare-account-id  --value "<account-id>"
+ *
+ * A credential already in the environment is used as-is (works offline / before
+ * the params are seeded). Missing creds are a warning, not a hard stop: commands
+ * that don't touch Cloudflare (e.g. `unlock`) still run, and sst surfaces its own
+ * error for one that does.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process'
+
+const REGION = process.env.AWS_REGION || 'ap-southeast-1'
+
+// SSM param consulted only when the matching env var is unset.
+const CREDS = [
+  { env: 'CLOUDFLARE_API_TOKEN', param: 'cloudflare-api-token' },
+  { env: 'CLOUDFLARE_DEFAULT_ACCOUNT_ID', param: 'cloudflare-account-id' },
+]
+
+const sstArgs = process.argv.slice(2)
+if (sstArgs.length === 0) {
+  console.error('sst-with-cloudflare: expected an sst subcommand (e.g. "deploy --stage dev")')
+  process.exit(1)
+}
+
+// Resolve the stage from the sst args (--stage x or --stage=x); the SSM path is
+// per-stage. Falls back to SST_STAGE then "dev".
+function resolveStage(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--stage' && args[i + 1]) return args[i + 1]
+    const m = args[i].match(/^--stage=(.+)$/)
+    if (m) return m[1]
+  }
+  return process.env.SST_STAGE || 'dev'
+}
+
+function fetchFromSsm(name) {
+  try {
+    const out = execFileSync(
+      'aws',
+      ['ssm', 'get-parameter', '--region', REGION, '--name', name, '--with-decryption', '--query', 'Parameter.Value', '--output', 'text'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+    ).trim()
+    return out && out !== 'None' ? out : null
+  } catch (err) {
+    if (err.code === 'ENOENT') console.warn('sst-with-cloudflare: `aws` CLI not found; skipping SSM lookup')
+    return null // ParameterNotFound / auth error → warn below and let sst decide
+  }
+}
+
+const stage = resolveStage(sstArgs)
+
+for (const { env, param } of CREDS) {
+  if (process.env[env]) continue // already provided — don't touch
+  const name = `/boxlite/${stage}/${param}`
+  const value = fetchFromSsm(name)
+  if (value) {
+    process.env[env] = value
+  } else {
+    console.warn(
+      `sst-with-cloudflare: ${env} not in env and ${name} not in SSM (${REGION}); ` +
+        `seed it with: aws ssm put-parameter --region ${REGION} --type SecureString --name ${name} --value <...>`,
+    )
+  }
+}
+
+// node_modules/.bin is on PATH because this runs via `npm run`, so `sst` resolves.
+const result = spawnSync('sst', sstArgs, { stdio: 'inherit', env: process.env })
+if (result.error) {
+  console.error(`sst-with-cloudflare: failed to launch sst: ${result.error.message}`)
+  process.exit(1)
+}
+process.exit(result.status ?? 1)

apps/infra/sst.config.ts

@@ -157,6 +157,22 @@ export default $config({
     const defaultRunnerApiKey = randomKey('DefaultRunnerApiKey')
     const pgAdminPassword = randomKey('PgAdminPassword', 24)
 
+    // App secrets — set via `sst secret set <NAME> --stage <stage>` (or bulk
+    // `sst secret load <dotenv>`); stored encrypted in SST state and shared
+    // per-stage by anyone with deploy access. Names match the env keys so a
+    // dotenv `sst secret load` maps 1:1. Optional ones carry an empty-string
+    // placeholder, so "unset" reads as '' — the same "empty = off" contract the
+    // SSH keys already relied on. NB: the Cloudflare provider creds can't live
+    // here (the provider initializes in app() before run() exists); they're
+    // injected from SSM by scripts/sst-with-cloudflare.mjs.
+    const oidcClientId = new sst.Secret('OIDC_CLIENT_ID', 'boxlite')
+    const oidcMgmtClientId = new sst.Secret('OIDC_MANAGEMENT_API_CLIENT_ID')
+    const oidcMgmtClientSecret = new sst.Secret('OIDC_MANAGEMENT_API_CLIENT_SECRET')
+    const posthogApiKey = new sst.Secret('POSTHOG_API_KEY', '')
+    const svixAuthToken = new sst.Secret('SVIX_AUTH_TOKEN', '')
+    const sshPrivateKey = new sst.Secret('SSH_PRIVATE_KEY_B64', '')
+    const sshHostKey = new sst.Secret('SSH_HOST_KEY_B64', '')
+
     // ─── 2. PLATFORM ─────────────────────────────────────────────────────────
     // Network model + rationale (subnets / NAT / egress-only public IP, AWS citations): ./NETWORKING.md
     // NAT instance (fck-nat, ~10× cheaper than a managed NAT Gateway). The Fargate
@@ -487,7 +503,7 @@ export default $config({
         ENCRYPTION_SALT: envOr('ENCRYPTION_SALT', encryptionSalt.result),
 
         // OIDC — external provider (Auth0/Okta/etc.)
-        OIDC_CLIENT_ID: envOr('OIDC_CLIENT_ID', 'boxlite'),
+        OIDC_CLIENT_ID: oidcClientId.value,
         OIDC_AUDIENCE: envOr('OIDC_AUDIENCE', 'boxlite'),
         OIDC_ISSUER_BASE_URL: requireOidcIssuer(),
         ...(process.env.PUBLIC_OIDC_DOMAIN && {
@@ -496,8 +512,12 @@ export default $config({
         // Optional: Auth0 Management API (enables account linking etc.)
         ...(process.env.OIDC_MANAGEMENT_API_ENABLED === 'true' && {
           OIDC_MANAGEMENT_API_ENABLED: 'true',
-          OIDC_MANAGEMENT_API_CLIENT_ID: requireEnv('OIDC_MANAGEMENT_API_CLIENT_ID', 'when OIDC_MANAGEMENT_API_ENABLED=true'),
-          OIDC_MANAGEMENT_API_CLIENT_SECRET: requireEnv('OIDC_MANAGEMENT_API_CLIENT_SECRET', 'when OIDC_MANAGEMENT_API_ENABLED=true'),
+          // Client id/secret come from the SST secret store now. If the feature
+          // is enabled but a secret is unset, the value resolves to '' and the
+          // Api errors at runtime — instead of the old deploy-time requireEnv
+          // throw (Output values can't be guarded at config-build time).
+          OIDC_MANAGEMENT_API_CLIENT_ID: oidcMgmtClientId.value,
+          OIDC_MANAGEMENT_API_CLIENT_SECRET: oidcMgmtClientSecret.value,
           OIDC_MANAGEMENT_API_AUDIENCE: requireEnv('OIDC_MANAGEMENT_API_AUDIENCE', 'when OIDC_MANAGEMENT_API_ENABLED=true'),
         }),
         // RP-initiated logout fallback. Safe to set unconditionally: the API
@@ -608,17 +628,14 @@ export default $config({
         DEFAULT_RUNNER_API_URL: runnerEndpoint('DEFAULT_RUNNER_API_URL', PORTS.RUNNER, 'http://'),
         DEFAULT_RUNNER_PROXY_URL: runnerEndpoint('DEFAULT_RUNNER_PROXY_URL', PORTS.PROXY, 'http://'),
 
-        // PostHog (enables the dashboard's "Create Box" feature flag)
-        ...(process.env.POSTHOG_API_KEY && {
-          POSTHOG_API_KEY: process.env.POSTHOG_API_KEY,
-          POSTHOG_HOST: envOr('POSTHOG_HOST', 'https://us.posthog.com'),
-        }),
+        // PostHog (enables the dashboard's "Create Box" feature flag). Token is a
+        // secret (empty = off); host stays plain config.
+        POSTHOG_API_KEY: posthogApiKey.value,
+        POSTHOG_HOST: envOr('POSTHOG_HOST', 'https://us.posthog.com'),
 
-        // Svix (webhook delivery; without this dashboard logs cosmetic errors)
-        ...(process.env.SVIX_AUTH_TOKEN && {
-          SVIX_AUTH_TOKEN: process.env.SVIX_AUTH_TOKEN,
-          ...(process.env.SVIX_SERVER_URL && { SVIX_SERVER_URL: process.env.SVIX_SERVER_URL }),
-        }),
+        // Svix (webhook delivery; empty token = off → dashboard logs cosmetic errors)
+        SVIX_AUTH_TOKEN: svixAuthToken.value,
+        ...(process.env.SVIX_SERVER_URL && { SVIX_SERVER_URL: process.env.SVIX_SERVER_URL }),
       },
     })
 
@@ -678,7 +695,7 @@ export default $config({
         PROXY_API_KEY: envOr('PROXY_API_KEY', proxyApiKey.result),
         // api-client-go appends paths like "/config" directly → include /api suffix
         BOXLITE_API_URL: $interpolate`${stripTrailingSlash(api.url)}/api`,
-        OIDC_CLIENT_ID: envOr('OIDC_CLIENT_ID', 'boxlite'),
+        OIDC_CLIENT_ID: oidcClientId.value,
         OIDC_AUDIENCE: envOr('OIDC_AUDIENCE', 'boxlite'),
         OIDC_DOMAIN: requireOidcIssuer(),
       },
@@ -698,8 +715,8 @@ export default $config({
         // must use the API base path rather than the raw ALB root.
         API_URL: $interpolate`${stripTrailingSlash(api.url)}/api`,
         API_KEY: envOr('SSH_GATEWAY_API_KEY', sshGatewayApiKey.result), // NB: not SSH_GATEWAY_API_KEY
-        SSH_PRIVATE_KEY: envOr('SSH_PRIVATE_KEY_B64', ''),
-        SSH_HOST_KEY: envOr('SSH_HOST_KEY_B64', ''),
+        SSH_PRIVATE_KEY: sshPrivateKey.value,
+        SSH_HOST_KEY: sshHostKey.value,
       },
     })
 
@@ -830,7 +847,7 @@ export default $config({
     // nothing on the internet can reach the runner.
     const runnerSecurityGroup = new aws.ec2.SecurityGroup('RunnerSecurityGroup', {
       vpcId: vpc.nodes.vpc.id,
-      description: 'BoxLite runner — inbound only on the runner API port from within the VPC',
+      description: 'BoxLite runner - inbound only on the runner API port from within the VPC',
       ingress: [
         {
           protocol: 'tcp',