@amtp/protocol 1.0.1

package/dist/server/notifications.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * AMTP Notifications - Webhook + SSE Push Model (v2.0)
+ *
+ * Provides real-time push notifications to agents via:
+ * - Server-Sent Events (SSE) for long-lived connections
+ * - Webhooks for fire-and-forget delivery
+ *
+ * Security:
+ * - Webhooks are signed with HMAC-SHA256 using a per-subscription secret
+ * - Agents should verify the signature on every webhook call
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notificationBus = exports.NotificationBus = void 0;
+const events_1 = require("events");
+const crypto_1 = __importDefault(require("crypto"));
+const WEBHOOK_SIGNATURE_HEADER = "X-AMTP-Signature";
+const WEBHOOK_TIMESTAMP_HEADER = "X-AMTP-Timestamp";
+/**
+ * Simple in-memory event bus for AMTP notifications.
+ * In production, replace with Redis / NATS / etc.
+ */
+class NotificationBus extends events_1.EventEmitter {
+    constructor() {
+        super(...arguments);
+        this.webhooks = new Map();
+        this.sseClients = new Map();
+    }
+    /**
+     * Emit an event to all subscribers (SSE + Webhooks)
+     */
+    emitEvent(event) {
+        // 1. Notify SSE clients
+        const listeners = this.sseClients.get(event.type) || new Set();
+        listeners.forEach((send) => {
+            try {
+                send(event);
+            }
+            catch (err) {
+                // client disconnected, will be cleaned up on close
+            }
+        });
+        // 2. Deliver to webhooks
+        this.deliverToWebhooks(event);
+    }
+    /**
+     * Register a new webhook subscription
+     */
+    registerWebhook(req) {
+        const id = `wh_${Date.now()}_${crypto_1.default.randomBytes(4).toString("hex")}`;
+        const sub = {
+            id,
+            url: req.url,
+            events: req.events,
+            secret: req.secret,
+            createdAt: new Date().toISOString(),
+            active: true,
+            description: req.description,
+        };
+        this.webhooks.set(id, sub);
+        return sub;
+    }
+    getWebhook(id) {
+        return this.webhooks.get(id);
+    }
+    listWebhooks() {
+        return Array.from(this.webhooks.values());
+    }
+    deleteWebhook(id) {
+        return this.webhooks.delete(id);
+    }
+    /**
+     * Subscribe an SSE client to specific event types
+     */
+    subscribeSSE(types, send) {
+        const unsubs = [];
+        types.forEach((type) => {
+            if (!this.sseClients.has(type)) {
+                this.sseClients.set(type, new Set());
+            }
+            const set = this.sseClients.get(type);
+            set.add(send);
+            unsubs.push(() => {
+                set.delete(send);
+                if (set.size === 0)
+                    this.sseClients.delete(type);
+            });
+        });
+        return () => unsubs.forEach((fn) => fn());
+    }
+    async deliverToWebhooks(event) {
+        const deliveries = Array.from(this.webhooks.values())
+            .filter((sub) => sub.active && sub.events.some((e) => e === event.type || e === "*"))
+            .map(async (sub) => {
+            try {
+                const timestamp = Math.floor(Date.now() / 1000).toString();
+                const payload = JSON.stringify(event);
+                const signature = this.signPayload(payload, timestamp, sub.secret);
+                const res = await fetch(sub.url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        [WEBHOOK_SIGNATURE_HEADER]: signature,
+                        [WEBHOOK_TIMESTAMP_HEADER]: timestamp,
+                        "User-Agent": "AMTP-Webhook/1.1",
+                    },
+                    body: payload,
+                    // In real impl: add timeout, retries, dead letter queue
+                });
+                if (!res.ok) {
+                    console.warn(`[AMTP Webhook] Delivery failed to ${sub.url}: ${res.status}`);
+                }
+            }
+            catch (err) {
+                console.error(`[AMTP Webhook] Error delivering to ${sub.url}:`, err);
+            }
+        });
+        await Promise.allSettled(deliveries);
+    }
+    signPayload(payload, timestamp, secret) {
+        if (!secret)
+            return "";
+        const hmac = crypto_1.default.createHmac("sha256", secret);
+        hmac.update(`${timestamp}.${payload}`);
+        return `sha256=${hmac.digest("hex")}`;
+    }
+}
+exports.NotificationBus = NotificationBus;
+// Singleton for the reference implementation
+exports.notificationBus = new NotificationBus();
+//# sourceMappingURL=notifications.js.map

