adp-agent 0.2.0

package/dist/src/envelope.d.ts

@@ -0,0 +1,55 @@
+import { TrustStore } from './trust-store';
+export declare const MESSAGE_SIZE_LIMIT: number;
+export interface Envelope {
+    protocol: string;
+    id: string;
+    from: string;
+    to: string;
+    action: string;
+    params: unknown;
+    timestamp: string;
+    sig: string;
+    reply_to?: string;
+    error?: {
+        code: string;
+        message: string;
+        data?: unknown;
+    };
+    trace_id?: string;
+    span_id?: string;
+    encoding?: string;
+    expires_at?: string;
+}
+export interface VerificationResult {
+    valid: boolean;
+    error?: string;
+    message?: string;
+}
+export interface VerifierOptions {
+    /** Enable TOFU (Trust On First Use) — auto-trusts unknown senders on first verified message.
+     *  Default: false. Enable only in development or when you understand the risk. */
+    tofuEnabled?: boolean;
+    /** Called when a previously-unknown agent is encountered. */
+    onNewAgent?: (agentId: string) => void;
+    /** Max clock skew tolerance in milliseconds. Default: 300_000 (5 min). */
+    timestampToleranceMs?: number;
+}
+export declare class MessageVerifier {
+    private trustStore;
+    private tofuEnabled;
+    private onNewAgent?;
+    private timestampToleranceMs;
+    constructor(trustStore: TrustStore, options?: VerifierOptions);
+    verify(envelope: Envelope): Promise<VerificationResult>;
+}
+export declare function generateMessageId(): string;
+export declare function buildEnvelope(from: string, to: string, action: string, params?: unknown, options?: {
+    reply_to?: string;
+    error?: {
+        code: string;
+        message: string;
+        data?: unknown;
+    };
+    trace_id?: string;
+    span_id?: string;
+}): Omit<Envelope, 'sig'>;

