acp-runtime 0.1.0

package/dist/jsonSupport.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2026 ACP Project
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for details.
+ */
+import { validationError } from "./errors.js";
+function normalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeJson(item));
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const output = {};
+    const keys = Object.keys(value).sort();
+    for (const key of keys) {
+        output[key] = normalizeJson(value[key]);
+    }
+    return output;
+}
+export function canonicalJsonString(value) {
+    return JSON.stringify(normalizeJson(value));
+}
+export function canonicalJsonBytes(value) {
+    return new TextEncoder().encode(canonicalJsonString(value));
+}
+export function parseJsonMap(raw) {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw validationError("unable to parse JSON object");
+    }
+    return parsed;
+}
+export function toJsonMap(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw validationError("expected JSON object");
+    }
+    return value;
+}

package/dist/keyProvider.d.ts

@@ -0,0 +1,50 @@
+import { JsonMap } from "./jsonSupport.js";
+export interface IdentityKeyMaterial {
+    signing_private_key: string;
+    encryption_private_key: string;
+    signing_public_key?: string;
+    encryption_public_key?: string;
+    signing_kid?: string;
+    encryption_kid?: string;
+}
+export interface TlsMaterial {
+    cert_file?: string;
+    key_file?: string;
+    ca_file?: string;
+}
+export type KeyProviderInfo = JsonMap;
+export interface KeyProvider {
+    loadIdentityKeys(agentId: string): Promise<IdentityKeyMaterial>;
+    loadTlsMaterial(agentId: string): Promise<TlsMaterial>;
+    loadCaBundle(agentId: string): Promise<string | undefined>;
+    describe(): KeyProviderInfo;
+}
+export declare class LocalKeyProvider implements KeyProvider {
+    private readonly storageDir;
+    private readonly certFile?;
+    private readonly keyFile?;
+    private readonly caFile?;
+    constructor(storageDir: string, certFile?: string | undefined, keyFile?: string | undefined, caFile?: string | undefined);
+    loadIdentityKeys(agentId: string): Promise<IdentityKeyMaterial>;
+    loadTlsMaterial(_agentId: string): Promise<TlsMaterial>;
+    loadCaBundle(_agentId: string): Promise<string | undefined>;
+    describe(): KeyProviderInfo;
+}
+export declare class VaultKeyProvider implements KeyProvider {
+    private readonly vaultUrl;
+    private readonly vaultPath;
+    private readonly vaultTokenEnv;
+    private readonly token?;
+    private readonly timeoutSeconds;
+    private readonly cache;
+    private readonly fetchOptions;
+    constructor(vaultUrl: string, vaultPath: string, vaultTokenEnv?: string, token?: string | undefined, timeoutSeconds?: number, caFile?: string, allowInsecureTls?: boolean, allowInsecureHttp?: boolean);
+    describe(): KeyProviderInfo;
+    private resolveToken;
+    private secretPath;
+    private loadSecret;
+    loadIdentityKeys(agentId: string): Promise<IdentityKeyMaterial>;
+    loadTlsMaterial(agentId: string): Promise<TlsMaterial>;
+    loadCaBundle(agentId: string): Promise<string | undefined>;
+}
+export declare function readCaFile(path: string | undefined): Promise<string | undefined>;

