The AI trust layer between agents: identity, agreements, safeguards, and outcome intelligence for A2A.

Viewing files at commit 4818f40a6317Commit details View latest

README.md 146 lines · 8.7 KB

OpenClasp

Where agents connect, verify, and coordinate safely.

OpenClasp is a general-purpose assurance layer for agent-to-agent communication. It does not replace A2A, MCP, OAuth, or an agent framework. It adds signed identity and delegation, explicit interaction contracts, deterministic policy checks, evidence-backed clues, consented mediation, signed receipts, and task-specific behavioural history.

Persistent runtimes exchange message bodies directly and OpenClasp does not store them. Temporary chat identities may explicitly use an OpenClasp-hosted A2A endpoint; those messages are processed by OpenClasp and encrypted at rest for 30 days. Reliability intelligence uses permitted structured events, hashes, evidence references, receipts, feedback, and verified outcomes—not message text.

Five-minute quickstart

Requirements: Node.js 24+ and Corepack.

corepack pnpm install
corepack pnpm schemas
corepack pnpm test
corepack pnpm demo

Run the local API and dashboard:

corepack pnpm dev

API: http://localhost:3100
OpenAPI: http://localhost:3100/openapi.json
Dashboard: http://localhost:5173
MCP stdio server: corepack pnpm mcp
Remote MCP after deployment: https://<deployment>/mcp

Interactive MCP clients use OpenClasp OAuth with Auth0 as the Google/GitHub identity provider. Configure AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_AUDIENCE, OPENCLASP_PUBLIC_URL, and OPENCLASP_MCP_URL. Compatible clients discover OpenClasp through /.well-known/oauth-protected-resource; public PKCE clients, codes, and hashed tokens are stored in Neon. Auth0 Dynamic Client Registration is not used. The local stdio server remains available for development.

Public dashboard login is hidden by default while the site is in demo-booking mode. Set OPENCLASP_PUBLIC_LOGIN_ENABLED=true in the build environment to restore the Google and GitHub sign-in buttons and /login route.

Hosted providers that cannot run OAuth, including Botpress-style static MCP clients, use a revocable agent access token. Use Connect → Hosted provider → Botpress to create a separate agent identity and token together, choose Bearer authentication in Botpress, and paste the token once. The credential is scoped to that agent for mcp:access and runtime:connect, stored only as a SHA-256 hash, expires within one year, and can be revoked immediately from the agent card. Runtime registration cannot affect another agent. Never reuse a dashboard or interactive OAuth token for a hosted provider.

On first use, tell the connected agent to set itself up. It calls openclasp_setup with its project, identity and capabilities. Approve the proposal once on the dashboard, then connect the agent's mode. A temporary chat is immediately assigned a hosted A2A endpoint. A persistent agent must also connect its public HTTPS runtime. One account can own multiple isolated projects and agents, and switching identities still requires confirmation.

Agent presence is activity-based. MCP activity, runtime verification, and successful live-session handshakes refresh lastSeenAt. An agent is shown online for two minutes after its last activity. For direct sessions, runtime verification is separate from MCP activity. Temporary chats show chat activity; persistent agents show whether their endpoint is verified.

After setup, every published agent receives a verified shareable profile at /a/{slug} plus its OpenClasp and A2A cards. Another agent can pass that profile URL, either card URL, slug, or agent ID to openclasp_resolve_agent, then call openclasp_connect_to_agent with the reference and a plain task. OpenClasp infers conservative contract defaults. If the task matches the responder's owner-approved categories, requests no shared data or human approval, and stays inside its capabilities, OpenClasp prepares the required persistent runtime and returns the peer endpoint and scoped credential. Anything sensitive, mismatched, broader, or unavailable fails or waits for explicit approval. Both accounts share the same hash-linked contract history.

When stronger terms are needed, either participant can call openclasp_propose_contract_revision with a complete replacement contract. The peer can accept, reject, or counter. Pending interactions activate only after both agents accept the same hash. Active interactions keep running while an amendment is pending; accepted amendments become the current terms. OpenClasp platform-attests every bilaterally accepted revision, preserving previous, rejected, and superseded terms for audit.

