@vorionsys/proof-plane 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +57 -0
- package/LICENSE +190 -0
- package/README.md +492 -0
- package/dist/api/index.d.ts +9 -0
- package/dist/api/index.d.ts.map +1 -0
- package/dist/api/index.js +9 -0
- package/dist/api/index.js.map +1 -0
- package/dist/api/routes.d.ts +88 -0
- package/dist/api/routes.d.ts.map +1 -0
- package/dist/api/routes.js +402 -0
- package/dist/api/routes.js.map +1 -0
- package/dist/events/event-emitter.d.ts +1 -1
- package/dist/events/event-emitter.d.ts.map +1 -1
- package/dist/events/event-emitter.js +4 -2
- package/dist/events/event-emitter.js.map +1 -1
- package/dist/events/event-signatures.d.ts +1 -1
- package/dist/events/event-signatures.d.ts.map +1 -1
- package/dist/events/event-store.d.ts +1 -1
- package/dist/events/event-store.d.ts.map +1 -1
- package/dist/events/hash-chain.d.ts +17 -2
- package/dist/events/hash-chain.d.ts.map +1 -1
- package/dist/events/hash-chain.js +42 -3
- package/dist/events/hash-chain.js.map +1 -1
- package/dist/events/memory-store.d.ts +1 -1
- package/dist/events/memory-store.d.ts.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/proof-plane/logger.d.ts +1 -1
- package/dist/proof-plane/logger.d.ts.map +1 -1
- package/dist/proof-plane/proof-plane.d.ts +1 -1
- package/dist/proof-plane/proof-plane.d.ts.map +1 -1
- package/dist/proof-plane/proof-plane.js +1 -1
- package/dist/proof-plane/proof-plane.js.map +1 -1
- package/openapi.yaml +571 -0
- package/package.json +48 -7
package/README.md
ADDED
|
@@ -0,0 +1,492 @@
|
|
|
1
|
+
# @vorionsys/proof-plane
|
|
2
|
+
|
|
3
|
+
Immutable dual-hash audit trail for AI agent governance decisions.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@vorionsys/proof-plane)
|
|
6
|
+
[](./LICENSE)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
The **Proof Plane** is a core component of the [Vorion](https://github.com/vorionsys/vorion) AI governance stack, built on the **BASIS** (Baseline Authority for Safe & Interoperable Systems) framework. It provides a cryptographically verifiable, immutable audit trail for every decision made by AI agents -- from intent submission through authorization, execution, and trust score changes.
|
|
13
|
+
|
|
14
|
+
Every event in the proof plane is:
|
|
15
|
+
|
|
16
|
+
- **Hash-chained** using dual hashing (SHA-256 + SHA3-256) so that tampering with any record breaks the chain
|
|
17
|
+
- **Digitally signed** (optional Ed25519 signatures) for authenticity and non-repudiation
|
|
18
|
+
- **Correlation-linked** so that complete request traces can be reconstructed from intent to outcome
|
|
19
|
+
|
|
20
|
+
This makes the Proof Plane the **single source of truth** for compliance auditing, incident forensics, and trust calibration in multi-agent AI systems.
|
|
21
|
+
|
|
22
|
+
## Installation
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install @vorionsys/proof-plane
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
> Requires Node.js >= 18.0.0
|
|
29
|
+
|
|
30
|
+
## What is PROOF?
|
|
31
|
+
|
|
32
|
+
PROOF stands for the immutable audit trail at the heart of Vorion's AI governance model. Every time an AI agent submits an intent, receives an authorization decision, begins or completes execution, or has its trust score adjusted, a **proof event** is emitted and appended to the chain.
|
|
33
|
+
|
|
34
|
+
The proof chain answers critical governance questions:
|
|
35
|
+
|
|
36
|
+
- **What did this agent request?** (INTENT_RECEIVED)
|
|
37
|
+
- **Was it authorized, and why?** (DECISION_MADE -- includes trust band, score, and reasoning)
|
|
38
|
+
- **What trust score change occurred?** (TRUST_DELTA)
|
|
39
|
+
- **Did execution succeed or fail?** (EXECUTION_STARTED / EXECUTION_COMPLETED / EXECUTION_FAILED)
|
|
40
|
+
- **Has anyone tampered with this record?** (Chain and signature verification)
|
|
41
|
+
|
|
42
|
+
## How Dual-Hash Works
|
|
43
|
+
|
|
44
|
+
Each proof event carries two independent hashes for defense-in-depth tamper detection:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
Event N
|
|
48
|
+
+--------------------------------------------+
|
|
49
|
+
| eventId, eventType, correlationId, |
|
|
50
|
+
| agentId, payload, occurredAt, signedBy |
|
|
51
|
+
| previousHash -----> Event N-1 eventHash |
|
|
52
|
+
+--------------------------------------------+
|
|
53
|
+
| eventHash = SHA-256(canonical content) | <-- primary chain hash
|
|
54
|
+
| eventHash3 = SHA3-256(canonical content) | <-- integrity anchor
|
|
55
|
+
+--------------------------------------------+
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
1. **SHA-256 content hash (`eventHash`)** -- The primary chain hash. Each event's `previousHash` field points to the preceding event's `eventHash`, forming a linked chain identical in principle to a blockchain.
|
|
59
|
+
|
|
60
|
+
2. **SHA3-256 integrity anchor (`eventHash3`)** -- A secondary hash computed with a different algorithm family (Keccak-based SHA-3). Even if a collision or weakness is discovered in SHA-256, the SHA3-256 anchor provides an independent integrity check.
|
|
61
|
+
|
|
62
|
+
Content is **canonically serialized** (sorted keys, deterministic JSON) before hashing, guaranteeing that the same logical event always produces the same hash regardless of property insertion order.
|
|
63
|
+
|
|
64
|
+
**Verification** walks the chain from genesis to tip, recomputing both hashes for every event and confirming that each `previousHash` matches the prior event's `eventHash`. A single mismatch pinpoints the exact tampered record.
|
|
65
|
+
|
|
66
|
+
## Quick Start
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
import {
|
|
70
|
+
createProofPlane,
|
|
71
|
+
createInMemoryEventStore,
|
|
72
|
+
} from '@vorionsys/proof-plane';
|
|
73
|
+
|
|
74
|
+
// 1. Create an event store (in-memory for dev; use Postgres/Supabase in production)
|
|
75
|
+
const store = createInMemoryEventStore();
|
|
76
|
+
|
|
77
|
+
// 2. Create the proof plane
|
|
78
|
+
const proofPlane = createProofPlane({
|
|
79
|
+
signedBy: 'my-service',
|
|
80
|
+
store,
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
// 3. Log governance events
|
|
84
|
+
const intentResult = await proofPlane.logIntentReceived(intent);
|
|
85
|
+
const decisionResult = await proofPlane.logDecisionMade(decision);
|
|
86
|
+
|
|
87
|
+
// 4. Retrieve a full request trace by correlation ID
|
|
88
|
+
const trace = await proofPlane.getTrace(correlationId);
|
|
89
|
+
// Returns: [INTENT_RECEIVED, DECISION_MADE, ...] in chronological order
|
|
90
|
+
|
|
91
|
+
// 5. Verify chain integrity
|
|
92
|
+
const verification = await proofPlane.verifyChain();
|
|
93
|
+
console.log(verification.valid); // true
|
|
94
|
+
console.log(verification.verifiedCount); // number of events checked
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Usage Examples
|
|
98
|
+
|
|
99
|
+
### Creating and Chaining Proof Events
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
import { createProofPlane } from '@vorionsys/proof-plane';
|
|
103
|
+
|
|
104
|
+
const proofPlane = createProofPlane({ signedBy: 'auth-service' });
|
|
105
|
+
|
|
106
|
+
// Log an intent (first event becomes the genesis -- previousHash is null)
|
|
107
|
+
const r1 = await proofPlane.logIntentReceived(intent);
|
|
108
|
+
console.log(r1.isGenesis); // true
|
|
109
|
+
console.log(r1.previousHash); // null
|
|
110
|
+
|
|
111
|
+
// Log a decision (chains to previous event)
|
|
112
|
+
const r2 = await proofPlane.logDecisionMade(decision);
|
|
113
|
+
console.log(r2.isGenesis); // false
|
|
114
|
+
console.log(r2.previousHash); // r1.event.eventHash
|
|
115
|
+
|
|
116
|
+
// Log execution lifecycle
|
|
117
|
+
await proofPlane.logExecutionStarted(executionId, actionId, decisionId, adapterId, agentId, correlationId);
|
|
118
|
+
await proofPlane.logExecutionCompleted(executionId, actionId, durationMs, outputHash, agentId, correlationId);
|
|
119
|
+
|
|
120
|
+
// Log trust score changes
|
|
121
|
+
await proofPlane.logTrustDelta(agentId, previousProfile, newProfile, 'Positive behavioral evidence');
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Verifying Chain Integrity
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
// Verify the entire chain
|
|
128
|
+
const result = await proofPlane.verifyChain();
|
|
129
|
+
// {
|
|
130
|
+
// valid: true,
|
|
131
|
+
// verifiedCount: 42,
|
|
132
|
+
// totalEvents: 42,
|
|
133
|
+
// firstEventId: '...',
|
|
134
|
+
// lastEventId: '...'
|
|
135
|
+
// }
|
|
136
|
+
|
|
137
|
+
// Verify a specific correlation chain
|
|
138
|
+
const traceResult = await proofPlane.verifyCorrelationChain(correlationId);
|
|
139
|
+
|
|
140
|
+
// Low-level: verify individual events
|
|
141
|
+
import { verifyEventHash, verifyChainWithDetails } from '@vorionsys/proof-plane';
|
|
142
|
+
|
|
143
|
+
const hashOk = await verifyEventHash(event); // recompute + compare SHA-256
|
|
144
|
+
const details = await verifyChainWithDetails(events); // full chain walk
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Querying Audit Records
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
// Get trace for a specific request
|
|
151
|
+
const trace = await proofPlane.getTrace(correlationId);
|
|
152
|
+
|
|
153
|
+
// Get all events for an agent
|
|
154
|
+
const history = await proofPlane.getAgentHistory(agentId);
|
|
155
|
+
|
|
156
|
+
// Query with filters and pagination
|
|
157
|
+
const result = await proofPlane.queryEvents(
|
|
158
|
+
{ agentId, eventTypes: [ProofEventType.DECISION_MADE] },
|
|
159
|
+
{ limit: 50, offset: 0, order: 'desc' }
|
|
160
|
+
);
|
|
161
|
+
console.log(result.events);
|
|
162
|
+
console.log(result.totalCount);
|
|
163
|
+
console.log(result.hasMore);
|
|
164
|
+
|
|
165
|
+
// Get statistics
|
|
166
|
+
const stats = await proofPlane.getStats();
|
|
167
|
+
// { totalEvents, byType: { INTENT_RECEIVED: 10, ... }, byAgent: { ... } }
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Ed25519 Digital Signatures
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
import {
|
|
174
|
+
createProofPlane,
|
|
175
|
+
generateSigningKeyPair,
|
|
176
|
+
createSigningService,
|
|
177
|
+
} from '@vorionsys/proof-plane';
|
|
178
|
+
|
|
179
|
+
// Generate a key pair
|
|
180
|
+
const keyPair = await generateSigningKeyPair('auth-service');
|
|
181
|
+
|
|
182
|
+
// Create a signing service
|
|
183
|
+
const signingService = createSigningService({
|
|
184
|
+
serviceId: 'auth-service',
|
|
185
|
+
privateKey: keyPair.privateKey,
|
|
186
|
+
keyId: keyPair.keyId,
|
|
187
|
+
trustedKeys: [{ publicKey: keyPair.publicKey, keyId: keyPair.keyId, owner: 'auth-service' }],
|
|
188
|
+
});
|
|
189
|
+
|
|
190
|
+
// Create proof plane with signing enabled
|
|
191
|
+
const proofPlane = createProofPlane({
|
|
192
|
+
signedBy: 'auth-service',
|
|
193
|
+
enableSignatures: true,
|
|
194
|
+
signingService,
|
|
195
|
+
});
|
|
196
|
+
|
|
197
|
+
// Events are now automatically signed
|
|
198
|
+
const result = await proofPlane.logIntentReceived(intent);
|
|
199
|
+
console.log(result.event.signature); // base64-encoded Ed25519 signature
|
|
200
|
+
|
|
201
|
+
// Verify signatures
|
|
202
|
+
const sigResult = await proofPlane.verifyEventSignature(result.event);
|
|
203
|
+
console.log(sigResult.valid); // true
|
|
204
|
+
|
|
205
|
+
// Verify both chain AND signatures in one call
|
|
206
|
+
const fullVerification = await proofPlane.verifyChainAndSignatures();
|
|
207
|
+
console.log(fullVerification.fullyVerified); // true
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
### Real-Time Event Subscriptions
|
|
211
|
+
|
|
212
|
+
```typescript
|
|
213
|
+
// Subscribe to all events
|
|
214
|
+
const unsubscribe = proofPlane.subscribe((event) => {
|
|
215
|
+
console.log(`[${event.eventType}] ${event.correlationId}`);
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
// Subscribe to specific event types
|
|
219
|
+
proofPlane.subscribeToType(ProofEventType.DECISION_MADE, (event) => {
|
|
220
|
+
console.log('Decision:', event.payload);
|
|
221
|
+
});
|
|
222
|
+
|
|
223
|
+
// Unsubscribe when done
|
|
224
|
+
unsubscribe();
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### Custom Event Stores
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
import type { ProofEventStore, EventQueryOptions } from '@vorionsys/proof-plane';
|
|
231
|
+
|
|
232
|
+
class PostgresEventStore implements ProofEventStore {
|
|
233
|
+
async append(event) { /* INSERT INTO proof_events ... */ }
|
|
234
|
+
async get(eventId) { /* SELECT ... WHERE event_id = $1 */ }
|
|
235
|
+
async getLatest() { /* SELECT ... ORDER BY occurred_at DESC LIMIT 1 */ }
|
|
236
|
+
async getLatestHash() { /* ... */ }
|
|
237
|
+
async query(filter?, options?) { /* ... */ }
|
|
238
|
+
async getByCorrelationId(id, options?) { /* ... */ }
|
|
239
|
+
async getByAgentId(id, options?) { /* ... */ }
|
|
240
|
+
async getByTimeRange(from, to, options?) { /* ... */ }
|
|
241
|
+
async getByType(type, options?) { /* ... */ }
|
|
242
|
+
async getSummaries(filter?, options?) { /* ... */ }
|
|
243
|
+
async getChain(fromEventId?, limit?) { /* ... */ }
|
|
244
|
+
async count(filter?) { /* ... */ }
|
|
245
|
+
async getStats() { /* ... */ }
|
|
246
|
+
async exists(eventId) { /* ... */ }
|
|
247
|
+
async clear() { /* ... */ }
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
const proofPlane = createProofPlane({
|
|
251
|
+
store: new PostgresEventStore(pool),
|
|
252
|
+
signedBy: 'my-service',
|
|
253
|
+
});
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### REST API Routes
|
|
257
|
+
|
|
258
|
+
```typescript
|
|
259
|
+
// Fastify
|
|
260
|
+
import Fastify from 'fastify';
|
|
261
|
+
import { createProofPlane } from '@vorionsys/proof-plane';
|
|
262
|
+
import { registerProofRoutes } from '@vorionsys/proof-plane/api';
|
|
263
|
+
|
|
264
|
+
const app = Fastify();
|
|
265
|
+
const proofPlane = createProofPlane({ signedBy: 'api-service' });
|
|
266
|
+
|
|
267
|
+
await app.register(async (instance) => {
|
|
268
|
+
registerProofRoutes(instance, proofPlane);
|
|
269
|
+
}, { prefix: '/v1' });
|
|
270
|
+
|
|
271
|
+
// Express
|
|
272
|
+
import express from 'express';
|
|
273
|
+
import { createProofExpressRouter } from '@vorionsys/proof-plane/api';
|
|
274
|
+
|
|
275
|
+
const app = express();
|
|
276
|
+
const { handler } = createProofExpressRouter(proofPlane);
|
|
277
|
+
app.use('/v1', handler);
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
**Available endpoints:**
|
|
281
|
+
|
|
282
|
+
| Method | Path | Description |
|
|
283
|
+
|--------|------|-------------|
|
|
284
|
+
| `POST` | `/proof` | Submit a new proof event |
|
|
285
|
+
| `GET` | `/proof/:id` | Retrieve a proof event by ID |
|
|
286
|
+
| `GET` | `/proof/verify/:id` | Verify a single event (hash + signature) |
|
|
287
|
+
| `GET` | `/proof/chain/:correlationId` | Get event trace by correlation ID |
|
|
288
|
+
| `POST` | `/proof/chain/verify` | Verify chain integrity |
|
|
289
|
+
| `GET` | `/proof/stats` | Get event statistics |
|
|
290
|
+
| `GET` | `/proof/latest` | Get the most recent event |
|
|
291
|
+
|
|
292
|
+
See [`openapi.yaml`](./openapi.yaml) for the full OpenAPI 3.1 specification.
|
|
293
|
+
|
|
294
|
+
## Subpath Imports
|
|
295
|
+
|
|
296
|
+
The package exposes granular entry points for tree-shaking:
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
// Main entry -- everything
|
|
300
|
+
import { createProofPlane, sha256, InMemoryEventStore } from '@vorionsys/proof-plane';
|
|
301
|
+
|
|
302
|
+
// Events module -- stores, emitter, hash chain, signatures
|
|
303
|
+
import { InMemoryEventStore, createEventEmitter } from '@vorionsys/proof-plane/events';
|
|
304
|
+
|
|
305
|
+
// Proof Plane module -- ProofPlane class and logger
|
|
306
|
+
import { ProofPlane, createProofPlaneLogger } from '@vorionsys/proof-plane/proof-plane';
|
|
307
|
+
|
|
308
|
+
// API module -- REST route handlers
|
|
309
|
+
import { createProofRoutes, registerProofRoutes } from '@vorionsys/proof-plane/api';
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
## API Reference
|
|
313
|
+
|
|
314
|
+
### Core
|
|
315
|
+
|
|
316
|
+
| Export | Type | Description |
|
|
317
|
+
|--------|------|-------------|
|
|
318
|
+
| `ProofPlane` | class | Main proof plane class |
|
|
319
|
+
| `createProofPlane(config?)` | function | Factory for ProofPlane instances |
|
|
320
|
+
| `ProofPlaneConfig` | type | Configuration options (store, signedBy, signatures, shadow mode, hooks) |
|
|
321
|
+
|
|
322
|
+
### Event Logging (ProofPlane methods)
|
|
323
|
+
|
|
324
|
+
| Method | Description |
|
|
325
|
+
|--------|-------------|
|
|
326
|
+
| `logIntentReceived(intent, correlationId?)` | Log an intent submission |
|
|
327
|
+
| `logDecisionMade(decision, correlationId?)` | Log an authorization decision |
|
|
328
|
+
| `logTrustDelta(agentId, prevProfile, newProfile, reason, correlationId?)` | Log a trust score change |
|
|
329
|
+
| `logExecutionStarted(executionId, actionId, decisionId, adapterId, agentId, correlationId)` | Log execution start |
|
|
330
|
+
| `logExecutionCompleted(executionId, actionId, durationMs, outputHash, agentId, correlationId, status?)` | Log execution completion |
|
|
331
|
+
| `logExecutionFailed(executionId, actionId, error, durationMs, retryable, agentId, correlationId)` | Log execution failure |
|
|
332
|
+
| `logEvent(eventType, correlationId, payload, agentId?)` | Log a generic event |
|
|
333
|
+
|
|
334
|
+
### Querying (ProofPlane methods)
|
|
335
|
+
|
|
336
|
+
| Method | Description |
|
|
337
|
+
|--------|-------------|
|
|
338
|
+
| `getEvent(eventId)` | Get event by ID |
|
|
339
|
+
| `getLatestEvent()` | Get most recent event |
|
|
340
|
+
| `getTrace(correlationId)` | Get all events for a correlation ID |
|
|
341
|
+
| `getAgentHistory(agentId, options?)` | Get all events for an agent |
|
|
342
|
+
| `getEventsByType(eventType, options?)` | Get events by type |
|
|
343
|
+
| `queryEvents(filter?, options?)` | Query with filters and pagination |
|
|
344
|
+
| `getEventCount(filter?)` | Count matching events |
|
|
345
|
+
| `getStats()` | Get aggregate statistics |
|
|
346
|
+
|
|
347
|
+
### Verification (ProofPlane methods)
|
|
348
|
+
|
|
349
|
+
| Method | Description |
|
|
350
|
+
|--------|-------------|
|
|
351
|
+
| `verifyChain(fromEventId?, limit?)` | Verify hash chain integrity |
|
|
352
|
+
| `verifyCorrelationChain(correlationId)` | Verify chain for a correlation ID |
|
|
353
|
+
| `verifyEventSignature(event)` | Verify Ed25519 signature on an event |
|
|
354
|
+
| `verifySignatures(events)` | Batch signature verification |
|
|
355
|
+
| `verifyChainAndSignatures(fromEventId?, limit?)` | Verify both chain and signatures |
|
|
356
|
+
|
|
357
|
+
### Hash Chain Utilities
|
|
358
|
+
|
|
359
|
+
| Export | Description |
|
|
360
|
+
|--------|-------------|
|
|
361
|
+
| `sha256(data)` | Compute SHA-256 hash |
|
|
362
|
+
| `sha3_256(data)` | Compute SHA3-256 hash |
|
|
363
|
+
| `computeEventHash(event)` | Compute SHA-256 event hash |
|
|
364
|
+
| `computeEventHash3(event)` | Compute SHA3-256 event hash |
|
|
365
|
+
| `verifyEventHash(event)` | Verify event SHA-256 hash |
|
|
366
|
+
| `verifyEventHash3(event)` | Verify event SHA3-256 hash |
|
|
367
|
+
| `verifyChainLink(event, previousEvent)` | Verify a single chain link |
|
|
368
|
+
| `verifyChain(events)` | Verify a chain of events |
|
|
369
|
+
| `verifyChainWithDetails(events)` | Verify chain with detailed results |
|
|
370
|
+
| `getGenesisHash()` | Get the genesis hash (null) |
|
|
371
|
+
|
|
372
|
+
### Event Signatures
|
|
373
|
+
|
|
374
|
+
| Export | Description |
|
|
375
|
+
|--------|-------------|
|
|
376
|
+
| `generateSigningKeyPair(owner)` | Generate Ed25519 key pair |
|
|
377
|
+
| `signEvent(event, privateKey, signedBy)` | Sign an event |
|
|
378
|
+
| `verifyEventSignature(event, publicKey)` | Verify an event signature |
|
|
379
|
+
| `verifyEventSignatures(events, signingService)` | Batch verification |
|
|
380
|
+
| `EventSigningService` | class | Key management and signing service |
|
|
381
|
+
| `createSigningService(config)` | Factory for EventSigningService |
|
|
382
|
+
|
|
383
|
+
### Event Store
|
|
384
|
+
|
|
385
|
+
| Export | Description |
|
|
386
|
+
|--------|-------------|
|
|
387
|
+
| `ProofEventStore` | interface | Abstract storage interface |
|
|
388
|
+
| `InMemoryEventStore` | class | Reference in-memory implementation |
|
|
389
|
+
| `createInMemoryEventStore()` | Factory for InMemoryEventStore |
|
|
390
|
+
| `EventStoreError` | class | Storage error type |
|
|
391
|
+
| `EventStoreErrorCode` | enum | Error codes (DUPLICATE_EVENT, NOT_FOUND, etc.) |
|
|
392
|
+
|
|
393
|
+
### Event Emitter
|
|
394
|
+
|
|
395
|
+
| Export | Description |
|
|
396
|
+
|--------|-------------|
|
|
397
|
+
| `ProofEventEmitter` | class | Event creation with hash chaining |
|
|
398
|
+
| `createEventEmitter(config)` | Factory for ProofEventEmitter |
|
|
399
|
+
|
|
400
|
+
### Logger (A3I Bridge)
|
|
401
|
+
|
|
402
|
+
| Export | Description |
|
|
403
|
+
|--------|-------------|
|
|
404
|
+
| `ProofPlaneLoggerImpl` | class | Bridges A3I authorization engine to proof plane |
|
|
405
|
+
| `createProofPlaneLogger(config)` | Factory for the logger |
|
|
406
|
+
| `noopProofPlaneLogger` | No-op logger when proof plane is not connected |
|
|
407
|
+
|
|
408
|
+
### API Routes
|
|
409
|
+
|
|
410
|
+
| Export | Description |
|
|
411
|
+
|--------|-------------|
|
|
412
|
+
| `createProofRoutes(proofPlane)` | Create route definitions |
|
|
413
|
+
| `registerProofRoutes(fastify, proofPlane)` | Register routes on a Fastify instance |
|
|
414
|
+
| `createProofExpressRouter(proofPlane)` | Create an Express middleware handler |
|
|
415
|
+
|
|
416
|
+
### Key Types
|
|
417
|
+
|
|
418
|
+
```typescript
|
|
419
|
+
import type {
|
|
420
|
+
ProofPlaneConfig,
|
|
421
|
+
ProofPlaneLogger,
|
|
422
|
+
ProofPlaneLoggerConfig,
|
|
423
|
+
ProofEventStore,
|
|
424
|
+
EventQueryOptions,
|
|
425
|
+
EventQueryResult,
|
|
426
|
+
EventStats,
|
|
427
|
+
EventEmitterConfig,
|
|
428
|
+
EventListener,
|
|
429
|
+
EmitResult,
|
|
430
|
+
BatchEmitOptions,
|
|
431
|
+
BatchEmitResult,
|
|
432
|
+
ChainVerificationResult,
|
|
433
|
+
SigningKeyPair,
|
|
434
|
+
PublicKey,
|
|
435
|
+
SignatureVerificationResult,
|
|
436
|
+
SigningServiceConfig,
|
|
437
|
+
BatchVerificationResult,
|
|
438
|
+
ProofRoute,
|
|
439
|
+
} from '@vorionsys/proof-plane';
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
## Shadow Mode (T0 Sandbox)
|
|
443
|
+
|
|
444
|
+
The proof plane supports **shadow mode** for sandbox and testnet environments. Events emitted in shadow mode are tagged and can be filtered separately, enabling safe experimentation with T0_SANDBOX agents whose events require human-in-the-loop (HITL) verification before counting toward production trust scores.
|
|
445
|
+
|
|
446
|
+
```typescript
|
|
447
|
+
const sandboxPlane = createProofPlane({
|
|
448
|
+
signedBy: 'sandbox-service',
|
|
449
|
+
shadowMode: 'shadow',
|
|
450
|
+
environment: 'testnet',
|
|
451
|
+
});
|
|
452
|
+
|
|
453
|
+
// Query unverified shadow events
|
|
454
|
+
const pending = await sandboxPlane.getUnverifiedShadowEvents(agentId);
|
|
455
|
+
|
|
456
|
+
// Mark a shadow event as HITL-verified
|
|
457
|
+
await sandboxPlane.verifyShadowEvent(eventId, verificationId, 'human-reviewer', true);
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
## Architecture
|
|
461
|
+
|
|
462
|
+
The proof plane sits at the foundation of the Vorion governance stack:
|
|
463
|
+
|
|
464
|
+
```
|
|
465
|
+
+----------------------------+
|
|
466
|
+
| Application Layer |
|
|
467
|
+
+----------------------------+
|
|
468
|
+
| A3I Authorization | <-- emits intents & decisions
|
|
469
|
+
+----------------------------+
|
|
470
|
+
| PROOF PLANE | <-- this package
|
|
471
|
+
| (dual-hash chain + |
|
|
472
|
+
| Ed25519 signatures) |
|
|
473
|
+
+----------------------------+
|
|
474
|
+
| Event Store | <-- pluggable (memory, Postgres, etc.)
|
|
475
|
+
+----------------------------+
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
## License
|
|
479
|
+
|
|
480
|
+
[Apache-2.0](./LICENSE)
|
|
481
|
+
|
|
482
|
+
## Repository
|
|
483
|
+
|
|
484
|
+
This package is part of the [Vorion](https://github.com/vorionsys/vorion) monorepo.
|
|
485
|
+
|
|
486
|
+
```
|
|
487
|
+
vorion/
|
|
488
|
+
packages/
|
|
489
|
+
proof-plane/ <-- you are here
|
|
490
|
+
contracts/
|
|
491
|
+
...
|
|
492
|
+
```
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Proof Plane API Module
|
|
3
|
+
*
|
|
4
|
+
* Provides REST API routes for the Vorion audit system.
|
|
5
|
+
*
|
|
6
|
+
* @packageDocumentation
|
|
7
|
+
*/
|
|
8
|
+
export { createProofRoutes, registerProofRoutes, createProofExpressRouter, type ProofRoute, } from './routes.js';
|
|
9
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,GAEzB,MAAM,aAAa,CAAC"}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Proof Plane API Routes
|
|
3
|
+
*
|
|
4
|
+
* Provides REST API endpoints for the Vorion audit system:
|
|
5
|
+
* - POST /proof - Submit a proof event
|
|
6
|
+
* - GET /proof/:id - Retrieve proof event by ID
|
|
7
|
+
* - GET /proof/verify/:id - Verify a single proof event
|
|
8
|
+
* - GET /proof/chain/:correlationId - Get event trace by correlation ID
|
|
9
|
+
* - POST /proof/chain/verify - Verify chain integrity
|
|
10
|
+
*
|
|
11
|
+
* @packageDocumentation
|
|
12
|
+
*/
|
|
13
|
+
import { z } from 'zod';
|
|
14
|
+
import type { ProofPlane } from '../proof-plane/proof-plane.js';
|
|
15
|
+
/**
|
|
16
|
+
* Route handler context - generic interface for Fastify-like frameworks
|
|
17
|
+
*/
|
|
18
|
+
interface RouteContext {
|
|
19
|
+
request: {
|
|
20
|
+
params?: unknown;
|
|
21
|
+
query?: unknown;
|
|
22
|
+
body?: unknown;
|
|
23
|
+
id?: string;
|
|
24
|
+
};
|
|
25
|
+
reply: {
|
|
26
|
+
status(code: number): RouteContext['reply'];
|
|
27
|
+
send(data: unknown): void;
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Route definition for registration
|
|
32
|
+
*/
|
|
33
|
+
export interface ProofRoute {
|
|
34
|
+
method: 'GET' | 'POST' | 'PUT' | 'DELETE';
|
|
35
|
+
path: string;
|
|
36
|
+
handler: (ctx: RouteContext, proofPlane: ProofPlane) => Promise<void>;
|
|
37
|
+
schema?: {
|
|
38
|
+
params?: z.ZodSchema;
|
|
39
|
+
query?: z.ZodSchema;
|
|
40
|
+
body?: z.ZodSchema;
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Define all proof API routes
|
|
45
|
+
*/
|
|
46
|
+
export declare function createProofRoutes(proofPlane: ProofPlane): ProofRoute[];
|
|
47
|
+
/**
|
|
48
|
+
* Fastify plugin registration helper
|
|
49
|
+
*
|
|
50
|
+
* Usage with Fastify:
|
|
51
|
+
* ```typescript
|
|
52
|
+
* import Fastify from 'fastify';
|
|
53
|
+
* import { createProofPlane } from '@vorionsys/proof-plane';
|
|
54
|
+
* import { registerProofRoutes } from '@vorionsys/proof-plane/api';
|
|
55
|
+
*
|
|
56
|
+
* const app = Fastify();
|
|
57
|
+
* const proofPlane = createProofPlane({ signedBy: 'my-service' });
|
|
58
|
+
*
|
|
59
|
+
* await app.register(async (instance) => {
|
|
60
|
+
* registerProofRoutes(instance, proofPlane);
|
|
61
|
+
* }, { prefix: '/v1' });
|
|
62
|
+
* ```
|
|
63
|
+
*/
|
|
64
|
+
export declare function registerProofRoutes(fastify: {
|
|
65
|
+
get: (path: string, handler: (request: any, reply: any) => Promise<void>) => void;
|
|
66
|
+
post: (path: string, handler: (request: any, reply: any) => Promise<void>) => void;
|
|
67
|
+
}, proofPlane: ProofPlane): void;
|
|
68
|
+
/**
|
|
69
|
+
* Express middleware adapter
|
|
70
|
+
*
|
|
71
|
+
* Usage with Express:
|
|
72
|
+
* ```typescript
|
|
73
|
+
* import express from 'express';
|
|
74
|
+
* import { createProofPlane } from '@vorionsys/proof-plane';
|
|
75
|
+
* import { createProofExpressRouter } from '@vorionsys/proof-plane/api';
|
|
76
|
+
*
|
|
77
|
+
* const app = express();
|
|
78
|
+
* const proofPlane = createProofPlane({ signedBy: 'my-service' });
|
|
79
|
+
*
|
|
80
|
+
* app.use('/v1', createProofExpressRouter(proofPlane));
|
|
81
|
+
* ```
|
|
82
|
+
*/
|
|
83
|
+
export declare function createProofExpressRouter(proofPlane: ProofPlane): {
|
|
84
|
+
routes: ProofRoute[];
|
|
85
|
+
handler: (req: any, res: any, next: any) => Promise<void>;
|
|
86
|
+
};
|
|
87
|
+
export {};
|
|
88
|
+
//# sourceMappingURL=routes.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAiEhE;;GAEG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE;QACP,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,CAAC;IACF,KAAK,EAAE;QACL,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;KAC3B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;QACrB,KAAK,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;QACpB,IAAI,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;KACpB,CAAC;CACH;AA4BD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,EAAE,CA0PtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IACP,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IAClF,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;CACpF,EACD,UAAU,EAAE,UAAU,GACrB,IAAI,CA0CN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG;IAChE,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D,CA+CA"}
|