package/dist/keyProvider.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright 2026 ACP Project
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for details.
+ */
+import { readFileSync } from "node:fs";
+import { buildFetchOptions, validateHttpUrl } from "./httpSecurity.js";
+import { toJsonMap } from "./jsonSupport.js";
+import { keyProviderError } from "./errors.js";
+import { readIdentity, sanitizeAgentId } from "./identity.js";
+function normalizeOptional(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function secretValue(secret, keys) {
+    for (const key of keys) {
+        const value = secret[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+export class LocalKeyProvider {
+    storageDir;
+    certFile;
+    keyFile;
+    caFile;
+    constructor(storageDir, certFile, keyFile, caFile) {
+        this.storageDir = storageDir;
+        this.certFile = certFile;
+        this.keyFile = keyFile;
+        this.caFile = caFile;
+    }
+    async loadIdentityKeys(agentId) {
+        const bundle = readIdentity(this.storageDir, agentId);
+        if (!bundle) {
+            throw keyProviderError(`Local identity not found for ${agentId}`);
+        }
+        return {
+            signing_private_key: bundle.identity.signing_private_key,
+            encryption_private_key: bundle.identity.encryption_private_key,
+            signing_public_key: bundle.identity.signing_public_key,
+            encryption_public_key: bundle.identity.encryption_public_key,
+            signing_kid: bundle.identity.signing_kid,
+            encryption_kid: bundle.identity.encryption_kid
+        };
+    }
+    async loadTlsMaterial(_agentId) {
+        return {
+            cert_file: normalizeOptional(this.certFile),
+            key_file: normalizeOptional(this.keyFile),
+            ca_file: normalizeOptional(this.caFile)
+        };
+    }
+    async loadCaBundle(_agentId) {
+        return normalizeOptional(this.caFile);
+    }
+    describe() {
+        return {
+            provider: "local",
+            storage_dir: this.storageDir
+        };
+    }
+}
+export class VaultKeyProvider {
+    vaultUrl;
+    vaultPath;
+    vaultTokenEnv;
+    token;
+    timeoutSeconds;
+    cache = new Map();
+    fetchOptions;
+    constructor(vaultUrl, vaultPath, vaultTokenEnv = "VAULT_TOKEN", token, timeoutSeconds = 10, caFile, allowInsecureTls = false, allowInsecureHttp = false) {
+        this.vaultUrl = vaultUrl;
+        this.vaultPath = vaultPath;
+        this.vaultTokenEnv = vaultTokenEnv;
+        this.token = token;
+        this.timeoutSeconds = timeoutSeconds;
+        if (!vaultUrl.trim()) {
+            throw keyProviderError("vault_url is required for VaultKeyProvider");
+        }
+        if (!vaultPath.trim()) {
+            throw keyProviderError("vault_path is required for VaultKeyProvider");
+        }
+        validateHttpUrl(vaultUrl, allowInsecureHttp, false, "Vault key provider URL");
+        const policy = {
+            allow_insecure_http: allowInsecureHttp,
+            allow_insecure_tls: allowInsecureTls,
+            mtls_enabled: false,
+            ca_file: caFile,
+            cert_file: undefined,
+            key_file: undefined
+        };
+        this.fetchOptions = buildFetchOptions(policy);
+    }
+    describe() {
+        return {
+            provider: "vault",
+            vault_url: this.vaultUrl.replace(/\/+$/, ""),
+            vault_path: this.vaultPath.replace(/^\/+/, ""),
+            vault_token_env: this.vaultTokenEnv
+        };
+    }
+    resolveToken() {
+        if (this.token && this.token.trim()) {
+            return this.token.trim();
+        }
+        const envValue = process.env[this.vaultTokenEnv];
+        return envValue?.trim() || undefined;
+    }
+    secretPath(agentId) {
+        const sanitized = sanitizeAgentId(agentId);
+        if (this.vaultPath.includes("{agent_id}")) {
+            return this.vaultPath.replace("{agent_id}", sanitized);
+        }
+        return `${this.vaultPath.replace(/\/+$/, "")}/${sanitized}`;
+    }
+    async loadSecret(agentId) {
+        const path = this.secretPath(agentId);
+        const cached = this.cache.get(path);
+        if (cached) {
+            return cached;
+        }
+        const token = this.resolveToken();
+        if (!token) {
+            throw keyProviderError(`Vault token is missing. Set token or environment variable ${this.vaultTokenEnv}.`);
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), Math.max(1, this.timeoutSeconds) * 1000);
+        try {
+            const url = `${this.vaultUrl.replace(/\/+$/, "")}/v1/${path.replace(/^\/+/, "")}`;
+            const response = await fetch(url, {
+                method: "GET",
+                headers: {
+                    Accept: "application/json",
+                    "X-Vault-Token": token
+                },
+                signal: controller.signal,
+                ...this.fetchOptions
+            });
+            if (response.status !== 200) {
+                throw keyProviderError(`Vault returned HTTP ${response.status} for path ${path}`);
+            }
+            const parsed = toJsonMap((await response.json()));
+            const dataValue = parsed.data;
+            if (!dataValue || typeof dataValue !== "object" || Array.isArray(dataValue)) {
+                throw keyProviderError(`Vault response for path ${path} is missing data object`);
+            }
+            const topData = dataValue;
+            const nestedData = topData.data && typeof topData.data === "object" && !Array.isArray(topData.data)
+                ? topData.data
+                : topData;
+            this.cache.set(path, nestedData);
+            return nestedData;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async loadIdentityKeys(agentId) {
+        const secret = await this.loadSecret(agentId);
+        const signingPrivateKey = secretValue(secret, [
+            "signing_key",
+            "identity_signing_key",
+            "signing_private_key"
+        ]);
+        const encryptionPrivateKey = secretValue(secret, [
+            "encryption_key",
+            "identity_encryption_key",
+            "encryption_private_key"
+        ]);
+        if (!signingPrivateKey) {
+            throw keyProviderError(`Vault secret for ${agentId} is missing signing_key`);
+        }
+        if (!encryptionPrivateKey) {
+            throw keyProviderError(`Vault secret for ${agentId} is missing encryption_key`);
+        }
+        return {
+            signing_private_key: signingPrivateKey,
+            encryption_private_key: encryptionPrivateKey,
+            signing_public_key: secretValue(secret, ["signing_public_key"]),
+            encryption_public_key: secretValue(secret, ["encryption_public_key"]),
+            signing_kid: secretValue(secret, ["signing_kid"]),
+            encryption_kid: secretValue(secret, ["encryption_kid"])
+        };
+    }
+    async loadTlsMaterial(agentId) {
+        const secret = await this.loadSecret(agentId);
+        return {
+            cert_file: secretValue(secret, ["tls_cert_file", "tls_cert", "cert_file"]),
+            key_file: secretValue(secret, ["tls_key_file", "tls_key", "key_file"]),
+            ca_file: secretValue(secret, ["ca_bundle_file", "ca_file", "ca_bundle"])
+        };
+    }
+    async loadCaBundle(agentId) {
+        const secret = await this.loadSecret(agentId);
+        return secretValue(secret, ["ca_bundle_file", "ca_file", "ca_bundle"]);
+    }
+}
+export async function readCaFile(path) {
+    if (!path) {
+        return undefined;
+    }
+    return readFileSync(path, "utf-8");
+}

package/dist/messages.d.ts

@@ -0,0 +1,75 @@
+import { JsonMap } from "./jsonSupport.js";
+export type MessageClass = "SEND" | "ACK" | "FAIL" | "CAPABILITIES" | "COMPENSATE";
+export type DeliveryState = "PENDING" | "DELIVERED" | "ACKNOWLEDGED" | "FAILED" | "DECLINED" | "EXPIRED";
+export type DeliveryMode = "auto" | "direct" | "relay" | "amqp" | "mqtt";
+export interface WrappedContentKey {
+    recipient: string;
+    ephemeral_public_key: string;
+    nonce: string;
+    ciphertext: string;
+}
+export interface Envelope {
+    acp_version: string;
+    message_class: MessageClass;
+    message_id: string;
+    operation_id: string;
+    timestamp: string;
+    expires_at: string;
+    sender: string;
+    recipients: string[];
+    context_id: string;
+    crypto_suite: string;
+    correlation_id?: string;
+    in_reply_to?: string;
+}
+export interface ProtectedPayload {
+    nonce: string;
+    ciphertext: string;
+    wrapped_content_keys: WrappedContentKey[];
+    payload_hash: string;
+    signature_kid: string;
+    signature: string;
+}
+export interface AcpMessage {
+    envelope: Envelope;
+    protected: ProtectedPayload;
+    sender_identity_document?: JsonMap;
+}
+export interface DeliveryOutcome {
+    recipient: string;
+    state: DeliveryState;
+    status_code?: number;
+    response_class?: MessageClass;
+    reason_code?: string;
+    detail?: string;
+    response_message?: JsonMap;
+}
+export interface SendResult {
+    operation_id: string;
+    message_id: string;
+    message_ids: string[];
+    outcomes: DeliveryOutcome[];
+}
+export interface CompensateInstruction {
+    operation_id: string;
+    reason: string;
+    actions: JsonMap[];
+}
+export declare function parseMessageClass(value: string | undefined): MessageClass | undefined;
+export declare function buildEnvelope(input: {
+    sender: string;
+    recipients: string[];
+    message_class: MessageClass;
+    context_id: string;
+    expires_in_seconds: number;
+    operation_id?: string;
+    correlation_id?: string;
+    in_reply_to?: string;
+    crypto_suite?: string;
+}): Envelope;
+export declare function validateEnvelope(envelope: Envelope): void;
+export declare function isExpired(envelope: Envelope): boolean;
+export declare function parseAcpMessage(map: JsonMap): AcpMessage;
+export declare function messageToMap(message: AcpMessage): JsonMap;
+export declare function buildAckPayload(receivedMessageId: string, status: string): JsonMap;
+export declare function buildFailPayload(reasonCode: string, detail: string, retriable: boolean): JsonMap;

package/dist/messages.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 ACP Project
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for details.
+ */
+import { randomUUID } from "node:crypto";
+import { ACP_VERSION, DEFAULT_CRYPTO_SUITE } from "./constants.js";
+import { toJsonMap } from "./jsonSupport.js";
+import { validationError } from "./errors.js";
+export function parseMessageClass(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === "SEND" ||
+        value === "ACK" ||
+        value === "FAIL" ||
+        value === "CAPABILITIES" ||
+        value === "COMPENSATE") {
+        return value;
+    }
+    return undefined;
+}
+export function buildEnvelope(input) {
+    const now = new Date();
+    const expires = new Date(now.getTime() + Math.max(1, input.expires_in_seconds) * 1000);
+    const envelope = {
+        acp_version: ACP_VERSION,
+        message_class: input.message_class,
+        message_id: randomUUID(),
+        operation_id: input.operation_id ?? randomUUID(),
+        timestamp: now.toISOString(),
+        expires_at: expires.toISOString(),
+        sender: input.sender,
+        recipients: input.recipients,
+        context_id: input.context_id,
+        crypto_suite: input.crypto_suite ?? DEFAULT_CRYPTO_SUITE
+    };
+    if (input.correlation_id) {
+        envelope.correlation_id = input.correlation_id;
+    }
+    if (input.in_reply_to) {
+        envelope.in_reply_to = input.in_reply_to;
+    }
+    validateEnvelope(envelope);
+    return envelope;
+}
+export function validateEnvelope(envelope) {
+    if (!envelope.sender.trim()) {
+        throw validationError("Envelope sender is required");
+    }
+    if (!Array.isArray(envelope.recipients) || envelope.recipients.length === 0) {
+        throw validationError("Envelope recipients must not be empty");
+    }
+    const timestamp = Date.parse(envelope.timestamp);
+    const expires = Date.parse(envelope.expires_at);
+    if (Number.isNaN(timestamp) || Number.isNaN(expires)) {
+        throw validationError("Envelope timestamps must be RFC3339 strings");
+    }
+    if (expires <= timestamp) {
+        throw validationError("Envelope expires_at must be after timestamp");
+    }
+}
+export function isExpired(envelope) {
+    const expires = Date.parse(envelope.expires_at);
+    return Number.isNaN(expires) || expires <= Date.now();
+}
+export function parseAcpMessage(map) {
+    const envelope = toJsonMap(map.envelope);
+    const protectedPayload = toJsonMap(map.protected);
+    const message = {
+        envelope,
+        protected: protectedPayload
+    };
+    if (map.sender_identity_document !== undefined && map.sender_identity_document !== null) {
+        message.sender_identity_document = toJsonMap(map.sender_identity_document);
+    }
+    validateEnvelope(envelope);
+    return message;
+}
+export function messageToMap(message) {
+    const output = {
+        envelope: message.envelope,
+        protected: message.protected
+    };
+    if (message.sender_identity_document) {
+        output.sender_identity_document = message.sender_identity_document;
+    }
+    return output;
+}
+export function buildAckPayload(receivedMessageId, status) {
+    return {
+        status,
+        received_message_id: receivedMessageId
+    };
+}
+export function buildFailPayload(reasonCode, detail, retriable) {
+    return {
+        reason_code: reasonCode,
+        detail,
+        retriable
+    };
+}

package/dist/mqttTransport.d.ts

@@ -0,0 +1,19 @@
+import { JsonMap } from "./jsonSupport.js";
+export declare const DEFAULT_MQTT_QOS = 1;
+export declare const DEFAULT_MQTT_TOPIC_PREFIX = "acp/agent";
+export type MqttMessageHandler = (message: JsonMap) => boolean | Promise<boolean>;
+export declare function metadataProperties(message: JsonMap): Record<string, string>;
+export declare class MqttTransportClient {
+    readonly broker_url: string;
+    readonly qos: number;
+    readonly topic_prefix: string;
+    readonly timeout_seconds: number;
+    readonly keepalive_seconds: number;
+    constructor(brokerUrl: string, qos?: number, topicPrefix?: string, timeoutSeconds?: number, keepaliveSeconds?: number);
+    static agentIdentifierToken(agentId: string): string;
+    static topicForAgent(agentId: string, topicPrefix?: string): string;
+    static buildServiceHint(agentId: string, brokerUrl: string, topic?: string, qos?: number, topicPrefix?: string): JsonMap;
+    private connectClient;
+    publish(message: JsonMap, recipientAgentId: string, service?: JsonMap): Promise<void>;
+    consume(agentId: string, handler: MqttMessageHandler, service?: JsonMap, maxMessages?: number, pollTimeoutMs?: number): Promise<number>;
+}