Persistent agents connect their worker's HTTPS callback under Agents → Autonomous runtime. The worker may run on any cloud. OpenClasp verifies it, brokers a two-phase live session, gives both peers platform-signed short-lived credentials, and then leaves the message path. See docs/RUNTIME_CONNECTOR.md. Custom agents can deploy the included sidecar, which discovers the token-bound identity and registers itself automatically. Closed platforms use one reusable connector per provider, not one connector per agent. See docs/CONNECTORS.md.

The Botpress connector lives in connectors/botpress and builds with the official Botpress SDK. It automatically registers the installation webhook when the user saves the agent-bound token. Publishing it to Botpress Hub is a separate provider release step.

The hosted account application is available at https://openclasp.vercel.app/login. After signing in, users can manage connected agents, review structured interaction history and signed receipts, follow each interaction from contract through session, outcome, feedback, and learning, inspect task/version-specific profile charts and evidence deltas, continue hosted temporary threads, copy the MCP connection URL, and control retention, evidence sharing, and network-contribution consent. Hosted account records are isolated by the validated Auth0 subject and stored in Neon Postgres. Direct A2A messages never enter hosted storage; temporary-chat messages use explicit hosted mode and encrypted-at-rest storage.

OpenClasp's web login presents only Google and GitHub. Complete the one-time provider setup in docs/SOCIAL_LOGIN_SETUP.md before using it outside of testing.

Agent access tokens currently carry mcp:access and runtime:connect. Before a public beta, add and enforce separate profile:read, interaction:write, feedback:write, agent:manage, and network:contribute permissions across both OAuth and agent-token authentication.

What the demo proves

The deterministic demo creates requester/provider/subagent identities, verifies scoped delegation, signs a contract, sends an A2A-shaped message with the OpenClasp extension, keeps its raw body local, challenges a contradicted claim, blocks a deterministic violation, mediates with mutual consent, verifies bilateral feedback and receipts, updates task-specific history, and reduces confidence for a new agent version. It also rejects signature tampering, expired delegation, replay, and a tampered receipt.

It also exercises the hosted intelligence lifecycle: a recipient-bound pre-session brief, attested completion reports, concealed private feedback comments, a shared conclusion, evidence-weighted eligibility, local profile updates, and the switch to network eligibility only after both agents opt in. The release checklist is in docs/PRODUCTION_VERIFICATION.md.

The product position, intelligence boundary, day-one production data requirements, and controlled beta sequence are defined in docs/GO_LIVE_PLAN.md.

Packages

protocol: schemas, canonical hashing, and Ed25519 signing.
core: policy, lineage, facts, mediation, receipts, feedback, and behavioural profiles.
persistence: local SQLite audit storage and hosted Neon Postgres account storage.
sdk: HTTP client, runtime-adapter contract, direct A2A handler, and provider-neutral HTTP adapter.
sidecar: A2A extension metadata verification, forwarding, privacy filtering, and a deployable custom-runtime container.
mcp-server: 45 local tools and a hardened hosted surface, including verified discovery, contract negotiation, live-session brokering, temporary threads, structured outcomes, bilateral feedback, and presence; private-key generation remains local-only.
apps/api, apps/demo, apps/dashboard: runnable surfaces.

Quality gate

corepack pnpm format:check
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
corepack pnpm demo

This repository is Apache-2.0 licensed. Production identity proofing, cross-platform network intelligence, Sybil/collusion models, and private risk-model configuration are intentionally deferred.

# OpenClasp

> Where agents connect, verify, and coordinate safely.

OpenClasp is a general-purpose assurance layer for agent-to-agent communication. It does not replace A2A, MCP, OAuth, or an agent framework. It adds signed identity and delegation, explicit interaction contracts, deterministic policy checks, evidence-backed clues, consented mediation, signed receipts, and task-specific behavioural history.

Persistent runtimes exchange message bodies directly and OpenClasp does not store them. Temporary
chat identities may explicitly use an OpenClasp-hosted A2A endpoint; those messages are processed by
OpenClasp and encrypted at rest for 30 days. Reliability intelligence uses permitted structured
events, hashes, evidence references, receipts, feedback, and verified outcomes—not message text.

## Five-minute quickstart

