@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.
Files changed (37) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/LICENSE +190 -0
  3. package/README.md +492 -0
  4. package/dist/api/index.d.ts +9 -0
  5. package/dist/api/index.d.ts.map +1 -0
  6. package/dist/api/index.js +9 -0
  7. package/dist/api/index.js.map +1 -0
  8. package/dist/api/routes.d.ts +88 -0
  9. package/dist/api/routes.d.ts.map +1 -0
  10. package/dist/api/routes.js +402 -0
  11. package/dist/api/routes.js.map +1 -0
  12. package/dist/events/event-emitter.d.ts +1 -1
  13. package/dist/events/event-emitter.d.ts.map +1 -1
  14. package/dist/events/event-emitter.js +4 -2
  15. package/dist/events/event-emitter.js.map +1 -1
  16. package/dist/events/event-signatures.d.ts +1 -1
  17. package/dist/events/event-signatures.d.ts.map +1 -1
  18. package/dist/events/event-store.d.ts +1 -1
  19. package/dist/events/event-store.d.ts.map +1 -1
  20. package/dist/events/hash-chain.d.ts +17 -2
  21. package/dist/events/hash-chain.d.ts.map +1 -1
  22. package/dist/events/hash-chain.js +42 -3
  23. package/dist/events/hash-chain.js.map +1 -1
  24. package/dist/events/memory-store.d.ts +1 -1
  25. package/dist/events/memory-store.d.ts.map +1 -1
  26. package/dist/index.d.ts +2 -1
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +3 -1
  29. package/dist/index.js.map +1 -1
  30. package/dist/proof-plane/logger.d.ts +1 -1
  31. package/dist/proof-plane/logger.d.ts.map +1 -1
  32. package/dist/proof-plane/proof-plane.d.ts +1 -1
  33. package/dist/proof-plane/proof-plane.d.ts.map +1 -1
  34. package/dist/proof-plane/proof-plane.js +1 -1
  35. package/dist/proof-plane/proof-plane.js.map +1 -1
  36. package/openapi.yaml +571 -0
  37. 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
+ [![npm](https://img.shields.io/npm/v/@vorionsys/proof-plane)](https://www.npmjs.com/package/@vorionsys/proof-plane)
6
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./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,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, } from './routes.js';
9
+ //# sourceMappingURL=index.js.map
@@ -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"}