Files
mtusi2026lab7/API-BOUNDARY.md

75 lines
9.5 KiB
Markdown

# Lab7 API / infrastructure boundary
Owner: lab7 infrastructure worker. Backend is owned by builtin `/root/vp`; this file is the integration contract, not a request to copy changing lab6 code.
## Reuse without weakening network security
Every API/worker process shares one network namespace with its dedicated HAProxy gateway (`network_mode: service:api1-gateway`, `api2-gateway`, or `worker-gateway`). All plaintext listeners bind **127.0.0.1 only**. HAProxy is the sole network-facing listener and checks TLS >=1.2, chain, server hostname, expiry and explicit client role. No app/backend port is published. This is the closed local proxy boundary expressly allowed by the original trust matrix.
API `APP_HOST=127.0.0.1`, `APP_PORT=8080`. HAProxy receives mandatory mTLS at api1-gateway:8443 and api2-gateway:8443, allows only certificate CN `lb` (CA-signed SAN `DNS:lb`), and forwards to 127.0.0.1:8080. LB verifies server identity `api1-gateway` / `api2-gateway`. No separate unprotected health port. Random `X-Instance-Id` aliases must not reveal hostname/IP.
All DB/cache/S3/OTLP clients may retain the current plaintext local transport implementation, because their endpoints are loopback in this namespace, behind a TLS-verifying outgoing proxy:
| Existing consumer | File / value | Network path behind local proxy |
|---|---|---|
| `DATABASE_URL_FILE` | `/run/app/database_url` containing postgresql://api or worker@127.0.0.1:15432/messenger?sslmode=disable | HAProxy TLS `postgres:5432`, verifyhost postgres, app/worker cert; separate DB roles |
| `CACHE_URL_FILE` | `/run/app/cache_url`, redis://api or worker@127.0.0.1:16379/0 | HAProxy mTLS broker-gateway:6379, verifyhost broker-gateway; Valkey ACL role |
| `BROKER_PUBLISH_URL_FILE` | `/run/app/publisher_url`, separate publisher ACL URL | worker composition uses an XADD-only publisher; CACHE_URL_FILE is the consumer, API is cache-only |
| `S3_CONFIG_FILE` | `/run/app/s3.json`: exact Go `storage.Config` keys `Endpoint`, `Access`, `Secret`, `Bucket`; Endpoint=127.0.0.1:19000 | HAProxy TLS s3-gateway:9000, verifyhost s3-gateway; scoped S3 principal |
| OTel HTTP/protobuf | `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:14318` | HAProxy mTLS collector-gateway:4318, verifyhost collector-gateway; API/worker roles |
No insecure flag crosses a container/host boundary. The *_FILE inputs are generated by native OpenBao Agent certificate auto-auth and KV-v2 templates, never baked into the image or included in process arguments. Each service agent has its own `api` or `worker` certificate, policy, short-lived renewable token and app-only secret volume. The app receives no root/unseal/bootstrap CA material. Startup waits for all rendered files. Agent keeps renewing/re-authenticating and rendering; connection pools reread credentials on **controlled process restart** after rotation. Revocation of a transport certificate requires fresh connections; gateways must be restarted when allowlists/trust/certs change.
The accepted native server is OpenBao2.7.2 with durable single-node PebbleDB, not the removed file backend. After unseal, Docker health and Agent retry backoff converge independently: recovery waits for the same owned Bao container to become healthy, deliberately restarts the three native Agents, then requires actual post-seal fresh renders for API1/API2/worker before application recovery. The measured sealed rejection retains the original baseline and cause/exit/public503 before recovery; no universal120-second or hung-filesystem bound is claimed. Exact native/CLI provenance and retained failed commands are linked by evidence/openbao/NATIVE-COMPOSITE.json.
## Backend expectations owned by `/root/vp`
- Keep asynchronous lab5 pipeline and full lab6 telemetry, build app/worker and migrations from this lab's backend.
- API host binding must honor APP_HOST=127.0.0.1. Worker has no inbound API.
- `DATABASE_URL_FILE`, `CACHE_URL_FILE`, `S3_CONFIG_FILE` paths above are existing integration points; report any changed spelling before merging.
- No automatic migrations as API's runtime DB identity. Explicit operator migration service uses an operator-only credential file and exits.
- API role creates application entities and outbox. Worker role has no SELECT on users/sessions/chats/messages; only pipeline tables needed by real queries. Any worker startup read of unrelated tables must be removed or split.
- Session/auth: Argon2id >=19456KiB,t=2,p=1; rehash on login; token hashes at rest; shared rate-limit across replicas, HTTP429 + Retry-After; bound KDF concurrency. These are backend changes, not satisfied by HAProxy alone.
- Secrets/files/errors/telemetry never emit password, Authorization, token, DSN, S3 secret, OpenBao token or private keys. SDK logs use safe codes.
- Exact OTel metrics/log schema and exporter defaults must be provided with stable backend so provisioning can be verified against real samples.
## Completion gates
Full public HTTPS smoke, persistence and both actual replica failures; wrong CA/hostname/expiry tests; missing/foreign/forbidden client identities on each gateway; DB/S3/Valkey/OpenBao ACLs; secret and certificate rotation/revocation, sealed behavior; scans and grade5 worker-compromise experiment. Infrastructure tests alone do not close backend acceptance.
## Confirmed freshness adapter API (new backend package owned by security worker)
`backend/internal/adapter/freshness` exports:
```go
watcher, err := freshness.New(freshness.Ports{
Read: freshness.FileReader(path),
Now: time.Now,
NewTicker: freshness.SystemTicker,
}, 120*time.Second, 5*time.Second)
// Check before opening business listeners or processing jobs.
err = watcher.Check(ctx)
// Run in composition-owned goroutine; on any error stop normal work and perform graceful shutdown.
err = watcher.Run(ctx)
```
No hidden production defaults in the constructor, no os.Exit/signals. Reader requests129bytes, accepts at most128bytes, regular non-symlink file only, no blocking FIFO open. Whitespace is trimmed; timestamp parses as RFC3339Nano. Empty/malformed/future/stale or unreadable is fail-closed. Age exactly120s remains valid;120s+1ns fails. Poll at most5s and at most maxAge. Error text is fixed and omits path/content. Cancellation returns context error and stops ticker.
Infrastructure emits `/run/app/freshness` via `{{ with secret "kv/data/api" }}{{ timestamp }}{{ end }}` (worker gets its own path) at native static-secret5s render intervals. `SECRET_FRESHNESS_FILE=/run/app/freshness`; `SECRET_MAX_AGE_SECONDS=120`. This temporary default yields detection <=125s plus composition shutdown grace; it is not a fixed instructor limit. When OpenBao is sealed the last timestamp ages, fresh startup is denied, and an existing process must stop on the adapter error. Recovery requires unseal, successful agent render and controlled process start.
## PostgreSQL auth correction from the real native client
The first actual libpq18 query proved that TLS terminates correctly but SCRAM-SHA-256-PLUS over the local non-TLS half is rejected as suspected TLS stripping. API/worker now use PostgreSQL18 native `cert` authentication, which checks CA and requires certificate CN equal to the requested database role; role impersonation is a separate negative test. Operator direct native TLS keeps SCRAM plus client certificate. No SCRAM/channel-binding downgrade flag is used to hide the rejection.
The API/worker DB URL has no password because its credential is the scoped gateway client certificate. OpenBao still delivers the actually consumed S3/Valkey secrets and DB endpoint. All cross-namespace DB traffic remains native TLS verified by HAProxy with `alpn postgresql`, CA, hostname and CRL.
Freshness timing is bounded by poll/max-age only under normal local filesystem I/O and scheduling. Context checks before/after regular-file syscalls cannot cancel a kernel-stalled filesystem operation, so125s is not a universal wall-clock deadline on a hung host/filesystem. No host-wide availability guarantee is claimed.
## Producer / consumer identity split
Original broker row requires different producer/consumer identities. The worker's outbox publisher and consumer use distinct native Valkey clients: `BROKER_PUBLISH_URL_FILE=/run/app/publisher_url` contains publisher-only principal (XADD on attachment-jobs); `CACHE_URL_FILE=/run/app/cache_url` contains consumer principal worker (XGROUP CREATE/XREADGROUP/XAUTOCLAIM/XACK/XDEL on attachment-jobs, no XADD). OpenBao worker KV includes publisher_url because the same legitimate worker composition owns both loops, while their broker permissions remain separate. API principal is cache-only GET/SET profile:*; login rate-limit lives in PostgreSQL login_limits, so no unused Lua/script/stream permission is granted to API.
## OpenObserve storage migration boundary
Backend112 keeps the same API/worker OTLP HTTP/protobuf endpoint and W3C propagation. No OpenObserve credential or new application environment contract is introduced. Collector-k8s0.163.2 exports all three signals through its dedicated mTLS identity to OpenObserve1.1.2; logs/traces use stream-name messenger, metrics have native normalized names without the old exporter namespace or automatic _total suffix. Included measured schema: docs/OPENOBSERVE-NATIVE-SCHEMA.json; native identity contract: docs/OPENOBSERVE-NATIVE-IDENTITIES.json. Canonical shared decision origin is vp/OPENOBSERVE-BOUNDARY.md; the standalone package includes its byte-identical snapshot docs/OPENOBSERVE-SHARED-BOUNDARY.md. Own actual112/OO acceptance is separately bound in evidence/openobserve; no Grafana/Bao acceptance follows from the schema handover.