@aexhq/sdk 0.13.6

package/dist/_contracts/proxy-protocol.js

@@ -0,0 +1,234 @@
+// Wire format between the in-container runtime bridge (mounted at
+// `/mnt/session/uploads/aex/aex`, invoked through `node`) and
+// the dashboard BFF proxy route
+// (`POST /api/runs/:runId/proxy/:endpointName`).
+//
+// This module is the single source of truth for the request shape, the
+// response shape, the error-code enum, and the protocol version header.
+// CLI and BFF both import from here; drift becomes a build-time type error.
+//
+/**
+ * Wire-protocol version. Bumped on any breaking change to the request or
+ * response shape. The CLI sends this in the `X-Aex-Proxy-Protocol`
+ * header on every request; the BFF rejects mismatches with HTTP 426
+ * `unsupported_protocol`.
+ *
+ * Bumps are coordinated: CLI and BFF release together, the worker
+ * bundles the matching CLI artifact, and the e2e suite runs both with
+ * the new version.
+ */
+export const PROXY_PROTOCOL_VERSION = "1";
+export const PROXY_PROTOCOL_HEADER = "x-aex-proxy-protocol";
+/**
+ * Default `User-Agent` the proxy attaches to every outbound request when
+ * the caller did not supply one via `allowHeaders`. Some upstreams reject
+ * requests that arrive without a meaningful UA — notably the Wikimedia
+ * family (Wikidata, Wikipedia, Wikimedia Commons), whose policy requires
+ * a contactable identifier and otherwise returns HTTP 403 with a
+ * `Please identify your user agent` body.
+ *
+ * Callers can override per request by listing `user-agent` in their
+ * endpoint's `allowHeaders` and setting it on the proxy call; the
+ * default only fires when nothing was forwarded.
+ *
+ * See <https://meta.wikimedia.org/wiki/User-Agent_policy>.
+ */
+export const PROXY_DEFAULT_USER_AGENT = "aex-proxy/1.0 (+https://aex.dev/contact)";
+export const PROXY_METHOD_HEADER = "x-aex-method";
+export const PROXY_PATH_HEADER = "x-aex-path";
+export const PROXY_QUERY_HEADER = "x-aex-query";
+export const PROXY_HEADERS_HEADER = "x-aex-headers";
+export const PROXY_RESPONSE_MODE_HEADER = "x-aex-response-mode";
+export const PROXY_ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+export const PROXY_RESPONSE_MODES = ["status_only", "headers_only", "full"];
+/**
+ * Narrowing order: a request may only narrow below the policy ceiling.
+ * `status_only` is narrowest, `full` is widest. The BFF computes
+ * `narrowest(policyMode, headerMode)` and ignores escalation attempts,
+ * auditing them as `mode_clamped`.
+ */
+const RESPONSE_MODE_WIDTH = {
+    status_only: 0,
+    headers_only: 1,
+    full: 2
+};
+/**
+ * Returns the narrower of the two response modes (lower width wins).
+ * Pure function so the CLI and BFF can both call it without import cycles.
+ */
+export function narrowResponseMode(policy, requested) {
+    return RESPONSE_MODE_WIDTH[requested] < RESPONSE_MODE_WIDTH[policy] ? requested : policy;
+}
+/**
+ * Error codes returned by the proxy route. Stable strings — the CLI
+ * matches against them in scripts. Adding a new code is non-breaking;
+ * removing or renaming an existing code requires a protocol bump.
+ */
+export const PROXY_ERROR_CODES = [
+    "unsupported_protocol",
+    "unauthorized",
+    "endpoint_not_found",
+    "policy_denied",
+    "rate_limited",
+    "budget_exceeded",
+    "ssrf_denied",
+    "upstream_timeout",
+    "upstream_error",
+    "exceeded_cap",
+    "bad_request",
+    "internal_error"
+];
+/**
+ * Default caps for a proxy endpoint when the submission doesn't specify
+ * one. Conservative on purpose. Lives in the protocol module (next to the
+ * index-file shape) so {@link buildProxyIndexFile} can fill every optional
+ * cap with a concrete value; the submission parser re-exports it.
+ */
+export const PROXY_ENDPOINT_DEFAULTS = {
+    allowHeaders: [],
+    responseMode: "headers_only",
+    maxRequestBytes: 64 * 1024,
+    maxResponseBytes: 1024 * 1024,
+    timeoutMs: 10_000,
+    perCallBudget: 60,
+    responseByteBudget: 1024 * 1024
+};
+/**
+ * Build the per-run {@link ProxyIndexFile} mounted into the container at
+ * `/mnt/session/uploads/aex/index.json`. Pure: applies
+ * {@link PROXY_ENDPOINT_DEFAULTS} so every optional cap is concrete, and
+ * carries ONLY the non-secret endpoint policy — auth values never appear.
+ *
+ * ALWAYS emits a file (the always-on surface). With zero endpoints OR no
+ * `proxyPublicBaseUrl`, `proxyBaseUrl` is `null` and `endpoints` is `[]`.
+ * Otherwise `proxyBaseUrl` is `<trimmed base>/api/runs/<runId>/proxy`, the
+ * prefix the in-container runtime bridge appends `/<endpointName>` to (proxy.ts).
+ */
+export function buildProxyIndexFile(input) {
+    const endpoints = input.endpoints ?? [];
+    const base = input.proxyPublicBaseUrl?.trim() ?? "";
+    const haveBase = base.length > 0;
+    const proxyBaseUrl = endpoints.length > 0 && haveBase
+        ? `${base.replace(/\/+$/, "")}/api/runs/${input.runId}/proxy`
+        : null;
+    return {
+        protocolVersion: PROXY_PROTOCOL_VERSION,
+        runId: input.runId,
+        proxyBaseUrl,
+        endpoints: endpoints.map((e) => ({
+            name: e.name,
+            baseUrl: e.baseUrl,
+            authShape: e.authShape,
+            allowMethods: e.allowMethods,
+            allowPathPrefixes: e.allowPathPrefixes,
+            allowHeaders: e.allowHeaders ?? PROXY_ENDPOINT_DEFAULTS.allowHeaders,
+            responseMode: e.responseMode ?? PROXY_ENDPOINT_DEFAULTS.responseMode,
+            maxRequestBytes: e.maxRequestBytes ?? PROXY_ENDPOINT_DEFAULTS.maxRequestBytes,
+            maxResponseBytes: e.maxResponseBytes ?? PROXY_ENDPOINT_DEFAULTS.maxResponseBytes,
+            timeoutMs: e.timeoutMs ?? PROXY_ENDPOINT_DEFAULTS.timeoutMs,
+            perCallBudget: e.perCallBudget ?? PROXY_ENDPOINT_DEFAULTS.perCallBudget,
+            responseByteBudget: e.responseByteBudget ?? PROXY_ENDPOINT_DEFAULTS.responseByteBudget
+        }))
+    };
+}
+/**
+ * Header name (lowercase) that an upstream auth shape uses as its
+ * carrier. Returns `undefined` for query-based and keyless auth.
+ *
+ * Used by the submission parser to forbid `allowHeaders` from listing
+ * the auth header (avoids leaks via caller-supplied headers), and by
+ * the proxy route to strip any caller header that would collide with
+ * the auth carrier at request time.
+ */
+export function authShapeHeaderName(shape) {
+    switch (shape.type) {
+        case "bearer":
+        case "basic":
+            return "authorization";
+        case "header":
+            return shape.name.toLowerCase();
+        case "query":
+        case "none":
+            return undefined;
+    }
+}
+/**
+ * Query-string key that an upstream query-based auth shape uses as its
+ * carrier. Returns `undefined` for non-query shapes (including "none").
+ */
+export function authShapeQueryName(shape) {
+    return shape.type === "query" ? shape.name : undefined;
+}
+/**
+ * Inbound request headers every Aex proxy plane STRIPS before
+ * forwarding a runtime/runner request upstream. Three categories:
+ *
+ *   - Credential carriers (`authorization`, `x-api-key`, `cookie`,
+ *     `proxy-authorization`) — these belong to Aex's own auth gate
+ *     (the per-run bearer) or to the caller, never the upstream. The
+ *     legitimate upstream credential is injected server-side from the
+ *     run's Vault bundle / endpoint auth shape AFTER this strip, so it is
+ *     never sourced from an inbound header.
+ *   - Hop-by-hop fields (RFC 7230 §6.1: `connection`, `keep-alive`,
+ *     `transfer-encoding`, `te`, `trailer`, `upgrade`, `expect`,
+ *     `proxy-authenticate`, `proxy-connection`) — must not survive a
+ *     proxy hop.
+ *   - Routing primitives a compromised runner could spoof to bypass an
+ *     upstream's IP allowlist / rate-limit (`host`, `content-length`,
+ *     `x-forwarded-*`, `x-real-ip`, `forwarded`).
+ *
+ * The api Worker provider-proxy and the dashboard MCP proxy strip exactly
+ * this set (both inject upstream auth separately — the provider key, or the
+ * Vault MCP-bundle headers, applied AFTER the strip). The dashboard
+ * customer HTTP proxy hard-denies this set MINUS `x-api-key`, because a
+ * customer endpoint may legitimately declare `x-api-key` as its auth
+ * carrier; it derives from this constant so the hop-by-hop + routing
+ * entries never drift. Keeping the membership here is the single source of
+ * truth that stops those surfaces diverging.
+ */
+export const PROXY_STRIPPED_INBOUND_HEADERS = new Set([
+    // credential carriers
+    "authorization",
+    "x-api-key",
+    "cookie",
+    "proxy-authorization",
+    // hop-by-hop (RFC 7230 §6.1)
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    "expect",
+    "proxy-authenticate",
+    "proxy-connection",
+    // routing primitives a runner could spoof
+    "host",
+    "content-length",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-proto",
+    "x-forwarded-port",
+    "x-real-ip",
+    "forwarded"
+]);
+/**
+ * Status code → error code mapping used by the BFF to ensure the audit
+ * row's error code and the HTTP response line up. Kept here so callers
+ * can do a sanity check in tests.
+ */
+export const PROXY_ERROR_HTTP_STATUS = {
+    unsupported_protocol: 426,
+    unauthorized: 401,
+    endpoint_not_found: 404,
+    policy_denied: 403,
+    rate_limited: 429,
+    budget_exceeded: 429,
+    ssrf_denied: 403,
+    upstream_timeout: 504,
+    upstream_error: 502,
+    exceeded_cap: 502,
+    bad_request: 400,
+    internal_error: 500
+};
+//# sourceMappingURL=proxy-protocol.js.map

