Identity & Governance

Overview

Trellis builds identity and permissions directly into the data structure — not a third-party auth server. Every author is a cryptographic identity, every op can carry a signature, and governance policies are enforced at the middleware layer.

CLI

trellis identity show                     # Show your current identity
trellis identity create                   # Generate a new Ed25519 key pair
trellis identity list                     # List all known identities

Identities

Each identity is an Ed25519 key pair stored locally. The public key is embedded into every op authored by that identity. DIDs (Decentralized Identifiers) are the long-term identifier format.

interface VcsOp {
  agentId: string;      // Author identity (DID or opaque string)
  signature?: string;   // Ed25519 signature over op content (Phase 4+)
  // …
}

Creating an identity generates a key pair and writes it to .trellis/identity.json:

trellis identity create
# ✓ Created identity: did:key:z6Mk…
# ✓ Saved to .trellis/identity.json

Op Signing

When signing is enabled, each op's content hash is signed with the author's private key before it enters the causal stream. Recipients verify the signature against the embedded public key.

Enable signing in .trellis/config.json:

{
  "signing": {
    "enabled": true,
    "keyPath": ".trellis/identity.json"
  }
}

Governance Policies

Governance policies are enforced by KernelMiddleware — they intercept ops before they are applied and can reject or transform them.

Built-in Policy Types

Policy Configuration

{
  "governance": {
    "policies": [
      { "type": "branchProtection", "branch": "main", "requireReview": true },
      { "type": "requireSigning", "branches": ["main", "release/*"] },
      {
        "type": "identityWhitelist",
        "branch": "release/*",
        "identities": ["did:key:z6MkAlice", "did:key:z6MkBob"]
      }
    ]
  }
}

Governance Subgraph

Identities and policies are stored as first-class entities in the EAV graph, making them queryable:

// Query all identities that have authored ops on main
const result = engine.query(
  'find Identity where branch = "main" limit 20'
);

// Check what policies apply to a branch
const policies = engine.query(
  'find GovernancePolicy where branch = "main"'
);

The Governance Pillar

Trellis' Governance Subgraph is one of the Five Pillars. Rather than bolting on auth after the fact, governance is expressed in the same EAV primitives as everything else:

• Identity entities — public keys, DIDs, display names
• PolicyRule entities — typed rules with scope (repo, branch, operation kind)
• AuditTrail links — every policy decision is linked to the op that triggered it

This makes compliance queries trivial:

trellis query "find AuditTrail where action = 'rejected' since '2026-01-01'"