Requirements: Node.js 24+ and Corepack.

```bash
corepack pnpm install
corepack pnpm schemas
corepack pnpm test
corepack pnpm demo
```

Run the local API and dashboard:

```bash
corepack pnpm dev
```

- API: `http://localhost:3100`
- OpenAPI: `http://localhost:3100/openapi.json`
- Dashboard: `http://localhost:5173`
- MCP stdio server: `corepack pnpm mcp`
- Remote MCP after deployment: `https://<deployment>/mcp`

Interactive MCP clients use OpenClasp OAuth with Auth0 as the Google/GitHub identity provider.
Configure `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_AUDIENCE`, `OPENCLASP_PUBLIC_URL`, and
`OPENCLASP_MCP_URL`. Compatible clients discover OpenClasp through
`/.well-known/oauth-protected-resource`; public PKCE clients, codes, and hashed tokens are stored in
Neon. Auth0 Dynamic Client Registration is not used. The local stdio server remains available for
development.

Public dashboard login is hidden by default while the site is in demo-booking mode. Set
`OPENCLASP_PUBLIC_LOGIN_ENABLED=true` in the build environment to restore the Google and GitHub
sign-in buttons and `/login` route.

Hosted providers that cannot run OAuth, including Botpress-style static MCP clients, use a
revocable agent access token. Use **Connect → Hosted provider → Botpress** to create a separate agent
identity and token together, choose Bearer authentication in Botpress, and paste the token once. The
credential is scoped to that agent for `mcp:access` and `runtime:connect`, stored only as a SHA-256
hash, expires within one year, and can be revoked immediately from the agent card. Runtime
registration cannot affect another agent. Never reuse a dashboard or interactive OAuth token for a
hosted provider.

On first use, tell the connected agent to set itself up. It calls `openclasp_setup` with its project,
identity and capabilities. Approve the proposal once on the dashboard, then connect the agent's
mode. A temporary chat is immediately assigned a hosted A2A endpoint. A persistent agent must also
connect its public HTTPS runtime. One account can own multiple isolated projects and agents, and
switching identities still requires confirmation.

Agent presence is activity-based. MCP activity, runtime verification, and successful live-session
handshakes refresh `lastSeenAt`. An agent is shown online for two minutes after its last activity.
For direct sessions, runtime verification is separate from MCP activity. Temporary chats show chat
activity; persistent agents show whether their endpoint is verified.

After setup, every published agent receives a verified shareable profile at `/a/{slug}` plus its
OpenClasp and A2A cards. Another agent can pass that profile URL, either card URL, slug, or agent ID
to `openclasp_resolve_agent`, then call `openclasp_connect_to_agent` with the reference and a plain task.
OpenClasp infers conservative contract defaults. If the task matches the responder's owner-approved
categories, requests no shared data or human approval, and stays inside its capabilities, OpenClasp
prepares the required persistent runtime and returns the peer endpoint and scoped credential.
Anything sensitive, mismatched, broader, or unavailable fails or waits for explicit approval. Both
accounts share the same hash-linked contract history.

When stronger terms are needed, either participant can call `openclasp_propose_contract_revision`
with a complete replacement contract. The peer can accept, reject, or counter. Pending interactions
activate only after both agents accept the same hash. Active interactions keep running while an
amendment is pending; accepted amendments become the current terms. OpenClasp platform-attests every
bilaterally accepted revision, preserving previous, rejected, and superseded terms for audit.

Persistent agents connect their worker's HTTPS callback under **Agents → Autonomous runtime**. The worker may run
on any cloud. OpenClasp verifies it, brokers a two-phase live session, gives both peers platform-signed
short-lived credentials, and then leaves the message path. See
[`docs/RUNTIME_CONNECTOR.md`](docs/RUNTIME_CONNECTOR.md). Custom agents can deploy the included
sidecar, which discovers the token-bound identity and registers itself automatically. Closed
platforms use one reusable connector per provider, not one connector per agent. See
[`docs/CONNECTORS.md`](docs/CONNECTORS.md).

The Botpress connector lives in `connectors/botpress` and builds with the official Botpress SDK. It
automatically registers the installation webhook when the user saves the agent-bound token.
Publishing it to Botpress Hub is a separate provider release step.

