@7h3/protocol 0.1.2 → 0.4.0

package/src/wsBinding.ts

@@ -0,0 +1,100 @@
+import {
+  signEnvelopeEd25519, verifyEnvelopeEd25519,
+  createEnvelope, validateEnvelope,
+  generateEd25519KeypairBase64Url, type ProtocolEnvelope
+} from './protocol'
+import type { KeyRegistry } from './keyRegistry'
+
+export { type KeyRegistry, generateEd25519KeypairBase64Url }
+
+// Minimal WebSocket interface (works with browser WebSocket, ws library, etc.)
+export interface WebSocketLike {
+  send(data: string): void
+  addEventListener(event: 'message', handler: (e: { data: string | Buffer }) => void): void
+  addEventListener(event: 'close', handler: () => void): void
+  removeEventListener(event: string, handler: (...args: unknown[]) => void): void
+  readyState?: number
+}
+
+export interface WsBindingOptions {
+  privateKey: string
+  sender: string
+  recipient?: string
+  keyRegistry: KeyRegistry   // to look up peer public keys by sender ID
+  ttlMs?: number             // per-frame TTL, default 30_000
+  onVerifyFail?: (err: Error, rawData: string) => void
+}
+
+export interface ProtectedWebSocket {
+  // Send a payload — automatically signs it
+  send(payload: unknown): Promise<void>
+  // Register handler for verified incoming messages
+  onMessage(handler: (payload: unknown, envelope: ProtocolEnvelope) => void): void
+  // Register handler for verify failures (optional)
+  onVerifyFail(handler: (err: Error, rawData: string) => void): void
+  // Sequence number of last sent message
+  readonly seq: number
+}
+
+export function wrapWebSocket(ws: WebSocketLike, opts: WsBindingOptions): ProtectedWebSocket {
+  let seq = 0
+  const messageHandlers: Array<(payload: unknown, envelope: ProtocolEnvelope) => void> = []
+  const failHandlers: Array<(err: Error, rawData: string) => void> = []
+
+  function fireVerifyFail(err: Error, raw: string) {
+    opts.onVerifyFail?.(err, raw)
+    for (const h of failHandlers) h(err, raw)
+  }
+
+  // Listen for incoming frames
+  const messageListener = async (e: { data: string | Buffer }) => {
+    const raw = typeof e.data === 'string' ? e.data : e.data.toString('utf8')
+    let envelope: ProtocolEnvelope
+    try { envelope = JSON.parse(raw) as ProtocolEnvelope }
+    catch (err) { fireVerifyFail(new Error('malformed frame'), raw); return }
+
+    const sender = envelope?.header?.sender
+    if (!sender) { fireVerifyFail(new Error('missing sender'), raw); return }
+
+    const publicKey = await opts.keyRegistry.getPublicKey(sender)
+    if (!publicKey) { fireVerifyFail(new Error(`unknown sender: ${sender}`), raw); return }
+
+    const valid = await verifyEnvelopeEd25519(envelope, publicKey).catch(() => false)
+    if (!valid) { fireVerifyFail(new Error('invalid signature'), raw); return }
+
+    const diags = validateEnvelope(envelope)
+    if (diags.some(d => d.level === 'error')) {
+      fireVerifyFail(new Error(`envelope invalid: ${diags.map(d => d.message).join('; ')}`), raw)
+      return
+    }
+
+    let payload: unknown = envelope.body.content
+    try { payload = JSON.parse(envelope.body.content) } catch { /* keep as string */ }
+    for (const h of messageHandlers) h(payload, envelope)
+  }
+
+  ws.addEventListener('message', messageListener as any)
+  ws.addEventListener('close', () => {
+    ws.removeEventListener('message', messageListener as any)
+  })
+
+  return {
+    get seq() { return seq },
+    async send(payload: unknown): Promise<void> {
+      const content = typeof payload === 'string' ? payload : JSON.stringify(payload)
+      const envelope = createEnvelope({
+        sender: opts.sender,
+        recipient: opts.recipient,
+        ttlMs: opts.ttlMs ?? 30_000,
+        intent: 'TASK',
+        content,
+      })
+      // embed sequence number in correlationId to help downstream ordering
+      ;(envelope.body as any).correlationId = String(++seq)
+      const signed = await signEnvelopeEd25519(envelope, opts.privateKey)
+      ws.send(JSON.stringify(signed))
+    },
+    onMessage(handler) { messageHandlers.push(handler) },
+    onVerifyFail(handler) { failHandlers.push(handler) },
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023", "DOM"],
+    "types": ["node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": false
+  },
+  "include": ["src/**/*.ts", "scripts/**/*.ts"]
+}

package/tsconfig.lib.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "outDir": "./dist/protocol",
+    "rootDir": "./src",
+    "stripInternal": true,
+    "strict": true,
+    "types": ["node"],
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.bench.ts"]
+}

package/vite.lib.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: 'src/index.ts',
+      formats: ['es'],
+      fileName: () => 'index.js',
+    },
+    outDir: 'dist/protocol',
+    emptyOutDir: false,
+    rollupOptions: {
+      external: [],
+    },
+  },
+})

package/agentAdapter.d.ts

