storage/docs/architecture/acl.md

---
status: draft
last_updated: 2026-05-30
---

# Access Control Graph

How access control is modeled as a metagraph, how it integrates with
`@alkdev/operations`' `Identity` and `AccessControl`, and how the
principal-agent framework maps to graph relationships.

## Purpose

Access control in the alk.dev platform needs to serve two distinct but
overlapping audiences:

1. **Setup-time** — A hub/spoke administrator defines which operations exist,
   what their access requirements are, and which principal-agent relationships
   are valid. This is the *schema* of authorization.

2. **Runtime** — When a session calls an operation, the system resolves whether
   that specific call is permitted given the caller's identity, their scope
   within the org, and any delegation chain involved. This is the *evaluation*
   of authorization.

Both can be expressed as graphs. The setup-time definitions (operations, org
structures, trust relationships) become graph types — schema-level declarations
of what kinds of nodes and edges are valid. The runtime instances (who has
delegated to whom, which org has which scope over which resource) become graph
instances — concrete data that the authorization evaluator traverses.

This document defines:

- The **AclGraph Module** — a TypeBox `Type.Module` that defines the node and
  edge types for access control
- The **ACL graph instance model** — how principal-agent relationships,
  org-scoped permissions, and operation-level access control are represented as
  graph instances
- The **relationship between setup-time and runtime** — how `OperationSpec`
  definitions seed ACL graph types, and how `Identity` is evaluated at runtime
- The **principal-agent hierarchy** — how liability flows upward and permissions
  flow downward through delegation edges
- The **scoping model** — how org membership and resource access are graph edges

## Design Decisions

| ADR | Decision | Status |
|-----|----------|--------|
| [034](decisions/034-acl-as-metagraph.md) | ACL is a metagraph, not domain-specific tables | Accepted |
| [035](decisions/035-actors-become-acl-nodes.md) | Actors become node types in ACL and org graphs, standalone table removed | Accepted |
| [036](decisions/036-principal-agent-as-delegation-edges.md) | Principal-agent relationships are `delegates` edges with scope narrowing | Accepted |
| [037](decisions/037-setup-vs-runtime-separation.md) | Setup-time definitions seed graph types; runtime instances are separate graphs | Accepted |

**Sub-decisions** (documented inline, not separate ADRs):

- **`identityType` discriminator over separate node types**: A single
  `PrincipalNode` with an `identityType` field is used instead of separate
  `AccountNode`, `OrgNode`, `ServiceNode`, `RoleNode` types. This avoids
  node type proliferation and keeps the AclGraph Module compact. The type
  discriminator drives evaluation branching rather than requiring separate
  Module entries for each identity type.
- **AclGraph Config: directed, no multi, no self-loops**: Delegation and
  scoping are inherently directional. Multi-edges between the same pair
  (delegating different scope sets) carry no additional information — a
  single edge with `narrowedScopes` attributes is sufficient. Self-loops
  would represent self-delegation, which is semantically meaningless.

## Two Kinds of Authorization Scopes

A distinction that makes ACL tractable:

| Aspect | Setup-Time (Schema) | Runtime (Data) |
|--------|---------------------|----------------|
| What it is | Operation definitions and their `AccessControl` requirements | Who can do what, where, under whose authority |
| Source | `OperationSpec.accessControl` registered in the operations registry | ACL graph instances, org memberships, delegation chains |
| Stored as | Operation rows in the hub's `operations` table | Nodes and edges in ACL graph instances |
| Mutability | Changes when operations are registered/updated | Changes when org membership, delegation, or scoping changes |
| Evaluation | None — it's declarative | Traversed at call time to resolve permissions |

**Setup-time** answers: "What operations *could* require?" — it defines the
`AccessControl` schema per operation.

**Runtime** answers: "Does *this specific caller* have permission for *this
specific call*?" — it traverses the ACL graph instance.

The ACL graph type captures **runtime** authorization data. Setup-time
definitions live in `@alkdev/operations` and the hub's `operations` table. They
are related but distinct: setup-time defines the *rules*, runtime instances
store the *facts* about who follows those rules.

## The AclGraph Module

### Graph Type Configuration

