@embassys/ambassador 0.0.0 → 0.2.6

package/dist/process-lock.js

@@ -0,0 +1,122 @@
+import { lstatSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { GatewayError } from "./errors.js";
+import { preparePrivateSqliteArtifact } from "./sqlite-artifact.js";
+const LOCK_HANDOFF_TIMEOUT_MS = 1_000;
+const activeLockKeys = new Set();
+const pendingLockPaths = new Set();
+function errorCode(error) {
+    if (error !== null && typeof error === "object" && "code" in error) {
+        return typeof error.code === "string" ? error.code : undefined;
+    }
+    return undefined;
+}
+function invalidLockArtifact() {
+    return new GatewayError("lock_invalid", "The Ambassador lock artifact is invalid", 7);
+}
+function daemonRunning() {
+    return new GatewayError("daemon_running", "Ambassador is already running", 7);
+}
+function pathKey(path) {
+    return process.platform === "win32" ? path.toLowerCase() : path;
+}
+function filesystemLockKey(path) {
+    try {
+        const stats = lstatSync(path, { bigint: true });
+        return `artifact:${stats.dev}:${stats.ino}`;
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+        const parentStats = lstatSync(dirname(path), { bigint: true });
+        return `new:${parentStats.dev}:${parentStats.ino}:${pathKey(basename(path))}`;
+    }
+}
+export class ProcessLock {
+    database;
+    keys;
+    released = false;
+    constructor(database, keys) {
+        this.database = database;
+        this.keys = keys;
+    }
+    static async acquire(path) {
+        const artifactPath = resolve(path);
+        const pendingPath = pathKey(artifactPath);
+        if (pendingLockPaths.has(pendingPath))
+            throw daemonRunning();
+        pendingLockPaths.add(pendingPath);
+        const keys = [];
+        try {
+            await mkdir(dirname(artifactPath), { recursive: true, mode: 0o700 });
+            const initialKey = filesystemLockKey(artifactPath);
+            if (activeLockKeys.has(initialKey))
+                throw daemonRunning();
+            activeLockKeys.add(initialKey);
+            keys.push(initialKey);
+            pendingLockPaths.delete(pendingPath);
+            const artifact = preparePrivateSqliteArtifact(artifactPath, invalidLockArtifact);
+            let database;
+            try {
+                const artifactKey = filesystemLockKey(artifactPath);
+                if (artifactKey !== initialKey) {
+                    if (activeLockKeys.has(artifactKey))
+                        throw daemonRunning();
+                    activeLockKeys.add(artifactKey);
+                    keys.push(artifactKey);
+                }
+                database = new Database(artifactPath, { timeout: LOCK_HANDOFF_TIMEOUT_MS });
+                artifact.validate();
+                // Closing another descriptor for this inode after BEGIN can release POSIX process locks.
+                artifact.releaseFile();
+                database.pragma(`busy_timeout = ${LOCK_HANDOFF_TIMEOUT_MS}`);
+                database.pragma("trusted_schema = OFF");
+                database.exec("BEGIN EXCLUSIVE");
+                artifact.validateDirectory();
+                return new ProcessLock(database, keys);
+            }
+            catch (error) {
+                database?.close();
+                const code = errorCode(error);
+                if (code?.startsWith("SQLITE_BUSY"))
+                    throw daemonRunning();
+                if (code === "SQLITE_NOTADB" || code === "SQLITE_FORMAT" || code === "SQLITE_CORRUPT") {
+                    throw invalidLockArtifact();
+                }
+                throw error;
+            }
+            finally {
+                artifact.close();
+            }
+        }
+        catch (error) {
+            pendingLockPaths.delete(pendingPath);
+            for (const key of keys)
+                activeLockKeys.delete(key);
+            if (errorCode(error) === "ENOENT" && keys.some((key) => key.startsWith("artifact:"))) {
+                throw daemonRunning();
+            }
+            throw error;
+        }
+    }
+    async release() {
+        if (this.released)
+            return;
+        this.released = true;
+        try {
+            this.database.exec("ROLLBACK");
+        }
+        finally {
+            try {
+                this.database.close();
+            }
+            finally {
+                for (const key of this.keys)
+                    activeLockKeys.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=process-lock.js.map

package/dist/process-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-lock.js","sourceRoot":"","sources":["../src/process-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAEpE,MAAM,uBAAuB,GAAG,KAAK,CAAC;AACtC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;AACzC,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE3C,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QACnE,OAAO,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO,IAAI,YAAY,CAAC,cAAc,EAAE,yCAAyC,EAAE,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,aAAa;IACpB,OAAO,IAAI,YAAY,CAAC,gBAAgB,EAAE,+BAA+B,EAAE,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAClE,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,OAAO,YAAY,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,QAAQ;YAAE,MAAM,KAAK,CAAC;QAC/C,MAAM,WAAW,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,OAAO,OAAO,WAAW,CAAC,GAAG,IAAI,WAAW,CAAC,GAAG,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IAChF,CAAC;AACH,CAAC;AAED,MAAM,OAAO,WAAW;IAIH,QAAQ;IACR,IAAI;IAJf,QAAQ,GAAG,KAAK,CAAC;IAEzB,YACmB,QAA2B,EAC3B,IAAc;wBADd,QAAQ;oBACR,IAAI;IACpB,CAAC;IAEJ,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAY;QAC/B,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,MAAM,aAAa,EAAE,CAAC;QAC7D,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAClC,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACrE,MAAM,UAAU,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;YACnD,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC;gBAAE,MAAM,aAAa,EAAE,CAAC;YAC1D,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACtB,gBAAgB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YAErC,MAAM,QAAQ,GAAG,4BAA4B,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;YACjF,IAAI,QAAuC,CAAC;YAE5C,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;gBACpD,IAAI,WAAW,KAAK,UAAU,EAAE,CAAC;oBAC/B,IAAI,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC;wBAAE,MAAM,aAAa,EAAE,CAAC;oBAC3D,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;oBAChC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACzB,CAAC;gBACD,QAAQ,GAAG,IAAI,QAAQ,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;gBAC5E,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACpB,yFAAyF;gBACzF,QAAQ,CAAC,WAAW,EAAE,CAAC;gBACvB,QAAQ,CAAC,MAAM,CAAC,kBAAkB,uBAAuB,EAAE,CAAC,CAAC;gBAC7D,QAAQ,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;gBACxC,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;gBACjC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;gBAC7B,OAAO,IAAI,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,EAAE,KAAK,EAAE,CAAC;gBAClB,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;gBAC9B,IAAI,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC;oBAAE,MAAM,aAAa,EAAE,CAAC;gBAC3D,IAAI,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,eAAe,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;oBACtF,MAAM,mBAAmB,EAAE,CAAC;gBAC9B,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gBAAgB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YACrC,KAAK,MAAM,GAAG,IAAI,IAAI;gBAAE,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACnD,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC;gBACrF,MAAM,aAAa,EAAE,CAAC;YACxB,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACjC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC;gBACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACxB,CAAC;oBAAS,CAAC;gBACT,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI;oBAAE,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/sqlite-artifact.d.ts

@@ -0,0 +1,7 @@
+export interface PreparedSqliteArtifact {
+    validate: () => void;
+    validateDirectory: () => void;
+    releaseFile: () => void;
+    close: () => void;
+}
+export declare function preparePrivateSqliteArtifact(path: string, invalidArtifact: () => Error): PreparedSqliteArtifact;

package/dist/sqlite-artifact.js

@@ -0,0 +1,121 @@
+import { chmodSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, openSync, } from "node:fs";
+import { dirname } from "node:path";
+const POSIX = process.platform !== "win32";
+function errorCode(error) {
+    return error !== null && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function sameArtifact(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function secureExistingFile(path, invalidArtifact) {
+    let pathStats;
+    try {
+        pathStats = lstatSync(path, { bigint: true });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return;
+        throw error;
+    }
+    if (!pathStats.isFile() || pathStats.nlink !== 1n)
+        throw invalidArtifact();
+    if (POSIX)
+        chmodSync(path, 0o600);
+    const currentStats = lstatSync(path, { bigint: true });
+    if (!currentStats.isFile() ||
+        currentStats.nlink !== 1n ||
+        !sameArtifact(pathStats, currentStats)) {
+        throw invalidArtifact();
+    }
+}
+export function preparePrivateSqliteArtifact(path, invalidArtifact) {
+    const directoryPath = dirname(path);
+    const initialDirectoryStats = lstatSync(directoryPath, { bigint: true });
+    if (!initialDirectoryStats.isDirectory())
+        throw invalidArtifact();
+    let directoryDescriptor;
+    let fileDescriptor;
+    try {
+        if (POSIX) {
+            directoryDescriptor = openSync(directoryPath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            const descriptorStats = fstatSync(directoryDescriptor, { bigint: true });
+            const pathStats = lstatSync(directoryPath, { bigint: true });
+            if (!descriptorStats.isDirectory() || !pathStats.isDirectory())
+                throw invalidArtifact();
+            if (!sameArtifact(descriptorStats, pathStats))
+                throw invalidArtifact();
+            if (typeof process.getuid === "function" &&
+                descriptorStats.uid !== BigInt(process.getuid())) {
+                throw invalidArtifact();
+            }
+            fchmodSync(directoryDescriptor, 0o700);
+        }
+        for (const suffix of ["-wal", "-shm", "-journal"]) {
+            secureExistingFile(`${path}${suffix}`, invalidArtifact);
+        }
+        try {
+            fileDescriptor = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR, 0o600);
+        }
+        catch (error) {
+            if (errorCode(error) !== "EEXIST")
+                throw error;
+            const pathStats = lstatSync(path, { bigint: true });
+            if (!pathStats.isFile() || pathStats.nlink !== 1n)
+                throw invalidArtifact();
+            fileDescriptor = openSync(path, constants.O_RDWR | constants.O_NOFOLLOW);
+        }
+        const validateDirectory = () => {
+            const currentDirectoryStats = lstatSync(directoryPath, { bigint: true });
+            const expectedDirectoryStats = directoryDescriptor === undefined
+                ? initialDirectoryStats
+                : fstatSync(directoryDescriptor, { bigint: true });
+            if (!currentDirectoryStats.isDirectory() ||
+                !sameArtifact(expectedDirectoryStats, currentDirectoryStats)) {
+                throw invalidArtifact();
+            }
+        };
+        const validate = () => {
+            const descriptorStats = fstatSync(fileDescriptor, { bigint: true });
+            const pathStats = lstatSync(path, { bigint: true });
+            if (!descriptorStats.isFile() ||
+                !pathStats.isFile() ||
+                descriptorStats.nlink !== 1n ||
+                pathStats.nlink !== 1n ||
+                !sameArtifact(descriptorStats, pathStats)) {
+                throw invalidArtifact();
+            }
+            validateDirectory();
+        };
+        const releaseFile = () => {
+            if (fileDescriptor !== undefined) {
+                closeSync(fileDescriptor);
+                fileDescriptor = undefined;
+            }
+        };
+        validate();
+        if (POSIX)
+            fchmodSync(fileDescriptor, 0o600);
+        return {
+            validate,
+            validateDirectory,
+            releaseFile,
+            close: () => {
+                releaseFile();
+                if (directoryDescriptor !== undefined) {
+                    closeSync(directoryDescriptor);
+                    directoryDescriptor = undefined;
+                }
+            },
+        };
+    }
+    catch (error) {
+        if (fileDescriptor !== undefined)
+            closeSync(fileDescriptor);
+        if (directoryDescriptor !== undefined)
+            closeSync(directoryDescriptor);
+        throw error;
+    }
+}
+//# sourceMappingURL=sqlite-artifact.js.map

package/dist/sqlite-artifact.js.map

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

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,23 @@
+import type { CentralMessage } from "./central-rest.js";
+export type WebhookDeliveryErrorCode = "delivery_failed" | "invalid_configuration";
+export declare class WebhookDeliveryError extends Error {
+    readonly code: WebhookDeliveryErrorCode;
+    constructor(code: WebhookDeliveryErrorCode);
+}
+export interface WebhookDeliveryTargetOptions {
+    readonly url: string;
+    readonly secret: string;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+    readonly deadlineMs?: number;
+    readonly maximumAttempts?: number;
+    readonly retryDelayMs?: number;
+}
+export declare class WebhookDeliveryTarget {
+    #private;
+    constructor(options: WebhookDeliveryTargetOptions);
+    deliver(message: CentralMessage, signal: AbortSignal): Promise<{
+        readonly status: "accepted";
+    }>;
+    close(): Promise<void>;
+}

package/dist/webhook-delivery.js

@@ -0,0 +1,122 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { canonicalWebhookUrl } from "./delivery-profile.js";
+const DEFAULT_DEADLINE_MS = 10_000;
+const DEFAULT_MAXIMUM_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 250;
+const MAX_MESSAGE_BYTES = 512 * 1024;
+export class WebhookDeliveryError extends Error {
+    code;
+    constructor(code) {
+        super("Webhook delivery failed");
+        this.code = code;
+        this.name = "WebhookDeliveryError";
+    }
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+async function cancel(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+export class WebhookDeliveryTarget {
+    #url;
+    #secret;
+    #authorization;
+    #fetch;
+    #now;
+    #deadlineMs;
+    #maximumAttempts;
+    #retryDelayMs;
+    #lifetime = new AbortController();
+    constructor(options) {
+        try {
+            this.#url = canonicalWebhookUrl(options.url);
+        }
+        catch {
+            throw new WebhookDeliveryError("invalid_configuration");
+        }
+        if (!/^[\x21-\x7e]{32,256}$/u.test(options.secret)) {
+            throw new WebhookDeliveryError("invalid_configuration");
+        }
+        this.#secret = options.secret;
+        this.#authorization = `Bearer ${options.secret}`;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#now = options.now ?? Date.now;
+        this.#deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+        this.#maximumAttempts = options.maximumAttempts ?? DEFAULT_MAXIMUM_ATTEMPTS;
+        this.#retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+        if (!positiveInteger(this.#deadlineMs) ||
+            !positiveInteger(this.#maximumAttempts) ||
+            !positiveInteger(this.#retryDelayMs)) {
+            throw new WebhookDeliveryError("invalid_configuration");
+        }
+    }
+    async deliver(message, signal) {
+        let body;
+        try {
+            body = JSON.stringify(message);
+        }
+        catch {
+            throw new WebhookDeliveryError("delivery_failed");
+        }
+        if (Buffer.byteLength(body, "utf8") > MAX_MESSAGE_BYTES) {
+            throw new WebhookDeliveryError("delivery_failed");
+        }
+        const requestId = message.id ?? randomUUID();
+        const deadline = AbortSignal.timeout(this.#deadlineMs);
+        const requestSignal = AbortSignal.any([signal, deadline, this.#lifetime.signal]);
+        for (let attempt = 1; attempt <= this.#maximumAttempts; attempt += 1) {
+            if (requestSignal.aborted)
+                throw new WebhookDeliveryError("delivery_failed");
+            const now = this.#now();
+            if (!Number.isSafeInteger(now) || now < 0) {
+                throw new WebhookDeliveryError("invalid_configuration");
+            }
+            const timestamp = String(Math.floor(now / 1_000));
+            const signature = createHmac("sha256", this.#secret)
+                .update(timestamp, "ascii")
+                .update(".", "ascii")
+                .update(body, "utf8")
+                .digest("hex");
+            try {
+                const response = await this.#fetch(this.#url, {
+                    method: "POST",
+                    headers: {
+                        authorization: this.#authorization,
+                        "content-type": "application/json",
+                        "idempotency-key": requestId,
+                        "x-request-id": requestId,
+                        "x-webhook-timestamp": timestamp,
+                        "x-webhook-signature-v2": signature,
+                    },
+                    body,
+                    credentials: "omit",
+                    redirect: "manual",
+                    signal: requestSignal,
+                });
+                const accepted = response.status >= 200 && response.status < 300;
+                await cancel(response);
+                if (accepted)
+                    return { status: "accepted" };
+            }
+            catch {
+                if (requestSignal.aborted)
+                    throw new WebhookDeliveryError("delivery_failed");
+            }
+            if (attempt < this.#maximumAttempts) {
+                try {
+                    await delay(this.#retryDelayMs, undefined, { signal: requestSignal });
+                }
+                catch {
+                    throw new WebhookDeliveryError("delivery_failed");
+                }
+            }
+        }
+        throw new WebhookDeliveryError("delivery_failed");
+    }
+    async close() {
+        this.#lifetime.abort();
+    }
+}
+//# sourceMappingURL=webhook-delivery.js.map

package/dist/webhook-delivery.js.map

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

package/docs/getting-started-claude.md

@@ -0,0 +1,94 @@
+# Get started with Claude Code
+
+Release target: `@embassys/ambassador@0.2.6`. The profile is source-reviewed
+against Claude Code 2.1.257 and 2.1.258 plus
+`@agentclientprotocol/claude-agent-acp` 0.73.0, and its exact ACP initialization
+contract passed. Real-agent direct and webhook qualification remain open under
+the one-release qualification exception in ADR 0015.
+
+Ambassador enables Claude Code only for this exact contract:
+
+| Field | Value |
+| --- | --- |
+| MCP `clientInfo` | `claude-code` / `2.1.257` or `2.1.258` |
+| Delivery modes | direct and webhook |
+| Direct command | `claude-agent-acp` |
+| ACP adapter | `@agentclientprotocol/claude-agent-acp` / `0.73.0` |
+| Accepted ACP `agentInfo` | `@agentclientprotocol/claude-agent-acp` / `0.73.0` |
+| Ambassador MCP in the direct session | ACP HTTP MCP injection |
+
+Ambassador uses the existing
+[`agentclientprotocol/claude-agent-acp`](https://github.com/agentclientprotocol/claude-agent-acp)
+adapter. It does not contain a Claude adapter. The reviewed release is
+[`v0.73.0`](https://github.com/agentclientprotocol/claude-agent-acp/tree/v0.73.0).
+Its
+[`package.json`](https://github.com/agentclientprotocol/claude-agent-acp/blob/v0.73.0/package.json)
+defines the `claude-agent-acp` command, pins `@agentclientprotocol/sdk` 1.4.0,
+and pins `@anthropic-ai/claude-agent-sdk` 0.3.257. Its
+[`acp-agent.ts`](https://github.com/agentclientprotocol/claude-agent-acp/blob/v0.73.0/src/acp-agent.ts)
+returns the adapter identity and maps HTTP MCP session configuration into the
+Claude Agent SDK.
+
+The selected SDK contains Claude Code 2.1.257. The separately reviewed current
+Claude Code package is 2.1.258. Both exact versions use the `claude-code` MCP
+identity and map to the same fixed profile. Other Claude Code or adapter
+versions fail closed until the registry is reviewed and updated.
+
+## Setup
+
+1. Install Node.js `>=24.19.0 <25` and
+   `@agentclientprotocol/claude-agent-acp` 0.73.0 through its normal package
+   installation process. Ambassador never installs or updates the adapter.
+2. Authenticate Claude through normal Claude Code setup, or set one approved
+   adapter authentication variable outside chat: `ANTHROPIC_API_KEY`,
+   `ANTHROPIC_AUTH_TOKEN`, or `CLAUDE_CODE_OAUTH_TOKEN`.
+3. Generate the local MCP token without putting its value in chat or a command
+   argument:
+
+   ```sh
+   export AMBASSADOR_LOCAL_TOKEN="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+4. If you may choose webhook delivery, create its secret in the same shell
+   before starting Ambassador:
+
+   ```sh
+   export AMBASSADOR_WEBHOOK_SECRET="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+5. From the directory the direct agent may access, start the exact release and
+   keep it running in the foreground:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.6 start \
+     --local-token-env=AMBASSADOR_LOCAL_TOKEN
+   ```
+
+6. Configure Claude Code's MCP client to use the loopback endpoint printed by
+   Ambassador, with a bearer token read from `AMBASSADOR_LOCAL_TOKEN`. Use the
+   provider's normal MCP configuration mechanism; do not copy the token value
+   into chat.
+7. Ask Claude Code to register with your email and optional display name. The
+   first `register_agent` call contains `email` and, if wanted, `display_name`.
+   Ambassador recognizes the Claude Code profile and asks direct versus
+   webhook, with direct as the default.
+8. For direct mode, choose direct. The follow-up repeats the same `email` and
+   optional `display_name` and adds `delivery: {"mode":"direct"}`. Ambassador
+   starts `claude-agent-acp` and injects its authenticated HTTP MCP server into
+   the new ACP session.
+9. For webhook mode, choose webhook and provide the HTTPS receiver URL plus
+   the environment-variable name `AMBASSADOR_WEBHOOK_SECRET`. The follow-up
+   repeats the registration fields and adds `delivery.mode`, `delivery.url`,
+   and `delivery.secret_env`; it never sends the secret value.
+10. Enter the email verification code when Claude Code asks for it. Claude
+    Code calls `verify_email` with that `email` and six-digit `code`; the
+    central token and DPoP key stay inside Ambassador.
+
+Ambassador does not pass `CLAUDE_CODE_EXECUTABLE` or another executable
+override. It never receives Claude account credentials, the central token, or
+the DPoP private key. Never put the local token or a provider credential in
+chat or registration arguments.

package/docs/getting-started-codex.md

@@ -0,0 +1,103 @@
+# Get started with Codex
+
+Release target: `@embassys/ambassador@0.2.6`. The profile is source-reviewed
+against Codex 0.149.0 and 0.152.1 plus
+`@agentclientprotocol/codex-acp` 1.8.0. The exact ACP initialization contract
+and direct live-central flow passed. Webhook qualification and a repeat of the
+direct case on supported Node remain open under the one-release qualification
+exception in ADR 0015.
+
+Ambassador enables Codex only for this exact contract:
+
+| Field | Value |
+| --- | --- |
+| MCP `clientInfo` | `codex-mcp-client` / `0.149.0` or `0.152.1` |
+| Delivery modes | direct and webhook |
+| Direct command | `codex-acp` |
+| ACP adapter | `@agentclientprotocol/codex-acp` / `1.8.0` |
+| Accepted ACP `agentInfo` | `@agentclientprotocol/codex-acp` / `1.8.0` |
+| Ambassador MCP in the direct session | ACP HTTP MCP injection |
+
+Ambassador uses the existing
+[`agentclientprotocol/codex-acp`](https://github.com/agentclientprotocol/codex-acp)
+adapter. It does not contain a Codex adapter. The reviewed adapter revision is
+[`87997e2627e8fa246a49de533c612f6196c4004e`](https://github.com/agentclientprotocol/codex-acp/tree/87997e2627e8fa246a49de533c612f6196c4004e).
+Its
+[`package.json`](https://github.com/agentclientprotocol/codex-acp/blob/87997e2627e8fa246a49de533c612f6196c4004e/package.json)
+defines the `codex-acp` command and exact adapter version. Its
+[`CodexAcpServer.ts`](https://github.com/agentclientprotocol/codex-acp/blob/87997e2627e8fa246a49de533c612f6196c4004e/src/CodexAcpServer.ts)
+returns the ACP identity, and
+[`CodexAcpClient.ts`](https://github.com/agentclientprotocol/codex-acp/blob/87997e2627e8fa246a49de533c612f6196c4004e/src/CodexAcpClient.ts)
+maps session MCP configuration into Codex App Server.
+
+The Codex MCP alias comes from
+[`rmcp_client.rs`](https://github.com/openai/codex/blob/dcfcb570b2cd0a2500b1d47a7b04a7cb1b0a0bd2/codex-rs/codex-mcp/src/rmcp_client.rs).
+OpenAI documents App Server as the protocol for embedding Codex in another
+product in the
+[`Codex App Server` documentation](https://learn.chatgpt.com/docs/app-server).
+Later Codex or adapter versions fail closed until the registry is reviewed and
+updated.
+
+## Setup
+
+1. Install Node.js `>=24.19.0 <25` and
+   `@agentclientprotocol/codex-acp` 1.8.0 through its normal package
+   installation process. Ambassador never installs or updates the adapter.
+2. Authenticate Codex through the adapter's normal ChatGPT login, or set
+   `CODEX_API_KEY` or `OPENAI_API_KEY` outside chat. The adapter owns provider
+   authentication.
+3. Generate the local MCP token without putting its value in chat or a command
+   argument:
+
+   ```sh
+   export AMBASSADOR_LOCAL_TOKEN="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+4. If you may choose webhook delivery, create its secret in the same shell
+   before starting Ambassador:
+
+   ```sh
+   export AMBASSADOR_WEBHOOK_SECRET="$(
+     node -e "process.stdout.write(require('node:crypto').randomBytes(24).toString('hex'))"
+   )"
+   ```
+
+5. From the directory the direct agent may access, start the exact release and
+   keep it running in the foreground:
+
+   ```sh
+   npx --yes @embassys/ambassador@0.2.6 start \
+     --local-token-env=AMBASSADOR_LOCAL_TOKEN
+   ```
+
+6. In a shell where `AMBASSADOR_LOCAL_TOKEN` is available, configure Codex to
+   use the endpoint printed by Ambassador:
+
+   ```sh
+   codex mcp add ambassador \
+     --url http://127.0.0.1:8787/mcp \
+     --bearer-token-env-var AMBASSADOR_LOCAL_TOKEN
+   ```
+
+7. Ask Codex to register with your email and optional display name. The first
+   `register_agent` call contains `email` and, if wanted, `display_name`.
+   Ambassador recognizes the Codex MCP profile and asks direct versus webhook,
+   with direct as the default.
+8. For direct mode, choose direct. The follow-up repeats the same `email` and
+   optional `display_name` and adds `delivery: {"mode":"direct"}`. Ambassador
+   starts `codex-acp` and injects its authenticated HTTP MCP server into the new
+   ACP session.
+9. For webhook mode, choose webhook and provide the HTTPS receiver URL plus
+   the environment-variable name `AMBASSADOR_WEBHOOK_SECRET`. The follow-up
+   repeats the registration fields and adds `delivery.mode`, `delivery.url`,
+   and `delivery.secret_env`; it never sends the secret value.
+10. Enter the email verification code when Codex asks for it. Codex calls
+    `verify_email` with that `email` and six-digit `code`; the central token and
+    DPoP key stay inside Ambassador.
+
+Ambassador does not pass `CODEX_PATH`, `CODEX_CONFIG`, or another executable or
+session override. It never receives Codex account credentials, the central
+token, or the DPoP private key. Never put the local token or a provider API key
+in chat or registration arguments.