feat(bb-data): configurable TLS for external database connections

[vishaalmehrishi]

What

Adds an ssl option to the connection-string form of fromExisting(...) and makes server-certificate verification the default for external PostgreSQL connections (Supabase, Neon, RDS). db pull captures the provider's CA so generated apps verify by default — including in the deployed Lambda — with no runtime configuration.

Previously the external-database paths hardcoded ssl: { rejectUnauthorized: false }, so there was no supported way to configure TLS verification for these connections.

Approach

The connection's TLS policy is now configurable and verifies by default, with the CA delivered so verification actually works at every layer:

1. Type — ExternalDatabaseRef's connection-string variant gains ssl?: { rejectUnauthorized?: boolean; ca?: string }.
2. Runtime (index.aws.ts) — passes the caller's ssl through; PgClientEngine already defaults to { rejectUnauthorized: true }, so omitting ssl verifies.
3. Local dev (index.mock.ts) — honors connection.ssl; keeps an unverified default only for self-signed local databases.
4. db pull — prompts for the provider CA and writes it to a generated, committed database.ca.ts (a public, non-secret certificate — public key + issuer metadata, no private key). The generated supabase.ts pins it via a visible resolveDbSsl(). Because it's a bundled JS import (not a runtime file/env read), verification works in the deployed Lambda with no env/SSM/CDK plumbing. DATABASE_CA_CERT (inline PEM or path) overrides it; with no CA the wiring falls back to a visible, editable rejectUnauthorized: false.
5. Operational paths (introspect, migrate CLI, external migrations) — resolve ssl via a shared externalDbSsl() helper and strip sslmode from the URL so a pinned CA takes effect (node pg ignores a programmatic ssl.ca when sslmode is present).

Why a committed cert (not an env var): .env.* is only loaded on the deploy host, never injected into the Lambda — so an env-only CA would leave the deployed runtime unverified. The CA isn't secret, so committing + bundling it is the simplest mechanism that verifies in production. It's regenerated on each db pull (rotation) and preserved when a re-pull doesn't re-supply it (no silent downgrade).

What a customer sees

npx bb-data pull now asks for the CA and explains what it does:

TLS verification (recommended): download your CA certificate from the Supabase
dashboard → Database Settings → SSL Configuration (prod-ca-2021.crt).
  Path to CA certificate [Enter to skip]: ./prod-ca-2021.crt
  ✓ CA captured. It will be written to aws-blocks/database.ca.ts (a public cert, committed with
    your app). The generated connection (resolveDbSsl in supabase.ts) pins it, so
    your database's TLS certificate is verified — both with `npm run dev` and in the
    deployed function (the file is bundled). Re-run `bb-data pull` to refresh a
    rotated CA. Details: MIGRATION_GUIDE.md → "Securing the connection (TLS)".

Generated aws-blocks/supabase.ts (the wiring — TLS policy is visible and editable):

import { DATABASE_CA_CERT } from './database.ca.js';

function resolveDbSsl(): { ca?: string; rejectUnauthorized: boolean } {
  // DATABASE_CA_CERT (inline PEM or a file path) overrides the committed cert.
  const envCa = process.env.DATABASE_CA_CERT;
  const ca = envCa
    ? (envCa.includes('-----BEGIN') ? envCa : readFileSync(envCa, 'utf8'))
    : (DATABASE_CA_CERT || undefined);
  if (ca) {
    console.log('[bb-data] DB TLS: verifying the server certificate against the pinned CA (verify-full equivalent).');
    return { ca, rejectUnauthorized: true };
  }
  console.warn('[bb-data] DB TLS: server certificate NOT verified — encrypted only (no CA). ...');
  return { rejectUnauthorized: false };
}

export const db = new Database(scope, 'db', {
  connection: fromExisting({ connectionString: { get: resolveConnString }, ssl: resolveDbSsl() }),
  rlsPolicy: 'enforce',
  schema: tableMeta,
});

Generated aws-blocks/database.ca.ts (regenerated each pull; the customer's actual project CA):

// Generated by `db pull` — safe to regenerate.
export const DATABASE_CA_CERT = `-----BEGIN CERTIFICATE-----
MII... (your project's CA)
-----END CERTIFICATE-----`;

How the customer uses it is unchanged — spread supabaseCrud into an ApiNamespace:

import { supabaseCrud } from './supabase.js';
export const api = new ApiNamespace(scope, 'api', (context) => ({
  ...supabaseCrud(context, auth),
}));

On first connect the runtime logs the resolved mode, e.g. [bb-data] DB TLS: verifying the server certificate against the pinned CA (verify-full equivalent).

Behavior change

For hand-written fromExisting({ connectionString }) with no ssl, the connection now verifies the server certificate (it previously did not). Private-CA providers (e.g. Supabase) require pinning the CA via ssl: { ca } (the certificate contents). Pass ssl: { rejectUnauthorized: false } to keep the old behavior explicitly. db pull-generated apps are unaffected in default connectivity. Released as a minor bump (see the changeset's upgrade note).

Testing

• bb-data unit suite: 336/336 passing (engine default + explicit ssl, externalDbSsl, generateCaFile, resolveCaFileWrite incl. the preserve-on-re-pull regression, generated-wiring assertions, updated toSessionPortUrl).
• db-pull-typecheck app tsc --noEmit passes against the regenerated snapshot (generated wiring imports the committed CA constant).
• Not run in this environment: Biome lint and the live Supabase end-to-end job (no DB credentials) — both run in CI.

Notes

• database.ca.ts holds a certificate only (no private key); the connection string and other secrets continue to flow through SSM, not the repo. The MIGRATION_GUIDE notes keeping it committed and that a separate production project may present its own CA.
• Operational db pull introspection resolves ssl from the captured CA / environment (it runs on the operator host, not the Lambda).

[soberm]

What happens with an app that used a prior version? Will it keep ssl off?

[vishaalmehrishi]

What happens with an app that used a prior version? Will it keep ssl off?

Two cases:

• db pull-generated apps: the verified wiring (resolveDbSsl() + the committed database.ca.ts) is only emitted on a re-pull. An app generated before this change keeps its existing supabase.ts (no ssl) until the next npx bb-data pull — so yes, it stays ssl-off until re-pulled. A re-pull regenerates the wiring and prompts for the CA.
• Hand-written fromExisting({ connectionString }) with no ssl: behavior changes to verify by default. A private-CA provider (e.g. Supabase) will now fail until the CA is pinned via ssl: { ca } — or pass ssl: { rejectUnauthorized: false } to keep the old behavior explicitly. This is captured as an upgrade note in the changeset (minor bump).

Happy to add the "re-pull to pick up verification" note to the generated migration guide so existing-app users aren't surprised.

[vishaalmehrishi]

What happens with an app that used a prior version? Will it keep ssl off?

Good question — it's a deliberate behavior change, and it splits by how the app connects:

• db pull-generated apps: unaffected in default connectivity. The generated supabase.ts wiring (resolveDbSsl()) is regenerated on each pull and supplies an explicit ssl config (pins the captured CA, or a visible commented opt-out), so upgrading the library doesn't silently change their behavior.
• Hand-written fromExisting({ connectionString }) with no ssl: this now verifies the server certificate (it previously hardcoded rejectUnauthorized: false). For a private-CA provider like Supabase that means the connection will fail until they pin the CA via ssl: { ca } — which is the intent: the old default silently accepted any certificate (MITM-exposed). Passing ssl: { rejectUnauthorized: false } keeps the old behavior explicitly.

Shipped as a minor with an upgrade/remediation note in the changeset so the break is discoverable. So no — it does not keep ssl off by default anymore; that default was the vulnerability.