package/dist/_contracts/proxy-validation.d.ts

@@ -0,0 +1,19 @@
+import type { PlatformProxyEndpoint, PlatformProxyEndpointAuth } from "./submission.js";
+/**
+ * Cross-validate a `proxyEndpoints` policy list against a
+ * `secrets.proxyEndpointAuth` value list. Throws on the first mismatch
+ * with an actionable, field-named error message.
+ *
+ * Mirrors the BFF's authoritative validator so misconfigured submissions
+ * fail fast in the SDK/CLI before going over the wire.
+ */
+export declare function validateProxyAuth(endpoints: readonly PlatformProxyEndpoint[], auth: readonly PlatformProxyEndpointAuth[] | undefined): void;
+/**
+ * Build an `allowedHosts` list for `environment.network` that includes
+ * the aex proxy host (and optionally Anthropic's MCP host) when the
+ * caller is hand-rolling networking.
+ */
+export declare function buildPlatformAllowedHosts(input: {
+    readonly baseUrl: string;
+    readonly extraHosts?: readonly string[];
+}): readonly string[];

package/dist/_contracts/proxy-validation.js

@@ -0,0 +1,51 @@
+/**
+ * Cross-validate a `proxyEndpoints` policy list against a
+ * `secrets.proxyEndpointAuth` value list. Throws on the first mismatch
+ * with an actionable, field-named error message.
+ *
+ * Mirrors the BFF's authoritative validator so misconfigured submissions
+ * fail fast in the SDK/CLI before going over the wire.
+ */
+export function validateProxyAuth(endpoints, auth) {
+    const authList = auth ?? [];
+    const endpointNames = new Set(endpoints.map((e) => e.name));
+    const authNames = new Set();
+    for (const entry of authList) {
+        if (authNames.has(entry.name)) {
+            throw new Error(`secrets.proxyEndpointAuth contains duplicate name '${entry.name}'`);
+        }
+        authNames.add(entry.name);
+        if (!endpointNames.has(entry.name)) {
+            throw new Error(`secrets.proxyEndpointAuth[].name='${entry.name}' has no matching proxyEndpoints[].name`);
+        }
+    }
+    for (const endpoint of endpoints) {
+        const match = authList.find((a) => a.name === endpoint.name);
+        if (!match) {
+            throw new Error(`proxyEndpoints[].name='${endpoint.name}' is missing a matching secrets.proxyEndpointAuth entry`);
+        }
+        if (match.value.type !== endpoint.authShape.type) {
+            throw new Error(`secrets.proxyEndpointAuth[name='${endpoint.name}'].value.type='${match.value.type}' does not match proxyEndpoints[name='${endpoint.name}'].authShape.type='${endpoint.authShape.type}'`);
+        }
+    }
+}
+/**
+ * Build an `allowedHosts` list for `environment.network` that includes
+ * the aex proxy host (and optionally Anthropic's MCP host) when the
+ * caller is hand-rolling networking.
+ */
+export function buildPlatformAllowedHosts(input) {
+    const result = [];
+    try {
+        result.push(new URL(input.baseUrl).host);
+    }
+    catch {
+        throw new Error("buildPlatformAllowedHosts: baseUrl must be an absolute URL");
+    }
+    for (const host of input.extraHosts ?? []) {
+        if (!result.includes(host))
+            result.push(host);
+    }
+    return result;
+}
+//# sourceMappingURL=proxy-validation.js.map