@@ -1,26 +0,0 @@
-import { type AgentReceiveResult, type AgentSessionConfig } from './protocolAgent';
-import { type IntentKind, type ProtocolEnvelope } from './protocol';
-import { type WireEnvelope, type WireFormat } from './protocolTransport';
-export interface AipAdapterConfig extends AgentSessionConfig {
-    wireFormat?: WireFormat;
-}
-export declare class AipAgentAdapter {
-    private readonly session;
-    private readonly wireFormat;
-    constructor(config: AipAdapterConfig);
-    toRaw(envelope: ProtocolEnvelope): WireEnvelope;
-    createRawIntent(input: {
-        recipient?: string;
-        intent: IntentKind;
-        content: string;
-        capability?: string;
-        correlationId?: string;
-        ttlMs?: number;
-        messageId?: string;
-        nonce?: string;
-        nowMs?: number;
-    }): Promise<WireEnvelope>;
-    receiveRaw(raw: WireEnvelope, nowMs?: number): Promise<AgentReceiveResult>;
-    handleRaw(raw: WireEnvelope, emitResponseRaw: (rawResponse: WireEnvelope, responseEnvelope: ProtocolEnvelope) => void | Promise<void>, nowMs?: number): Promise<AgentReceiveResult>;
-}
-export declare function createAipAgentAdapter(config: AipAdapterConfig): AipAgentAdapter;

package/conformanceVectors.d.ts

@@ -1,20 +0,0 @@
-import type { ProtocolEnvelope } from './protocol';
-export interface ConformanceVector {
-    id: string;
-    secret: string;
-    keyId: string;
-    envelope: Omit<ProtocolEnvelope, 'signature'>;
-    canonical: string;
-    signature: string;
-}
-export interface Ed25519ConformanceVector {
-    id: string;
-    keyId: string;
-    publicKey: string;
-    privateKey: string;
-    envelope: Omit<ProtocolEnvelope, 'signature'>;
-    canonical: string;
-    signature: string;
-}
-export declare const AIP_V01_CONFORMANCE_VECTORS: ConformanceVector[];
-export declare const AIP_V01_ED25519_CONFORMANCE_VECTORS: Ed25519ConformanceVector[];

package/frameworkAdapters.d.ts

@@ -1,72 +0,0 @@
-import { type AipAgentAdapter } from './agentAdapter';
-import { type ProtocolEnvelope } from './protocol';
-import { type WireEnvelope } from './protocolTransport';
-export interface LangChainMessageLike {
-    content: string;
-    name?: string;
-    additionalKwargs?: Record<string, unknown>;
-}
-export interface LlamaIndexMessageLike {
-    role: 'user' | 'assistant' | 'system';
-    content: string;
-    additionalKwargs?: Record<string, unknown>;
-}
-export interface JsonRpcError {
-    code: number;
-    message: string;
-    data?: unknown;
-}
-export interface JsonRpcRequestLike {
-    jsonrpc: '2.0';
-    id: string | number;
-    method: string;
-    params?: unknown;
-}
-export interface JsonRpcResponseLike {
-    jsonrpc: '2.0';
-    id: string | number;
-    result?: unknown;
-    error?: JsonRpcError;
-}
-export interface JsonRpcBridgeOptions {
-    recipient?: string;
-    allowedMethods?: readonly string[];
-    methodToCapability?: (method: string) => string;
-    authorizeMethod?: (request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => boolean | Promise<boolean>;
-    rateLimitKey?: (request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => string;
-    rateLimiter?: {
-        consume: (key: string, request: JsonRpcRequestLike, context: JsonRpcPolicyContext) => boolean | Promise<boolean>;
-    };
-    onPolicyEvent?: (event: JsonRpcPolicyEvent) => void | Promise<void>;
-}
-export interface JsonRpcPolicyContext {
-    intent: 'TASK';
-    recipient?: string;
-    capability: string;
-    correlationId: string;
-    createdAtMs: number;
-}
-export interface JsonRpcPolicyEvent {
-    stage: 'allowlist' | 'authorize' | 'rateLimit';
-    decision: 'allow' | 'deny';
-    method: string;
-    context: JsonRpcPolicyContext;
-    reason?: string;
-}
-export interface JsonRpcResponseOptions {
-    defaultErrorCode?: number;
-}
-export declare function createRawTaskFromLangChain(adapter: AipAgentAdapter, message: LangChainMessageLike, options?: {
-    recipient?: string;
-    capability?: string;
-    correlationId?: string;
-}): Promise<WireEnvelope>;
-export declare function toLangChainMessage(envelope: ProtocolEnvelope): LangChainMessageLike;
-export declare function createRawTaskFromLlamaIndex(adapter: AipAgentAdapter, message: LlamaIndexMessageLike, options?: {
-    recipient?: string;
-    capability?: string;
-    correlationId?: string;
-}): Promise<WireEnvelope>;
-export declare function toLlamaIndexMessage(envelope: ProtocolEnvelope): LlamaIndexMessageLike;
-export declare function createRawTaskFromJsonRpc(adapter: AipAgentAdapter, request: JsonRpcRequestLike, options?: JsonRpcBridgeOptions): Promise<WireEnvelope>;
-export declare function toJsonRpcResponse(envelope: ProtocolEnvelope, id: string | number, options?: JsonRpcResponseOptions): JsonRpcResponseLike;

package/index.d.ts

@@ -1,20 +0,0 @@
-export * from './protocol';
-export * from './protocolTransport';
-export * from './protocolBinary';
-export * from './protocolCapabilities';
-export * from './protocolReplay';
-export * from './keyRotation';
-export * from './protocolAgent';
-export * from './agentAdapter';
-export * from './frameworkAdapters';
-export * from './mcpGateway';
-export * from './runtimePolicy';
-export * from './policyEnforcer';
-export * from './runtimePolicyManager';
-export * from './runtimePolicyPresets';
-export * from './policyTelemetryFeedback';
-export * from './redisClient';
-export * from './replayStores';
-export * from './revocation';
-export * from './mcpWrapper';
-export * from './mcpTransports';