ibexharness
DocsBlogReleasesRoadmap
GitHub
ibexharness

Documentation

Architecture Decision RecordsADR-0002: Repository foundation bootstrapADR-0003: Branch protection and merge policyADR-0004: Protobuf and code generation policyADR-0005: Postgres migration strategyADR-0006: Auth protobuf contract (`ibex.auth.v1`)ADR-0007: Auth token validation implementationADR-0008: Security scanning and CI quality gatesADR-0009: Permission bitmap layoutADR-0010: Cryptography policyADR-0011: Proxy auth gRPC client and middlewareADR-0012: Proxy request normalization (OpenAI chat)ADR-0013: Proxy input validation and stable error envelopeADR-0014: Core domain migration sequencingADR-0015: Proxy rate limit skeleton (Phase 1)ADR-0016: Proxy agent identity verification (Phase 1)ADR-0017: Request ID and trace context strategy (Phase 1)ADR-0018: Graceful shutdown contract (Phase 1)ADR-0019: OpenTelemetry provider configuration (Phase 1)ADR-0020: Shared package boundaries — `packages/config` and `packages/apierror`ADR-0021: Prometheus Metric Catalog (Phase 1)ADR-0022: Health check contract (Phase 1)ADR-0023: Docs site architecture (Phase 1.5)
ADRs›ADR-0006: Auth protobuf contract (`ibex.auth.v1`)
ADRs

ADR-0006: Auth protobuf contract (`ibex.auth.v1`)

Architecture decision record 0006.

ADR-0006: Auth protobuf contract (ibex.auth.v1)

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

Context

Milestone 1.1.1 established Postgres schema for ibex_core.tokens and RLS. Milestones 1.1.3 (auth service) and 1.2.1 (proxy auth client) need a stable internal gRPC contract for token validation before implementation.

ADR-0004 defines Buf lint/breaking and uncommitted gen/. ARCHITECTURE.md documents the auth validation pipeline: proxy calls auth on cache miss and expects org_id, optional agent_id, permission bitmap, and expiry.

Decision

1) Package and file layout

  • Protobuf package: ibex.auth.v1
  • Source file: packages/proto/proto/ibex/auth/v1/auth.proto
  • Layout: Same pattern as ibex.context.v1 under packages/proto/proto/ibex/<domain>/v1/ (FILE_STRUCTURE.md §4.1)

2) Service and RPCs (v1)

  • Service: AuthService
  • RPCs:
    • ValidateToken — proxy hot path; no caller bearer required
    • CreateToken — returns plaintext once; requires caller bearer with TokenCreate (ADR-0009)
    • RevokeToken — requires TokenRevoke or revoking caller's own token_id
    • ListTokens — metadata only (no hash/plaintext); requires TokenCreate for v1
  • Caller auth (management RPCs): gRPC metadata authorization: Bearer <pat> validated via the same path as ValidateToken
  • Deferred: JWT issuance, SSO exchange, Redis bloom invalidation RPCs

3) Messages

ValidateTokenRequest

  • access_token (string): full value from Authorization: Bearer ... (e.g. ibex_pat_...). The auth service hashes and looks up internally; callers must not log this field.

ValidateTokenResponse (success)

  • org_id (string): tenant UUID for SET LOCAL app.current_org_id in the auth service
  • permissions (int64): 64-bit permission bitmap per ARCHITECTURE.md
  • agent_id (optional string): when the token is agent-scoped
  • user_id (optional string): when the token is user-scoped
  • token_id (optional string): ibex_core.tokens.id for audit/revocation
  • expires_at (google.protobuf.Timestamp, optional): unset when the token is non-expiring

4) Error model

Use standard gRPC status codes only. Do not define REST-style error envelope messages in proto.

ConditiongRPC code
Missing, malformed, unknown, revoked, or expired tokenUnauthenticated
Valid token but insufficient permission for a later scoped operationPermissionDenied (enforced by callers using permissions; not returned by successful ValidateToken)
Invalid create/list request fieldsInvalidArgument
Token not found in org scope (revoke/list)NotFound
Caller bearer missing on management RPCUnauthenticated

ValidateToken returns OK with populated ValidateTokenResponse when the token is valid and not revoked.

5) go_package and codegen

  • go_package: github.com/Rick1330/ibex-harness/packages/proto/gen/go/ibex/auth/v1;authv1
  • Generated output: packages/proto/gen/ (gitignored per ADR-0004)
  • Plugins: protocolbuffers/go + grpc/go in buf.gen.yaml for local buf generate
  • Local command: make proto-gen (runs buf generate in packages/proto)
  • Contract tests: make proto-test (unit); make proto-test-integration (requires buf; generates stubs ephemerally)
  • CI: buf lint and buf breaking against main; proto-contract job runs ephemeral buf generate + contract tests — gen/ is never committed (ADR-0004)

6) Consumers

MilestoneRole
1.1.3Auth service: implement ValidateToken server
1.1.4Auth service: CreateToken, RevokeToken, ListTokens
1.2.1Proxy: gRPC client + middleware

Consequences

Positive

  • Proxy and auth share a versioned, linted contract before service code lands.
  • buf breaking protects downstream implementers from accidental breaks.

Negative

  • Developers must run buf generate locally before building auth/proxy against stubs.
  • Adding grpc plugin affects all RPC protos locally (including context); acceptable for 1.1.3.

Alternatives considered

OptionWhy not
REST-only auth validationProxy hot path uses gRPC per architecture
Embed errors in proto messagesDuplicates HTTP envelope; gRPC status is sufficient
Commit gen/ADR-0004 policy; noisy diffs

References

  • ADR-0004
  • ADR-0005
  • Milestone 1.1.2
  • packages/proto/README.md

Was this page helpful?

Edit on GitHub

Last updated on

PreviousADR-0005: Postgres migration strategyNextADR-0007: Auth token validation implementation

On this page

  • Context
  • Decision
  • 1) Package and file layout
  • 2) Service and RPCs (v1)
  • 3) Messages
  • 4) Error model
  • 5) go_package and codegen
  • 6) Consumers
  • Consequences
  • Positive
  • Negative
  • Alternatives considered
  • References
0%