The ACL graph type is **directed**, does not allow multi-edges, and does not
allow self-loops. Delegation and scoping are inherently directional (principal
→ agent, org → member). Self-delegation and multi-edges between the same pair
don't carry additional information — a single `delegates` edge with narrowed
scope attributes is sufficient.

```ts
Config: Type.Composite([
  Metagraph.Import("Config"),
  Type.Object({
    type: Type.Literal("directed"),
    multi: Type.Literal(false),
    allowSelfLoops: Type.Literal(false),
  }),
]),
```

### Node Types

| Node Type | Purpose | Key Attributes |
|-----------|---------|----------------|
| `PrincipalNode` | An identity that can delegate authority | `identityId`, `identityType`, `scopes`, `resources` |
| `ResourceNode` | A resource that can be scoped | `resourceType`, `resourceId` |

#### `PrincipalNode`

Represents an entity that holds authority and can delegate it. This is the
node-level equivalent of `@alkdev/operations`' `Identity` interface, extended
with the `identityType` concept needed for the principal-agent framework.

```ts
PrincipalNode: Type.Composite([
  Metagraph.Import("BaseNode"),
  Type.Object({
    identityId: Type.String({ minLength: 1, maxLength: 255 }),
    identityType: Type.Union([
      Type.Literal("account"),
      Type.Literal("service"),
      Type.Literal("org"),
      Type.Literal("role"),
    ]),
    scopes: Type.Array(Type.String()),
    resources: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String()))),
  }),
]),
```

- `identityId` references the account, service account, org, or role by its
  canonical identifier. This is **not** a foreign key — it's a logical reference
  to an entity in another system (the hub's `accounts` or `organizations` table,
  or a role name in the `roles` table). The ACL graph stores the shape; the hub
  stores the authoritative identity records. (See ADR-034.)
- `identityType` determines what kind of entity this principal represents. This
  matters for evaluation: an `org` principal aggregates its members' scopes, a
  `role` principal is a named set of scopes, an `account` principal is a human
  or service identity.
- `scopes` and `resources` map directly from `@alkdev/operations`' `Identity`
  interface. They represent the **base authority** of this principal before
  any delegation narrowing.
- `OrgNode` and `AccountNode` are **not separate node types**. The
  `identityType` discriminator on `PrincipalNode` avoids proliferating node
  types for entities that are structurally identical (they all hold scopes
  and resources). When evaluation needs entity-specific behavior (e.g., org
  account aggregation), the `identityType` drives branching, not the node
  type.

#### `ResourceNode`

Represents a resource that permission scopes can reference. Resources are the
targets of `AccessControl.resourceType` and `AccessControl.resourceAction` —
projects, spokes, workspaces, or any entity that an operation scopes to.

```ts
ResourceNode: Type.Composite([
  Metagraph.Import("BaseNode"),
  Type.Object({
    resourceType: Type.String({ minLength: 1, maxLength: 255 }),
    resourceId: Type.String({ minLength: 1, maxLength: 255 }),
  }),
]),
```

- `resourceType` maps to `AccessControl.resourceType` (e.g., `"project"`,
  `"spoke"`, `"workspace"`).
- `resourceId` is the canonical identifier for the specific resource instance.
  Together, `resourceType:resourceId` forms the key for
  `Identity.resources` lookups.

### Edge Types

| Edge Type | Source → Target | Purpose |
|-----------|-----------------|---------|
| `DelegatesEdge` | PrincipalNode → PrincipalNode | Principal delegates (a subset of) authority to agent |
| `ScopesEdge` | PrincipalNode → ResourceNode | Principal has specific access to a resource |
| `BelongsToEdge` | PrincipalNode → PrincipalNode (identityType org) | Account/service is a member of an org |

#### `DelegatesEdge`

The core of the principal-agent framework. When principal P delegates to agent
A, a `DelegatesEdge` is created from P → A with `narrowedScopes` attributes
that represent the subset of P's authority transferred to A.

```ts
DelegatesEdge: Type.Composite([
  Metagraph.Import("BaseEdge"),
  Type.Object({
    type: Type.Literal("delegates"),
    narrowedScopes: Type.Array(Type.String()),
    narrowedResources: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String()))),
  }),
]),

DelegatesEdgeConstraints: Type.Object({
  edgeType: Type.Literal("delegates"),
  allowedSourceTypes: Type.Array(Type.Literal("Principal")),
  allowedTargetTypes: Type.Array(Type.Literal("Principal")),
}),
```

