Parimit

Bounded authority for agent payments.

Parimit (परिमित, pronounced puh-REE-mit) means measured or bounded. It is an open-source, proposal-only payment-intent governance boundary for AI agents.

Alpha safety demo: Parimit does not connect to UPI, a bank, a PSP, or any live payment rail. It cannot move money. Do not treat it as a payment processor, payment-rail authorization, or compliance certification.

Parimit lets an agent propose a structured payment intent, applies deterministic policy, asks a human to approve or reject the exact intent, and keeps a tamper-evident audit history. The included rail is a simulator for safe demonstrations of success, failure, reversal, and uncertain outcomes.

The boundary

AI agent                         Human operator
    |                                  |
    | propose / read / cancel own      | approve or reject exact proposal
    v                                  v
+------------------------- Parimit -------------------------+
| validation -> policy -> approval -> signed evidence -> audit |
+-----------------------------------------------------------+
                              |
                              v
                     mock simulator only
                        (never money)

The MCP surface intentionally exposes no pay, send, initiate, execute, or approve capability. The HTTP API supports verified OIDC bearer identity for a single-tenant pilot and keeps agent, approver, consumer, and admin roles separate. Clearly labelled, spoofable headers remain available only for an explicit local demo. No surface can dispatch an approval to a payment rail.

Related MCP server: Cerberus

What works in v0.1.0-alpha.3

• Create a proposal with an agent-scoped idempotency key.

• Validate amount, currency, payee, purpose, and expiry.

• Apply deterministic amount, allowlist, and velocity policies.

• Require one or two distinct human approvals according to policy.

• Cancel or inspect a proposal without moving funds.

• Produce an HMAC-protected, non-dispatchable authorization receipt.

• Issue a short-lived, audience-bound Ed25519 evidence envelope after full approval, with signed execution_authorized: false and moves_money: false.

• Publish public verification keys through JWKS and verify exact intent, policy/configuration digest, identity trust domain, approver set, state version, tenant, audit tip, audience, and expiry.

• Atomically record one-time envelope consumption inside the single-instance SQLite boundary; offline recipients still need their own durable replay ledger.

• Append hash-chained audit events.

• Simulate labelled outcomes; recording IN_DOUBT freezes the mock observation stream and rejects every later mock outcome.

• Use the browser dashboard and proposal-only MCP server locally, or the OIDC-protected REST API/SDK for the narrow hosted pilot.

• Verify OIDC JWT signatures, issuer, audience, lifetime, key algorithm, and a fail-closed role mapping, with bounded JWKS caching and key rotation.

• Scope agents to their own proposals while reviewers and administrators use separate capabilities.

• Use a dependency-free, role-shaped TypeScript SDK preview.

• Use the optional AiNxt source-review-anchored sidecar adapter for a synthetic, proposal-only compatibility pilot; it is not a native AiNxt tool or NPCI endorsement.

• Review the PostgreSQL 14+ schema and transaction contract for the next storage port. PostgreSQL is not runtime-selectable yet.

• Run locally with Node.js 24 and no third-party runtime dependencies.

Quick start

Requirements: Node.js 24 and a modern browser.

git clone https://github.com/cad07/parimit.git
cd parimit
npm start

Open http://localhost:8787. The application stores demo state locally; it is not suitable for shared or production deployment.

The local dashboard starts as demo-agent. Create a proposal, then use the identity menu to switch to a distinct approver for review and to an admin for a labelled mock observation.

Run the complete core, HTTP/OIDC, SDK, and safety-boundary gate:

npm run check

Run the local-demo MCP server over standard input/output:

npm run mcp

For a containerized demo:

docker compose up --build

Controlled local OIDC pilot

The repository also includes a local-only Keycloak profile for exercising the real OIDC boundary over TLS. It keeps the machine agent and consumer identities separate from two interactive human accounts and does not enable a password grant, payment connector, or execution route.

With Docker Compose and OpenSSL available, generate a fresh ignored recovery set and run the controlled acceptance flow:

npm run pilot:keycloak:bootstrap
npm run pilot:keycloak:accept

The acceptance runner requires a person to complete the reviewer and admin device logins and to confirm each exact fictional proposal before a decision. For CI or connectivity diagnostics, npm run pilot:keycloak:smoke exercises workload authentication only; it never approves a proposal and is not human acceptance. With a separately running, loopback-only AiNxt model runtime, npm run pilot:ainxt:keycloak -- --expected-ainxt-control-plane-sha '<exact-AiNxt-control-plane-SHA>' keeps the real Keycloak agent token in-process and proves only the bounded path through one AWAITING_APPROVAL proposal and a policy-denied simulation. It never performs a human decision and is not payment integration. See integrations/ainxt/README.md for the disclosed local Ollama compatibility profile and deploy/keycloak/README.md before running or resetting the identity profile.

Configuration

The server reads configuration from exported environment variables. The Node process does not load .env automatically; .env.example is a reference. Docker Compose forwards the receipt and policy variables from a local .env file, while keeping its container host, port, database path, and demo mode fixed.

Use only fictional references. Do not put bank, PSP, UPI, OTP, PIN, or customer credentials into this application or its environment.

