ADR-0009: Permission bitmap layout

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

Context

The 64-bit permission bitmap is stored on ibex_core.tokens.permissions and returned by ValidateToken. Multiple docs reference the layout, but no single Go package or ADR locked the bit assignments. Milestone 1.1.5 establishes the contract before token management (1.1.4) and proxy auth (1.2.1) enforce permission checks.

Decision

1) Canonical implementation

• Package: packages/permissions (github.com/Rick1330/ibex-harness/packages/permissions)
• Helpers: Has, HasAny, RequiresMFA, UsesReservedHighBits
• Predefined sets: AgentDefault, ProxyChatCompletion, ReadOnly, Admin

2) Bit layout (v1)

3) Phase 2 proxy minimum

For OpenAI-compatible chat completion through the proxy, a token must include:

MemoryRead | SessionCreate | SessionRead (permissions.ProxyChatCompletion).

4) Change policy

• Bit positions are stable for ibex.auth.v1 and stored token rows.
• New permissions consume reserved bits within a group or require ADR + migration if layout changes.
• Bits 56-63 are reserved for future expansion.

Consequences

Positive

• Single import path for all services checking permissions.
• Tests verify non-overlap and subset relationships.

Negative

• Renumbering bits requires data migration and a new ADR.

References

• ARCHITECTURE.md — auth permission table
• Milestone 1.1.5
• ADR-0006 — ValidateTokenResponse.permissions