fix(security): guard + audit the dev-fallback direct customer-DB DROP path (truehomie-db) (#286)

* fix(security): guard + audit the dev-fallback direct customer-DB DROP path (truehomie-db)

The PROVISIONER_ADDR-unset dev-fallback providers (db/local.go, nosql/mongo.go)
ran direct DROP DATABASE / DROP USER (Postgres) and dropDatabase / dropUser
(Mongo) as the customer-DB superuser with ZERO audit trail. An api process
started without PROVISIONER_ADDR but with a prod CUSTOMER_DATABASE_URL /
MONGO_ADMIN_URI (a laptop/.env/E2E run pointed at the then-public admin host)
would CREATE/DROP real customer databases unlogged — the 2026-06-03 truehomie
incident signature (an active Pro customer's DB + role dropped by an
unidentified, non-audited path).

Defense in depth, smallest blast radius first, in a new internal/providers/
dbsafety package (api-internal mirror of the provisioner-side dropguard D3):

  1. Production refusal. The fallback is DEV-ONLY, so GuardDrop fails closed
     when effectively in production: a prod-class ENVIRONMENT, OR a target DSN
     host that is not clearly local/in-cluster/dev (public FQDN, *.instanode.dev,
     *.ondigitalocean.com, routable public IP). Localhost / 127.x / ::1 /
     RFC1918 / in-cluster service short-names stay dev-safe, so local dev, CI
     (TEST_* DBs on localhost), and the port-forwarded full-stack E2E flow keep
     working.
  2. Name-convention + denylist guard. Every DROP target must carry the
     per-tenant db_ / usr_ prefix + a [A-Za-z0-9._-] token and miss the system
     denylist (postgres, template0/1, instant_customers, instant_platform,
     instanode_admin, doadmin, admin/local/config, …). An empty/wildcard/system
     name can never reach the DROP.
  3. Audit. Every sanctioned drop emits an audit_log row of new kind
     customer_db.direct_drop (operator-internal, NOT a customer email) via an
     injected sink — models.WireDBSafetyAuditSink wires a *sql.DB writer at
     handler construction; provider unit tests fall back to a structured-slog
     sink. So even if layers 1+2 pass there is a forensic trail.

The guard runs BEFORE the superuser connection is opened, so a refused op never
touches the customer cluster. New dbsafety + sink code is 100% unit-covered;
the four DROP sites (local.go DROP DATABASE/USER, mongo.go dropUser/
dropDatabase) are all guarded.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(dbsafety): cover uppercase char-class branch in validTokenChars

CI diff-cover flagged dbsafety.go:134 (the `case c >= 'A' && c <= 'Z'`
branch) — every existing good-token in TestCheckDatabaseName was lowercase
(UUIDs are lowercase hex), so the uppercase case never fired. Added a
mixed-case good token (e2e/CI tokens may carry A-Z, per the function's own
comment). dbsafety pkg now 100.0% statements; line 134 covered.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mastermanas805

internal/handlers/db.go

@@ -53,6 +53,9 @@ func NewDBHandler(db *sql.DB, rdb *redis.Client, cfg *config.Config, provClient
 	if provClient == nil {
 		// fall back to local provider
 		h.dbProvider = dbprovider.New(cfg, cfg.PostgresCustomersURL)
+		// Wire the *sql.DB-backed dbsafety audit sink so the dev-fallback
+		// provider's direct DROPs are recorded in audit_log (truehomie-db).
+		models.WireDBSafetyAuditSink(db)
 	}
 	return h
 }

internal/handlers/nosql.go

@@ -41,7 +41,10 @@ func NewNoSQLHandler(db *sql.DB, rdb *redis.Client, cfg *config.Config, provClie
 	}
 	if provClient == nil {
 		// fall back to local provider
-		h.nosqlProvider = nosqlprovider.New(cfg.MongoAdminURI, cfg.MongoHost)
+		h.nosqlProvider = nosqlprovider.New(cfg.MongoAdminURI, cfg.MongoHost, cfg.Environment)
+		// Wire the *sql.DB-backed dbsafety audit sink so the dev-fallback
+		// provider's dropUser/dropDatabase are recorded in audit_log.
+		models.WireDBSafetyAuditSink(db)
 	}
 	return h
 }

internal/handlers/vector.go