package/dist/server/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/server/notifications.ts"],"names":[],"mappings":"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"}

package/dist/server/permissions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AMTP Permission Guard — middleware for policy-based access control.
+ *
+ * Evaluates the permissions/policies declared in an AMTPDocument against
+ * the current session's granted permissions at action-execution time.
+ *
+ * Design:
+ *  - Documents declare `permissions` and `policies` as first-class protocol blocks.
+ *  - Sessions hold a flat `permissions: string[]` of granted permission IDs.
+ *  - PermissionGuard resolves which policies apply to the current session,
+ *    checks conditions, and denies the action if a required permission is missing.
+ */
+import { AMTPDocument, Action, Session } from "../types/amtp.types";
+export interface PermissionCheckResult {
+    allowed: boolean;
+    reason?: string;
+    requiredPermissions?: string[];
+    matchedPolicy?: string;
+}
+export interface PermissionGuardConfig {
+    /** When true, actions with no matching permission/policy are denied (default: false) */
+    denyByDefault?: boolean;
+    /** Custom error message for denied actions */
+    deniedMessage?: string;
+}
+export declare class PermissionGuard {
+    private config;
+    constructor(config?: PermissionGuardConfig);
+    /**
+     * Check whether a session is allowed to execute an action on a document
+     * given the document's declared permissions and policies.
+     */
+    check(action: Action, doc: AMTPDocument, session?: Session): PermissionCheckResult;
+    /**
+     * Convenience: throws AMTPError if the action is not permitted.
+     */
+    assert(action: Action, doc: AMTPDocument, session?: Session): void;
+    private evaluateConditions;
+    private resolveField;
+}