- `narrowedScopes` is the **subset** of the principal's scopes that are
  delegated. It MUST be a subset — an agent cannot receive more authority than
  the principal holds. Enforcement happens at edge creation time: the evaluator
  validates that `narrowedScopes` ⊆ principal's effective scopes.
- `narrowedResources` is an optional narrowing of resource-scoped permissions.
  If absent, the agent inherits all of the principal's resource scoping. If
  present, it must be a subset of the principal's effective resources.
- The **no-escalation invariant**: a delegation chain must never grant an agent
  higher privilege than any ancestor. This is enforced by the evaluator at
  edge creation time and at call-time evaluation. See Principal-Agent Framework
  below.

#### `ScopesEdge`

Links a principal to a resource they have specific access to. This is the
graph-level representation of `Identity.resources`.

```ts
ScopesEdge: Type.Composite([
  Metagraph.Import("BaseEdge"),
  Type.Object({
    type: Type.Literal("scopes"),
    actions: Type.Array(Type.String()),
  }),
]),

ScopesEdgeConstraints: Type.Object({
  edgeType: Type.Literal("scopes"),
  allowedSourceTypes: Type.Array(Type.Literal("Principal")),
  allowedTargetTypes: Type.Array(Type.Literal("Resource")),
}),
```

- `actions` maps to `AccessControl.resourceAction` values. For example,
  `["read", "write"]` on a `ScopesEdge` from an account principal to a project
  resource means that account has read+write access to that project.
- This edge type directly mirrors `Identity.resources` where the key format
  `"type:id"` maps to `resourceType:resourceId` on the target `ResourceNode`,
  and the value array maps to `actions`.

#### `BelongsToEdge`

Declares that an account (or service) is a member of an organization. This is
the graph-level representation of the hub's `organization_members` table.

```ts
BelongsToEdge: Type.Composite([
  Metagraph.Import("BaseEdge"),
  Type.Object({
    type: Type.Literal("belongs_to"),
    membershipLevel: Type.Union([
      Type.Literal("owner"),
      Type.Literal("admin"),
      Type.Literal("member"),
    ]),
  }),
]),

BelongsToEdgeConstraints: Type.Object({
  edgeType: Type.Literal("belongs_to"),
  allowedSourceTypes: Type.Array(Type.Literal("Principal")),
  allowedTargetTypes: Type.Array(Type.Literal("Principal")),
  sourceTypeConstraint: Type.Optional(Type.Literal("account")),
  targetTypeConstraint: Type.Optional(Type.Literal("org")),
}),
```

- `membershipLevel` maps directly from the hub's `organization_members.membershipLevel`.
- The target must be a PrincipalNode with `identityType: "org"`.
- The source is typically a `PrincipalNode` with `identityType: "account"` or
  `"service"`.
- `sourceTypeConstraint` and `targetTypeConstraint` are **optional metadata**
  on the edge constraints. They are NOT enforced by the metagraph schema
  (which validates attribute schemas, not `identityType` values). They serve
  as documentation for evaluation logic and can be validated at the
  application layer. This is consistent with ADR-020 (no nodeTypeId on
  nodes): the metagraph validates structural constraints (which node types
  can be source/target), not domain semantics (which identityType values are
  valid for a given edge type).

### Complete AclGraph Module

```ts
export const AclGraph = Type.Module({
  Config: /* directed, no multi, no self-loops */,

  PrincipalNode: /* identityId, identityType, scopes, resources */,
  ResourceNode: /* resourceType, resourceId */,

  DelegatesEdge: /* delegates with narrowedScopes, narrowedResources */,
  DelegatesEdgeConstraints: /* Principal → Principal */,

  ScopesEdge: /* scopes with actions */,
  ScopesEdgeConstraints: /* Principal → Resource */,

  BelongsToEdge: /* belongs_to with membershipLevel */,
  BelongsToEdgeConstraints: /* account/service → org */,

  MembershipLevel: Type.Union([
    Type.Literal("owner"),
    Type.Literal("admin"),
    Type.Literal("member"),
  ]),

  IdentityType: Type.Union([
    Type.Literal("account"),
    Type.Literal("service"),
    Type.Literal("org"),
    Type.Literal("role"),
  ]),
});
```