@@ -87,6 +87,8 @@ func NewVectorHandler(db *sql.DB, rdb *redis.Client, cfg *config.Config, provCli
 	}
 	if provClient == nil {
 		h.dbProvider = dbprovider.New(cfg, cfg.PostgresCustomersURL)
+		// Wire the dbsafety audit sink for the dev-fallback DROP path.
+		models.WireDBSafetyAuditSink(db)
 	}
 	return h
 }

internal/models/dbsafety_audit_sink.go

@@ -0,0 +1,84 @@
+package models
+
+// dbsafety_audit_sink.go — the *sql.DB-backed audit sink for the dbsafety guard
+// used by the dev-fallback (PROVISIONER_ADDR-unset) customer-data providers
+// (internal/providers/db/local.go + internal/providers/nosql/mongo.go).
+//
+// dbsafety lives below the models layer and must not import it (that would pull
+// the platform-DB stack into the provider packages and risk a cycle). So the
+// audit emission is an injected seam: dbsafety calls its AuditSink interface;
+// this file provides the production implementation that writes an audit_log row
+// of kind customer_db.direct_drop via InsertAuditEvent.
+//
+// The sink is registered once at handler construction (the fallback path of
+// NewDBHandler / NewNoSQLHandler / NewVectorHandler) via WireDBSafetyAuditSink.
+// Writes are best-effort and bounded: an audit failure must NEVER block (or
+// fail) a deprovision (audit_log.go's contract).
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"log/slog"
+	"time"
+
+	"instant.dev/internal/providers/dbsafety"
+	"instant.dev/internal/safego"
+)
+
+// dbSafetyAuditTimeout bounds the best-effort audit write so a stalled
+// platform-DB never wedges (or delays) the deprovision goroutine.
+const dbSafetyAuditTimeout = 3 * time.Second
+
+// dbSafetyAuditSink persists one audit_log row of kind customer_db.direct_drop
+// per sanctioned direct drop. It never blocks the caller — the row is written
+// in a panic-safe, bounded-context goroutine.
+type dbSafetyAuditSink struct {
+	db *sql.DB
+}
+
+// WireDBSafetyAuditSink installs a *sql.DB-backed dbsafety audit sink. Called
+// once from the fallback path of the provisioning handler constructors. A nil
+// db (test config) leaves the structured-slog default sink in place so the
+// event is still logged.
+func WireDBSafetyAuditSink(db *sql.DB) {
+	if db == nil {
+		return
+	}
+	dbsafety.SetAuditSink(&dbSafetyAuditSink{db: db})
+}
+
+// Emit writes the audit_log row best-effort. The metadata captures the
+// destroyed identifiers + the admin DSN host (never credentials) so an operator
+// can reconstruct exactly what the api dropped, and where — even though layers
+// 1+2 of the guard should make a prod drop unreachable.
+func (s *dbSafetyAuditSink) Emit(_ context.Context, rec dbsafety.AuditRecord) {
+	// json.Marshal of a fixed-shape map[string]string cannot error — the only
+	// failure modes are unsupported types / cycles, neither of which a string
+	// map has. A nil meta would be a strictly worse audit than the marshalled
+	// one, which always succeeds here, so the error is intentionally dropped.
+	meta, _ := json.Marshal(map[string]string{
+		"provider": rec.Provider,
+		"token":    rec.Token,
+		"database": rec.DatabaseName,
+		"user":     rec.UserName,
+		"dsn_host": rec.DSNHost,
+	})
+
+	safego.Go("dbsafety.audit.emit", func() {
+		bgCtx, cancel := context.WithTimeout(context.Background(), dbSafetyAuditTimeout)
+		defer cancel()
+		ev := AuditEvent{
+			Actor:    "system",
+			Kind:     rec.Kind,
+			Summary:  "direct customer-DB drop via dev-fallback provider",
+			Metadata: meta,
+		}
+		if err := InsertAuditEvent(bgCtx, s.db, ev); err != nil {
+			// Best-effort: a failed audit write must not surface anywhere.
+			// Log loudly — a missing trail for THIS kind is itself notable.
+			slog.WarnContext(bgCtx, "dbsafety_audit: InsertAuditEvent failed",
+				"audit_kind", rec.Kind, "error", err)
+		}
+	})
+}

internal/models/dbsafety_audit_sink_mock_test.go

