Overview

LATCH defines a small HTTPS/JSON boundary between an agent and a service: a well-known card at /.well-known/latch.json and one POST endpoint with five operations — ask (read without side effects), quote (offer plus SHA-256 digest, no execution), approve (local trusted-host/user decision bound to that digest), commit (digest + approval + idempotency key) and status (task and provider receipt). It is meant for agent-to-service actions that need explicit, reviewable terms before an effect happens.

It is not an identity or payment system and does not replace MCP, A2A, OpenAPI or UCP/ACP/AP2. A Node.js 20+ reference client, server and CLI ship in one dependency-free ESM file; an optional MCP stdio bridge and a PHP 8.2 provider are also included. The wire version is experimental 0.1, implementation 0.2.0, under MIT.

Quick Start

Requires Node.js 20+. Clone and run the demo trace:

git clone https://github.com/Balanov/latch.git
cd latch
npm test
node latch.mjs demo --trace examples/trace.json

The trace shows real local discovery, ask, quote, approval, commit and receipt messages with full IDs and HTTP headers. To try it interactively, start the provider in one terminal with node latch.mjs demo --port 8787, then from another terminal run discovery, a read and a quote:

node latch.mjs discover http://127.0.0.1:8787
node latch.mjs ask http://127.0.0.1:8787 materials.list
node latch.mjs quote http://127.0.0.1:8787 print3d.order \
  '{"model_url":"https://example.com/model.stl","material":"pla","quantity":1,"delivery":{"country":"NL","postal_code":"1011"}}'

Review the terms, origin, expiry and digest, then repeat the exact digest after --yes to commit; a mismatch aborts before a connection. See the specification for canonical JSON, expiry, approval, replay and security rules.

Connect a Provider

Scaffold a service from the template, install and run it:

npx --yes github:Balanov/latch init my-latch-service
cd my-latch-service
npm install
node service.mjs

Alternatively use createLatchServer(card, handlers, options) and listen(server, options) from latch-protocol. Write capabilities need separate quote and commit handlers: quote returns summary, terms and expiry without doing work; commit performs the effect only after exact offer/approval validation and idempotency handling. Providers remain responsible for authorization, full schema validation, accurate terms, rate limits and external effects.

Persistence and Authentication

Storage defaults to in-memory and unauthenticated. For restart-safe local use, pass createFileStore() plus an explicit authenticate verifier that returns a stable principal id or null; offers, tasks, idempotency records and pending commits are then scoped by principal. The file store serializes writes, replaces files atomically and rejects a second writer or corrupt file, but it is not a distributed database, encryption layer or exactly-once guarantee for external effects. Implement the async get/set adapter for a production database.

Constraints and Limits

• The digest binds content, not a person, provider or business claim, and a provider_assertion receipt is not independent physical evidence.
• Idempotency prevents duplicate processing but cannot undo an external effect. Library users must reuse the same idempotency key when retrying the same commit.
• Remote cards, descriptions and results are untrusted data, not agent instructions.
• Client responses are size-limited while streaming; timeouts return 504 timeout. Custom headers are origin-bound, and cross-origin headers need separate opt-in.
• The dependency-free validator supports a documented JSON Schema subset, not the full specification.
• For MCP use, the host must display the actual offer and enforce approval before calling latch_commit; a tool call is not verified human identity.
• Demo orders are simulations: nothing is paid for, manufactured or delivered. The public demo uses CORS * only because it has no credentials or real effects and should not be copied to private services.

HotRepo's take

On its first day (2026-11-04, UTC) the repository entered HotRepo's new-project list with 100 stars gained over a window starting 16:57, all of which are also its current total, and one fork. No GitHub all-language daily rank was recorded, so there is no placement to compare against. That makes this an early signal rather than evidence of adoption: development effort visible in the repo — CLI demos, a PHP provider, benchmarks against official MCP SDK 1.32.2, and a browser check — is more informative than the single day of stars for judging whether the contract has practical value.