Architecture & Security Model

Architecture Overview

git-grass is structured around a strict separation of concerns between your local development workstation and optional cloud inference:

• Local Workstation (Trust Zone A): Owns all Git operations, pre-commit hooks, staged files, credentials, and the temporary mobile LAN server (:4242).
• Developer Mobile Device (Trust Zone B): Operates as a temporary screen-free bridge across local Wi-Fi. Authenticates via 48-char random hex tokens.
• Render Cloud Backend (Trust Zone C - Optional): Stateless inference proxy executing Backboard AI requests using minimal bounded metadata. Never touches Git or source code.

System Boundaries & Data Flow

[ Local Developer Workstation ]
  ├── Git Repository (.git/)
  │     ├── pre-commit hook (runs git-grass check)
  │     └── index (staged tree fingerprinted via git write-tree)
  │
  ├── Local Server (Node/Express :4242)
  │     └── Binds to LAN interface (e.g. 192.168.1.142:4242)
  │           ▲
  │           │ Authenticated via 48-char crypto token (timingSafeEqual)
  │           ▼
  [ Mobile Device on Local Wi-Fi ]
        └── Lock Screen & Outdoor Walk -> Check-in Reflection

[ Render Web Service (Optional Cloud) ]
  ├── Express API (0.0.0.0:${PORT})
  ├── Sliding-Window Rate Limiter (15 req/min per IP)
  ├── 1-hour TTL Cache (1000 items, zero token cost on hits)
  └── Backboard API Client (Gemini 2.0 Flash)
        ▲
        │ Transmits ONLY: repoName, category, durationMinutes
        ▼
  (Zero source code, diffs, or git history ever uploaded)

End-to-End Sequence

1. Commit Interception: Developer runs git commit. Pre-commit hook executes git grass check.
2. Focus Evaluation: Calculates elapsed time since last completed break in .git-grass/config.json. If within interval, exits 0. If expired, exits 1.
3. Session & Tree Locking: Workstation computes git write-tree SHA, generates 24-byte crypto token, and prints session link.
4. Challenge Retrieval: Local CLI attempts hosted backend (5s timeout), then falls back to bundled offline library.
5. Outdoor Period: Developer accesses session URL on phone, locks screen, and takes a physical 10-30 min walk. Workstation timer enforces minimum 10 min.
6. Check-in & Execution: Developer submits reflection and commit message on phone. Workstation verifies staged tree SHA, runs atomic commit, and releases terminal.

Staging Index Integrity Guarantee

When a break is enforced, git write-tree creates a tree object in the Git database representing the exact staged index. Before executing the post-break commit, git-grass verifies:

// src/git/staged-state.ts
const currentTreeHash = await getStagedTreeHash(repoRoot);
if (currentTreeHash !== session.stagedTreeHash) {
  throw new Error('Staged index was modified during the break session.');
}

Safe Process Execution (Zero Shell Injection)

All Git commands execute via node:child_process.execFile with explicit argument arrays and shell: false. Arbitrary user input from the mobile check-in (reflections or commit messages) is passed strictly as discrete argument strings, eliminating shell command injection risks.

Constant-Time Token Validation

Sessions are authenticated with 24-byte random hex tokens evaluated using Node.js's crypto.timingSafeEqual to prevent timing attacks across the local network:

// src/session/validation.ts
const tokenBuf = Buffer.from(token);
const sessionBuf = Buffer.from(session.sessionToken);
if (tokenBuf.length !== sessionBuf.length || !crypto.timingSafeEqual(tokenBuf, sessionBuf)) {
  return { valid: false, reason: 'Invalid session token' };
}

Credit Safeguards: In-Memory Cache & Rate Limiting

To strictly honor the ₹0 spend requirement, the hosted Render backend features:

• In-Memory LRU/TTL Cache: 1,000 entries with 1-hour expiration. Repeated queries for identical repository categories return cached responses in <2ms at zero token cost.
• Sliding-Window Rate Limiter: Capped at 15 requests/minute per client IP (HTTP 429 Too Many Requests).