package/dist/server/permissions.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * AMTP Permission Guard — middleware for policy-based access control.
+ *
+ * Evaluates the permissions/policies declared in an AMTPDocument against
+ * the current session's granted permissions at action-execution time.
+ *
+ * Design:
+ *  - Documents declare `permissions` and `policies` as first-class protocol blocks.
+ *  - Sessions hold a flat `permissions: string[]` of granted permission IDs.
+ *  - PermissionGuard resolves which policies apply to the current session,
+ *    checks conditions, and denies the action if a required permission is missing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionGuard = void 0;
+const amtp_types_1 = require("../types/amtp.types");
+/* ================================================================
+   PERMISSION GUARD
+   ================================================================ */
+class PermissionGuard {
+    constructor(config) {
+        this.config = {
+            denyByDefault: config?.denyByDefault ?? false,
+            deniedMessage: config?.deniedMessage ?? "Action denied by policy",
+        };
+    }
+    /**
+     * Check whether a session is allowed to execute an action on a document
+     * given the document's declared permissions and policies.
+     */
+    check(action, doc, session) {
+        // If the action doesn't declare required permissions, policy is optional
+        const requiredPerms = action.permissions;
+        if (!requiredPerms || requiredPerms.length === 0) {
+            return { allowed: !this.config.denyByDefault };
+        }
+        const sessionPerms = session?.permissions ?? [];
+        // If no session but action requires auth, deny
+        if (!session && action.requiresAuthentication !== false) {
+            return {
+                allowed: false,
+                reason: "Authentication required",
+                requiredPermissions: requiredPerms,
+            };
+        }
+        // Find policies in the document that apply to the session's role
+        const docPolicies = doc.policies ?? [];
+        const sessionRole = session?.metadata?.role;
+        const matchingPolicies = docPolicies.filter((p) => {
+            // If the policy has a role restriction, the session must match
+            if (p.roles && p.roles.length > 0) {
+                if (!sessionRole || !p.roles.includes(sessionRole))
+                    return false;
+            }
+            return true;
+        });
+        // Check conditions on matching policies
+        for (const policy of matchingPolicies) {
+            if (policy.conditions && policy.conditions.length > 0) {
+                const conditionsMet = this.evaluateConditions(policy.conditions, session);
+                if (!conditionsMet)
+                    continue;
+            }
+            // Check if this policy covers all the action's required permissions
+            const hasAllPerms = requiredPerms.every((rp) => {
+                return policy.permissions.includes(rp) || sessionPerms.includes(rp);
+            });
+            if (hasAllPerms) {
+                return {
+                    allowed: true,
+                    matchedPolicy: policy.id,
+                    requiredPermissions: requiredPerms,
+                };
+            }
+        }
+        // Fallback: check if session directly has the required permissions
+        const hasDirectPerms = requiredPerms.every((rp) => sessionPerms.includes(rp));
+        if (hasDirectPerms) {
+            return {
+                allowed: true,
+                requiredPermissions: requiredPerms,
+            };
+        }
+        // Deny
+        const missingPerms = requiredPerms.filter((rp) => !sessionPerms.includes(rp));
+        return {
+            allowed: false,
+            reason: `${this.config.deniedMessage}: missing permissions [${missingPerms.join(", ")}]`,
+            requiredPermissions: requiredPerms,
+        };
+    }
+    /**
+     * Convenience: throws AMTPError if the action is not permitted.
+     */
+    assert(action, doc, session) {
+        const result = this.check(action, doc, session);
+        if (!result.allowed) {
+            throw new amtp_types_1.AMTPError(amtp_types_1.ErrorCode.PERMISSION_DENIED, result.reason || this.config.deniedMessage, amtp_types_1.StatusCode.FORBIDDEN);
+        }
+    }
+    evaluateConditions(conditions, session) {
+        if (!session)
+            return false;
+        for (const cond of conditions) {
+            const actual = this.resolveField(cond.field, session);
+            const expected = cond.value;
+            switch (cond.operator) {
+                case "eq":
+                    if (actual !== expected)
+                        return false;
+                    break;
+                case "neq":
+                    if (actual === expected)
+                        return false;
+                    break;
+                case "in": {
+                    if (!Array.isArray(expected) || !expected.includes(actual))
+                        return false;
+                    break;
+                }
+                case "gt":
+                    if (typeof actual !== "number" || typeof expected !== "number" || actual <= expected)
+                        return false;
+                    break;
+                case "lt":
+                    if (typeof actual !== "number" || typeof expected !== "number" || actual >= expected)
+                        return false;
+                    break;
+                case "contains":
+                    if (typeof actual !== "string" || !actual.includes(String(expected)))
+                        return false;
+                    break;
+                case "exists":
+                    if (actual === undefined || actual === null)
+                        return false;
+                    break;
+            }
+        }
+        return true;
+    }
+    resolveField(field, session) {
+        const parts = field.split(".");
+        let value = session;
+        for (const part of parts) {
+            if (value && typeof value === "object") {
+                value = value[part];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return value;
+    }
+}
+exports.PermissionGuard = PermissionGuard;
+//# sourceMappingURL=permissions.js.map

package/dist/server/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/server/permissions.ts"],"names":[],"mappings":"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"}

package/dist/server/security.d.ts

@@ -0,0 +1,127 @@
+/**
+ * AMTP Security Utilities
+ * Centralized security utilities for the AMTP protocol
+ */
+/**
+ * Generate a cryptographically secure random string
+ * Replaces Math.random()-based session and request IDs
+ */
+export declare function secureRandomString(length?: number): string;
+/** Session ID prefix for AMTP */
+export declare const AMTP_SESSION_ID_PREFIX = "sess_";
+/** Generate a secure AMTP session ID */
+export declare function generateSecureSessionId(): string;
+/** Request ID prefix for AMTP */
+export declare const AMTP_REQUEST_ID_PREFIX = "req_";
+/** Generate a secure AMTP request ID */
+export declare function generateSecureRequestId(): string;
+/** Allowed redirect schemes — block javascript:, data:, file:, vbscript: */
+export declare const ALLOWED_URL_SCHEMES: Set<string>;
+/** Dangerous HTML/script patterns in markdown content */
+export declare const XSS_PATTERNS: RegExp[];
+/**
+ * Parse and validate a URL against SSRF / open-redirect patterns.
+ * Returns the validated URL string or throws.
+ */
+export declare function validateUrl(value: string, baseUrl?: string): string;
+/**
+ * Strip potentially dangerous HTML/script content from a string
+ * Returns the sanitized string and a boolean indicating whether
+ * anything was removed.
+ */
+export declare function sanitizeHtml(input: string): string;
+/**
+ * Validate a string field (non-empty, no control characters, max length)
+ */
+export declare function validateTextField(value: string, options?: {
+    minLength?: number;
+    maxLength?: number;
+    fieldName?: string;
+}): string;
+/** Common security response headers for AMTP endpoints */
+export declare const AMTP_SECURITY_HEADERS: Record<string, string>;
+/**
+ * Map of IP -> { count, resetAt } used in in-memory rate limiting.
+ * Callers should reset expired entries periodically.
+ */
+export declare class InMemoryRateLimiter {
+    private windowMs;
+    private maxRequests;
+    private map;
+    constructor(windowMs: number, maxRequests: number);
+    /**
+     * Returns true if the request is within the allowed rate limit,
+     * false if it should be rejected with 429.
+     */
+    check(ip: string): boolean;
+    /**
+     * Compute Retry-After (seconds) for a rejected IP.
+     */
+    retryAfterSeconds(ip: string): number;
+    /**
+     * Prune stale entries from the store.
+     */
+    prune(): void;
+}
+/** Default session timeout: 24 hours */
+export declare const DEFAULT_SESSION_TIMEOUT_MS: number;
+/** Absolute cap for any session lifetime regardless of extensions */
+export declare const MAX_SESSION_LIFETIME_MS: number;
+export declare class SecurityError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode: number);
+}
+/** Default maximum request body size: 1 MB */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+/**
+ * Wrap a request/stream body consumer so it stops after maxBytes.
+ * Returns the accumulated string (truncated) and a flag indicating truncation.
+ * Supports: string, browser ReadableStream, Node.js Readable.
+ */
+export declare function readBodyWithLimit(body: any, maxBytes?: number): Promise<{
+    body: string;
+    truncated: boolean;
+}>;
+/**
+ * Returns true if the string looks like a valid AMTP session ID.
+ */
+export declare function isValidSessionId(sessionId: string | null | undefined): boolean;
+/**
+ * Returns the CSRF token header name.
+ */
+export declare function csrfHeaderName(): string;
+/**
+ * Returns the value for a new CSRF token.
+ * Note: The actual token-to-session binding is managed externally (see SessionManager).
+ * This generates the token value only.
+ */
+export declare function generateCsrfToken(_sessionId: string): string;
+/**
+ * Validate that a CSRF token is non-empty and properly formatted.
+ */
+export declare function isValidCsrfToken(token: string | undefined | null): boolean;
+/**
+ * Strictly sanitize an action identifier.
+ * Only [A-Z0-9_] allowed, must start with letter, max 64 chars.
+ * This prevents injection of new actions, newlines, or control chars
+ * into the machine-readable action contract.
+ */
+export declare function sanitizeActionId(raw: string): string;
+/**
+ * Strictly sanitize an endpoint path for actions/forms.
+ * Only safe path characters. No query strings, fragments, or protocol.
+ */
+export declare function sanitizeEndpoint(raw: string): string;
+/**
+ * Strictly validate and normalize HTTP method.
+ */
+export declare function sanitizeHttpMethod(raw: string): string;
+/**
+ * Sanitize free-text fields (descriptions, labels, help text) that will be
+ * shown to or used in prompts for LLMs/agents.
+ *
+ * This is the key defense against prompt injection via action descriptions.
+ * We aggressively strip common jailbreak patterns while preserving useful hints.
+ */
+export declare function sanitizeFreeText(text: string, maxLength?: number): string;