## Principal-Agent Framework

### Core Principle

The principal-agent framework comes from legal theory: a **principal** delegates
authority to an **agent**, and the principal bears responsibility for the
agent's actions within the scope of delegation. Two rules follow:

1. **Liability flows upward**: If an agent makes a mistake, the principal who
   delegated to them is responsible. This chain continues upward through
   delegation levels.
2. **Permissions flow downward**: An agent's effective permissions are always
   a subset of their principal's permissions. Delegation can only narrow scope,
   never expand it.

### As a Directed Graph

In the ACL graph, delegation is a `DelegatesEdge` from principal → agent:

```
       User (principal)
        │
        │ delegates [{ scopes: ["dev:*"], narrowedResources: { "project:alpha": ["read", "write"] } }]
        │
        ▼
    Coordinator (agent of User)
        │
        │ delegates [{ scopes: ["dev.fs.read", "dev.fs.write"], narrowedResources: { "project:alpha": ["read"] } }]
        │
        ▼
    Implementer (agent of Coordinator)
```

Each `DelegatesEdge` carries `narrowedScopes` — what the principal is passing
down. The no-escalation invariant means:

- If User has `scopes: ["admin", "dev:*"]`, the Coordinator can only receive a
  subset: `narrowedScopes: ["dev:*"]`
- If the Coordinator has effective `scopes: ["dev:*"]`, the Implementer can
  only receive `narrowedScopes: ["dev.fs.read", "dev.fs.write"]`
- At no point can the Implementer have higher privilege than User

### Evaluation Algorithm

Given a call with `Identity { id, scopes, resources }` and an operation's
`AccessControl { requiredScopes, requiredScopesAny, resourceType, resourceAction }`:

1. **Check scopes (AND)**: Every scope in `requiredScopes` must be in the
   identity's effective scopes.
2. **Check scopes (OR)**: At least one scope in `requiredScopesAny` must be in
   the effective scopes.
3. **Check resource**: If `resourceType` and `resourceAction` are set, the
   identity's `resources["resourceType:resourceId"]` must include
   `resourceAction`.

The **effective scopes** for an identity are computed by traversing the ACL
graph:

```
effectiveScopes(identity) =
  identity.scopes
  ∩ (delegation chain intersection)
  ∪ (org membership scopes)
```

For a chain of `DelegatesEdge`s from root principal to this identity, each
edge narrows the scope. The effective scopes are the intersection of all scope
sets along the chain from root to leaf.