package/dist/_contracts/run-artifacts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Single source of truth for a run's artifact namespaces.
+ *
+ * Every run stores its artifacts under two sibling prefixes:
+ *
+ *   runs/<runId>/outputs/<rel>   — the run's real deliverables.
+ *   runs/<runId>/logs/<rel>      — platform diagnostics (`runtime/`,
+ *                                  `host/`, `provider-proxy/`,
+ *                                  `control-plane/`).
+ *
+ * The runner uploads every file with a workspace-relative path and the
+ * server decides the namespace from that path's prefix, so the split is
+ * owned here — the runner does not need to know about it. Diagnostics
+ * reach the upload route as workspace dotdirs (`.runtime-logs/...`,
+ * `.host-logs/...`, etc.); the stored path uses canonical log namespaces.
+ * Legacy diagnostic prefixes are normalized on read/write compatibility paths.
+ */
+export declare const RUN_OUTPUTS_PREFIX = "outputs";
+export declare const RUN_LOGS_PREFIX = "logs";
+/**
+ * Relative-path prefixes that mark a stored artifact as a platform diagnostic
+ * rather than a run deliverable. Dotted forms are upload-time paths; legacy
+ * forms are accepted so old records normalize to the canonical namespace.
+ */
+export declare const RUN_LOG_REL_PREFIXES: readonly [".runtime-logs/", ".host-logs/", ".provider-proxy/", ".control-plane/", ".anthropic-debug/", ".goose-logs/", ".fly-logs/", "runtime/", "host/", "provider-proxy/", "control-plane/", "anthropic-debug/", "goose-logs/", "fly-logs/"];
+/** True when a workspace-relative artifact path belongs to the `logs` namespace. */
+export declare function isRunLogRelPath(rel: string): boolean;
+/**
+ * The artifact's path relative to its namespace prefix as stored. Diagnostics
+ * are canonicalized (`.runtime-logs/x` -> `runtime/x`,
+ * legacy `.goose-logs/x` -> `runtime/x`, legacy `.fly-logs/x` -> `host/x`).
+ */
+export declare function runArtifactRel(rel: string): string;
+/**
+ * Storage key for a run artifact uploaded with relative path `rel`, routing
+ * diagnostics into `logs/` and everything else into `outputs/`.
+ */
+export declare function runArtifactKey(runId: string, rel: string): string;
+/** The `assets` namespace under a run's prefix. */
+export declare const RUN_ASSETS_PREFIX = "assets";
+/**
+ * Storage key for a run's snapshotted asset, addressed by its content hash.
+ * At submit, each referenced shared-store asset is copied here so the run owns
+ * its bytes. Accepts a `sha256:<hex>` hash or a bare 64-hex digest; the stored
+ * suffix is the hex.
+ */
+export declare function runAssetKey(runId: string, hash: string): string;

