TORII 鳥居

The Ultimate Git Control Plane

守護者の門 - Guardian of the Gate

---

🎌 Philosophy

"Just as the sacred torii gate marks the boundary between the mundane and the divine, TORII stands as the guardian between chaos and order in your Git infrastructure."

TORII embodies three core principles:

• 🛡️ Zero Trust - Every operation is validated, no exceptions
• 📜 Policy as Code - Governance defined in version-controlled YAML
• ⚡ Git-Native - Enforcement at the protocol level, not post-facto

---

📖 What is TORII?

TORII is a production-ready Git Control Plane built in Rust that enforces policy-driven governance for Git operations. Unlike traditional Git hosting solutions that rely on webhooks and post-receive validation, TORII intercepts operations at the pre-receive stage, providing true zero-trust enforcement.

Why TORII?

Modern enterprises face critical challenges with Git governance:

• ❌ No Central Control - Teams push directly to production branches
• ❌ Post-Facto Validation - Webhooks catch violations too late
• ❌ Inconsistent Policies - Rules differ across repositories
• ❌ Audit Gaps - No comprehensive record of who did what

TORII solves these problems by acting as a policy enforcement point for all Git operations.

---

🏗️ Architecture

┌────────────────────────────────────────────────────────────────────┐
│                         TORII Ecosystem                             │
├────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Developer              Admin Interface          CI/CD System      │
│      │                        │                        │           │
│      │ git push              │ manage policies        │           │
│      ▼                        ▼                        ▼           │
│  ┌────────┐            ┌──────────┐             ┌─────────┐       │
│  │  SSH   │───────────▶│  torii-  │◀────────────│  HTTP   │       │
│  │ (Port  │            │  server  │             │  API    │       │
│  │  22)   │            │ :3000    │             │         │       │
│  └────┬───┘            └─────┬────┘             └─────────┘       │
│       │                      │                                     │
│       │ ┌────────────────────┼─────────────────────┐              │
│       │ │  Control Plane     │                     │              │
│       │ │                    ▼                     │              │
│       │ │          ┌──────────────────┐           │              │
│       │ │          │  Policy Engine   │           │              │
│       │ │          │  (torii-core)    │           │              │
│       │ │          └────────┬─────────┘           │              │
│       │ │                   │                     │              │
│       │ │                   ▼                     │              │
│       │ │          ┌──────────────────┐           │              │
│       │ │          │  Storage Layer   │           │              │
│       │ │          │  SQLite/Postgres │           │              │
│       │ │          └──────────────────┘           │              │
│       │ └──────────────────────────────────────────┘              │
│       │                                                            │
│       │ ┌──────────────────────────────────────────┐              │
│       │ │  Enforcement Layer                       │              │
│       │ └──────────────────────────────────────────┘              │
│       │                                                            │
│       └──────────▶  torii-hook (pre-receive)                      │
│                    ├─ Validates refs                              │
│                    ├─ Checks policies                             │
│                    └─ Allows/Denies push                          │
│                                                                     │
│  Authentication: torii-auth ◀──── sshd (AuthorizedKeysCommand)   │
│                                                                     │
└────────────────────────────────────────────────────────────────────┘

---

✨ Key Features

🛡️ Policy-Driven Enforcement

Define governance rules as declarative YAML policies:

apiVersion: torii.io/v1beta1
kind: RepositoryPolicy
metadata:
  name: "protect-production"
spec:
  defaultAction: "deny"
  rules:
    - name: "senior-engineers-only"
      scope:
        refs: ["refs/heads/main", "refs/heads/production"]
      conditions:
        - field: "actor.group"
          operator: "in"
          value: ["senior-engineers", "platform-team"]
      decision: "allow"

🔐 Real SSH Authentication

• Integrated with OpenSSH's AuthorizedKeysCommand
• Automatic identity injection via environment variables
• No custom Git clients required

💾 Multi-Database Support

• SQLite - Perfect for edge deployments and single-node setups
• PostgreSQL - Production-grade for multi-node clusters

⚡ High Performance

• Written in Rust for memory safety and speed
• Async/await for concurrent request handling
• Zero-copy policy evaluation

🧪 Production Ready

• Comprehensive E2E test suite with Testcontainers
• Docker support for Postgres integration tests
• CI/CD validated across multiple database backends

---

🎯 Use Cases

1. Enterprise Branch Protection

Problem: Developers accidentally push to production branches.

Solution: TORII enforces strict branch policies at the Git protocol level.

# Only allow releases from CI/CD
- name: "production-from-ci-only"
  scope:
    refs: ["refs/heads/production"]
  conditions:
    - field: "actor.type"
      operator: "equals"
      value: "service-account"
  decision: "allow"

2. Multi-Tenant Platforms

Problem: SaaS platforms need to isolate customer repositories.

Solution: Dynamic policies per repository with tenant-specific rules.

# Tenant isolation
- name: "tenant-a-only"
  conditions:
    - field: "actor.tenant_id"
      operator: "equals"
      value: "tenant-a"
  decision: "allow"

3. Compliance & Audit