For `resources`, the same narrowing applies: if a `DelegatesEdge` has
`narrowedResources`, those narrow the resource scoping. If absent, the chain
is unchanged (agent inherits principal's resource scoping).

**Scope string semantics** follow `@alkdev/operations`' keypal convention:
colon-separated hierarchical segments where `*` is a wildcard matching any
suffix. `"dev:*"` matches `"dev.read"`, `"dev.write"`, `"dev.fs.read"`, etc.
`"dev:read"` matches only `"dev:read"`, not `"dev:write"`. The subset check
`narrowedScopes ⊆ effectiveScopes` uses this wildcard matching, not simple
string equality. This is consistent with `@alkdev/operations`' `AccessControl`
enforcement (see `checkAccess` in `access.ts`).

**Graph traversal optimization**: The evaluator can cache effective scopes per
identity per graph. When a `DelegatesEdge` or `ScopesEdge` is created or
removed, only identities in the affected subtree need recalculation.

### Multi-Parent Aggregation

A `PrincipalNode` can have multiple incoming edges. The aggregation rules
differ by edge type:

**Multiple `DelegatesEdge` incoming edges** (multiple principals delegating
to the same agent): The agent's effective scopes are the **union** of
delegation chains. Each chain is independently intersected (narrowed), then
the results are unioned. This allows an agent to receive authority from
multiple independent principals without either principal's chain restricting
the other.

```
effectiveScopes(agent) = ⋃(chain_i: root_i.scopes ∩ ... ∩ edge_n.narrowedScopes)
```

This preserves the no-escalation invariant per chain: no single chain can
exceed its root principal's authority. The union across chains means the agent
accumulates authority from multiple independent delegations, each bounded by
its own chain.

**`DelegatesEdge` + `BelongsToEdge` incoming edges**: These are additive.
`DelegatesEdge` provides delegation-chained scopes; `BelongsToEdge` provides
org-level scopes. The identity's effective scopes are the **union** of all
delegation chain results plus org-derived scopes.

```
effectiveScopes(identity) =
  (⋃ delegation_chains) ∪ (⋃ org_memberships)
```

Each component is independently bounded: delegation chains by their root
principal's authority, org memberships by the `membershipLevel`-derived
scope mapping.

### Transitivity

Delegation edges are **transitive**: if A delegates to B, and B delegates to C,
then C's effective authority is:

```
effectiveScopes(C) = A.scopes ∩ B.narrowedScopes ∩ C.narrowedScopes
```

This is equivalent to: C's effective authority is whatever A gave B, further
narrowed by what B gave C. The graph traversal is a depth-first walk up the
delegation chain, intersecting at each step.

### Cycle Detection

The ACL graph must be a **directed acyclic graph (DAG)**. Cycles in delegation
create paradoxes (A delegates to B who delegates back to A) and make scope
computation non-terminating.

**Detection algorithm**: At edge creation time, perform a DFS from the target
node upward through all `DelegatesEdge`s. If the source node is reachable, the
edge would create a cycle and must be rejected.

**`allowSelfLoops: false`** in the AclGraph Config prevents self-delegation
edges (A → A), but does NOT prevent longer cycles (A → B → A). Cycle
detection is performed at the application layer during edge insertion. The
`BelongsToEdge` type cannot create cycles because its target must have
`identityType: "org"` and orgs cannot delegate (they are not agents), so only
`DelegatesEdge` cycles need to be checked.

The chain always terminates** because the ACL graph is a DAG enforced at
edge creation time.

### BelongsTo vs Delegates

`BelongsToEdge` and `DelegatesEdge` serve different purposes:

- `BelongsToEdge` declares **organizational membership**: "Account A is a
  member of Org O with level 'admin'." It enables org-level scoping: when an
  operation requires `resourceType: "project"` access, and the project belongs
  to Org O, account A's membership in O can be checked.
- `DelegatesEdge` declares **authority transfer**: "Principal P delegates scopes
  S to Agent A." It creates the principal-agent relationship for a specific
  task or session.

A `BelongsToEdge` does NOT carry scope narrowing — org membership is not
delegation. The org's effective scopes for a member are determined by the
member's `membershipLevel`, which maps to org-level permissions (owner → full
control, admin → manage projects and members, member → access org resources).

Org-level permissions can also be modeled explicitly with `ScopesEdge`:
an org principal can have a `ScopesEdge` to a resource representing the org
itself, with `actions: ["admin"]` for owners, `["manage"]` for admins.

## Scoping Model

### Two-Level Scoping

The ACL system operates at two levels:

1. **Operation-level** (setup-time): `AccessControl` on `OperationSpec` defines
   *what scopes and resource actions are required* to invoke an operation. This
   is registered once when the operation is defined and changes infrequently.
   This data lives in `@alkdev/operations` and the hub's `operations` table.

2. **Graph-level** (runtime): The ACL graph instance stores *who has what* and
   *who delegates to whom*. This is queried at call time to resolve whether a
   specific identity satisfies an operation's access control requirements.

### How They Connect

```
OperationSpec.accessControl         ACL Graph Instance
┌─────────────────────┐            ┌─────────────────────────┐
│ requiredScopes:      │            │ PrincipalNode            │
│   ["dev:read"]       │◄───────────│   identityId: "user-1"  │
│ resourceType:        │  evaluate  │   scopes: ["dev:*"]      │
│   "project"          │            │                          │
│ resourceAction:      │            │ ScopesEdge               │
│   "write"            │            │   → ResourceNode          │
│                      │            │     (project:alpha)      │
└─────────────────────┘            │   actions: ["read","write"]│
                                   └─────────────────────────┘
```

The **evaluator** bridges the two:

1. Receives `AccessControl` from the operation definition
2. Looks up the caller's `Identity` (which may reference an ACL graph)
3. Traverses the ACL graph to compute effective scopes and resources
4. Applies `enforceAccess(accessControl, effectiveIdentity)`

