OpenGranter is a planned gateway for controlling LLM access by user and role and reviewing usage and audit records. It supports an OpenRouter-delegated route for existing OpenRouter users and a managed route to registered direct providers. This repository contains planning documents, an engineering harness, gateway modules, and PostgreSQL adapters. Deployment startup, management APIs, and other release gates remain under development.
The repository includes grill-with-docs and its two required skills. They are also installed in the Codex user skill directory. Planning interviews resolve decisions in rounds, capture agreed terms in CONTEXT.md, and record qualifying architectural decisions in docs/adr/. The skills come from mattpocock/skills; their license is preserved in skills/LICENSE.
Repository documentation is written in English. CLAUDE.md is a symbolic link to AGENTS.md, so both agent entry points always use the same instructions.
Contributions follow the issue, branch, and pull-request workflow, including DCO sign-off by a human contributor and disclosure of material AI assistance.
- Product requirements
- Architecture and open decisions
- Acceptance scenarios
- Roadmap
- OpenRouter client compatibility and setup
- Engineering harness
- TypeScript coding rules
- Name decision
- OpenRouter feature comparison
- OpenRouter control-layer review
- Dual upstream routing decision
- Routing and authorization contract
- Final inference provider authorization decision
Use Node.js 22 and npm. Python 3.11 or later is required for the planning-document checker.
npm ci
npm run checkThe command checks TypeScript types, formatting, linting, policy and route-authorization contract tests, document links, contract structure, and common credential patterns in fixtures. The gate also validates the pinned OpenRouter request-schema projection offline. More service tests will be added as implementation proceeds.
CI runs the complete checks against a disposable PostgreSQL 17 service. To run the same driver integration locally, supply a test database URL to the check process:
OPENGRANTER_TEST_DATABASE_URL=postgresql://postgres@127.0.0.1:5432/postgres npm run checkUse only a disposable database; the integration test creates a uniquely named schema, applies the migrations there, and removes it afterward. The example assumes a localhost test database configured without a password. Never use that authentication configuration for production. Without the explicit test URL, the real PostgreSQL integration test skips; unit and embedded database tests still run.
createPostgresConnection in src/storage/postgres-connection.ts accepts trusted node-postgres configuration and returns query, transaction, and close ports. Pass it to the PostgreSQL gateway factory and migration runner; it does not run migrations or start HTTP automatically. Close HTTP before awaiting database close() so active requests can finish. See driver ownership for failure handling and deployment responsibilities.
npm run compatibility:check validates the reviewed request-schema pin without network access and is included in npm run check. Run npm run compatibility:drift explicitly to compare selected structural fields against the official public schema; it performs no inference, sends no credentials, and does not update the pin. Review differences through an issue and pull request before updating provenance and contract expectations.
This covers selected request definitions, not full schema validation, referenced definitions, streaming, tools or named external-client certification. See coverage and limitations.