ADR-0007: Auth token validation implementation

• Status: Accepted
• Date: 2026-06-03
• Authors: IBEX Harness team

Context

Milestones 1.1.1 and 1.1.2 delivered Postgres ibex_core.tokens with RLS and the ibex.auth.v1 ValidateToken gRPC contract (ADR-0006). Milestone 1.1.3 implements the auth service server consumed by the proxy (1.2.1).

SECURITY.md requires Argon2id for stored tokens, fail-closed behavior, and no raw tokens in logs. TESTING_STRATEGY.md §6.2 defines auth unit and integration expectations.

Decision

1) Token wire format (v1: PAT only)

ibex_pat_<token_uuid>_<secret>

• token_uuid: standard UUID string (36 characters)
• secret: opaque suffix (non-empty)
• DB prefix: ibex_pat_<token_uuid> (lookup key; safe to store and log after parse)
• DB hash: PHC-encoded Argon2id of the full bearer string (same value sent in access_token)
• JWT, org_token, service_token, and marketplace types are not validated in v1; malformed or unsupported shapes return Unauthenticated

2) ValidateToken flow (fail closed)

1. Reject empty access_token → Unauthenticated
2. Parse PAT wire format → on failure Unauthenticated
3. Open DB transaction with SET LOCAL app.is_service_account = 'true' (ADR-0005)
4. SELECT token row by prefix where is_revoked = false and (expires_at IS NULL OR expires_at > now())
5. Argon2id verify presented bearer against stored hash → on failure Unauthenticated (same message as not found)
6. Map row to ValidateTokenResponse (org_id, permissions, optional agent_id, user_id, token_id, expires_at)
7. Do not update last_used_at in v1 (deferred)

All failure paths use gRPC codes.Unauthenticated with a generic message (no existence oracle), per ADR-0006.

3) Database access

• Driver: database/sql + github.com/lib/pq (root module; no new pgx dependency)
• Connection pool configured via POSTGRES_DSN
• Lookup uses service-account RLS bypass only for the validation query; no app.current_org_id until a future org-scoped write path

4) Service layout

services/auth/
  internal/
    config/       # HTTP + gRPC ports, Argon2 params
    repository/   # SQL
    token/        # parse, hash verify, validator
    grpc/         # AuthService server
    metrics/      # validate_token_* metrics (no org_id labels)
  cmd/auth/main.go  # HTTP + gRPC listeners, graceful shutdown

Generated stubs: make proto-gen → packages/proto/gen/go/ibex/auth/v1 (gitignored per ADR-0004).

5) Configuration

Argon2id parameters are defined in ADR-0010. Implementation: packages/crypto. Env vars override production defaults at process start; stored PHC strings embed the parameters used at hash time.

6) Observability

• Structured logs: never log access_token; after successful parse may log token_id / prefix
• Metrics: ibex_auth_validate_token_total, ibex_auth_validate_token_errors_total, ibex_auth_validate_token_duration_seconds (no org_id label)

Consequences

Positive

• Proxy can call a real validation server on cache miss
• RLS-safe lookup pattern documented and tested
• Minimal dependency surface (stdlib + pq + x/crypto)

Negative

• v1 PAT-only; other token types need follow-up ADR or version bump
• last_used_at not updated until a later milestone

References

• ADR-0006
• ADR-0005
• Milestone 1.1.3
• ARCHITECTURE.md — auth validation pipeline