lawsynth/services/api/docs/security.md
caelum0x b011dce423 test+config: connector test suite + service config/docs (manifest files)
Connectors: 22 real pytest modules (186 pass / 7 optional-dep skips) exercising
every connector's dependency-free surface + missing-driver degradation; SSRF
guard verified; errors_connector.py as a thin re-export (no forked taxonomy).
Services: config/{dev,staging,prod,test,limits,logging}.yaml + docs/*.md for
api/gateway/scheduler/worker, mapped to the real config structs; gateway/scheduler
Dockerfiles + scheduler .env/README. All YAML validated.

Closes 66 manifest files (gap 175->109). No source behavior changed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-17 19:23:14 +03:00

2.4 KiB

Security boundary

lawsynth-api is the authenticated HTTP boundary in front of the local domain core. It authenticates callers, isolates tenants, bounds every request, and serializes responses defensively. It is not a multi-tenant identity provider.

What the process does

  • Bearer authentication. Tokens are compared in constant time (hmac.compare_digest) against the grant map in LAWSYNTH_API_TOKENS_JSON. Each token resolves to one organization_id and a scope set.
  • Tenant isolation. Every domain operation is scoped to the principal's organization_id; a caller for tenant A can never read or mutate tenant B's projects, runs, artifacts, or events. Event streams are partitioned by the same scope.
  • Scope enforcement. Reads require read, mutations require write, admin implies both. Writes additionally require an Idempotency-Key.
  • Admission limits. Method allowlist, absolute/normalized path checks (rejecting ./../NUL/backslash), header line-break rejection, a bounded query (max 32 params, no duplicates), application/json-only bodies, and a max_request_bytes ceiling.
  • Defensive responses. Fixed safe headers on every response (Cache-Control: no-store, X-Content-Type-Options: nosniff, X-Api-Version), a validated Content-Length, and JSON serialized with allow_nan=False. Error bodies never include stack traces or secrets.

What the process does not do

  • No transport encryption. The stdlib server is loopback-only; a deployment must terminate TLS at the gateway or reverse proxy. Do not expose the WSGI socket directly to the internet.
  • No external identity. OAuth/OIDC verification is deliberately out of scope (lawsynth_server/auth.py); it belongs to a deployment-specific identity adapter. This process only verifies pre-provisioned local bearer tokens.
  • No distributed guarantees. Repositories are process-local; the API does not claim distributed metadata, shared idempotency, or remote worker execution. /v1/worker/* is an honest 501, and a missing native runtime is an honest 503 native_unavailable.

Deployment guidance

Run as the dedicated non-root user that owns the database and object root, put the audited gateway (and TLS) in front, and keep LAWSYNTH_API_TOKENS_JSON in a secret manager — never in config/ or .env.example. Rotate any token that may have been exposed by replacing the grant map and restarting.