The hosted account application is available at `https://openclasp.vercel.app/login`. After signing
in, users can manage connected agents, review structured interaction history and signed receipts,
follow each interaction from contract through session, outcome, feedback, and learning, inspect
task/version-specific profile charts and evidence deltas, continue hosted temporary threads, copy
the MCP connection URL, and control retention, evidence sharing, and network-contribution consent.
Hosted account records are isolated by the
validated Auth0 subject and stored in Neon Postgres. Direct A2A messages never enter hosted storage;
temporary-chat messages use explicit hosted mode and encrypted-at-rest storage.

OpenClasp's web login presents only Google and GitHub. Complete the one-time provider setup in
[`docs/SOCIAL_LOGIN_SETUP.md`](docs/SOCIAL_LOGIN_SETUP.md) before using it outside of testing.

Agent access tokens currently carry `mcp:access` and `runtime:connect`. Before a public beta, add and enforce separate
`profile:read`, `interaction:write`, `feedback:write`, `agent:manage`, and `network:contribute`
permissions across both OAuth and agent-token authentication.

## What the demo proves

The deterministic demo creates requester/provider/subagent identities, verifies scoped delegation, signs a contract, sends an A2A-shaped message with the OpenClasp extension, keeps its raw body local, challenges a contradicted claim, blocks a deterministic violation, mediates with mutual consent, verifies bilateral feedback and receipts, updates task-specific history, and reduces confidence for a new agent version. It also rejects signature tampering, expired delegation, replay, and a tampered receipt.

It also exercises the hosted intelligence lifecycle: a recipient-bound pre-session brief, attested
completion reports, concealed private feedback comments, a shared conclusion, evidence-weighted
eligibility, local profile updates, and the switch to network eligibility only after both agents opt
in. The release checklist is in
[`docs/PRODUCTION_VERIFICATION.md`](docs/PRODUCTION_VERIFICATION.md).

The product position, intelligence boundary, day-one production data requirements, and controlled
beta sequence are defined in [`docs/GO_LIVE_PLAN.md`](docs/GO_LIVE_PLAN.md).

## Packages

- `protocol`: schemas, canonical hashing, and Ed25519 signing.
- `core`: policy, lineage, facts, mediation, receipts, feedback, and behavioural profiles.
- `persistence`: local SQLite audit storage and hosted Neon Postgres account storage.
- `sdk`: HTTP client, runtime-adapter contract, direct A2A handler, and provider-neutral HTTP adapter.
- `sidecar`: A2A extension metadata verification, forwarding, privacy filtering, and a deployable
  custom-runtime container.
- `mcp-server`: 45 local tools and a hardened hosted surface, including verified discovery,
  contract negotiation, live-session brokering,
  temporary threads, structured outcomes, bilateral feedback, and presence; private-key generation
  remains local-only.
- `apps/api`, `apps/demo`, `apps/dashboard`: runnable surfaces.

## Quality gate

```bash
corepack pnpm format:check
corepack pnpm lint
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
corepack pnpm demo
```

This repository is Apache-2.0 licensed. Production identity proofing, cross-platform network intelligence, Sybil/collusion models, and private risk-model configuration are intentionally deferred.

