poimen-memory/tasks/M3.5.10-auth-integration.md

M3.5.10 — Auth integration with Authentik/Vault

Field	Value
Phase	M3.5 — Distributed API Layer
Size	M — 1–3 days
Status	⬜ Not started
Flags	—
Spec	inlined below
Blocks	—
Depends	M3.5.1

Goal

Replace the placeholder apikey header check with proper authentication via the cluster's IAM stack: Authentik (OIDC provider) → HashiCorp Vault (token issuer) → memory service (token validator).

Facts (inlined — no spec read needed)

Current (wrong):

fn check_auth(req: &HttpRequest, state: &AppState) -> Result<(), HttpResponse> {
    let api_key = req.headers().get("apikey").and_then(|h| h.to_str().ok());
    if api_key != Some(&state.api_key) {
        return Err(HttpResponse::Unauthorized().json(...));
    }
    Ok(())
}

This is a raw string match against MEM_API_KEY env var. No JWT, no Vault, no user identity. It does not integrate with the cluster's IAM stack.

Cluster IAM stack:

• Authentik (iam namespace) — OIDC provider at https://authentik.riotpiao.com/application/o/vault/
• HashiCorp Vault (iam namespace) — OIDC auth method enabled, validates Authentik JWTs, issues Vault tokens based on role/policy.
• Vault OIDC role: auth/oidc/role/homelab-admin
  • bound_claims: { "permissions": "*" }
  • Policy: homelab-admin (path "*" full access)
• Vault unseal: Shamir 3/3, keys in vault-unseal-keys secret, S3 backend via MinIO.

Auth flow (production):

User/Agent authenticates with Authentik (OIDC)
  → Receives JWT with claims { sub, permissions, groups, ... }
  → Presents JWT to Vault OIDC auth method
  → Vault validates JWT against Authentik JWKS
  → Vault issues Vault token with matched policy
  → Client sends Vault token to memory service
  → Memory service validates token via Vault API

Three integration options (pick one):

Option A: Vault token validation (recommended)

Memory service receives X-Vault-Token header, calls Vault's POST /v1/auth/token/lookup-self to validate. Extracts policy and metadata.

• Pro: Vault is the single source of truth for authorization.
• Pro: Token revocation is immediate (Vault controls lifecycle).
• Con: Extra network call per request (cache with TTL to mitigate).

Option B: Direct JWKS validation

Memory service fetches Authentik's JWKS endpoint, validates JWT Authorization: Bearer <token> directly. No Vault in the request path.

• Pro: No Vault dependency at request time.
• Pro: Standard OAuth2/OIDC pattern.
• Con: Token revocation is delayed (until JWT expires).
• Con: Memory service must know about Authentik's OIDC config.

Option C: Trust gateway

Memory service trusts homelab-frontend gateway (cluster-internal traffic). Gateway validates auth, forwards X-User-Id and X-Capabilities headers. Memory service checks capabilities against ServiceAdapter CRD requirements.

• Pro: Auth logic centralized in gateway.
• Pro: Memory service stays simple.
• Con: Gateway auth is currently a stub (hasCapability() returns true for any Authorization header).
• Con: Requires gateway auth to be completed first (homelab-frontend task 8.3).

ServiceAdapter CRD for memory (memory-adapter):

auth:
  capability: memory:read    # default
  required: true
resources:
  - name: ingest
    methods:
      - verb: POST
        auth: { capability: memory:write, required: true }
  - name: query
    methods:
      - verb: POST
  - name: skills
    methods:
      - verb: GET

Capabilities needed:

• memory:read — query, skills, vault browse, projects, sources
• memory:write — ingest, source sync, skill draft

Steps

Option A (Vault token — recommended)

1. Add vault_addr to AppState (default: http://vault.iam.svc.cluster.local:8200).
2. Replace check_auth() with validate_vault_token():

   async fn validate_vault_token(req: &HttpRequest, state: &AppState) -> Result<VaultIdentity, HttpResponse> {
       let token = req.headers().get("X-Vault-Token")
           .or_else(|| req.headers().get("Authorization"))  // Bearer <token>
           .and_then(|h| h.to_str().ok());
       // POST vault_addr/v1/auth/token/lookup-self with X-Vault-Token header
       // Parse response: policies, metadata, ttl
       // Cache token -> identity for TTL duration
   }
   

3. Add token cache (HashMap<token_hash, (VaultIdentity, Instant)>) with configurable TTL.
4. Extract VaultIdentity (policies, metadata) from lookup response.
5. Map policies to capabilities: homelab-admin → memory:read + memory:write.
6. Update each handler to check required capability.
7. Keep apikey as fallback for dev/test (controlled by env var MEM_AUTH_MODE=vault|apikey).

For all options

8. Add env vars: VAULT_ADDR, MEM_AUTH_MODE (vault/jwks/gateway/apikey).
9. Update K8s deployment to inject VAULT_ADDR.
10. Update ServiceAdapter CRD if needed.
11. Document auth flow in README.

Acceptance

• Requests with valid Vault token are accepted.
• Requests with expired/revoked Vault token are rejected (401).
• Requests without any auth are rejected (401).
• memory:write capability required for ingest/sync endpoints.
• memory:read capability sufficient for query/skills/vault endpoints.
• Token cache reduces Vault API calls on repeated requests.
• Fallback to apikey mode for dev/test environments.

Verify

Integration test — tests/it_auth_integration.rs:

1. a1_vault_token_accepted — mock Vault lookup-self returning valid response; assert request proceeds.
2. a2_expired_token_rejected — mock Vault returning 403; assert 401 response.
3. a3_no_auth_rejected — request with no auth headers; assert 401.
4. a4_write_requires_capability — token with memory:read only; POST /ingest; assert 403.
5. a5_read_with_read_capability — token with memory:read; GET /query; assert proceeds.
6. a6_token_cache_hit — same token twice; assert Vault called once.
7. a7_apikey_fallback — MEM_AUTH_MODE=apikey; assert old behavior works.
8. a8_auth_mode_configurable — assert MEM_AUTH_MODE switches validation logic.

Command: cargo test --test it_auth_integration

False pass:

• Testing only with apikey fallback. The Vault integration is the whole point.
• Mocking Vault without testing cache expiry. A cache that never expires accepts revoked tokens forever.

Traps

• Calling Vault on every request without caching. Vault API calls add 5-10ms per request. Cache with TTL matching token TTL (or shorter).
• Not handling Vault being temporarily unreachable. Return 503 (not 401) if Vault is down — "cannot verify" is not "unauthorized".
• Hardcoding Vault addr. Use env var + service discovery.
• Not supporting Authorization: Bearer <token> format alongside X-Vault-Token. Different clients use different conventions.

---

Background: DESIGN.md — auth section, Authentik/Vault IAM stack