Skip to content

Latest commit

 

History

History
106 lines (88 loc) · 2.5 KB

api_spec.md

File metadata and controls

106 lines (88 loc) · 2.5 KB

TORII Control Plane API v1

The Control Plane API manages the state of the TORII system: Repositories, Policies, and Bindings. It is a synchronous HTTP JSON API (proto-ready).

Core Resources

1. Repository

Represents a Git repository managed by TORII.

Schema:

{
  "id": "repo_12345",
  "name": "torii-core",
  "owner_id": "org_eng_platform",
  "status": "active", // active, archived, locked
  "labels": {
    "sensitivity": "high",
    "language": "rust"
  },
  "created_at": "2025-01-01T12:00:00Z"
}

Endpoints:

  • POST /v1/repositories - Provision a new repo.
  • GET /v1/repositories/{id} - Get repo details.
  • PATCH /v1/repositories/{id} - Update metadata (labels, owner).
  • POST /v1/repositories/{id}/lock - Emergency freeze.

2. Policy

A versioned definition of governance rules (as defined in policy_spec.md).

Schema:

{
  "id": "pol_branch_protect_v1",
  "name": "standard-branch-protection",
  "version": "1.0",
  "spec": { ... } // YAML payload from Policy Spec
}

Endpoints:

  • POST /v1/policies - Create a new policy definition.
  • GET /v1/policies/{id} - Retrieve policy source.
  • PUT /v1/policies/{id} - Update constraints (creates new revision).

3. PolicyBinding

Attaches a Policy to a Repository or label selector.

Schema:

{
  "id": "bind_998877",
  "policy_id": "pol_branch_protect_v1",
  "target": {
    "type": "repository", // or 'selector'
    "id": "repo_12345"
  },
  "priority": 100
}

Endpoints:

  • POST /v1/bindings - Apply policy to repo.
  • DELETE /v1/bindings/{id} - Remove policy application.
  • GET /v1/debug/resolve/{repo_id} - [Diagnostic] Simulate which policies apply to a repo.

4. SSHKey (Identity)

Manages public keys allowed to authenticate as a specific user/agent.

Endpoints:

  • POST /v1/identities/{user_id}/keys - Add allowed key.
  • GET /v1/identities/{user_id}/keys - List keys.

Integration Patterns

Host Agent Communication

The Git Host (Execution Plane) communicates with the Control Plane via a specialized Check API for high-performance enforcement.

POST /v1/enforce/check

Request:

{
  "repository_id": "repo_12345",
  "actor": {
    "type": "ssh_key",
    "fingerprint": "sha256:..."
  },
  "operation": "git-receive-pack",
  "refs": [
    { "ref": "refs/heads/main", "old_oid": "...", "new_oid": "..." }
  ]
}

Response:

{
  "allowed": false,
  "reason": "Policy 'protect-main' violation: Force push not allowed.",
  "audit_id": "evt_555666"
}