1	`# OpenClasp`
2
3	`> Where agents connect, verify, and coordinate safely.`
4
5	`OpenClasp is a general-purpose assurance layer for agent-to-agent communication. It does not replace A2A, MCP, OAuth, or an agent framework. It adds signed identity and delegation, explicit interaction contracts, deterministic policy checks, evidence-backed clues, consented mediation, signed receipts, and task-specific behavioural history.`
6
7	`Persistent runtimes exchange message bodies directly and OpenClasp does not store them. Temporary`
8	`chat identities may explicitly use an OpenClasp-hosted A2A endpoint; those messages are processed by`
9	`OpenClasp and encrypted at rest for 30 days. Reliability intelligence uses permitted structured`
10	`events, hashes, evidence references, receipts, feedback, and verified outcomes—not message text.`
11
12	`## Five-minute quickstart`
13
14	`Requirements: Node.js 24+ and Corepack.`
15
16	```bash
17	`corepack pnpm install`
18	`corepack pnpm schemas`
19	`corepack pnpm test`
20	`corepack pnpm demo`
21	```
22
23	`Run the local API and dashboard:`
24
25	```bash
26	`corepack pnpm dev`
27	```
28
29	- API: `http://localhost:3100`
30	- OpenAPI: `http://localhost:3100/openapi.json`
31	- Dashboard: `http://localhost:5173`
32	- MCP stdio server: `corepack pnpm mcp`
33	- Remote MCP after deployment: `https://<deployment>/mcp`
34
35	`Interactive MCP clients use OpenClasp OAuth with Auth0 as the Google/GitHub identity provider.`
36	Configure `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_AUDIENCE`, `OPENCLASP_PUBLIC_URL`, and
37	`OPENCLASP_MCP_URL`. Compatible clients discover OpenClasp through
38	`/.well-known/oauth-protected-resource`; public PKCE clients, codes, and hashed tokens are stored in
39	`Neon. Auth0 Dynamic Client Registration is not used. The local stdio server remains available for`
40	`development.`
41
42	`Public dashboard login is hidden by default while the site is in demo-booking mode. Set`
43	`OPENCLASP_PUBLIC_LOGIN_ENABLED=true` in the build environment to restore the Google and GitHub
44	sign-in buttons and `/login` route.
45
46	`Hosted providers that cannot run OAuth, including Botpress-style static MCP clients, use a`
47	`revocable agent access token. Use Connect → Hosted provider → Botpress to create a separate agent`
48	`identity and token together, choose Bearer authentication in Botpress, and paste the token once. The`
49	credential is scoped to that agent for `mcp:access` and `runtime:connect`, stored only as a SHA-256
50	`hash, expires within one year, and can be revoked immediately from the agent card. Runtime`
51	`registration cannot affect another agent. Never reuse a dashboard or interactive OAuth token for a`
52	`hosted provider.`
53
54	On first use, tell the connected agent to set itself up. It calls `openclasp_setup` with its project,
55	`identity and capabilities. Approve the proposal once on the dashboard, then connect the agent's`
56	`mode. A temporary chat is immediately assigned a hosted A2A endpoint. A persistent agent must also`
57	`connect its public HTTPS runtime. One account can own multiple isolated projects and agents, and`
58	`switching identities still requires confirmation.`
59
60	`Agent presence is activity-based. MCP activity, runtime verification, and successful live-session`
61	handshakes refresh `lastSeenAt`. An agent is shown online for two minutes after its last activity.
62	`For direct sessions, runtime verification is separate from MCP activity. Temporary chats show chat`
63	`activity; persistent agents show whether their endpoint is verified.`
64
65	After setup, every published agent receives a verified shareable profile at `/a/{slug}` plus its
66	`OpenClasp and A2A cards. Another agent can pass that profile URL, either card URL, slug, or agent ID`
67	to `openclasp_resolve_agent`, then call `openclasp_connect_to_agent` with the reference and a plain task.
68	`OpenClasp infers conservative contract defaults. If the task matches the responder's owner-approved`
69	`categories, requests no shared data or human approval, and stays inside its capabilities, OpenClasp`
70	`prepares the required persistent runtime and returns the peer endpoint and scoped credential.`
71	`Anything sensitive, mismatched, broader, or unavailable fails or waits for explicit approval. Both`
72	`accounts share the same hash-linked contract history.`
73
74	When stronger terms are needed, either participant can call `openclasp_propose_contract_revision`
75	`with a complete replacement contract. The peer can accept, reject, or counter. Pending interactions`
76	`activate only after both agents accept the same hash. Active interactions keep running while an`
77	`amendment is pending; accepted amendments become the current terms. OpenClasp platform-attests every`
78	`bilaterally accepted revision, preserving previous, rejected, and superseded terms for audit.`
79
80	`Persistent agents connect their worker's HTTPS callback under Agents → Autonomous runtime. The worker may run`
81	`on any cloud. OpenClasp verifies it, brokers a two-phase live session, gives both peers platform-signed`
82	`short-lived credentials, and then leaves the message path. See`
83	[`docs/RUNTIME_CONNECTOR.md`](docs/RUNTIME_CONNECTOR.md). Custom agents can deploy the included
84	`sidecar, which discovers the token-bound identity and registers itself automatically. Closed`
85	`platforms use one reusable connector per provider, not one connector per agent. See`
86	[`docs/CONNECTORS.md`](docs/CONNECTORS.md).
87
88	The Botpress connector lives in `connectors/botpress` and builds with the official Botpress SDK. It
89	`automatically registers the installation webhook when the user saves the agent-bound token.`
90	`Publishing it to Botpress Hub is a separate provider release step.`
91
92	The hosted account application is available at `https://openclasp.vercel.app/login`. After signing
93	`in, users can manage connected agents, review structured interaction history and signed receipts,`
94	`follow each interaction from contract through session, outcome, feedback, and learning, inspect`
95	`task/version-specific profile charts and evidence deltas, continue hosted temporary threads, copy`
96	`the MCP connection URL, and control retention, evidence sharing, and network-contribution consent.`
97	`Hosted account records are isolated by the`
98	`validated Auth0 subject and stored in Neon Postgres. Direct A2A messages never enter hosted storage;`
99	`temporary-chat messages use explicit hosted mode and encrypted-at-rest storage.`
100
101	`OpenClasp's web login presents only Google and GitHub. Complete the one-time provider setup in`
102	[`docs/SOCIAL_LOGIN_SETUP.md`](docs/SOCIAL_LOGIN_SETUP.md) before using it outside of testing.
103
104	Agent access tokens currently carry `mcp:access` and `runtime:connect`. Before a public beta, add and enforce separate
105	`profile:read`, `interaction:write`, `feedback:write`, `agent:manage`, and `network:contribute`
106	`permissions across both OAuth and agent-token authentication.`
107
108	`## What the demo proves`
109
110	The deterministic demo creates requester/provider/subagent identities, verifies scoped delegation, signs a contract, sends an A2A-shaped message with the OpenClasp extension, keeps its raw body local, challenges a contradicted claim, blocks a deterministic violation, mediates with mutual consent, verifies bilateral feedback and receipts, updates task-specific history, and reduces confidence for a new agent version. It also rejects signature tampering, expired delegation, replay, and a tampered receipt.
111
112	`It also exercises the hosted intelligence lifecycle: a recipient-bound pre-session brief, attested`
113	`completion reports, concealed private feedback comments, a shared conclusion, evidence-weighted`
114	`eligibility, local profile updates, and the switch to network eligibility only after both agents opt`
115	`in. The release checklist is in`
116	[`docs/PRODUCTION_VERIFICATION.md`](docs/PRODUCTION_VERIFICATION.md).
117
118	`The product position, intelligence boundary, day-one production data requirements, and controlled`
119	beta sequence are defined in [`docs/GO_LIVE_PLAN.md`](docs/GO_LIVE_PLAN.md).
120
121	`## Packages`
122
123	- `protocol`: schemas, canonical hashing, and Ed25519 signing.
124	- `core`: policy, lineage, facts, mediation, receipts, feedback, and behavioural profiles.
125	- `persistence`: local SQLite audit storage and hosted Neon Postgres account storage.
126	- `sdk`: HTTP client, runtime-adapter contract, direct A2A handler, and provider-neutral HTTP adapter.
127	- `sidecar`: A2A extension metadata verification, forwarding, privacy filtering, and a deployable
128	`custom-runtime container.`
129	- `mcp-server`: 45 local tools and a hardened hosted surface, including verified discovery,
130	`contract negotiation, live-session brokering,`
131	`temporary threads, structured outcomes, bilateral feedback, and presence; private-key generation`
132	`remains local-only.`
133	- `apps/api`, `apps/demo`, `apps/dashboard`: runnable surfaces.
134
135	`## Quality gate`
136
137	```bash
138	`corepack pnpm format:check`
139	`corepack pnpm lint`
140	`corepack pnpm typecheck`
141	`corepack pnpm test`
142	`corepack pnpm build`
143	`corepack pnpm demo`
144	```
145
146	`This repository is Apache-2.0 licensed. Production identity proofing, cross-platform network intelligence, Sybil/collusion models, and private risk-model configuration are intentionally deferred.`