Problem: Financial institutions require immutable audit trails.

Solution: TORII logs every Git operation with policy decisions.

# Query audit logs
SELECT * FROM audit_log 
WHERE repository_id = 'trading-system' 
  AND action = 'git-receive-pack' 
  AND timestamp > NOW() - INTERVAL '7 days';

4. Secure CI/CD Pipelines

Problem: Pull requests bypass security checks via force-push.

Solution: Enforce linear history and required checks.

- name: "no-force-push"
  conditions:
    - field: "ref_update.forced"
      operator: "equals"
      value: "true"
  decision: "deny"

---

🚀 Quick Start

Prerequisites

• Rust 1.70+ (rustup)
• PostgreSQL or SQLite
• OpenSSH (for SSH auth)

Installation

# Clone the repository
git clone https://github.com/copyleftdev/torii.git
cd torii

# Build all components
cargo build --release

# Binaries are in target/release/
ls target/release/torii-*

1. Start the Server

# With SQLite (development)
TORII_DB_URL="sqlite:///tmp/torii.db" \
  cargo run -p torii-server

# With PostgreSQL (production)
TORII_DB_URL="postgres://user:pass@localhost/torii" \
  cargo run -p torii-server

Server will start on http://localhost:3000

2. Create Your First Policy

# Create a policy file
cat > policy.yaml <<EOF
apiVersion: torii.io/v1beta1
kind: RepositoryPolicy
metadata:
  name: "basic-protection"
  description: "Protect main branch"
spec:
  defaultAction: "allow"
  rules:
    - name: "protect-main"
      scope:
        refs: ["refs/heads/main"]
      conditions: []
      decision: "deny"
EOF

# Apply the policy
./target/release/torii-cli policy apply -f policy.yaml

3. Create and Configure a Repository

# Create repository
./target/release/torii-cli repo create \
  --name "my-app" \
  --owner "platform-team"

# Bind policy to repository
./target/release/torii-cli binding add \
  --repo "my-app" \
  --policy "basic-protection"

4. Install Git Hook

# In your bare Git repository
cd /path/to/my-app.git

# Install pre-receive hook
ln -s /path/to/torii/target/release/torii-hook \
  hooks/pre-receive

# Make it executable
chmod +x hooks/pre-receive

# Configure environment
export TORII_REPO_ID="my-app"
export TORII_CONTROL_PLANE="http://localhost:3000"

5. Test It!

# Try to push to main (should be denied)
cd /tmp
git clone /path/to/my-app.git
cd my-app
git checkout -b main
echo "test" > README.md
git commit -am "test"

# Set actor identity
export TORII_ACTOR_ID="alice"

git push origin main
# ❌ Denied by policy 'basic-protection'

---

🔧 Configuration

Environment Variables

Variable	Description	Default
TORII_DB_URL	Database connection string	sqlite::memory:
TORII_CONTROL_PLANE	API endpoint for hooks	http://localhost:3000
TORII_REPO_ID	Repository identifier	(required)
TORII_ACTOR_ID	User identifier	(from SSH env)
RUST_LOG	Log level	info

SSH Integration

Add to /etc/ssh/sshd_config:

AuthorizedKeysCommand /usr/local/bin/torii-auth
AuthorizedKeysCommandUser git
PermitUserEnvironment TORII_ACTOR_ID

---

📦 Components

Crate	Purpose	Lines of Code
torii-core	Domain models, policy engine	~600
torii-server	Control Plane API & web service	~400
torii-storage	Persistence (SQLite/Postgres)	~500
torii-hook	Git pre-receive enforcement	~150
torii-cli	Administrative CLI	~250
torii-auth	SSH key resolver	~50
torii-e2e	End-to-end tests	~200

Total: ~2,150 lines of Rust (excluding tests)

---

🧪 Testing

# Run all tests
cargo test --workspace

# Run E2E tests (requires Docker)
cargo test -p torii-e2e

# Run with coverage
cargo tarpaulin --workspace

# Integration tests only
cargo test -p torii-storage

Test Coverage: 85%+ across critical paths

---

🛣️ Roadmap

• Phase 1-4: Core Policy Engine & Server
• Phase 5: Persistent Storage (SQLite)
• Phase 6: Management CLI
• Phase 7: SSH Authentication
• Phase 8: E2E Testing (PostgreSQL)
• Phase 9: Event Plane (AsyncAPI webhooks)
• Phase 10: Observability (Prometheus metrics)
• Phase 11: HA Deployment (Kubernetes)
• Phase 12: Web UI Dashboard

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/copyleftdev/torii.git
cd torii
cargo build

# Run tests
cargo test

# Check formatting
cargo fmt --check

# Run linter
cargo clippy

---

📄 License

MIT License - see LICENSE for details.

---

🙏 Acknowledgments

Inspired by:

• Google's Piper and Critique
• Uber's Fusion
• HashiCorp's Sentinel

---

Built with ❤️ and ⚙️ in Rust

"守護者の門" - Guardian of the Gate

Documentation • Architecture • API Spec • Roadmap