package/dist/src/envelope.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageVerifier = exports.MESSAGE_SIZE_LIMIT = void 0;
+exports.generateMessageId = generateMessageId;
+exports.buildEnvelope = buildEnvelope;
+const crypto_1 = require("./crypto");
+const canonical_1 = require("./canonical");
+const agent_id_1 = require("./agent-id");
+const crypto_2 = require("crypto");
+const logger_1 = require("./logger");
+exports.MESSAGE_SIZE_LIMIT = 1024 * 1024;
+const TIMESTAMP_TOLERANCE_MS = 300000;
+class MessageVerifier {
+    constructor(trustStore, options = {}) {
+        this.trustStore = trustStore;
+        this.tofuEnabled = options.tofuEnabled ?? false;
+        this.onNewAgent = options.onNewAgent;
+        this.timestampToleranceMs = options.timestampToleranceMs ?? TIMESTAMP_TOLERANCE_MS;
+    }
+    async verify(envelope) {
+        if (!envelope.sig) {
+            return { valid: false, error: 'INVALID_SIGNATURE', message: 'Signature missing' };
+        }
+        const sigBytes = (0, crypto_1.decodeBase64URL)(envelope.sig);
+        if (sigBytes.length !== 64) {
+            return { valid: false, error: 'INVALID_SIGNATURE', message: 'Invalid signature length' };
+        }
+        const timestamp = new Date(envelope.timestamp).getTime();
+        if (isNaN(timestamp)) {
+            return { valid: false, error: 'INVALID_PARAMS', message: 'Invalid timestamp format' };
+        }
+        const now = Date.now();
+        if (Math.abs(now - timestamp) > this.timestampToleranceMs) {
+            return { valid: false, error: 'INVALID_PARAMS', message: 'Timestamp too old or in future' };
+        }
+        const publicKey = (() => {
+            try {
+                return (0, agent_id_1.extractPublicKey)(envelope.from);
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!publicKey) {
+            return { valid: false, error: 'INVALID_PARAMS', message: 'Invalid sender agent ID format' };
+        }
+        const { sig, ...unsigned } = envelope;
+        const canonical = (0, canonical_1.canonicalize)(unsigned);
+        const messageBytes = new TextEncoder().encode(canonical);
+        const isValid = (0, crypto_1.verify)(publicKey, messageBytes, sigBytes);
+        if (!isValid) {
+            return { valid: false, error: 'INVALID_SIGNATURE', message: 'Signature verification failed' };
+        }
+        if (this.trustStore.has(envelope.from)) {
+            if (this.trustStore.hasConflict(envelope.from, publicKey)) {
+                return { valid: false, error: 'TRUST_CONFLICT', message: 'Agent public key does not match trusted key' };
+            }
+        }
+        else {
+            if (this.tofuEnabled) {
+                this.trustStore.pin(envelope.from, publicKey, 'tofu');
+                this.onNewAgent?.(envelope.from);
+            }
+            else {
+                return {
+                    valid: false,
+                    error: 'TRUST_NOT_ESTABLISHED',
+                    message: `Agent ${envelope.from} is not in trust store. TOFU is disabled — pin the agent first.`,
+                };
+            }
+        }
+        this.trustStore.updateLastVerified(envelope.from);
+        this.trustStore.save().catch(err => {
+            (0, logger_1.getLogger)().warn('[ADP MessageVerifier] Failed to save trust store:', err);
+        });
+        return { valid: true };
+    }
+}
+exports.MessageVerifier = MessageVerifier;
+function generateMessageId() {
+    return 'msg_' + (0, crypto_2.randomBytes)(8).toString('base64url');
+}
+function buildEnvelope(from, to, action, params = {}, options) {
+    return {
+        protocol: 'adp/0.2',
+        id: generateMessageId(),
+        from,
+        to,
+        action,
+        params,
+        timestamp: new Date().toISOString(),
+        ...options,
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":";;;AA0HA,8CAEC;AAED,sCAsBC;AApJD,qCAAmD;AACnD,2CAA2C;AAC3C,yCAA8C;AAE9C,mCAAqC;AACrC,qCAAqC;AAExB,QAAA,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAAC;AAyB9C,MAAM,sBAAsB,GAAG,MAAO,CAAC;AAYvC,MAAa,eAAe;IAK1B,YACU,UAAsB,EAC9B,UAA2B,EAAE;QADrB,eAAU,GAAV,UAAU,CAAY;QAG9B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,IAAI,sBAAsB,CAAC;IACrF,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAkB;QAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;YAClB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;QACpF,CAAC;QAED,MAAM,QAAQ,GAAG,IAAA,wBAAe,EAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;QAC3F,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;QACzD,IAAI,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YACrB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;QACxF,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC1D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;QAC9F,CAAC;QAED,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE;YACtB,IAAI,CAAC;gBACH,OAAO,IAAA,2BAAgB,EAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QACL,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,gCAAgC,EAAE,CAAC;QAC9F,CAAC;QAED,MAAM,EAAE,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC;QACtC,MAAM,SAAS,GAAG,IAAA,wBAAY,EAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEzD,MAAM,OAAO,GAAG,IAAA,eAAM,EAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC;QAE1D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;QAChG,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;gBAC1D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,6CAA6C,EAAE,CAAC;YAC3G,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;gBACtD,IAAI,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,KAAK,EAAE,uBAAuB;oBAC9B,OAAO,EAAE,SAAS,QAAQ,CAAC,IAAI,iEAAiE;iBACjG,CAAC;YACJ,CAAC;QACH,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;YACjC,IAAA,kBAAS,GAAE,CAAC,IAAI,CAAC,mDAAmD,EAAE,GAAG,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;CACF;AA5ED,0CA4EC;AAED,SAAgB,iBAAiB;IAC/B,OAAO,MAAM,GAAG,IAAA,oBAAW,EAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC;AAED,SAAgB,aAAa,CAC3B,IAAY,EACZ,EAAU,EACV,MAAc,EACd,SAAkB,EAAE,EACpB,OAKC;IAED,OAAO;QACL,QAAQ,EAAE,SAAS;QACnB,EAAE,EAAE,iBAAiB,EAAE;QACvB,IAAI;QACJ,EAAE;QACF,MAAM;QACN,MAAM;QACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,GAAG,OAAO;KACX,CAAC;AACJ,CAAC"}

package/dist/src/gateway.d.ts

@@ -0,0 +1,78 @@
+import { WebSocket } from 'ws';
+import { Envelope, MessageVerifier } from './envelope';
+import { Manifest, Capability, Route, AgentInfo } from './manifest';
+import { TrustStore } from './trust-store';
+import { TaskManager } from './task-manager';
+import { ContactStore } from './contacts';
+import { CommunicationConfig } from './config';
+export interface GatewayOptions {
+    host?: string;
+    port: number;
+    path?: string;
+    secretKey: Uint8Array;
+    agentId: string;
+    displayName: string;
+    capabilities: (string | Capability)[];
+    routes?: Route[];
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    skipVerification?: boolean;
+    tofuEnabled?: boolean;
+    onNewAgent?: (agentId: string) => void;
+    onInfo?: (from: string, params: unknown) => void;
+    customHandlers?: Record<string, ActionHandler>;
+    taskManager?: TaskManager;
+    contacts?: ContactStore;
+    description?: string;
+    agentInfo?: AgentInfo;
+    trustStore?: TrustStore;
+    verifier?: MessageVerifier;
+    noServer?: boolean;
+    communication?: CommunicationConfig;
+}
+export type ActionHandler = (ws: WebSocket, envelope: Envelope) => Promise<void>;
+export declare class Gateway {
+    private server;
+    private wss;
+    private secretKey;
+    private agentId;
+    private manifest;
+    private trustStore;
+    private verifier;
+    private messageIdCache;
+    private skipVerification;
+    private onInfo?;
+    private customActions;
+    private taskManager?;
+    private connections;
+    private heartbeatIntervalMs;
+    private heartbeatTimeoutMs;
+    private webhookClient?;
+    private communicationConfig?;
+    private tasks;
+    constructor(options: GatewayOptions & {
+        heartbeatIntervalMs?: number;
+        heartbeatTimeoutMs?: number;
+    });
+    private handleConnection;
+    private processMessage;
+    private handleMessage;
+    private getCommunicationMode;
+    private handleAsyncRequest;
+    private handlePing;
+    private handleCapabilityQuery;
+    private handleInfo;
+    private handleKeyRotate;
+    private sendError;
+    private signAndBuildEnvelope;
+    registerCapability(cap: string | Capability, handler: ActionHandler): void;
+    getManifest(): Manifest;
+    getAgentId(): string;
+    processRelayMessage(rawEnvelope: unknown): Promise<void>;
+    private processMessageDirect;
+    private handleMessageDirect;
+    close(): void;
+}
+export declare function connectToAgent(agentId: string, address: string, localAgentId: string): Promise<WebSocket>;