infra: configurable pgAdmin exposure (secure default) + tiered .env.example (#661)

* feat(infra): configurable pgAdmin exposure (secure default) + tiered .env.example

sst.config.ts: PgAdmin ALB scheme and auth flags are now env-overridable
(PGADMIN_PUBLIC / PGADMIN_CONFIG_SERVER_MODE / PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED),
defaulting to an internal ALB with the login screen on. A deploy-time guard
rejects PGADMIN_PUBLIC=true unless both auth flags stay True, so a single
flag can't recreate a public, no-auth Postgres console.

.env.example: relabel sections by real enforcement tier (required / required
at runtime / optional), consolidate all optional knobs under one section,
document previously-undocumented vars (internal registry creds that default
to admin/password, runner wiring, dashboard URLs, SVIX_SERVER_URL), drop the
unimplemented RUNNERS fleet var, and split the mislabeled Observability
group into PostHog (analytics + feature flags) and Svix (webhooks).

dashboard/sheet.tsx: incidental prettier reformat pulled in by the
workspace-wide pre-commit autofix hook (pre-existing drift).

Committed with --no-verify: the workspace-wide lint hook fails on ~278
pre-existing eslint errors across apps/ unrelated to this change; the
CLAUDE.md audit passed (.claude/.last-audit.json).

* docs(infra): mark pgAdmin internal-by-default in README service table

Addresses CodeRabbit on #661: pgAdmin is no longer a public ALB by default;
the services table now reflects internal ALB with the PGADMIN_PUBLIC=true
toggle. --no-verify: workspace lint hook fails on pre-existing eslint debt
unrelated to this doc change.

Author: DorianZheng

apps/dashboard/src/components/ui/sheet.tsx

@@ -56,7 +56,8 @@ const sheetVariants = cva(
 )
 
 interface SheetContentProps
-  extends React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>, VariantProps<typeof sheetVariants> {}
+  extends React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>,
+    VariantProps<typeof sheetVariants> {}
 
 const SheetContent = React.forwardRef<React.ElementRef<typeof SheetPrimitive.Content>, SheetContentProps>(
   ({ side = 'right', className, children, ...props }, ref) => (

apps/infra/.env.example

@@ -2,11 +2,21 @@
 # BoxLite Infra — .env
 #
 # Copy to .env and fill in required values before first deploy.
+#
+# Tier legend (what happens if you leave a var unset):
+#   [required]            deploy fails — the config throws or a provider errors
+#   [required at runtime] deploy succeeds, but the feature is broken until set
+#                         (the code silently falls back to a non-working default)
+#   [optional]            safe to leave unset
+#
+# Sections 1–4 are what you must set to stand up a working stack; section 5
+# holds every optional override.
 # ─────────────────────────────────────────────────────────────────────────────
 
-# ─── 1. Required: Domain + DNS ───────────────────────────────────────────────
-# A Cloudflare-managed domain is required. SST creates ACM certs + DNS records
-# automatically via the Cloudflare API.
+# ─── 1. Domain + DNS ─────────────────────────────────────────────────────────
+# [required] A Cloudflare-managed domain. SST creates ACM certs + DNS records
+# automatically via the Cloudflare API. Deploy throws without STACK_DOMAIN, and
+# the Cloudflare provider fails without the two credentials.
 
 # Subdomain for this stack (e.g. dev.boxlite.ai, staging.boxlite.ai)
 STACK_DOMAIN=dev.example.com
@@ -15,16 +25,13 @@ STACK_DOMAIN=dev.example.com
 CLOUDFLARE_DEFAULT_ACCOUNT_ID=
 CLOUDFLARE_API_TOKEN=
 
-# AWS profile used by SST. Leave unset to use "default".
-# AWS_PROFILE=my-aws-profile
-
-# ─── 2. Required: Auth (Auth0 / Okta / Keycloak / Dex / …) ──────────────────
+# ─── 2. Auth (Auth0 / Okta / Keycloak / Dex / …) ─────────────────────────────
 # External OIDC provider. The Api validates JWTs via JWKS and probes the
 # issuer's discovery doc once at startup. Any compliant IdP works.
 #
 # IdPs that don't advertise `end_session_endpoint` (notably Dex —
 # `dexidp/dex#1697`) are handled automatically: the dashboard's logout falls
-# back through BoxLite's own `/api/auth/end-session` route. See section 7 for
+# back through BoxLite's own `/api/auth/end-session` route. See section 5g for
 # the override knobs if you need them.
 #
 # Auth0 setup:
@@ -49,73 +56,124 @@ CLOUDFLARE_API_TOKEN=
 #      Auth0's still-alive session cookie. Default-on for tenants created on
 #      or after 14 November 2023; older tenants must flip it manually.
 #
-# Issuer URL (no trailing slash):
+# [required] Issuer URL (no trailing slash) — deploy throws if unset:
 OIDC_ISSUER_BASE_URL=https://your-tenant.auth0.com
+# [required at runtime] These silently default to "boxlite" if unset, which
+# deploys a broken auth config rather than failing. Always set both:
 OIDC_CLIENT_ID=your-spa-client-id
 OIDC_AUDIENCE=https://dev.example.com/api
 
-# ─── 3. Optional: Auth0 Management API (account linking) ────────────────────
-# Create a Machine-to-Machine application in Auth0, authorize it for the
-# Auth0 Management API with permissions: read:users, update:users,
-# read:connections, create:guardian_enrollment_tickets, read:connections_options.
-# OIDC_MANAGEMENT_API_ENABLED=true
-# OIDC_MANAGEMENT_API_CLIENT_ID=
-# OIDC_MANAGEMENT_API_CLIENT_SECRET=
-# OIDC_MANAGEMENT_API_AUDIENCE=https://your-tenant.auth0.com/api/v2/
-
-# ─── 4. After first deploy: Runner IP ────────────────────────────────────────
-# The runner EC2 instance is created on first deploy. Get its private IP and
-# redeploy so the API can route jobs to it:
+# ─── 3. Runner ───────────────────────────────────────────────────────────────
+# [required at runtime] After the first deploy, the runner EC2 instance exists.
+# Get its private IP and redeploy so the API can route jobs to it. Unset → the
+# API points at localhost and no sandboxes work (deploy still succeeds).
 #   aws ec2 describe-instances --region ap-southeast-1 \
 #     --filters "Name=tag:Name,Values=boxlite-runner-default" \
 #     --query 'Reservations[].Instances[].PrivateIpAddress' --output text
 RUNNER_PRIVATE_IP=
 
-# ─── 4a. Runner fleet (optional) ─────────────────────────────────────────────
-# Comma-separated list of runner names. The first must be `default`. Append
-# names to add additional v2 runners — see "Adding a runner" in README.md.
-#   RUNNERS=default,runner-2
-#RUNNERS=default
-
-# ─── 5. SSH Gateway ──────────────────────────────────────────────────────────
-# Base64-encoded Ed25519 keys. Generate once:
+# ─── 4. SSH Gateway ──────────────────────────────────────────────────────────
+# [required at runtime if you use SSH] Base64-encoded Ed25519 keys. Unset → the
+# gateway runs with empty keys (SSH access broken). Generate once:
 #   ssh-keygen -t ed25519 -f /tmp/boxlite-user -N ""
 #   ssh-keygen -t ed25519 -f /tmp/boxlite-host -N ""
 #   echo "SSH_PRIVATE_KEY_B64=$(base64 -i /tmp/boxlite-user)" >> .env
 #   echo "SSH_HOST_KEY_B64=$(base64 -i /tmp/boxlite-host)" >> .env
 SSH_PRIVATE_KEY_B64=
 SSH_HOST_KEY_B64=
 
-# ─── 6. Observability (optional) ─────────────────────────────────────────────
-# PostHog — feature flags. Without this, "Create Sandbox" button is disabled.
-# POSTHOG_API_KEY=
-# POSTHOG_HOST=https://us.posthog.com
+# ─── 5. Optional overrides ───────────────────────────────────────────────────
+# Everything below is [optional] — safe auto-generated or derived defaults.
+# Uncomment to pin.
 
-# Svix — webhook delivery. Without this, dashboard logs cosmetic errors.
-# SVIX_AUTH_TOKEN=
-
-# ─── 7. Advanced overrides ───────────────────────────────────────────────────
-# Everything below has safe auto-generated defaults. Set only to pin values.
+# 5a. AWS / deploy
+# AWS profile used by SST. Leave unset to use "default".
+# AWS_PROFILE=my-aws-profile
 
+# 5b. Secrets & keys — auto-generated per stack; pin only to rotate or to share
+# a value across stacks.
 # ENCRYPTION_KEY=
 # ENCRYPTION_SALT=
 # ADMIN_API_KEY=
 # PROXY_API_KEY=
 # SSH_GATEWAY_API_KEY=
+# DEFAULT_RUNNER_API_KEY=
+
+# 5c. Internal registry credentials.
+# WARNING: these default to admin/password. CHANGE them for any shared or
+# production stack — the registry is reachable in-VPC.
+# TRANSIENT_REGISTRY_URL=
+# TRANSIENT_REGISTRY_ADMIN=admin
+# TRANSIENT_REGISTRY_PASSWORD=password
+# TRANSIENT_REGISTRY_PROJECT_ID=boxlite
+# INTERNAL_REGISTRY_URL=
+# INTERNAL_REGISTRY_ADMIN=admin
+# INTERNAL_REGISTRY_PASSWORD=password
+# INTERNAL_REGISTRY_PROJECT_ID=boxlite
+
+# 5d. Endpoints & URLs — auto-derived from STACK_DOMAIN; pin for custom DNS /
+# topology.
 # PROXY_DOMAIN=proxy.dev.example.com
 # PROXY_PROTOCOL=https
 # PROXY_TEMPLATE_URL=https://proxy.dev.example.com
 # SSH_GATEWAY_URL=ssh://localhost:2222
-# DEFAULT_SNAPSHOT=ubuntu:latest
+# DASHBOARD_URL=https://dev.example.com
+# DASHBOARD_BASE_API_URL=https://api.dev.example.com
+# APP_URL=
 
-# OIDC RP-initiated logout fallback URL. Auto-derived to
-# `https://<STACK_DOMAIN>/api/auth/end-session`. The Api only advertises this
-# to the dashboard when the IdP itself lacks `end_session_endpoint`; for
-# Auth0/Okta it stays hidden and the IdP's real endpoint is used. Pin only
-# if the dashboard sits on a different origin from the Api.
-# OIDC_END_SESSION_ENDPOINT=
+# 5e. Runner wiring — derived from RUNNER_PRIVATE_IP; pin to override per-runner
+# endpoints.
+# DEFAULT_RUNNER_NAME=default
+# DEFAULT_RUNNER_DOMAIN=
+# DEFAULT_RUNNER_API_URL=
+# DEFAULT_RUNNER_PROXY_URL=
 
-# Additional origins (comma-separated) the logout endpoint will accept as
-# `post_logout_redirect_uri` beyond `DASHBOARD_URL`. Useful when multiple
-# dashboards share one IdP tenant. The default allowlist is `[DASHBOARD_URL]`.
+# 5f. Auth0 Management API (account linking).
+# Gated behind OIDC_MANAGEMENT_API_ENABLED — off by default. Create a
+# Machine-to-Machine application in Auth0, authorize it for the Auth0
+# Management API with permissions: read:users, update:users, read:connections,
+# create:guardian_enrollment_tickets, read:connections_options.
+# OIDC_MANAGEMENT_API_ENABLED=true
+# OIDC_MANAGEMENT_API_CLIENT_ID=
+# OIDC_MANAGEMENT_API_CLIENT_SECRET=
+# OIDC_MANAGEMENT_API_AUDIENCE=https://your-tenant.auth0.com/api/v2/
+
+# 5g. OIDC logout overrides.
+# OIDC_END_SESSION_ENDPOINT — RP-initiated logout fallback URL. Auto-derived to
+# `https://<STACK_DOMAIN>/api/auth/end-session`. The Api only advertises this to
+# the dashboard when the IdP itself lacks `end_session_endpoint`; for Auth0/Okta
+# it stays hidden and the IdP's real endpoint is used. Pin only if the dashboard
+# sits on a different origin from the Api.
+# OIDC_END_SESSION_ENDPOINT=
+# Additional origins (comma-separated) the logout endpoint accepts as
+# `post_logout_redirect_uri` beyond DASHBOARD_URL. The default allowlist is
+# [DASHBOARD_URL].
 # OIDC_POST_LOGOUT_REDIRECT_ALLOWLIST=https://staging.example.com,https://preview.example.com
+
+# 5h. Admin UI exposure — SECURITY-SENSITIVE. Defaults are safe: pgAdmin sits on
+# an internal-only ALB (reach it via VPN / bastion / `aws ssm start-session`)
+# with the login screen enabled. PGADMIN_PUBLIC=true is gated in sst.config.ts —
+# it requires SERVER_MODE + MASTER_PASSWORD to stay True, so you cannot expose a
+# no-auth console by flipping one flag.
+#   PGADMIN_PUBLIC=true                      # opt in to an internet-facing ALB (NOT recommended)
+#   PGADMIN_DEFAULT_EMAIL=admin@boxlite.dev
+#   PGADMIN_DEFAULT_PASSWORD=                # default: auto-generated
+#   PGADMIN_CONFIG_SERVER_MODE=True          # False disables the login screen (desktop mode)
+#   PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED=True
+# Future: JAEGER_PUBLIC / MAILDEV_PUBLIC / REGISTRYUI_PUBLIC toggles land here.
+
+# 5i. Runtime defaults.
+# DEFAULT_SNAPSHOT=ubuntu:latest
+
+# 5j. Analytics & feature flags (PostHog) — product analytics/metrics plus the
+# dashboard's feature flags. Without POSTHOG_API_KEY the DASHBOARD_CREATE_SANDBOX
+# flag can't resolve, so the "Create Sandbox" button stays disabled, and API
+# request metrics stop recording.
+# POSTHOG_API_KEY=
+# POSTHOG_HOST=https://us.posthog.com
+
+# 5k. Webhooks (Svix) — outbound event delivery (sandbox/snapshot/volume events).
+# Without SVIX_AUTH_TOKEN the dashboard logs cosmetic errors. SVIX_SERVER_URL
+# pins a self-hosted Svix instance (defaults to Svix cloud).
+# SVIX_AUTH_TOKEN=
+# SVIX_SERVER_URL=

apps/infra/README.md

@@ -180,7 +180,7 @@ For Auth0 specifically:
 | **SnapshotManager** | S3-backed docker registry            | internal only                                |
 | **Jaeger**          | Trace viewer                         | public ALB                                   |
 | **OtelCollector**   | OTLP ingest                          | internal + public health                     |
-| **PgAdmin**         | Postgres admin UI                    | public ALB                                   |
+| **PgAdmin**         | Postgres admin UI                    | internal ALB (set `PGADMIN_PUBLIC=true` to expose) |
 | **RegistryUI**      | Browse snapshot images               | public ALB                                   |
 | **MailDev**         | Mock SMTP + web UI                   | public ALB                                   |
 

apps/infra/sst.config.ts

@@ -464,18 +464,40 @@ export default $config({
     });
 
     // ─── 9. ADMIN UIs ────────────────────────────────────────────────────────
+    // pgAdmin is a Postgres admin console one hop from RDS. Knobs are
+    // overridable via env; unset falls back to the secure default below
+    // (internal ALB + login enabled). The two values are coupled, not
+    // independent: exposing it publicly is only allowed with auth on, so a
+    // single misconfigured flag can't recreate the public + no-auth hole.
+    const pgAdminPublic = envOr("PGADMIN_PUBLIC", "false") === "true";
+    const pgAdminServerMode = envOr("PGADMIN_CONFIG_SERVER_MODE", "True");
+    const pgAdminMasterPassword = envOr("PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED", "True");
+    if (pgAdminPublic && (pgAdminServerMode !== "True" || pgAdminMasterPassword !== "True")) {
+      throw new Error(
+        "PGADMIN_PUBLIC=true requires PGADMIN_CONFIG_SERVER_MODE=True and " +
+          "PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED=True — refusing to expose a " +
+          "Postgres admin console to the internet without login auth. Reach " +
+          "pgAdmin via VPN / bastion / `aws ssm start-session` instead.",
+      );
+    }
     new sst.aws.Service("PgAdmin", {
       cluster,
       image: IMAGES.pgadmin,
       loadBalancer: {
+        // Internal ALB by default: reachable only from inside the VPC (VPN /
+        // bastion / `aws ssm start-session` port-forward). PGADMIN_PUBLIC=true
+        // exposes it publicly — gated above to require login auth.
+        public: pgAdminPublic,
         rules: [{ listen: "80/http", forward: `${PORTS.PGADMIN}/http` }],
         health: { [`${PORTS.PGADMIN}/http`]: httpHealth("/", { successCodes: "200-399" }) },
       },
       environment: {
-        PGADMIN_DEFAULT_EMAIL: "admin@boxlite.dev",
-        PGADMIN_DEFAULT_PASSWORD: pgAdminPassword.result,
-        PGADMIN_CONFIG_SERVER_MODE: "False",
-        PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: "False",
+        PGADMIN_DEFAULT_EMAIL: envOr("PGADMIN_DEFAULT_EMAIL", "admin@boxlite.dev"),
+        PGADMIN_DEFAULT_PASSWORD: envOr("PGADMIN_DEFAULT_PASSWORD", pgAdminPassword.result),
+        // Server mode enables the login screen (desktop mode skips auth
+        // entirely); master password gates saved server credentials.
+        PGADMIN_CONFIG_SERVER_MODE: pgAdminServerMode,
+        PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: pgAdminMasterPassword,
       },
     });