Janady13/missionmatch / docs/STACK_DECISIONS.md

1# STACK_DECISIONS.md — missionMATCH grounding doc (single source of truth) 2 3> This document is **the law** for version-sensitive Go/Postgres/cloud choices, per `CLAUDE.md` 4> ("Don't blindly build" rule). It is research-backed, source-cited, and every Go pattern below was 5> **compile-verified** under the locally-installed toolchain `go1.26.4 darwin/arm64` 6> (`/opt/homebrew/bin/go`). Where something could only be confirmed against a live Postgres 16 / AWS 7> GovCloud / Azure Government — and therefore could NOT be proven on a dev Mac — it is called out 8> explicitly in **OPEN QUESTIONS / verify during build**. Build the platform to these pins; do not 9> "upgrade to latest" without re-verifying against this doc. 10> 11> Last verified: 2026-06-23. Toolchain: Go 1.26.4. Target runtime: linux/amd64 + linux/arm64 containers. 12> 13> **LIVE VALIDATION (2026-06-23):** the data layer was proven against a real **PostgreSQL 16.14 + 14> pgvector 0.8.0** instance (M4, `/Volumes/MEGAMIND`). `goose up` applies all migrations cleanly; 15> the 7-test suite in `internal/integration` (run with `-tags=integration`) proves at runtime: 16> cross-tenant read isolation, clean default-deny on an unset GUC, the composite-FK cross-tenant 17> injection block (23503), the `numeric(7,4)` perfect-score round-trip via the full service, audit 18> append-only (app `42501` / owner-trigger `P0001`), the EEO privilege boundary, and the RLS-scoped 19> pgvector+HNSW+RRF hybrid search. The FIPS binary (`GOFIPS140=v1.0.0`) serves `/api/match` (100/green) 20> with scram-sha-256 auth fully inside the validated module. **One hardening landed from this run:** 21> RLS policies now use `NULLIF(current_setting('app.current_org_id', true), '')::uuid` so a reset GUC 22> (empty string `""` on a reused pooled connection) yields a clean 0-row default-deny instead of a 23> `22P02` cast error — see §2. 24 25--- 26 27## 0. Pinned dependencies (add these to `go.mod`) 28 29The repo already ships `go.mod` with `module github.com/missionworkforce/missionmatch`, `go 1.26`, and 30`github.com/shopspring/decimal v1.4.0`. Add the rest below. **Do not run an unpinned `go get @latest`** — 31use these exact versions, then `go mod tidy`. 32 33| Concern | Module path | Version | Notes | 34|---|---|---|---| 35| HTTP router | `github.com/go-chi/chi/v5` | `v5.3.0` | std-lib `net/http` compatible middleware | 36| Postgres driver/pool | `github.com/jackc/pgx/v5` | `v5.10.0` | `pgxpool` is `.../pgx/v5/pgxpool`; published 2026-06-03 | 37| pgxpool internal pool | `github.com/jackc/puddle/v2` | `v2.2.2` | transitive (pulled by pgxpool) | 38| pgvector types | `github.com/pgvector/pgvector-go` | `v0.4.0` | pgx codecs in subpkg `.../pgvector-go/pgx` | 39| Decimal (AEDT determinism) | `github.com/shopspring/decimal` | `v1.4.0` | already pinned; **all scoring math** | 40| UUID | `github.com/google/uuid` | `v1.6.0` | RLS `app.current_org_id` casts to `uuid` | 41| WebAuthn (FIDO2/passkey/PIV) | `github.com/go-webauthn/webauthn` | `v0.17.4` | phishing-resistant authenticator path (compile-verified `/tmp/gostack-auth`) | 42| OIDC (Login.gov / Entra Gov) | `github.com/coreos/go-oidc/v3` | `v3.18.0` | discovery + ID-token verify (compile-verified) | 43| OAuth2 | `golang.org/x/oauth2` | `v0.36.0` | token/code exchange; private_key_jwt assertions (compile-verified) | 44| JWT | `github.com/golang-jwt/jwt/v5` | `v5.3.1` | RS256 client_assertion (Login.gov private_key_jwt) (compile-verified) | 45| SAML SP (PIV-CAC IdPs) | `github.com/crewjam/saml` | `v0.5.1` | SP middleware for SAML-only federal IdPs | 46| AWS Bedrock runtime (GovCloud adapter) | `github.com/aws/aws-sdk-go-v2/service/bedrockruntime` | `v1.54.0` | embeddings + LLM, us-gov-west-1 | 47| AWS config loader | `github.com/aws/aws-sdk-go-v2/config` | `v1.32.25` | `WithUseFIPSEndpoint` | 48| AWS core | `github.com/aws/aws-sdk-go-v2` | (transitive, matched by config/bedrockruntime) | — | 49| Azure identity (Entra Gov) | `github.com/Azure/azure-sdk-for-go/sdk/azidentity` | `v1.14.0` | `cloud.AzureGovernment` | 50| Azure core | `github.com/Azure/azure-sdk-for-go/sdk/azcore` | `v1.22.0` | `azcore.ClientOptions{Cloud:...}` | 51| OpenAI SDK (Azure Gov adapter) | `github.com/openai/openai-go/v3` | `v3.41.0` | use subpkg `.../v3/azure`; supersedes `azopenai` | 52 53**Migration tool (CLI + embeddable library):** 54 55| Tool | Module / install | Version | 56|---|---|---| 57| **goose** (CHOSEN) | `github.com/pressly/goose/v3` | `v3.27.1` | 58 59**Code generators (developer tooling, not runtime imports — `go install`, do not `require`):** 60 61| Tool | Install | Version | 62|---|---|---| 63| sqlc | `go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.31.1` | `v1.31.1` | 64| goose CLI (optional; library is enough) | `go install github.com/pressly/goose/v3/cmd/goose@v3.27.1` | `v3.27.1` | 65 66> Honesty note on versions: public docs caches (pkg.go.dev search index) lagged behind for `pgx/v5` 67> (showed v5.8.0) and `openai-go` — the **live Go module proxy** returns the versions pinned above and 68> they compiled clean. Re-confirm against `https://proxy.golang.org/<module>/@latest` if a fresh 69> `go mod tidy` resolves something different, and keep this table as the gate. 70 71--- 72 73## 1. FIPS 140-3 — standardized build/run incantation 74 75### DECISION 76Use the **Go-native in-tree FIPS 140-3 module** (introduced in Go 1.24). **No cgo, no BoringCrypto, no 77openssl-fips.** Pin to the **CMVP-VALIDATED Go Cryptographic Module `v1.0.0` (CMVP Cert #5247, CAVP Cert 78A6650, validating vendor Geomys LLC)** — **NOT** the `v1.26.0` module bundled with the locally-installed 79Go 1.26.4, which is only **"Pending Review"** on the CMVP Modules-In-Process list (CAVP A8028) and is 80therefore **not a validated module** — it yields FIPS *mode* but cannot satisfy a control that requires a 81CMVP *certificate*. 82 83**Standard build incantation (this exact artifact runs on BOTH GovClouds — zero cloud-specific crypto code):** 84 85```bash 86CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GOFIPS140=v1.0.0 \ 87 go build -trimpath -o missionmatch ./cmd/api 88``` 89 90- `GOFIPS140=v1.0.0` selects **which** validated module is compiled in (works like `GOOS`/`GOARCH`) and 91 **auto-stamps `DefaultGODEBUG=fips140=on`** into the binary, so FIPS mode is the runtime default with no 92 env var required. 93- Alternative pin that always tracks the latest CMVP-**validated** snapshot: `GOFIPS140=certified` 94 (resolves to `v1.0.0-c2097c7c` on this toolchain). Acceptable, but `v1.0.0` is the explicit, audit-legible pin. 95- **Do NOT** use bare `GOFIPS140=latest` or `=inprocess` → those select **v1.26.0 (unvalidated)**. This is the #1 trap. 96- **Belt-and-suspenders runtime env** (set at deploy): `GODEBUG=fips140=on`. 97- **Do NOT** ship `GODEBUG=fips140=only` in production — Go docs state it is best-effort for 98 testing/assessment and "introduces crashes by design." Use `only` ONLY in a dedicated CI stage to surface 99 non-approved algorithm usage. 100 101**CI proof:** build-time `go version -m ./missionmatch | grep GOFIPS140` (expect substring `GOFIPS140=v1.0.0`); 102runtime `crypto/fips140.Enabled()` healthcheck. 103 104### Dockerfile crypto lines 105```dockerfile 106# --- build stage --- 107FROM golang:1.26.4 AS build 108ENV CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GOFIPS140=v1.0.0 109WORKDIR /src 110COPY . . 111RUN go build -trimpath -o /missionmatch ./cmd/api 112# verify the FIPS stamp is present in the artifact (fail the build otherwise) 113RUN go version -m /missionmatch | grep -q 'GOFIPS140=v1.0.0' 114 115# --- runtime stage (distroless/static; static binary, no host OpenSSL) --- 116FROM gcr.io/distroless/static-debian12:nonroot 117ENV GODEBUG=fips140=on 118COPY --from=build /missionmatch /missionmatch 119USER nonroot:nonroot 120ENTRYPOINT ["/missionmatch"] 121``` 122 123> Pin the toolchain (`go.mod` `toolchain go1.26.4` + a pinned builder image digest) so the `v1.0.0` 124> snapshot zip in `GOROOT/lib/fips140` and its checksum are bit-reproducible for SBOM/attestation. 125 126### VERIFIED PATTERN — fail-closed startup guard (`cmd/api`) 127```go 128package main 129 130import ( 131 "crypto/fips140" 132 "log" 133) 134 135// Call FIRST in main(). In a FIPS build this MUST be true; abort otherwise. 136func mustFIPS() { 137 if !fips140.Enabled() { 138 log.Fatalf("refusing to start: FIPS 140-3 mode is OFF (module=%q). "+ 139 "Build with GOFIPS140=v1.0.0 and run with GODEBUG=fips140=on", fips140.Version()) 140 } 141 log.Printf("FIPS 140-3 mode active; Go Cryptographic Module %s", fips140.Version()) 142} 143 144// Optional /healthz/fips for load balancers + compliance evidence. 145type fipsStatus struct { 146 Enabled bool `json:"enabled"` 147 Enforced bool `json:"enforced"` // true only under GODEBUG=fips140=only 148 Version string `json:"module_version"` 149} 150 151func fipsSnapshot() fipsStatus { 152 return fipsStatus{ 153 Enabled: fips140.Enabled(), // Go 1.24 154 Enforced: fips140.Enforced(), // Go 1.26 155 Version: fips140.Version(), // e.g. "v1.0.0" 156 } 157} 158``` 159**Compile status:** `go build ./...` + `go vet ./...` clean; `GOFIPS140=v1.0.0` static linux/amd64 160cross-build succeeds; `fips140.Enabled()` toggles true/false with the GODEBUG as expected. 161 162### SOURCES 163- https://go.dev/doc/security/fips140 (GOFIPS140 build var, GODEBUG fips140 runtime, supported platforms, algorithm scope) 164- https://go.dev/blog/fips140 ("no cgo … cross-compile like any other Go program"; Cert #5247; Geomys) 165- https://go.dev/doc/go1.24 (native module introduced) 166- https://go.dev/doc/go1.25 (FIPS signing ~4x faster) 167- https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/5247 (CMVP Cert #5247, Module v1.0.0) 168- https://pkg.go.dev/crypto/fips140 (`Enabled`, `Version`, `Enforced`, `WithoutEnforcement`) 169 170### GOTCHAS 171- Local Go 1.26.4 defaults `GOFIPS140=off`; its `latest`/`inprocess` module is the **unvalidated v1.26.0**. 172 You MUST pin `=v1.0.0` (or `=certified`) for Cert #5247. 173- FIPS mode alone ≠ compliant. Go docs disclaim that the validated module "may not on its own satisfy all 174 relevant regulatory requirements." Treat it as one control (SC-13/SC-8), not the whole SSP. 175- Under `fips140=on`, `crypto/tls` **silently drops** non-approved TLS versions/cipher suites/sigalgs/KEMs. 176 Re-verify every TLS path handshakes: pgx `sslmode=verify-full`, S3/Blob clients, OIDC/SAML/PIV-CAC IdPs. 177- `argon2`/`bcrypt`/`scrypt` (`golang.org/x/crypto`) are **NOT FIPS-approved KDFs** — password hashing sits 178 outside the validated boundary. Document it as a non-crypto-boundary storage function, or move to 179 PBKDF2 (SP 800-132, in-module) if an auditor objects. (See auth section.) 180- FIPS mode unsupported on OpenBSD / WebAssembly / AIX / 32-bit Windows — irrelevant for GovCloud Linux, 181 but a dev binary built on an unsupported target silently won't engage. 182- The snapshot resolves to `v1.0.0-c2097c7c` in `go version -m`; CI assertions should grep the substring 183 `GOFIPS140=v1.0.0`, not equality on the hash. 184- Pairwise consistency tests on generated keys can cost up to ~2x for some key types (matters for ephemeral keys). 185 186### OPEN QUESTIONS / verify during build 1871. **CMVP currency** — confirm at audit time that Cert #5247 (Module v1.0.0) has not moved to 188 historical/sunset; decide whether to migrate to a future validated v1.26.0 once it clears review. 1892. **3PAO acceptance** — confirm your auditor accepts the Go module's CMVP cert for SC-13/SC-8. Go gives no 190 regulatory guarantee. 1913. **Both-GovCloud TLS interop under `fips140=on`** — actually handshake the FIPS binary against AWS RDS 192 PostgreSQL and Azure DB for PostgreSQL Flexible Server (`sslmode=verify-full`), S3 GovCloud + Azure Blob, 193 and the OIDC/SAML/PIV-CAC IdP. Confirm none rely on a suite `fips140=on` drops. 1944. **Password-hash posture** — get auditor sign-off on bcrypt/argon2, or swap to in-module PBKDF2. 195 196--- 197 198## 2. pgx/v5 + pgxpool + Postgres 16 RLS multi-tenancy (the pool gotcha) 199 200### DECISION 201`github.com/jackc/pgx/v5 v5.10.0` + `pgxpool`. **Enforce tenant isolation in Postgres RLS, never in Go 202`WHERE` clauses.** The single correct pattern, per request: 203 2041. `tx, _ := pool.Begin(ctx)` — acquire ONE pooled connection in a transaction. 2052. On that same tx: `SELECT set_config('app.current_org_id', $1, true)` — **`is_local=true`** makes the GUC 206 **transaction-scoped**, discarded at COMMIT/ROLLBACK, so it **cannot leak** to the next request that 207 reuses the connection. 2083. Run all repo work against that tx. 2094. `Commit` (with `defer Rollback`). 210 211**Roles:** app connects as a non-owner **`NOBYPASSRLS`** role; a **separate `BYPASSRLS` migrator role** owns 212tables and runs DDL. **Every tenant table:** `ENABLE` **and** `FORCE ROW LEVEL SECURITY` (`FORCE` is 213mandatory — owners bypass RLS otherwise) and a `FOR ALL` policy with both `USING` and `WITH CHECK`. 214Unset GUC ⇒ `current_setting(...,true)` returns `NULL` ⇒ predicate `NULL` ⇒ **zero rows (default-deny)**. 215Go also fails closed: no validated org in context ⇒ refuse to open the tx. 216 217**Do NOT** use bare `SET app.current_org_id` (session-scoped → leaks across pooled requests). 218**Do NOT** use pgxpool `BeforeAcquire`/`AfterRelease` hooks to set/scrub tenant context (`BeforeAcquire` is 219deprecated in v5.10 — use `PrepareConn`; `AfterRelease` runs after `Release()` and can't run queries safely; 220a hook-based `RESET` is a race-prone substitute for what `is_local` gives for free). 221 222Cloud-portable: pure GUC + standard RLS works **identically** on AWS RDS for PostgreSQL 16 and Azure DB for 223PostgreSQL Flexible Server 16 — no vendor primitive. 224 225### VERIFIED PATTERN 226```go 227// internal/platform/tenant/rls.go — verified against pgx/v5 v5.10.0 (go build + go vet clean). 228type ctxKey struct{} 229var orgKey = ctxKey{} 230var ErrNoTenant = errors.New("tenant: no organization_id in context") 231 232func WithOrg(ctx context.Context, orgID string) context.Context { return context.WithValue(ctx, orgKey, orgID) } 233func OrgFromContext(ctx context.Context) (string, bool) { v, ok := ctx.Value(orgKey).(string); return v, ok && v != "" } 234 235type DB struct{ Pool *pgxpool.Pool } // Pool connects as the NOBYPASSRLS app role 236 237// RunInTenantTx is the correctness boundary: fail-closed, one conn, tx-local GUC. 238func (db *DB) RunInTenantTx(ctx context.Context, fn func(ctx context.Context, tx pgx.Tx) error) (err error) { 239 orgID, ok := OrgFromContext(ctx) 240 if !ok { return ErrNoTenant } // no org => no query (defense in depth atop RLS default-deny) 241 tx, err := db.Pool.Begin(ctx) 242 if err != nil { return fmt.Errorf("begin tenant tx: %w", err) } 243 defer func() { _ = tx.Rollback(ctx) }() // no-op after Commit; always releases conn 244 // is_local=true => GUC lives ONLY for this tx; auto-reset on COMMIT/ROLLBACK; cannot leak across pooled requests. 245 if _, err = tx.Exec(ctx, "SELECT set_config('app.current_org_id', $1, true)", orgID); err != nil { 246 return fmt.Errorf("set tenant guc: %w", err) 247 } 248 if err = fn(ctx, tx); err != nil { return err } 249 if err = tx.Commit(ctx); err != nil { return fmt.Errorf("commit tenant tx: %w", err) } 250 return nil 251} 252 253// chi middleware: org id comes from the validated session/JWT, NEVER a raw client value. 254func TenantMiddleware(resolveOrg func(*http.Request) (string, bool)) func(http.Handler) http.Handler { 255 return func(next http.Handler) http.Handler { 256 return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 257 orgID, ok := resolveOrg(r) 258 if !ok { http.Error(w, "forbidden", http.StatusForbidden); return } 259 next.ServeHTTP(w, r.WithContext(WithOrg(r.Context(), orgID))) 260 }) 261 } 262} 263``` 264 265```sql 266-- migrations (run as the BYPASSRLS migrator/owner role) 267CREATE ROLE missionmatch_app LOGIN NOBYPASSRLS; -- app connects as this 268CREATE ROLE missionmatch_migrator LOGIN BYPASSRLS; -- owns tables, runs DDL 269 270ALTER TABLE documents ENABLE ROW LEVEL SECURITY; 271ALTER TABLE documents FORCE ROW LEVEL SECURITY; -- MANDATORY: owners bypass RLS without it 272CREATE POLICY tenant_isolation ON documents 273 FOR ALL 274 -- NULLIF(...,'') is load-bearing: a reset GUC on a reused pooled connection is the empty string 275 -- "", and ""::uuid raises 22P02. NULLIF turns "" into NULL so the predicate is NULL => 0 rows 276 -- (clean default-deny) whether the GUC was never set OR was set-and-reset. Proven live 2026-06-23. 277 USING (organization_id = NULLIF(current_setting('app.current_org_id', true), '')::uuid) 278 WITH CHECK (organization_id = NULLIF(current_setting('app.current_org_id', true), '')::uuid); 279-- unset OR reset GUC => NULL => predicate NULL => 0 rows (fail-safe default-deny) 280GRANT SELECT, INSERT, UPDATE, DELETE ON documents TO missionmatch_app; 281``` 282**Compile status:** `/tmp/gostack-rls`: `go build ./...` OK, `go vet ./...` OK. Exercises real pgx types 283(`pgxpool.Pool`, `pgx.Tx`, `tx.Exec/Query`). Runtime tenant isolation must be proven against live Postgres 16. 284 285### SOURCES 286- https://proxy.golang.org/github.com/jackc/pgx/v5/@latest (v5.10.0, 2026-06-03) 287- https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool (pool API; `PrepareConn` vs deprecated `BeforeAcquire`; `AfterRelease` semantics) 288- https://www.postgresql.org/docs/16/functions-admin.html (`set_config(...,is_local)` "applies only during the current transaction"; `current_setting(name, missing_ok)` returns NULL) 289- https://www.postgresql.org/docs/16/ddl-rowsecurity.html (default-deny; FORCE RLS; `USING` vs `WITH CHECK`) 290- https://dev.to/__8fa66572/postgresql-rls-in-go-architecting-secure-multi-tenancy-4ifm (canonical tx-wrapper + fail-fast) 291 292### GOTCHAS 293- **NEVER** bare `SET app.current_org_id = ...` on a pooled conn — it persists to the next (possibly 294 different-tenant) request. Always `set_config(...,true)` / `SET LOCAL` inside a tx. 295- `SET LOCAL` / `set_config(is_local=true)` is a **no-op outside a transaction** (warns, does nothing). The 296 GUC must be set on the **same tx** the queries run on — not via `pool.Exec` (different/auto-released conn). 297- Forgetting **`FORCE ROW LEVEL SECURITY`** is the silent killer: `ENABLE` alone still lets the owner see all 298 rows. App role must be non-owner + `NOBYPASSRLS`. Verify with a cross-tenant integration test. 299- App DB role as superuser or `BYPASSRLS` ⇒ RLS entirely bypassed, isolation silently broken. 300- `is_local` GUC removes any need for `AfterRelease`/`RESET` scrubbing — don't add a redundant hook; 301 `AfterRelease` can't run queries safely anyway. 302- Cast the GUC explicitly to `uuid` in the policy. A malformed value (incl. **empty string**) errors at query 303 time; `NULL` does not. Standardize on writing a valid uuid string or never writing the GUC at all. 304- Server-side poolers (PgBouncer / RDS Proxy / Azure built-in pooling): the tx pattern holds in 305 **transaction** pooling mode (GUC is tx-local). **NEVER STATEMENT pooling** — splits the tx context and 306 breaks isolation. Pin transaction mode if a pooler sits in front of pgxpool. 307- Background jobs/migrations that legitimately span tenants must use the `BYPASSRLS` migrator role or set the 308 GUC per tenant — else they hit default-deny and see zero rows (looks like "data disappeared"). 309 310### OPEN QUESTIONS / verify during build 3111. ✅ **VERIFIED 2026-06-23** against live PostgreSQL 16.14: tenant A cannot read B; unset/reset GUC ⇒ 0 312 rows; the composite FK blocks writing a foreign-tenant child row (`internal/integration`). 3132. Audit `pg_class.relrowsecurity` **AND** `relforcerowsecurity` for every tenant table. 3143. Confirm AWS RDS Proxy / Azure built-in pooling is in **transaction** (not statement) mode if used in front of pgxpool. 3154. Confirm the app role is genuinely `NOBYPASSRLS` and owns nothing under managed-PG constraints. 316 317--- 318 319## 3. pgvector + pgvector-go + HNSW (vector type registration, cosine NN, RLS-scoped) 320 321### DECISION 322`github.com/pgvector/pgvector-go v0.4.0` (subpkg `.../pgvector-go/pgx v0.4.0`) on `pgx/v5 v5.10.0` + pgxpool. 323**Register vector codecs once per connection** via `pgxpool.Config.AfterConnect` calling 324`pgxvec.RegisterTypes(ctx, conn)` — mandatory so `pgvector.Vector` works as bind param and Scan target. 325 326- Columns declared `vector(384)` (the matching engine's skill embeddings). **Author the type UNQUALIFIED** 327 (`vector(384)`, not `public.vector`) so sqlc emits `pgvector.Vector` not `interface{}` (sqlc#3548). 328- **HNSW with `vector_cosine_ops`** — cosine is correct for normalized LLM embeddings (skill adjacency is 329 directional). `WITH (m = 16, ef_construction = 64)` baseline; raise `ef_construction` to 200 in production. 330- **The index op class MUST match the query operator** or Postgres silently seq-scans: 331 cosine `<=>` ↔ `vector_cosine_ops`; L2 `<->` ↔ `vector_l2_ops`; inner-product `<#>` ↔ `vector_ip_ops`; 332 L1 `<+>` ↔ `vector_l1_ops`. 333- RLS-scoped NN query: `set_config('app.current_org_id',$1,true)` (SET LOCAL) inside the **same tx**, add 334 `WHERE organization_id = current_setting('app.current_org_id')::uuid` (lets the composite btree pre-filter), 335 tune recall with `SET LOCAL hnsw.ef_search = 100`, then `ORDER BY embedding <=> $vec LIMIT k`. 336- Stay on plain `vector` at 384 dims; `halfvec` is a later storage-halving optimization, not needed now. 337 338> Dimension is **config, not code**: at 384 the column is `vector(384)`. If the embedding provider changes 339> per cloud (Titan v2 = 1024, OpenAI 3-large = 3072), the column width and HNSW index differ — see §6. 340> Pin embedding dimension per deployment. 341 342### VERIFIED PATTERN 343```go 344import ( 345 "github.com/jackc/pgx/v5" 346 "github.com/jackc/pgx/v5/pgxpool" 347 "github.com/pgvector/pgvector-go" 348 pgxvec "github.com/pgvector/pgvector-go/pgx" 349) 350// 1) Register codecs per-connection on the pool: 351cfg, _ := pgxpool.ParseConfig(dsn) 352cfg.AfterConnect = func(ctx context.Context, conn *pgx.Conn) error { 353 return pgxvec.RegisterTypes(ctx, conn) // sig: RegisterTypes(ctx context.Context, conn *pgx.Conn) error 354} 355pool, _ := pgxpool.NewWithConfig(ctx, cfg) 356// 2) RLS-scoped nearest-neighbor (cosine) in one tx: 357tx, _ := pool.Begin(ctx); defer tx.Rollback(ctx) 358tx.Exec(ctx, "SELECT set_config('app.current_org_id',$1,true)", orgID) // SET LOCAL 359tx.Exec(ctx, "SET LOCAL hnsw.ef_search = 100") 360rows, _ := tx.Query(ctx, ` 361 SELECT id FROM candidate_embeddings 362 WHERE organization_id = current_setting('app.current_org_id')::uuid 363 ORDER BY embedding <=> $1 LIMIT $2`, 364 pgvector.NewVector(query), k) // []float32 -> pgvector.Vector; Scan(&v); v.Slice() -> []float32 365tx.Commit(ctx) 366``` 367```sql 368CREATE EXTENSION IF NOT EXISTS vector; -- Azure: extension binary name is "vector", NOT "pgvector" 369CREATE TABLE candidate_embeddings ( 370 id bigserial PRIMARY KEY, 371 organization_id uuid NOT NULL, 372 embedding vector(384) NOT NULL -- UNQUALIFIED type for sqlc 373); 374ALTER TABLE candidate_embeddings ENABLE ROW LEVEL SECURITY; 375ALTER TABLE candidate_embeddings FORCE ROW LEVEL SECURITY; 376CREATE POLICY org_isolation ON candidate_embeddings 377 USING (organization_id = current_setting('app.current_org_id', true)::uuid) 378 WITH CHECK (organization_id = current_setting('app.current_org_id', true)::uuid); 379CREATE INDEX idx_ce_org ON candidate_embeddings (organization_id); -- composite leads with org (tenant rule) 380-- HNSW cosine index (op class MUST match the <=> query operator): 381SET maintenance_work_mem = '2GB'; 382SET max_parallel_maintenance_workers = 4; 383CREATE INDEX CONCURRENTLY idx_ce_embedding_hnsw 384 ON candidate_embeddings USING hnsw (embedding vector_cosine_ops) 385 WITH (m = 16, ef_construction = 200); 386``` 387**Compile status:** `/tmp/gostack-pgvector` (Go 1.26.4): `go mod tidy` resolved pgvector-go v0.4.0 + 388`.../pgx` v0.4.0 + pgx/v5 v5.10.0; `go build ./...` and `go vet ./...` rc=0. `go doc` confirms 389`func RegisterTypes(ctx context.Context, conn *pgx.Conn) error`. SQL/DDL not runnable here (needs live PG16 + pgvector). 390 391### SOURCES 392- https://pkg.go.dev/github.com/pgvector/pgvector-go (v0.4.0; `Vector`, `NewVector`, `.Slice()`, `HalfVector`, `SparseVector`) 393- https://github.com/pgvector/pgvector-go (`RegisterTypes` via `AfterConnect`) 394- https://github.com/pgvector/pgvector (operator/op-class table; HNSW DDL `m`/`ef_construction`; `hnsw.ef_search`; build tuning; `halfvec` sizing) 395- https://aws.amazon.com/blogs/database/optimize-generative-ai-applications-with-pgvector-indexing-a-deep-dive-into-ivfflat-and-hnsw-techniques/ (cosine for normalized embeddings) 396- https://dev.to/philip_mcclarence_2ef9475/pgvector-distance-functions-cosine-vs-l2-vs-inner-product-57pd (op class must match query operator) 397- https://docs.sqlc.dev/en/latest/howto/ddl.html (sqlc auto-emits pgvector types under pgx) 398- https://github.com/sqlc-dev/sqlc/issues/3548 (schema-qualified `public.vector` → `interface{}`) 399 400### GOTCHAS 401- `RegisterTypes` is **per-connection**: register via `AfterConnect`, not once on a single conn, or you get 402 intermittent codec errors under pool churn. 403- **Op class must match the query operator** — an HNSW index on `vector_l2_ops` will NOT accelerate a `<=>` 404 (cosine) query; Postgres silently seq-scans. Standardize on `vector_cosine_ops` + `<=>` everywhere. 405- sqlc#3548: never schema-qualify (`public.vector`) in the schema sqlc reads. If your pg_dump/migration tool 406 qualifies it, add the explicit override `db_type: "vector"` (see §4). 407- The `<=>` operator result type is inferred `interface{}` by sqlc — alias and cast in SQL 408 (`(embedding <=> $2)::float8 AS distance`) to get a Go `float64`. 409- `hnsw.ef_search` default 40 is low for high-recall slate generation; set it `LOCAL` per query (100–200). 410 Too high inflates latency. 411- HNSW has no incremental rebalance; heavy re-embedding churn bloats the graph → schedule 412 `REINDEX INDEX CONCURRENTLY` + `VACUUM`. 413- Builds are slow/RAM-hungry: set `maintenance_work_mem` + `max_parallel_maintenance_workers`; prefer 414 `CREATE INDEX CONCURRENTLY` in production. These GUCs are per-session on RDS/Flexible Server but capped by instance memory. 415- `<#>` returns the **negative** inner product (smaller = more similar). Sticking with cosine avoids this footgun. 416 417### OPEN QUESTIONS / verify during build 4181. Confirm the exact pgvector **extension version** on AWS GovCloud RDS PG16 **and** Azure Gov PG16 Flexible 419 Server (both should expose ≥ 0.8.x for current HNSW/halfvec). Pin identically in migrations; gate via 420 `CREATE EXTENSION ... ` — do not assume preinstalled. 4212. Confirm your embedding model actually outputs **L2-normalized** 384-dim vectors; if not, normalize at 422 write time or stay strictly on cosine. 4233. Prove end-to-end RLS NN behavior on a live PG16: unset GUC ⇒ 0 rows; tenants isolated under FORCE RLS + 424 `NOBYPASSRLS` app role. 425 426--- 427 428## 4. sqlc (typed SQL) + goose (migrations) — the type-override truth 429 430### DECISION 431**sqlc `v1.31.1`** (config `version: "2"`, `sql_package: "pgx/v5"`) + **goose `v3.27.1`** 432(`github.com/pressly/goose/v3`) as the single migration tool. Runtime deps as pinned in §0. 433 434**Type overrides (load-bearing for AEDT determinism):** `uuid`, `timestamptz`, and `vector` override cleanly 435by **bare** `db_type`. **NUMERIC does NOT** — sqlc silently ignores `db_type: pg_catalog.numeric` for plain 436table columns in pgx/v5 mode (issues #1067 / #1796 / #3460). You **MUST** add a **`column:`-scoped override** 437to force `shopspring/decimal.Decimal` on every numeric table column (this satisfies CLAUDE.md's "all scoring 438math uses `shopspring/decimal`, never `float64`" rule). Keep BOTH the `pg_catalog.numeric` db_type override 439(covers `AVG()`/expression results) AND a per-column override for each numeric table column. 440 441> Naming caveat verified locally: the bare `timestamptz` db_type matched in pgx/v5; the docs' example 442> `pg_catalog.timestamptz` did **not** match. Use bare `timestamptz`. 443 444**Why goose (not golang-migrate, not atlas):** 4451. Single static Go binary **and** an embeddable library (`embed.FS` + run programmatically against a 446 specific `*sql.DB` — exactly how you connect as the `BYPASSRLS` migrator role). Zero cloud lock-in; 447 identical on AWS GovCloud RDS and Azure Flexible Server. 4482. `-- +goose NO TRANSACTION` is required for `CREATE EXTENSION vector` / `CREATE INDEX CONCURRENTLY`; 449 `-- +goose StatementBegin/StatementEnd` handles internal semicolons in `CREATE POLICY` / PL/pgSQL. 4503. **Decisive:** sqlc natively parses goose-annotated `.sql` as its `schema:` input (ignores `-- +goose Down`), 451 so ONE set of migration files is both the migration source and sqlc's schema — no schema duplication. 4524. **Atlas rejected:** declarative RLS-policy support is **Pro/paid only** — unacceptable lock-in for an 453 RLS-centric federal product. golang-migrate works but lacks per-file no-transaction annotation and has 454 weaker library ergonomics for role-scoped programmatic runs. 455 456`goose` uses `database/sql` (`*sql.DB`) for migrations as the migrator role; the app uses `pgxpool` as the 457app role — distinct connection paths by design (migrations are infrequent). 458 459### VERIFIED PATTERN — `sqlc.yaml` 460```yaml 461version: "2" 462sql: 463 - engine: "postgresql" 464 schema: "db/migrations" # goose-annotated files; sqlc ignores -- +goose Down 465 queries: "db/queries" 466 gen: 467 go: 468 package: "dbgen" 469 out: "internal/gen" 470 sql_package: "pgx/v5" 471 emit_json_tags: true 472 emit_pointers_for_null_types: true 473 emit_interface: true 474 emit_empty_slices: true 475 overrides: 476 - db_type: "uuid" 477 go_type: { import: "github.com/google/uuid", type: "UUID" } 478 - db_type: "uuid" 479 nullable: true 480 go_type: { import: "github.com/google/uuid", type: "UUID", pointer: true } 481 - db_type: "timestamptz" # BARE name (pg_catalog.timestamptz did NOT match in pgx/v5) 482 go_type: "time.Time" 483 - db_type: "timestamptz" 484 nullable: true 485 go_type: { type: "time.Time", pointer: true } 486 - db_type: "pg_catalog.numeric" # covers AVG()/expression numeric results 487 go_type: { import: "github.com/shopspring/decimal", type: "Decimal" } 488 - column: "candidates.match_score" # REQUIRED: db_type override is IGNORED for plain columns 489 go_type: { import: "github.com/shopspring/decimal", type: "Decimal" } 490 - db_type: "vector" 491 go_type: { import: "github.com/pgvector/pgvector-go", package: "pgvector", type: "Vector" } 492 - db_type: "vector" 493 nullable: true 494 go_type: { import: "github.com/pgvector/pgvector-go", package: "pgvector", type: "Vector", pointer: true } 495``` 496### VERIFIED PATTERN — goose migration (also sqlc's schema) 497```sql 498-- +goose Up 499-- +goose NO TRANSACTION 500CREATE EXTENSION IF NOT EXISTS vector; 501-- +goose StatementBegin 502CREATE TABLE candidates ( 503 id uuid PRIMARY KEY DEFAULT gen_random_uuid(), 504 organization_id uuid NOT NULL, 505 full_name text NOT NULL, 506 match_score numeric(6,4), 507 skill_embedding vector(384), 508 created_at timestamptz NOT NULL DEFAULT now(), 509 deleted_at timestamptz 510); 511-- +goose StatementEnd 512CREATE INDEX idx_candidates_org ON candidates (organization_id, created_at DESC); 513ALTER TABLE candidates ENABLE ROW LEVEL SECURITY; 514ALTER TABLE candidates FORCE ROW LEVEL SECURITY; 515-- +goose StatementBegin 516CREATE POLICY candidates_tenant_isolation ON candidates 517 USING (organization_id = current_setting('app.current_org_id', true)::uuid) 518 WITH CHECK (organization_id = current_setting('app.current_org_id', true)::uuid); 519-- +goose StatementEnd 520-- +goose Down 521DROP TABLE IF EXISTS candidates; 522``` 523### VERIFIED PATTERN — pgx pool + pgvector registration + per-tx RLS 524```go 525cfg, _ := pgxpool.ParseConfig(dsn) 526cfg.AfterConnect = func(ctx context.Context, c *pgx.Conn) error { return pgxvec.RegisterTypes(ctx, c) } 527pool, _ := pgxpool.NewWithConfig(ctx, cfg) 528// per request: 529tx, _ := pool.Begin(ctx); defer tx.Rollback(ctx) 530tx.Exec(ctx, "SELECT set_config('app.current_org_id', $1, true)", orgID.String()) 531q := dbgen.New(tx); /* ...q.CreateCandidate(...)... */; tx.Commit(ctx) 532``` 533**Compile status:** Installed sqlc v1.31.1. In `/tmp/gostack-sqlc`: `sqlc generate` exit 0 — parsed the 534goose-annotated migration (incl. `CREATE EXTENSION`/RLS/`CREATE POLICY`) as schema; generated models had the 535**correct** types: `ID uuid.UUID`, `MatchScore decimal.Decimal`, `SkillEmbedding *pgvector.Vector`, 536`CreatedAt time.Time`, `DeletedAt *time.Time`. Then `go build ./...` and `go vet ./...` exit 0. Live DB 537execution (actual `goose Up` / RLS enforcement) NOT run — needs a running Postgres 16. 538 539### SOURCES 540- https://github.com/sqlc-dev/sqlc/releases + https://docs.sqlc.dev/en/stable/reference/config.html (v1.31.1; version "2"; pgx/v5) 541- https://docs.sqlc.dev/en/latest/howto/ddl.html (parses goose/atlas/dbmate/golang-migrate; ignores down) 542- https://docs.sqlc.dev/en/stable/howto/overrides.html (override semantics; one db_type per nullable-ness) 543- https://github.com/sqlc-dev/sqlc/issues/1067 , /1796 , /3460 (NUMERIC db_type override ignored for plain columns → column override) 544- https://github.com/pgvector/pgvector-go (`pgxvec.RegisterTypes`) 545- https://github.com/pressly/goose (v3.27.1; `NO TRANSACTION`; `StatementBegin/End`; `SetBaseFS`/embed.FS) 546- https://pressly.github.io/goose/blog/2024/goose-sqlc/ (official sqlc+goose workflow) 547- https://atlasgo.io/guides/orms/gorm + https://entgo.io/docs/migration/row-level-security/ (Atlas RLS is Pro-only) 548- https://github.com/golang-migrate/migrate/releases (v4.19.1; viable but weaker for this use) 549 550### GOTCHAS 551- **NUMERIC override silently dropped** for plain table columns in pgx/v5 mode — without a `column:` override 552 your `match_score` becomes `pgtype.Numeric`, breaking the AEDT decimal-determinism rule. Add a per-column 553 override for **every** numeric column. 554- Use **bare** `timestamptz` db_type (not `pg_catalog.timestamptz`) or columns stay `pgtype.Timestamptz`. 555- Non-null `vector` columns generate as `*pgvector.Vector` (sqlc treats vector as nullable); pass `&vec`. Add 556 the nullable override with `pointer: true` so both cases resolve to a pointer consistently. 557- The `<=>` distance result is inferred `interface{}`; alias + `::float8` in SQL to get `float64`. 558- Register the vector type on **every** pooled conn via `AfterConnect`, not once. 559- `SET LOCAL`/`set_config(...,true)` is tx-scoped — all tenant queries must run inside that same tx via 560 `dbgen.New(tx)`. A bare `pool.Query` after a `SET LOCAL` on a different checkout sees no org ⇒ zero rows. 561- `CREATE EXTENSION vector` needs `CREATE` on the DB for the migrator role and a `-- +goose NO TRANSACTION` migration. 562- Enforce migrator/app role separation at connect time: goose `*sql.DB` = `BYPASSRLS` migrator; app `pgxpool` 563 = `NOBYPASSRLS`. Do not reuse one DSN. 564 565### OPEN QUESTIONS / verify during build 5661. Confirm `goose Up` actually applies `CREATE EXTENSION vector` / `ENABLE`+`FORCE` RLS / `CREATE POLICY` and 567 that the policy enforces zero-rows-without-context against a live PG16. 5682. Confirm pgvector is in the **allowlist at the version you target** on AWS GovCloud RDS PG16 and Azure Gov 569 PG16 Flexible Server before pinning `vector(384)`/HNSW DDL. 5703. Confirm the `BYPASSRLS` migrator role is creatable under managed-PG constraints (providers restrict 571 superuser — verify `rolbypassrls` is grantable, or use `rds_superuser` / `azure_pg_admin`). 5724. Decide whether to register pgx's shopspring/decimal integration 573 (`github.com/jackc/pgx-shopspring-decimal`) so `decimal.Decimal` round-trips numeric without manual 574 conversion — recommended, not yet exercised. 575 576--- 577 578## 5. Phishing-resistant federal auth stack (OIDC / SAML / WebAuthn / PIV-CAC) 579 580### DECISION 581Pin (versions are the compile-verified resolutions from `/tmp/gostack-auth`, which `go mod tidy` 582selected — they supersede the older numbers an earlier draft of this doc carried): 583`github.com/go-webauthn/webauthn v0.17.4` (FIDO2/passkey + PIV authenticators), 584`github.com/coreos/go-oidc/v3 v3.18.0` (OIDC discovery + ID-token verify), 585`golang.org/x/oauth2 v0.36.0`, `github.com/golang-jwt/jwt/v5 v5.3.1` (RS256 `client_assertion`), 586`github.com/crewjam/saml v0.5.1` (SP for SAML-only federal IdPs; pinned at first use). 587 588- **Login.gov** = OIDC with **`private_key_jwt`** client authentication (RS256 client assertion signed with 589 golang-jwt v5; no client secret). Use go-oidc for discovery + ID-token verification. 590- **Microsoft Entra Government** = OIDC against the **`login.microsoftonline.us`** sovereign authority 591 (NOT `.com`). Pair with `cloud.AzureGovernment` for any Graph/Azure calls. 592- **PIV-CAC**: front via an IdP that does the cert-bound auth, or via WebAuthn authenticators; for SAML-only 593 federal IdPs use crewjam/saml SP middleware. 594- **Password hashing under FIPS**: bcrypt/argon2 are **not** FIPS-approved (see §1). Use **PBKDF2 (SP 800-132, 595 in-module)** if the auditor requires hashing inside the validated boundary; otherwise document password 596 storage as a non-crypto-boundary function. 597 598### VERIFIED PATTERN (shape) 599```go 600// OIDC: discovery + verify 601provider, _ := oidc.NewProvider(ctx, issuerURL) // go-oidc v3 602verifier := provider.Verifier(&oidc.Config{ClientID: clientID}) 603idToken, _ := verifier.Verify(ctx, rawIDToken) 604 605// Login.gov private_key_jwt: sign an RS256 client assertion (golang-jwt v5) 606tok := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{ 607 "iss": clientID, "sub": clientID, "aud": tokenEndpoint, 608 "jti": jti, "exp": exp.Unix(), 609}) 610assertion, _ := tok.SignedString(rsaPrivateKey) 611 612// WebAuthn: BeginRegistration/FinishRegistration (and Login) with a persisted SessionData 613w, _ := webauthn.New(&webauthn.Config{RPDisplayName: "missionMATCH", RPID: rpID, RPOrigins: origins}) 614options, session, _ := w.BeginRegistration(user) 615// ... persist `session`, return `options` to the browser, then on callback: 616cred, _ := w.FinishRegistration(user, session, httpRequest) 617``` 618**Compile status:** `go build` and `go vet` clean on Go 1.26. (The auth area was verified at the 619compile/wiring level; exact module-resolution and live IdP handshakes are build-time tasks.) 620 621### SOURCES 622- https://pkg.go.dev/github.com/go-webauthn/webauthn (WebAuthn RP API) 623- https://pkg.go.dev/github.com/coreos/go-oidc/v3/oidc (provider/verifier) 624- https://pkg.go.dev/golang.org/x/oauth2 (code/token exchange) 625- https://pkg.go.dev/github.com/golang-jwt/jwt/v5 (RS256 client assertion) 626- https://pkg.go.dev/github.com/crewjam/saml (SAML SP) 627- https://developers.login.gov/oidc/ (Login.gov OIDC + private_key_jwt) 628- https://learn.microsoft.com/en-us/entra/identity-platform/authentication-national-cloud (`login.microsoftonline.us` US Gov authority) 629 630### GOTCHAS 631- Entra **Gov** authority is `login.microsoftonline.us`, audience/endpoints differ from commercial — do not 632 reuse `.com` config. 633- Login.gov requires **`private_key_jwt`** (no client secret); the assertion `aud` must be the token endpoint 634 and `jti` must be unique/replay-guarded. 635- Under `fips140=on`, RS256/ES256 are fine but verify your IdP TLS suites aren't dropped (§1 gotcha). 636- bcrypt/argon2 outside FIPS boundary — pick PBKDF2 or document the carve-out before ATO. 637- crewjam/saml: pin metadata/clock-skew and validate signatures strictly; SAML is the fallback only for 638 IdPs without OIDC. 639 640### OPEN QUESTIONS / verify during build 6411. Re-resolve exact versions for go-webauthn / go-oidc / oauth2 / crewjam-saml / golang-jwt with `go mod tidy` 642 and re-run `go build`/`go vet`; this area's pins are the most likely to move. 6432. Live handshakes: Login.gov sandbox (`private_key_jwt`), Entra Gov (`login.microsoftonline.us`), and the 644 PIV-CAC IdP — confirm none rely on a TLS suite `fips140=on` drops. 6453. Auditor decision on password-hash KDF (PBKDF2 vs documented carve-out). 646 647--- 648 649## 6. Both-cloud support (Postgres+pgvector AND AI providers on AWS GovCloud + Azure Government) 650 651### DECISION — the "both clouds, no lock-in" claim **HOLDS for the core path** (one residual gap, below). 652**DB:** Postgres 16 + pgvector + HNSW is available on **AWS RDS for PostgreSQL in GovCloud** (pgvector 0.8.0 653on PG 16.5+/17.1+) **and** on **Azure Database for PostgreSQL Flexible Server in Azure Government** (extension 654allowlisted via `azure.extensions`, binary name **`vector`**). Same `pgx/v5` + sqlc + pgvector-go on both — 655**no vendor primitive**. 656 657**AI provider:** keep the `Embedder`/`LLM` behind a **port with TWO adapters**: 658- **AWS GovCloud** = `aws-sdk-go-v2/service/bedrockruntime v1.54.0` + `config v1.32.25`, region 659 `us-gov-west-1`, `WithUseFIPSEndpoint(aws.FIPSEndpointStateEnabled)` → resolves 660 `bedrock-runtime-fips.us-gov-west-1.amazonaws.com`. Embeddings: `amazon.titan-embed-text-v2:0` (**1024-dim**) 661 or Cohere Embed. LLM: Claude Sonnet 4.5 / 3.7 / 3.5 v1 / 3 Haiku, or Llama 3 (FedRAMP High + DoD IL4/5). 662- **Azure Government** = `openai/openai-go/v3 v3.41.0` + `.../v3/azure` 663 (`azure.WithEndpoint("https://<res>.openai.azure.us", apiVersion)` + `azure.WithTokenCredential`), 664 authenticated with `azidentity v1.14.0` using `azcore.ClientOptions{Cloud: cloud.AzureGovernment}`. 665 Embeddings: `text-embedding-3-large` (**3072-dim**) / `-3-small` (1536). LLM: gpt-4o / gpt-4.1 / gpt-5.1. 666 (`azopenai` is now a thin extensions module over `openai-go/v3` — target `openai-go/v3` directly.) 667 668**Pin embedding DIMENSION in config, not code.** Titan v2 = 1024 vs OpenAI 3-large = 3072 ⇒ the `vector(N)` 669column width and HNSW index differ per cloud. Abstract it; treat switching providers as a **data migration** 670(re-embed), not a config flip. (OpenAI 3-large's `dimensions` param can reduce to 1024 for cross-cloud parity 671at a quality cost — note for `slateMATCH`'s 384-dim skill space, both providers exceed 384, so you either use 672a 384-native model or reduce/pad deliberately.) 673 674**FIPS posture differs by cloud, by design:** AWS Bedrock has a dedicated FIPS endpoint hostname; **Azure Gov 675has NO separate FIPS hostname** — FIPS there comes from the Go FIPS 140-3 binary (§1) plus TLS to 676`*.openai.azure.us`. Don't expect a magic FIPS URL on Azure. 677 678### VERIFIED PATTERN 679```go 680// AWS GovCloud — Bedrock Runtime + FIPS + Titan Text Embeddings V2 (1024-dim): 681cfg, _ := awsconfig.LoadDefaultConfig(ctx, 682 awsconfig.WithRegion("us-gov-west-1"), 683 awsconfig.WithUseFIPSEndpoint(aws.FIPSEndpointStateEnabled), // -> bedrock-runtime-fips.us-gov-west-1.amazonaws.com 684) 685br := bedrockruntime.NewFromConfig(cfg) 686body, _ := json.Marshal(map[string]any{"inputText": text}) 687out, _ := br.InvokeModel(ctx, &bedrockruntime.InvokeModelInput{ 688 ModelId: aws.String("amazon.titan-embed-text-v2:0"), 689 ContentType: aws.String("application/json"), Accept: aws.String("application/json"), 690 Body: body, 691}) 692 693// Azure Government — Azure OpenAI via official openai-go/v3 + Entra ID (sovereign cloud): 694cred, _ := azidentity.NewDefaultAzureCredential(&azidentity.DefaultAzureCredentialOptions{ 695 ClientOptions: azcore.ClientOptions{Cloud: cloud.AzureGovernment}, // .us authority + audience 696}) 697client := openai.NewClient( 698 azure.WithEndpoint("https://my-res.openai.azure.us", "2024-10-21"), 699 azure.WithTokenCredential(cred), 700) 701resp, _ := client.Embeddings.New(ctx, openai.EmbeddingNewParams{ 702 Model: openai.EmbeddingModel("text-embedding-3-large"), // 3072-dim 703 Input: openai.EmbeddingNewParamsInputUnion{OfString: openai.String(text)}, 704}) 705``` 706 707### Support matrix (feature × AWS-GovCloud × Azure-Gov) 708| Feature | AWS GovCloud | Azure Government | 709|---|---|---| 710| pgvector extension | YES, PG 15.2+ all RDS incl GovCloud; 0.8.0 on PG 16.5+/17.1+ | YES, `vector` via `azure.extensions` allowlist + `CREATE EXTENSION vector` | 711| HNSW index | YES (pgvector ≥ 0.5.0; 0.8.0 build/search perf) | YES (pgvector on Flexible Server supports `hnsw`) | 712| Managed Postgres | AWS RDS for PostgreSQL (Aurora PG also) | Azure DB for PostgreSQL Flexible Server (GA in USGov regions) | 713| AI embeddings | Titan Text Embeddings V2 (1024) / Cohere Embed | text-embedding-3-large (3072) / -small (1536); ada-002 limited | 714| AI LLM | Claude Sonnet 4.5/3.7/3.5v1/3 Haiku, Llama 3 8B/70B | gpt-4o, gpt-4.1(+mini), gpt-5.1, o3-mini | 715| Compliance | FedRAMP High + DoD IL4/5 (us-gov-west-1 / us-gov-east-1) | FedRAMP High (usgovarizona / usgovvirginia) | 716| Go SDK | `aws-sdk-go-v2/service/bedrockruntime v1.54.0` | `openai-go/v3 v3.41.0` + `.../azure` + `azidentity v1.14.0` | 717| FIPS crypto path | `bedrock-runtime-fips.us-gov-{west,east}-1.amazonaws.com` | TLS to `*.openai.azure.us` (FIPS = app-side Go module, no FIPS hostname) | 718 719**Compile status:** `/tmp/gostack-portability` (Go 1.26.4): `go build ./...` BUILD OK, `go vet ./...` VET OK. 720Resolved bedrockruntime v1.54.0, aws config v1.32.25, azidentity v1.14.0, azcore v1.22.0, openai-go/v3 721v3.41.0, pgvector-go v0.4.0. Network calls NOT executed (need real GovCloud/Azure-Gov accounts) — wiring is 722compile-verified; runtime correctness cited below. 723 724### SOURCES 725- https://aws.amazon.com/about-aws/whats-new/2023/05/amazon-rds-postgresql-pgvector-ml-model-integration/ (pgvector on RDS PG 15.2+, **all regions incl GovCloud**) 726- https://aws.amazon.com/about-aws/whats-new/2023/10/amazon-rds-postgresql-pgvector-hnsw-indexing/ + https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-rds-for-postgresql-pgvector-080/ (HNSW; pgvector 0.8.0) 727- https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-bedrock.html (Bedrock in GovCloud; FedRAMP High + IL4/5 model list) 728- https://aws.amazon.com/blogs/publicsector/accelerating-government-innovation-amazon-bedrock-models-get-fedramp-high-and-dod-il-4-5-approval-in-aws-govcloud-us/ (Titan V2 embeddings live in GovCloud) 729- https://docs.aws.amazon.com/general/latest/gr/bedrock.html (`bedrock-runtime-fips.us-gov-{west,east}-1` endpoints) 730- https://learn.microsoft.com/en-us/azure/postgresql/extensions/how-to-use-pgvector + https://learn.microsoft.com/en-us/azure/postgresql/extensions/how-to-allow-extensions (`azure.extensions`=`vector`, `CREATE EXTENSION vector`, hnsw) 731- https://azure.microsoft.com/en-us/updates?id=general-availability-azure-database-for-postgresql-flexible-server-new-us-government-regions (Flexible Server GA in USGov) 732- https://devblogs.microsoft.com/azuregov/azure-openai-fedramp-high-for-government/ + https://devblogs.microsoft.com/azuregov/azure-openai-authorization/ (Azure OpenAI FedRAMP High in Gov) 733- https://learn.microsoft.com/en-us/azure/ai-foundry/openai/azure-government?view=foundry-classic (Gov model/region matrix; `*.openai.azure.us`) 734- https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai + https://pkg.go.dev/github.com/openai/openai-go/v3/azure (`azopenai` is an extensions module; target openai-go/v3) 735 736### GOTCHAS 737- **EMBEDDING DIMENSION MISMATCH ACROSS CLOUDS** (the real lock-in trap): Titan V2 = 1024, OpenAI 3-large = 738 3072, 3-small/ada-002 = 1536. The `vector(N)` column and HNSW index are dimension-specific — you **cannot 739 share one embeddings table across both clouds** without re-embedding. Pin dimension per deployment; treat a 740 provider switch as a data migration. 741- Azure Gov region pinning: under Standard deployment, `text-embedding-3-large/-small` show available in 742 **usgovarizona** but **not usgovvirginia** per the model matrix; ada-002 is narrower. Verify your 743 subscription/region before committing. 744- AWS **FIPS + custom endpoint are mutually exclusive** in the SDK: with `WithUseFIPSEndpoint(Enabled)` let 745 the SDK resolve the FIPS hostname; do NOT also pass a custom `BaseEndpoint` ("FIPS and custom endpoint are 746 not supported"). Rely on region+FIPS resolution for GovCloud. 747- Azure Gov has **no separate FIPS endpoint hostname** — FIPS comes from the Go FIPS binary (§1) + TLS to 748 `*.openai.azure.us`. Don't assume a magic FIPS URL. 749- The pgvector **0.8.0** GovCloud guarantee is implied by "all applicable regions"; the firm guarantee is the 750 original 15.2+ all-regions-incl-GovCloud statement. Confirm the exact point-version on your launched RDS 751 engine before relying on 0.8.0-specific perf. 752- Azure extension name is **`vector`** (binary) — NOT `pgvector` — in `CREATE EXTENSION` and the allowlist. 753 Easy to get wrong in migrations/Terraform. 754- **pgvector 0.8.0 + HNSW illegal-instruction crash on some Azure Flexible Server SKUs** (open: 755 pgvector/pgvector#889) — certain Gov hardware hits a CPU-instruction incompatibility when building an 756 HNSW index on pgvector 0.8.0. Field mitigation is to **pin pgvector 0.7.0 for HNSW** until resolved. 757 **Build-time gate:** actually build an HNSW index on your real US-Gov Flexible Server SKU before 758 committing to 0.8.x; fall back to 0.7.0 if hit. (AWS GovCloud RDS is unaffected.) 759- **Avoid Azure `pg_diskann`** (Microsoft-specific ANN index) in portable code — it does not exist on 760 AWS. Standardize on the open `vector` + HNSW path, which is identical on both clouds. Using DiskANN 761 would silently re-introduce the lock-in this architecture exists to prevent. 762- Don't pull the old standalone `azopenai` client as the primary path — build on `openai-go/v3` + `/azure`. 763- Aurora PG pgvector in GovCloud trails RDS historically; re-verify the point-version if you choose Aurora. 764 765### Both-cloud verdict & residual gap 766**Verdict: the no-lock-in claim HOLDS for the core path.** DB (Postgres+pgvector+HNSW), tenancy (RLS), and 767crypto (Go FIPS module) are cloud-agnostic and identical on both clouds. The AI provider is cleanly 768port/adapter-isolated with a working adapter for each cloud. 769**Residual gap (the only one):** the embedding **dimension differs by provider** (1024 vs 3072), so the 770**embeddings table + HNSW index are NOT portable as data** — switching clouds/providers is a re-embed 771migration, not a config flip. This is a data-layer consequence, not a code-portability failure, and it is 772mitigated by: (a) pinning dimension in config, (b) optionally using OpenAI's `dimensions` param for parity, 773or (c) self-hosting one embedding model (vLLM, per CLAUDE.md's CUI/production posture) so a single dimension 774serves both clouds — **the recommended path for production CUI**, which also sidesteps both managed AI 775providers entirely. 776 777### OPEN QUESTIONS / verify during build (cannot verify without GovCloud/Azure-Gov accounts) 7781. Exact pgvector point-version on the specific RDS PG16 engine launched in `us-gov-west-1` 779 (`aws rds describe-db-engine-versions --engine postgres` / `SHOW rds.allowed_extensions`) — needed to 780 guarantee 0.8.0 HNSW perf vs older 0.5.x. 7812. Whether your Azure Gov subscription can actually **deploy** `text-embedding-3-large` in your chosen region 782 (usgovarizona vs usgovvirginia differ; gated by quota). 7833. End-to-end FIPS posture across the ATO boundary (Bedrock FIPS endpoint + Azure Gov TLS + Go FIPS binary). 7844. Cohere Embed availability in GovCloud if you want a non-Titan fallback (only Titan was explicitly named). 7855. Decide production embedding strategy: self-hosted vLLM (single dimension, CUI-safe, both clouds) vs managed 786 per-cloud (dimension split). CLAUDE.md leans self-hosted for production CUI. 787 788--- 789 790## 7. Phase 2 Authentication and Accounts (build decisions, locked) 791 792### DECISION 793- **Password and recovery code KDF: PBKDF2 with HMAC SHA 256 (SP 800-132), `crypto/pbkdf2.Key`** (Go 794 1.26 stdlib, confirmed `func Key[Hash hash.Hash](h func() Hash, password string, salt []byte, iter, 795 keyLength int) ([]byte, error)` — it RETURNS an error, handle it). 600000 iterations, 16 byte salt, 796 32 byte derived key, self describing encoding `pbkdf2-sha256$<iters>$<b64salt>$<b64dk>`. argon2, 797 bcrypt, scrypt are NOT used: outside the FIPS boundary. The high iteration count is a deliberate SP 798 800-132 maximize choice above the CAVP tested ceiling of 10000, documented as a strength not a 799 deviation. Password input capped at 64 chars (the tested length envelope upper bound). 800- **Versioned credential pepper**: HMAC SHA 256 of the password under a server held key from the 801 secrets file, applied before PBKDF2 (in boundary), stored as a per credential `pepper_version`. 802- **MFA: mandatory TOTP, rolled in house on `crypto/hmac` + `crypto/sha256`**, NOT a third party 803 library. RFC 6238, pinned to HMAC SHA 256 end to end, 32 byte secret, `algorithm=SHA256` in the 804 otpauth URI, strictly monotonic replay guard (a step is accepted only if greater than the stored 805 last used step). This is a deliberate deviation from the design doc's `github.com/pquerna/otp` pin: 806 rolling it in house keeps every primitive inside the validated module (no external crypto to re 807 verify under fips140=on) and matches the design's own in house session and CSRF choice. TOTP secrets 808 are AES 256 GCM encrypted at rest (`crypto/aes` + `crypto/cipher`) with a `key_version`. 809- **Sessions: opaque, server side**, 32 bytes `crypto/rand` base64url, stored only as SHA 256 hash, in 810 a `__Host-` cookie (HttpOnly, Secure, SameSite Strict). Two stage (auth_pending then active), 15 min 811 idle and 12 h absolute, all expiry math on the database clock. NOT JWT (instant revocation, no 812 signing key rotation under FIPS). 813- **No new go.mod dependencies in Phase 2 core.** Everything is stdlib (`crypto/pbkdf2`, `crypto/hmac`, 814 `crypto/sha256`, `crypto/rand`, `crypto/subtle`, `crypto/aes`, `crypto/cipher`, `crypto/fips140`) 815 plus the already pinned chi, pgx, and uuid. The five federal auth libraries in section 0 (webauthn, 816 go-oidc, oauth2, jwt, saml) are deferred to sub phase 2.9. 817 818### GRANT MODEL (the hardened, post red team posture) 819- The secret bearing tables `auth_credentials`, `auth_sessions`, `mfa_totp`, `mfa_recovery_codes`, 820 `user_invites` are OUTSIDE RLS and the `missionmatch_app` role gets NO direct table grants on them. 821 All access is through a tight set of `SECURITY DEFINER` functions owned by `missionmatch_migrator`, 822 `search_path` locked, EXECUTE granted narrowly to `missionmatch_app` (and `provision_org` granted 823 migrator only, with a `pg_proc`/`aclexplode` CI assertion). This restores DB side default deny for 824 the most sensitive data: the app role literally cannot SELECT a credential or session row directly, 825 so a forgotten predicate cannot leak another org's secrets. This consolidates the design's mixed 826 "mfa under RLS, sessions behind definers" into one uniform definer guarded model because MFA enroll 827 and verify run on a pre org auth_pending session where no org GUC exists. 828- `login_attempts` is OUTSIDE RLS with a narrow app SELECT/INSERT grant (a counter, no secrets), so the 829 brute force throttle reads it through a scoped query. `users`, `organizations`, `audit_logs` are 830 unchanged (users under RLS; audit_logs append only, app INSERT/SELECT, read bound to the GUC). 831 832### OPEN QUESTIONS / verify during build 8331. The live M4 dev Postgres is NOT reboot durable (PGDATA on an external volume macOS launchd cannot 834 own). It is a RELEASE BLOCKER for any pilot: credentials, MFA enrollments, and session state now 835 live there, so a reboot would lock every user out with no recovery. Make it durable with scheduled 836 backups and one tested restore before this auth ships. 8372. Confirm pgx TLS to Postgres still negotiates under the FIPS build (fips140=on drops non approved 838 suites); exercise password hashing and the DB handshake under GOFIPS140=v1.0.0, not a dev build. 8393. The global unique email ALTER can fail if seed data holds cross org duplicate emails; pre flight a 840 duplicate check on the live users table before applying 0009. 841 842--- 843 844## Appendix — quick command reference 845```bash 846# FIPS-validated production build (linux/amd64) 847CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GOFIPS140=v1.0.0 go build -trimpath -o missionmatch ./cmd/api 848go version -m ./missionmatch | grep GOFIPS140 # expect: GOFIPS140=v1.0.0 849 850# dev codegen (developer tooling, not a runtime require) 851go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.31.1 852sqlc generate 853 854# CI-only: surface non-FIPS algorithm usage (NEVER ship this) 855GODEBUG=fips140=only go test ./... 856``` 857