@@ -0,0 +1,73 @@
+package models
+
+// dbsafety_audit_sink_mock_test.go — white-box (package models) coverage of the
+// dbSafetyAuditSink.Emit branches via sqlmock, with no live DB. Covers the
+// goroutine insert (happy) and the InsertAuditEvent-failure log branch
+// deterministically. The integration row-lands test lives in the package
+// models_test file.
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/stretchr/testify/require"
+
+	"instant.dev/internal/providers/dbsafety"
+)
+
+func sampleRecord() dbsafety.AuditRecord {
+	return dbsafety.AuditRecord{
+		Kind:         dbsafety.AuditKindCustomerDBDirectDrop,
+		Provider:     "db.local",
+		Token:        "tok",
+		DatabaseName: "db_tok",
+		UserName:     "usr_tok",
+		DSNHost:      "postgres-customers",
+	}
+}
+
+// waitForExpectations polls the mock until every expectation is met or the
+// deadline passes — the Emit insert runs in a safego goroutine.
+func waitForExpectations(t *testing.T, mock sqlmock.Sqlmock) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		if err := mock.ExpectationsWereMet(); err == nil {
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("sqlmock expectations not met before deadline: %v", mock.ExpectationsWereMet())
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
+// TestDBSafetyAuditSink_Emit_Inserts covers the happy goroutine path: Emit
+// marshals the metadata and InsertAuditEvent writes the row.
+func TestDBSafetyAuditSink_Emit_Inserts(t *testing.T) {
+	db, mock := newMock(t)
+	mock.ExpectExec(`INSERT INTO audit_log`).WillReturnResult(sqlmock.NewResult(0, 1))
+
+	s := &dbSafetyAuditSink{db: db}
+	s.Emit(context.Background(), sampleRecord())
+
+	waitForExpectations(t, mock)
+}
+
+// TestDBSafetyAuditSink_Emit_InsertError covers the InsertAuditEvent-failure log
+// branch: the insert errors but Emit must not panic or surface anything.
+func TestDBSafetyAuditSink_Emit_InsertError(t *testing.T) {
+	db, mock := newMock(t)
+	mock.ExpectExec(`INSERT INTO audit_log`).WillReturnError(errors.New("boom"))
+
+	s := &dbSafetyAuditSink{db: db}
+	s.Emit(context.Background(), sampleRecord())
+
+	waitForExpectations(t, mock)
+	// Give the goroutine a beat to run its error-log branch after the failing
+	// exec is observed (the log call itself has no observable side effect).
+	require.NotNil(t, s.db)
+}

internal/models/dbsafety_audit_sink_test.go

@@ -0,0 +1,102 @@
+package models_test
+
+// dbsafety_audit_sink_test.go — covers the *sql.DB-backed dbsafety audit sink
+// (truehomie-db hardening). Integration test — needs TEST_DATABASE_URL; skips
+// cleanly otherwise.
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"instant.dev/internal/models"
+	"instant.dev/internal/providers/dbsafety"
+	"instant.dev/internal/testhelpers"
+)
+
+// TestWireDBSafetyAuditSink_NilIsNoop asserts a nil db leaves the default
+// (structured-slog) sink in place rather than installing a panicking nil-db
+// sink. Pure — no DB needed.
+func TestWireDBSafetyAuditSink_NilIsNoop(t *testing.T) {
+	dbsafety.SetAuditSink(nil)
+	t.Cleanup(func() { dbsafety.SetAuditSink(nil) })
+
+	models.WireDBSafetyAuditSink(nil) // must NOT install a *sql.DB sink over a nil db
+
+	// A guard against a dev host with valid names triggers exactly one emit;
+	// with the default slog sink this must not panic.
+	err := dbsafety.GuardDrop(context.Background(), dbsafety.DropParams{
+		Provider:     "db.local",
+		Env:          dbsafety.EnvDevelopment,
+		DSNHost:      "postgres://u:p@localhost:5432/d",
+		Token:        "tok",
+		DatabaseName: "db_tok",
+		UserName:     "usr_tok",
+	})
+	require.NoError(t, err)
+}
+
+// TestDBSafetyAuditSink_EmitWritesRow drives the production sink end-to-end: a
+// sanctioned (dev-host, valid-name) GuardDrop emits a customer_db.direct_drop
+// audit_log row carrying the destroyed identifiers + DSN host. The emit fires
+// from a goroutine, so the row is polled for.
+func TestDBSafetyAuditSink_EmitWritesRow(t *testing.T) {
+	db, clean := testhelpers.SetupTestDB(t)
+	defer clean()
+
+	models.WireDBSafetyAuditSink(db)
+	t.Cleanup(func() { dbsafety.SetAuditSink(nil) })
+
+	const token = "auditseam-tok"
+	err := dbsafety.GuardDrop(context.Background(), dbsafety.DropParams{
+		Provider:     "db.local",
+		Env:          dbsafety.EnvDevelopment,
+		DSNHost:      "postgres://u:p@postgres-customers:5432/d",
+		Token:        token,
+		DatabaseName: "db_" + token,
+		UserName:     "usr_" + token,
+	})
+	require.NoError(t, err)
+
+	// Poll for the audit row (team_id is NULL — admin-only rows — so query the
+	// kind directly rather than via ListAuditEventsByTeam, which filters team).
+	deadline := time.Now().Add(3 * time.Second)
+	var (
+		gotKind, gotActor, gotSummary, gotMeta string
+		found                                  bool
+	)
+	for {
+		row := db.QueryRowContext(context.Background(), `
+			SELECT kind, actor, summary, COALESCE(metadata::text, '')
+			  FROM audit_log
+			 WHERE kind = $1
+			   AND metadata->>'token' = $2
+			 ORDER BY created_at DESC
+			 LIMIT 1
+		`, dbsafety.AuditKindCustomerDBDirectDrop, token)
+		if err := row.Scan(&gotKind, &gotActor, &gotSummary, &gotMeta); err == nil {
+			found = true
+			break
+		}
+		if time.Now().After(deadline) {
+			break
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	require.True(t, found, "a customer_db.direct_drop audit row must land after a sanctioned drop")
+
+	assert.Equal(t, dbsafety.AuditKindCustomerDBDirectDrop, gotKind)
+	assert.Equal(t, "system", gotActor)
+	assert.Contains(t, gotSummary, "direct customer-DB drop")
+
+	var meta map[string]string
+	require.NoError(t, json.Unmarshal([]byte(gotMeta), &meta))
+	assert.Equal(t, "db.local", meta["provider"])
+	assert.Equal(t, "db_"+token, meta["database"])
+	assert.Equal(t, "usr_"+token, meta["user"])
+	assert.Equal(t, "postgres-customers", meta["dsn_host"], "DSN host (no credentials) must be recorded")
+}

internal/providers/db/local.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgconn"
+	"instant.dev/internal/providers/dbsafety"
 )
 
 const defaultCustomersURL = "postgres://instant_cust:instant_cust@postgres-customers:5432/instant_customers?sslmode=disable"
@@ -47,14 +48,18 @@ var pgxConnect = func(ctx context.Context, connString string) (pgConn, error) {
 // LocalBackend provisions databases on the shared postgres-customers instance.
 type LocalBackend struct {
 	customersURL string // admin connection URL
+	env          string // process ENVIRONMENT — feeds the dbsafety production refusal
 }
 
 // newLocalBackend creates a LocalBackend using the given admin connection URL.
-func newLocalBackend(customersURL string) *LocalBackend {
+// env is the process ENVIRONMENT (cfg.Environment); it feeds the dbsafety
+// production-refusal guard so this dev-only fallback fails closed when
+// PROVISIONER_ADDR is unset against a non-dev customer-DB host.
+func newLocalBackend(customersURL, env string) *LocalBackend {
 	if customersURL == "" {
 		customersURL = defaultCustomersURL
 	}
-	return &LocalBackend{customersURL: customersURL}
+	return &LocalBackend{customersURL: customersURL, env: env}
 }
 
 // generatePassword returns a cryptographically random alphanumeric string of length n.
@@ -206,6 +211,22 @@ func (b *LocalBackend) Deprovision(ctx context.Context, token, providerResourceI
 	dbName := "db_" + token
 	username := "usr_" + token
 
+	// dbsafety guard (truehomie-db incident): refuse the DROP entirely when
+	// this dev-only fallback is effectively in production (non-dev customer-DB
+	// host) or the target name doesn't match the per-tenant convention, and
+	// audit every sanctioned drop. Runs BEFORE we open the superuser
+	// connection so a refused op never even touches the customer cluster.
+	if err := dbsafety.GuardDrop(ctx, dbsafety.DropParams{
+		Provider:     "db.local",
+		Env:          b.env,
+		DSNHost:      b.customersURL,
+		Token:        token,
+		DatabaseName: dbName,
+		UserName:     username,
+	}); err != nil {
+		return fmt.Errorf("db.local.Deprovision: %w", err)
+	}
+
 	conn, err := pgxConnect(ctx, b.customersURL)
 	if err != nil {
 		return fmt.Errorf("db.local.Deprovision: connect: %w", err)