Skip to content

ADR-0001: Project tenancy and provider-neutral authentication

  • Status: accepted
  • Date: 2026-09-16

Context

HeyAira must support multiple independent projects, multiple AI harnesses and different model providers without copying source code or binding the durable state model to one vendor. GitHub remains the source of truth for code and files, while HeyAira stores memory, tasks, work receipts and references to Git state.

The public MCP endpoint must be usable by ChatGPT, Codex and other compatible MCP clients. A custom authentication protocol or a GitHub access token used as an MCP credential would create unnecessary vendor coupling and excessive permissions.

Decisions

Project is the tenant and security boundary

Every durable HeyAira record is scoped to a project_id. A user may belong to multiple projects through explicit memberships. Project membership controls access to HeyAira memory, tasks and work receipts.

The initial role vocabulary is owner, admin, contributor and viewer. Access checks deny by default.

Repository bindings are separate from project membership

A project may reference multiple repositories, and a repository may be referenced by multiple projects. This is represented by a project_repositories binding rather than a single repository column on the project.

HeyAira stores repository identity and Git checkpoints only: GitHub owner and repository, URL, default branch, optional GitHub App installation reference, and branch/commit references used by work receipts. HeyAira does not store repository contents or act as a code mirror.

Authentication is provider-neutral

The public MCP authorization flow uses OAuth 2.1 Authorization Code with PKCE, protected-resource metadata, authorization-server metadata, resource indicators, exact redirect validation, scopes, short-lived access tokens and rotated refresh tokens where issued.

The OAuth token is issued for the HeyAira MCP resource and is never passed through to GitHub or another upstream service. Codex may retain the existing project-scoped static Bearer credential as an internal compatibility path, but it is not the public registration flow.

GitHub access uses a separate integration

GitHub access is not represented by the HeyAira MCP token. A future GitHub App will be installed with access to explicitly selected repositories and will provide the minimum repository permissions required by each operation.

Creating a repository is a separate, explicit operation requiring suitable GitHub organization or account permissions. It is not an implicit side effect of creating a HeyAira project.

Consequences

  • A user can access several projects without exposing unrelated project data.
  • A project can contain several repositories without changing the core state model.
  • GitHub permissions can be revoked independently of HeyAira membership.
  • OpenAI, Anthropic and other MCP clients can use the same standards-based authorization boundary.
  • Routing, queues and live thread wake-up remain separate future layers.

Non-goals

  • copying GitHub files into PostgreSQL;
  • using GitHub user tokens as HeyAira MCP tokens;
  • automatic repository creation during ordinary project creation;
  • provider-specific model routing in the storage and authorization layers.