# PatchPass – Agent Guidelines

## What is PatchPass?

**A human approval layer for AI agents.** Agents submit structured change requests (code diffs, config updates, custom values); humans review and approve them in the browser; agents then verify the platform-signed decision through the API before applying anything. Packaged as a single `docker compose` stack.

---

## Repo layout

```
Backend/        Node.js + TypeScript API (rjweb-server)
  src/
    index.ts          server bootstrap + static UI serving + notFound SPA fallback
    lib/              service layer + shared utilities
      ChangeRequestService.ts   the request lifecycle — REST and MCP both call this
      AgentService.ts           agent CRUD (human-owned)
      Authentication.ts         session (human) + API key (agent) resolution
      Signing.ts                HMAC-SHA256 approval receipts
      ChangeNormalization.ts    diff normalization + content hashing
      Limits.ts                 rate/pending/agent-count limits
      Notifications.ts, WsHub.ts realtime notifications
      SystemCrons.ts            expiry + auto-delete jobs
      DataManager.ts            global (admin) settings
      mcp/                      MCP JSON-RPC server + tools
      middlewares/, RouteAuth.ts
    routes/
      api/          human-facing REST (auth, account, agents, change-requests, notifications, admin, global)
      v1/           agent-facing REST (/v1/change-requests)
      mcp.ts        MCP endpoint (/mcp)
      ws.ts         WebSocket (/api/ws/notifications)
    tests/          Vitest integration tests
  prisma/schema.prisma
UI/             React + TypeScript + Tailwind (Vite), builds to UI/build
Dockerfile
docker-compose.yml
.gitea/workflows/deploy.yml
```

---

## Stack

| Layer | Technology |
|---|---|
| Backend | Node.js + TypeScript (strict), rjweb-server |
| ORM | Prisma 7 (`@prisma/adapter-pg`) |
| Database | PostgreSQL |
| Frontend | React + Tailwind CSS (Vite) |
| Package manager | pnpm (Backend and UI are separate pnpm workspaces) |
| Backend tests | Vitest |

---

## Development workflow

### Branch strategy

```
feature/<name>  →  dev  →  main
```

### Running locally

```bash
# Backend
cd Backend
pnpm dev          # esbuild + node, http://localhost:5000

# UI (separate terminal)
cd UI
pnpm dev          # vite on :3000, proxies /api and /v1 to :5000
```

### Before committing

1. **Backend lint:** `cd Backend && pnpm lint`
2. **Backend tests:** `cd Backend && pnpm test`
3. **UI lint:** `cd UI && pnpm lint`
4. **UI build check:** `cd UI && pnpm build`

Never commit code that fails lint or tests.

---

## Key rules

### The service layer is the single source of truth
`ChangeRequestService.ts` contains ALL request lifecycle logic and authorization. The REST routes (`routes/v1`, `routes/api`) and the MCP tools (`lib/mcp/tools`) are thin adapters that call it. **Do not duplicate authorization or business logic** in a route or tool — add it to the service.

### Request state machine
States: `PENDING`, `CHANGES_REQUESTED`, `APPROVED`, `REJECTED`, `EXPIRED`, `CONSUMED`, `CANCELLED`.
- Decisions are only allowed on `PENDING`.
- Agent updates are only allowed on `PENDING` / `CHANGES_REQUESTED`.
- `REQUEST_CHANGES` requires a comment (≤500 chars) and resets to `PENDING` on agent resubmit (`resubmitted=true`).
- No mutation after `APPROVED`, `REJECTED`, `EXPIRED`, `CONSUMED`, or `CANCELLED`.
- Approvals are single-use: `consume` moves `APPROVED → CONSUMED`.

### Signing
Approve/reject decisions are signed with HMAC-SHA256 over a fixed canonical field order (see `Signing.ts`). The signature binds the decision to `content_hash`. Never reorder the canonical fields — it breaks every existing signature.

### Content hashing
`computeContentHash` hashes `{title, description, normalizedChanges}` with key-sorted canonical JSON and LF-normalized diffs. Equivalent inputs (CRLF vs LF, key order) must hash identically; any semantic change must change the hash. Covered by tests.

### Limits
`Limits.ts` centralizes: 15 requests/agent/hour, 5 agents/human, 1–10 pending/agent (default 5), expiry 60s–12h (default 30 min), auto-delete ≥7 days. Enforce through these helpers, not ad hoc.

### Auth
- Humans: session cookie (`patchpass_session`), bcrypt passwords, optional TOTP 2FA.
- Agents: one API key each, `x-api-key` header.
Resolution is in `Authentication.ts`; routes use `requireSession` / `requireAgent` / `requireAdmin` from `RouteAuth.ts`. Disabled humans/agents are rejected.

### Admin
First registered user is `ADMIN`. Global settings (`registration_enabled`, `requests_enabled`) live in `DataManager.ts`. Admin viewing another user's request payload is explicit and audited (`recordAudit`). Never remove the last admin.

### UTC & pagination
All timestamps are UTC ISO strings at the API boundary. History and admin logs are paginated.

---

## Database migrations – MANDATORY rules

> **Never use `prisma db push` or `prisma db pull` to evolve the schema.**

When you change `prisma/schema.prisma`:

1. Create a migration: `cd Backend && pnpm migrate` (`prisma migrate dev`), give a short slug.
2. Commit the generated `prisma/migrations/<timestamp>_<name>/migration.sql` with the schema change.
3. Never hand-edit an applied `migration.sql` — create a new migration.
4. Production/CI: `pnpm migrate:deploy`.

Prisma 7: the datasource URL lives in `prisma.config.ts` via `env("DATABASE_URL")`, not in `schema.prisma`. The client uses the `PrismaPg` adapter — do not remove it. Run `pnpm generate` for TS types without a migration.

---

## General coding rules

- TypeScript strict mode is on. Avoid `any` without reason (it is a lint warning).
- Do not use `console.*` in the Backend. Use `createLogger(component)` from `lib/logger.ts`.
- UI state uses React built-ins (Context + hooks) — no external state library.
- Follow existing conventions: route handlers in `routes/`, shared logic in `lib/`, MCP tools in `lib/mcp/tools/`.

---

## Keeping CLAUDE.md and AGENTS.md in sync – MANDATORY

`CLAUDE.md` (Claude Code) and `AGENTS.md` (all other AI agents) must always reflect the same rules. Any rule added, removed, or amended in one must be mirrored in the other **in the same commit**. If they drift, fix the gap before continuing.