### Org-Scoped Access

When a `BelongsToEdge` connects an account to an org, and the org has
`ScopesEdge` connections to resources, the account inherits org-level access
through its membership:

```
Account PrincipalNode ──belongs_to──→ Org PrincipalNode
                                          │
                                     scopes (actions: ["manage", "read"])
                                          │
                                          ▼
                                   ResourceNode (project:alpha)
```

The evaluation rule: if Account belongs to Org with `membershipLevel: "admin"`,
and Org has `ScopesEdge` to Resource with `actions: ["manage", "read"]`, then
Account has the intersection of `[Org-scopes for membershipLevel admin]` and
`[actions on ScopesEdge]` for that resource.

This intersection ensures that org-level permissions don't automatically grant
admin access just because the org admin has `actions: ["manage"]` — the account's
own base scopes limit what they can exercise from org membership.

## What This Replaces

### The Disconnected `actors` Table

The `actors` table in `src/sqlite/tables/actors.ts` is replaced by
`PrincipalNode` in the ACL graph. The `ACTOR_TYPE` enum (`Human`, `Llm`,
`Agent`) maps to `identityType` values (`account`, `service`, `account` — LLMs
are accounts in the hub model per ADR-012). The standalone table has no
foreign key relationships and was explicitly deferred pending ACL design (OQ-03).

This does **not** mean the hub's `accounts` table is replaced. The hub's
`accounts` table remains the authoritative identity store with email, access
level, and Gitea linking. `PrincipalNode` in the ACL graph **references** the
account by `identityId` but does not duplicate its columns. The ACL graph
stores *authorization* data; the hub's identity tables store *authentication*
data.

### Hub's `organization_members` as a Source

The hub's `organization_members` table is the authoritative source for who
belongs to which org. When org membership changes, the hub updates both:
1. The `organization_members` row (fast lookup, FK constraints)
2. The `BelongsToEdge` in the ACL graph instance (graph traversal, evaluation)

This dual-write is necessary because the hub needs fast SQL lookups for
membership checks (e.g., "list all members of this org"), while the ACL graph
needs the edge for traversal-based evaluation (e.g., "compute effective scopes
for this account across all orgs").

### Hub's Permission Resolution

The hub's current permission resolution model (role requests ∩ account scopes ∩
spoke trust level) is preserved. The ACL graph adds a **fourth input**:
delegation chain intersection. The full resolution becomes:

```
Effective permissions = ACL Effective ∩ Role.requests ∩ Account.allowed ∩ SpokeType.capable
```

The "ACL Effective" is the delegation-traversal result from the ACL graph.
This ensures that even if a role requests `admin` access, and an account has an
API key with `admin` scope, if the ACL delegation chain only grants `dev:read`,
the effective scope is `dev:read`.

## Open Questions

- **OQ-20**: Should `DelegatesEdge` support temporary delegation with
  expiration? (Referenced in [open-questions.md](open-questions.md))
- **OQ-21**: Should the ACL evaluator live in `@alkdev/storage` or in the hub?
  (Referenced in [open-questions.md](open-questions.md))
- **OQ-22**: How are ACL graph instances created and managed? (Referenced in
  [open-questions.md](open-questions.md))
- **OQ-23**: Should `BelongsToEdge` be derived (materialized from
  `organization_members`) or primary (ACL graph is the source of truth)?
  (Referenced in [open-questions.md](open-questions.md))
- **OQ-24**: How does `identityId` reference hub entities without creating a
  package dependency? (Referenced in [open-questions.md](open-questions.md))

## References

- Metagraph Module system: [metagraph-module.md](metagraph-module.md)
- SQLite host and actors table: [sqlite-host.md](sqlite-host.md)
- Operations `Identity` and `AccessControl`: `/workspace/@alkdev/operations/src/types.ts`
- Hub identity tables: `/workspace/@alkdev/hub/docs/architecture/storage/identity.md`
- Hub agent-roles model: `/workspace/@alkdev/hub/docs/architecture/agent-roles.md`
- Hub roles table: `/workspace/@alkdev/hub/docs/architecture/storage/roles.md`
- Encrypted data and SecretGraph pattern: [encrypted-data.md](encrypted-data.md)