package/dist/_contracts/run-artifacts.js

@@ -0,0 +1,101 @@
+/**
+ * Single source of truth for a run's artifact namespaces.
+ *
+ * Every run stores its artifacts under two sibling prefixes:
+ *
+ *   runs/<runId>/outputs/<rel>   — the run's real deliverables.
+ *   runs/<runId>/logs/<rel>      — platform diagnostics (`runtime/`,
+ *                                  `host/`, `provider-proxy/`,
+ *                                  `control-plane/`).
+ *
+ * The runner uploads every file with a workspace-relative path and the
+ * server decides the namespace from that path's prefix, so the split is
+ * owned here — the runner does not need to know about it. Diagnostics
+ * reach the upload route as workspace dotdirs (`.runtime-logs/...`,
+ * `.host-logs/...`, etc.); the stored path uses canonical log namespaces.
+ * Legacy diagnostic prefixes are normalized on read/write compatibility paths.
+ */
+export const RUN_OUTPUTS_PREFIX = "outputs";
+export const RUN_LOGS_PREFIX = "logs";
+/**
+ * Relative-path prefixes that mark a stored artifact as a platform diagnostic
+ * rather than a run deliverable. Dotted forms are upload-time paths; legacy
+ * forms are accepted so old records normalize to the canonical namespace.
+ */
+export const RUN_LOG_REL_PREFIXES = [
+    ".runtime-logs/",
+    ".host-logs/",
+    ".provider-proxy/",
+    ".control-plane/",
+    ".anthropic-debug/",
+    ".goose-logs/",
+    ".fly-logs/",
+    "runtime/",
+    "host/",
+    "provider-proxy/",
+    "control-plane/",
+    "anthropic-debug/",
+    "goose-logs/",
+    "fly-logs/"
+];
+/** True when a workspace-relative artifact path belongs to the `logs` namespace. */
+export function isRunLogRelPath(rel) {
+    return RUN_LOG_REL_PREFIXES.some((prefix) => rel.startsWith(prefix));
+}
+/**
+ * The artifact's path relative to its namespace prefix as stored. Diagnostics
+ * are canonicalized (`.runtime-logs/x` -> `runtime/x`,
+ * legacy `.goose-logs/x` -> `runtime/x`, legacy `.fly-logs/x` -> `host/x`).
+ */
+export function runArtifactRel(rel) {
+    if (rel.startsWith(".runtime-logs/"))
+        return `runtime/${rel.slice(".runtime-logs/".length)}`;
+    if (rel.startsWith("runtime/"))
+        return rel;
+    if (rel.startsWith(".host-logs/"))
+        return `host/${rel.slice(".host-logs/".length)}`;
+    if (rel.startsWith("host/"))
+        return rel;
+    if (rel.startsWith(".provider-proxy/"))
+        return `provider-proxy/${rel.slice(".provider-proxy/".length)}`;
+    if (rel.startsWith("provider-proxy/"))
+        return rel;
+    if (rel.startsWith(".control-plane/"))
+        return `control-plane/${rel.slice(".control-plane/".length)}`;
+    if (rel.startsWith("control-plane/"))
+        return rel;
+    if (rel.startsWith(".goose-logs/"))
+        return `runtime/${rel.slice(".goose-logs/".length)}`;
+    if (rel.startsWith("goose-logs/"))
+        return `runtime/${rel.slice("goose-logs/".length)}`;
+    if (rel.startsWith(".fly-logs/"))
+        return `host/${rel.slice(".fly-logs/".length)}`;
+    if (rel.startsWith("fly-logs/"))
+        return `host/${rel.slice("fly-logs/".length)}`;
+    if (rel.startsWith(".anthropic-debug/"))
+        return `provider-proxy/${rel.slice(".anthropic-debug/".length)}`;
+    if (rel.startsWith("anthropic-debug/"))
+        return `provider-proxy/${rel.slice("anthropic-debug/".length)}`;
+    return rel;
+}
+/**
+ * Storage key for a run artifact uploaded with relative path `rel`, routing
+ * diagnostics into `logs/` and everything else into `outputs/`.
+ */
+export function runArtifactKey(runId, rel) {
+    const namespace = isRunLogRelPath(rel) ? RUN_LOGS_PREFIX : RUN_OUTPUTS_PREFIX;
+    return `runs/${runId}/${namespace}/${runArtifactRel(rel)}`;
+}
+/** The `assets` namespace under a run's prefix. */
+export const RUN_ASSETS_PREFIX = "assets";
+/**
+ * Storage key for a run's snapshotted asset, addressed by its content hash.
+ * At submit, each referenced shared-store asset is copied here so the run owns
+ * its bytes. Accepts a `sha256:<hex>` hash or a bare 64-hex digest; the stored
+ * suffix is the hex.
+ */
+export function runAssetKey(runId, hash) {
+    const hex = hash.startsWith("sha256:") ? hash.slice("sha256:".length) : hash;
+    return `runs/${runId}/${RUN_ASSETS_PREFIX}/${hex}`;
+}
+//# sourceMappingURL=run-artifacts.js.map