PARIMIT_RECEIPT_KEY is bound to the database, tenant, envelope issuer, single envelope audience, authentication mode, exact identity trust-domain digest, policy-configuration digest, and envelope lifetime policy on first startup. Alpha.3 deliberately does not rotate this key or retarget that trust configuration in place: a mismatch fails startup before a new envelope signing key can be registered. A v3 database with material history but no root is treated as corruption. Recover the database, receipt key, trust configuration, and historical envelope-key registry as one set. A full-registry HMAC checkpoint detects removed historical public keys. OIDC mode refuses approval history that predates this authentication-mode binding.

Safe demo

1. Select the agent demo identity and create a proposal for a small amount and a fictional demo payee.

2. Observe the deterministic policy decision.

3. Switch to a distinct approver, open the approval view, and approve the exact proposal as a human.

4. Create a ₹600.00 proposal and use two distinct demo approvers.

5. Switch to admin, run the mock simulator, and select success, failure, reversal, or IN_DOUBT.

6. After IN_DOUBT, try another mock outcome and confirm that it is rejected with IN_DOUBT_FROZEN; this alpha has no reconciliation bypass.

7. Inspect the audit chain. Re-submit the same idempotency key to see duplicate protection.

The REST/SDK flow can additionally issue an evidence envelope as a reviewer, verify its Ed25519 signature and audience, then consume it once as a distinct consumer. Issuance and consumption are deliberately absent from MCP.

Nothing in this flow contacts an external service or moves money.

Agent interfaces

The REST contract is in openapi.yaml, and the preview TypeScript SDK is in sdk/typescript. Clients first call GET /v1/identity and use the returned actor_id as requested_by.id. The MCP server is a local process-boundary demo. It is disabled when PARIMIT_AUTH_MODE=oidc because this alpha has no cryptographically verified actor binding for stdio MCP. It is deliberately narrower and exposes only proposal-safe tools:

• create_payment_proposal

• get_payment_status

• cancel_payment_proposal

• get_policy_decision

• simulate_payment (mock outcomes only)

• get_payment_audit

MCP clients must not be given the human dashboard credentials or direct access to internal approval routes. See docs/safety-boundary.md.

The optional integrations/ainxt reference adapter uses AiNxt's public HTTP/SSE docking contract, accepts only code-owned synthetic fixtures, strictly validates the model draft, and then calls only the OIDC-protected Parimit agent REST surface. Its source review is anchored to an exact AiNxt commit and it never forwards the Parimit bearer token to AiNxt. It is an independent compatibility pilot, not an AiNxt native connector, AtOM integration, UPI access, or payment execution.

Design principles

• Agents propose; review stays separate. The MCP surface has no approval tool. The HTTP edge binds every proposal to an authenticated agent and only an approver or admin may review it. Demo headers are workflow labels, not human authentication.

• Approval is not execution. A receipt describes human authorization but is structurally non-dispatchable.

• Portable evidence is not a payment command. The public-key-verifiable envelope is audience-bound, short-lived, one-time, and signs explicit false values for dispatch, provider instruction, execution authority, and money movement.

• Exact-intent binding. Changing amount, currency, payee, or purpose invalidates earlier approvals.

• Fail closed. Invalid policy, expired intent, audit mismatch, and uncertain state all stop progress.

• Freeze after uncertainty. Once IN_DOUBT is recorded, all later mock observations are rejected. This alpha exposes no reconciliation mechanism.

• Pure core. Domain and policy code cannot import network modules.

The repository enforces part of this boundary with scripts/check-boundary.ts in CI.

Documentation

• Alpha.1 technical design paper (historical snapshot) (PDF)

• Architecture

• API and MCP usage

• Authorization Envelope v1

• Threat model

• Safety boundary

• Safe demo

• OIDC identity and role mapping

• Single-tenant pilot guide

• Local Keycloak OIDC pilot

• Adapter guide

• PostgreSQL integration track

• Requirements for a real payment integration

• Decision record: proposal-only

• Decision record: signed evidence envelopes

• Decision record: local Keycloak pilot

Relationship to NPCI AiNxt OS

The design was informed by the public, non-dispatchable payment boundary in NPCI's AiNxt OS, reviewed at commit 5b6fbb90eb715384559256f7257e4d661cb1d17b. AiNxt's settlement documentation states that its payment core does not perform I/O or talk to banks. Parimit preserves the same separation in its own independently written implementation.

No AiNxt source code is copied into this initial release. Parimit is not affiliated with or endorsed by NPCI, and it must not use NPCI, AiNxt, or UPI logos. See NOTICE.

An optional, independently written trusted-sidecar reference adapter now lives under integrations/ainxt. It uses the public AiNxt HTTP/SSE docking contract and Parimit OIDC REST boundary; it does not make AiNxt a dependency of Parimit's core and does not constitute native AiNxt or NPCI integration.

Contributing and security

Contributions are welcome, particularly policy tests, threat-model review, accessibility improvements, and additional mock scenarios. Read CONTRIBUTING.md and the CODE_OF_CONDUCT.md first.

Please do not open public issues for vulnerabilities. Follow SECURITY.md to report them privately.

License

MIT. See LICENSE. Product and payment-network names belong to their respective owners.