@agentproto/egress 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @agentproto/egress
+
+Outbound traffic control for agent sandboxes. Mode registry, provider allowlist, transport-agnostic proxy core.
+
+```bash
+npm install @agentproto/egress
+```
+
+## Concept
+
+Agent CLIs make outbound HTTP calls to upstream APIs (OpenAI, Anthropic, custom MCP servers, …). Letting the agent hold raw API keys means a `printenv` or prompt-injection-driven exfil leaks them. This package implements **the egress side of "agent uses the credential but never sees it"**: cooperative mode injects `$$SECRET[NAME]$$` placeholders into the agent's env; the host's egress proxy substitutes the real value at the network boundary.
+
+## Modes
+
+```
+off          no controls — raw creds in agent env (today's default)
+cooperative  $$SECRET[NAME]$$ placeholders + BASE_URL envs + HTTP_PROXY env
+strict       cooperative + sandbox-level enforcement (NAT or runtime mandate)
+paranoid     strict + TLS-MITM (catches anything new)
+```
+
+Hosts pick which modes their tier policy exposes. Bootstrap consumers branch on the mode's **declarative flags** (`emitsPlaceholders`, `emitsBaseUrlEnvs`, …) — never on the id, so adding a new mode never edits a switch.
+
+## Usage (host adapter)
+
+```ts
+import {
+  proxyEgressRequest,
+  COMMON_EGRESS_PROVIDERS,
+  EgressError,
+} from "@agentproto/egress"
+
+// In your HTTP framework (Hono / Express / Bun):
+const result = await proxyEgressRequest({
+  request: {
+    providerId: "openai",
+    path: "/chat/completions",
+    method: "POST",
+    headers: req.headers,
+    body: req.body,
+    search: req.search,
+  },
+  providers: COMMON_EGRESS_PROVIDERS,
+  resolver: async (name) => yourVault.lookup(guildId, name),
+})
+
+const upstream = await fetch(result.url, {
+  method: result.method,
+  headers: result.headers,
+  body: result.body,
+})
+
+// Audit the substitutions
+for (const r of result.substitutions) {
+  yourAudit.log({ guildId, secretName: r.name, resolved: r.resolved })
+}
+
+return upstream
+```
+
+## Modules
+
+- **`./modes`** — `EgressModeRegistry` + `DEFAULT_EGRESS_MODES`
+- **`./providers`** — `EgressProvider` + `COMMON_EGRESS_PROVIDERS` (openai, anthropic) + `composeEgressProviders` for extending
+- **`./proxy`** — `proxyEgressRequest` + `EgressError`
+
+## Related
+
+- **`@agentproto/secrets`** — declares `SecretExposure` shapes (env / file / egress-substitute) and the `$$SECRET[NAME]$$` substitution engine. This package depends on it.
+- **AIP-19** — SECRETS.md doctype declares what secrets exist + how they're exposed
+- **AIP-X (future)** — would standardize the egress mode taxonomy and the cooperative-mode wire shape
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+import { SecretResolver, SubstitutionRecord } from '@agentproto/secrets/exposure';
+
+/**
+ * Egress mode registry — describes how outbound traffic from an agent
+ * sandbox is controlled at the network boundary.
+ *
+ * Four canonical modes ship by default; hosts can `extend` with
+ * custom modes for their own infra. Bootstrap consumers branch on
+ * the mode's **declarative flags**, never on the id, so adding a
+ * new mode never edits a switch.
+ *
+ * # Mode hierarchy (weakest → strongest)
+ *   off          — no controls. Real credentials in agent env. Today's default.
+ *   cooperative  — agent sees `$$SECRET[NAME]$$` placeholders + BASE_URL envs
+ *                  + HTTP_PROXY env. Substituted by host's egress proxy at
+ *                  network boundary. Bypassable from inside (libs that
+ *                  ignore HTTP_PROXY); but agent has no real credentials.
+ *   strict       — cooperative + sandbox-level network enforcement (iptables
+ *                  NAT to local sidecar, or HTTP_PROXY enforced by container
+ *                  runtime). Agent literally cannot reach the network
+ *                  except via the proxy.
+ *   paranoid     — strict + TLS-MITM at the sidecar. Even calls to unknown
+ *                  destinations get intercepted. Catches anything new the
+ *                  agent might attempt.
+ *
+ * Hosts pick which modes are exposed to which guilds via their own
+ * tier/policy system (Guilde uses `PlanPolicy.egressModes`).
+ */
+type EgressModeId = "off" | "cooperative" | "strict" | "paranoid";
+interface EgressModeDefinition {
+    id: EgressModeId;
+    label: string;
+    description: string;
+    /** Surface-level state. UI shows a "preview" badge when not stable. */
+    status: "stable" | "preview" | "experimental";
+    /**
+     * Declarative bootstrap behavior. Bootstrap consumers branch on these
+     * flags, not on the id, so adding a new mode never edits a switch.
+     */
+    emitsPlaceholders: boolean;
+    emitsBaseUrlEnvs: boolean;
+    emitsHttpProxyEnvs: boolean;
+    /**
+     * Sandbox runtime requirements. When the host's runtime can't satisfy
+     * these (e.g. managed e2b without NET_ADMIN), the mode is unavailable
+     * AND the bootstrap should refuse to silently degrade — surface the
+     * shortfall so the operator can pick a different mode explicitly.
+     */
+    requiresSandboxNetCap: boolean;
+    requiresMitmCa: boolean;
+}
+/**
+ * Composable registry. Mirror of `EntitlementRegistry` shape from
+ * `@agstudio/core`/billing — same chainable methods so hosts can
+ * customize without forking the default set.
+ */
+declare class EgressModeRegistry {
+    private readonly entries;
+    register(def: EgressModeDefinition): this;
+    get(id: EgressModeId): EgressModeDefinition | undefined;
+    getAll(): EgressModeDefinition[];
+    /** Append entries from another source. Later wins on id collision. */
+    extend(defs: readonly EgressModeDefinition[]): this;
+    /** Drop entries by id. Useful for hosts that want to forbid a built-in. */
+    without(...ids: readonly EgressModeId[]): this;
+}
+/**
+ * Default registry pre-loaded with the four canonical modes. Hosts
+ * import this directly OR call `new EgressModeRegistry().extend(DEFAULT_EGRESS_MODES)`
+ * to start from a clean slate they own.
+ */
+declare const DEFAULT_EGRESS_MODES: readonly EgressModeDefinition[];
+/** Convenience factory — most hosts use this directly. */
+declare function createDefaultEgressModeRegistry(): EgressModeRegistry;
+
+/**
+ * Egress provider allowlist — the set of upstream URLs the proxy is
+ * willing to forward traffic to. Keeps the route from being a generic
+ * "proxy anywhere" hole.
+ *
+ * Hosts pick their own subset and may extend with private upstreams.
+ * Each entry is keyed by a stable provider id (`openai`, `anthropic`,
+ * …) used in the egress URL: `${apiUrl}/egress/<providerId>/...`.
+ *
+ * `pathPrefix` lets entries that have a versioned root (`/v1` for
+ * openai) match the SDK's default base URL convention — the agent's
+ * SDK sends `${BASE_URL}/chat/completions` and the proxy resolves to
+ * `${upstream}${pathPrefix}/chat/completions`.
+ */
+interface EgressProvider {
+    id: string;
+    /** Public origin (scheme + host). No trailing slash; no path. */
+    upstream: string;
+    /** Path prefix appended after the provider id in the egress URL.
+     *  e.g. `/v1` for openai so SDKs configured with
+     *  `OPENAI_BASE_URL=${apiUrl}/egress/openai/v1` work natively. */
+    pathPrefix?: string;
+    /** Header name SDKs use to send credentials. Information-only —
+     *  substitution happens on whatever header the agent sends; this
+     *  is for UI hints and audit grouping. */
+    authHeader?: string;
+}
+/**
+ * The shipped allowlist. Hosts compose by spreading this + their own.
+ * Kept narrow on purpose — the user-visible decision is "which providers
+ * does my proxy accept", not "which providers does the SDK universe
+ * support".
+ */
+declare const COMMON_EGRESS_PROVIDERS: Record<string, EgressProvider>;
+/** Convenience: build a registry from a base + extensions. */
+declare function composeEgressProviders(...sources: Array<Record<string, EgressProvider>>): Record<string, EgressProvider>;
+
+/**
+ * Transport-agnostic egress proxy core.
+ *
+ * Takes a normalized request shape + a provider lookup + a secret
+ * resolver, returns a normalized rewritten request ready to forward.
+ * Doesn't know about Hono, Express, or any HTTP framework — hosts
+ * adapt their server framework to this shape.
+ *
+ * Why split: keeps the proxy logic testable in isolation + lets new
+ * runtime hosts (Bun, Deno, Cloudflare Workers, etc.) reuse the same
+ * core without dragging in node:http or similar.
+ */
+
+/** Body type permissive enough for any reasonable runtime — node `fetch`,
+ *  Bun, Deno, Cloudflare Workers, browser. We don't pull in DOM types
+ *  (that would expose them to every consumer of this package); the
+ *  host's `fetch` call accepts whatever shape it understands. */
+type EgressBody = string | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | {
+    stream(): ReadableStream<Uint8Array>;
+};
+/** Inbound request shape — host-framework-agnostic. */
+interface EgressRequest {
+    /** Provider id from the URL — `/egress/<providerId>/...`. */
+    providerId: string;
+    /** Path inside the provider — what comes after `/egress/<providerId>`.
+     *  Should start with `/`. */
+    path: string;
+    /** HTTP method, uppercase. */
+    method: string;
+    /** Header bag — string values only (multi-value headers should be
+     *  pre-joined by the host framework). */
+    headers: Record<string, string>;
+    /** Optional request body. Substitution does NOT scan the body in
+     *  v0 — only headers. Body opt-in per provider lands later. */
+    body?: EgressBody | null;
+    /** Query string verbatim (with leading `?`) or empty string. */
+    search: string;
+}
+/** Outbound, rewritten request shape — what the host fetches. */
+interface RewrittenEgressRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: EgressBody | null;
+    /** Audit record — names of secrets that were substituted into the
+     *  outbound headers, in match order. */
+    substitutions: SubstitutionRecord[];
+}
+interface ProxyEgressRequestOptions {
+    request: EgressRequest;
+    /** Provider allowlist — typically `COMMON_EGRESS_PROVIDERS` merged
+     *  with host-specific entries. Unknown provider id → throws
+     *  EgressError("unknown_provider"). */
+    providers: Record<string, EgressProvider>;
+    /** Per-call secret resolver. The host wires its vault here. Returns
+     *  null when a placeholder name doesn't resolve — the proxy keeps
+     *  the placeholder verbatim and the upstream then 401s, which is
+     *  exactly the right surface (agent learns the secret isn't allowed
+     *  via the upstream's own auth-failure response). */
+    resolver: SecretResolver;
+}
+/**
+ * Build the rewritten request for an inbound egress call. The host
+ * uses the result with `fetch(rewritten.url, rewritten)` (or its
+ * runtime's equivalent). Audit records are returned alongside so the
+ * host can log per-call substitutions to its usage_events table.
+ *
+ * Throws `EgressError` with stable codes for the known failure modes
+ * — host framework adapter maps to its own HTTP responses (typically
+ * 400 / 404 / 500).
+ */
+declare function proxyEgressRequest(opts: ProxyEgressRequestOptions): Promise<RewrittenEgressRequest>;
+/** Stable error class for proxy-level failures. Codes:
+ *   - `unknown_provider`        — providerId not in allowlist
+ *   - `secret_value_empty`      — resolver returned an empty value
+ *   - `secret_value_unsafe`     — resolved value contained CR/LF/NUL
+ *   - `invalid_placeholder_name`— placeholder name failed regex
+ */
+declare class EgressError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
+export { COMMON_EGRESS_PROVIDERS, DEFAULT_EGRESS_MODES, EgressError, type EgressModeDefinition, type EgressModeId, EgressModeRegistry, type EgressProvider, type EgressRequest, type ProxyEgressRequestOptions, type RewrittenEgressRequest, composeEgressProviders, createDefaultEgressModeRegistry, proxyEgressRequest };

package/dist/index.mjs

@@ -0,0 +1,165 @@
+import { substituteSecrets, SecretSubstitutionError } from '@agentproto/secrets/exposure';
+
+/**
+ * @agentproto/egress v0.1.0-alpha
+ * Outbound traffic control for agent sandboxes — mode registry,
+ * proxy core, audit hooks. Cooperative mode delegates substitution
+ * to @agentproto/secrets/exposure.
+ */
+
+// src/modes.ts
+var EgressModeRegistry = class {
+  entries = /* @__PURE__ */ new Map();
+  register(def) {
+    this.entries.set(def.id, def);
+    return this;
+  }
+  get(id) {
+    return this.entries.get(id);
+  }
+  getAll() {
+    return [...this.entries.values()];
+  }
+  /** Append entries from another source. Later wins on id collision. */
+  extend(defs) {
+    for (const def of defs) this.register(def);
+    return this;
+  }
+  /** Drop entries by id. Useful for hosts that want to forbid a built-in. */
+  without(...ids) {
+    for (const id of ids) this.entries.delete(id);
+    return this;
+  }
+};
+var DEFAULT_EGRESS_MODES = [
+  {
+    id: "off",
+    label: "Direct (off)",
+    description: "No egress controls. Real credentials injected into agent env / files. Lowest latency; widest blast radius if the agent leaks.",
+    status: "stable",
+    emitsPlaceholders: false,
+    emitsBaseUrlEnvs: false,
+    emitsHttpProxyEnvs: false,
+    requiresSandboxNetCap: false,
+    requiresMitmCa: false
+  },
+  {
+    id: "cooperative",
+    label: "Cooperative",
+    description: "Agent sees only $$SECRET[NAME]$$ placeholders. Real credentials substituted at the host's egress proxy. Network bypassable by libs that ignore HTTP_PROXY, but the agent has nothing real to bypass with.",
+    status: "stable",
+    emitsPlaceholders: true,
+    emitsBaseUrlEnvs: true,
+    emitsHttpProxyEnvs: true,
+    requiresSandboxNetCap: false,
+    requiresMitmCa: false
+  },
+  {
+    id: "strict",
+    label: "Strict",
+    description: "Cooperative + sandbox-level enforcement (iptables NAT or runtime-level proxy mandate). Agent cannot reach the network except via the proxy.",
+    status: "preview",
+    emitsPlaceholders: true,
+    emitsBaseUrlEnvs: true,
+    emitsHttpProxyEnvs: true,
+    requiresSandboxNetCap: true,
+    requiresMitmCa: false
+  },
+  {
+    id: "paranoid",
+    label: "Paranoid",
+    description: "Strict + TLS-MITM at the sidecar. Catches any outbound call, including to destinations the host didn't anticipate. Breaks SDKs with cert pinning.",
+    status: "preview",
+    emitsPlaceholders: true,
+    emitsBaseUrlEnvs: true,
+    emitsHttpProxyEnvs: true,
+    requiresSandboxNetCap: true,
+    requiresMitmCa: true
+  }
+];
+function createDefaultEgressModeRegistry() {
+  return new EgressModeRegistry().extend(DEFAULT_EGRESS_MODES);
+}
+
+// src/providers.ts
+var COMMON_EGRESS_PROVIDERS = {
+  openai: {
+    id: "openai",
+    upstream: "https://api.openai.com",
+    pathPrefix: "/v1",
+    authHeader: "Authorization"
+  },
+  anthropic: {
+    id: "anthropic",
+    upstream: "https://api.anthropic.com",
+    authHeader: "x-api-key"
+  }
+};
+function composeEgressProviders(...sources) {
+  const out = {};
+  for (const src of sources) Object.assign(out, src);
+  return out;
+}
+async function proxyEgressRequest(opts) {
+  const provider = opts.providers[opts.request.providerId];
+  if (!provider) {
+    throw new EgressError(
+      "unknown_provider",
+      `Unknown egress provider '${opts.request.providerId}'.`
+    );
+  }
+  const url = buildUpstreamUrl(provider, opts.request.path, opts.request.search);
+  const rewrittenHeaders = {};
+  const allRecords = [];
+  for (const [name, value] of Object.entries(opts.request.headers)) {
+    if (HOP_BY_HOP.has(name.toLowerCase())) continue;
+    try {
+      const result = await substituteSecrets(value, opts.resolver);
+      rewrittenHeaders[name] = result.output;
+      allRecords.push(...result.replacements);
+    } catch (err) {
+      if (err instanceof SecretSubstitutionError) {
+        const sub = err;
+        throw new EgressError(sub.code, sub.message);
+      }
+      throw err;
+    }
+  }
+  delete rewrittenHeaders["host"];
+  delete rewrittenHeaders["Host"];
+  return {
+    url,
+    method: opts.request.method,
+    headers: rewrittenHeaders,
+    body: opts.request.body ?? null,
+    substitutions: allRecords
+  };
+}
+function buildUpstreamUrl(provider, path, search) {
+  const base = provider.upstream.replace(/\/$/, "");
+  const prefix = provider.pathPrefix?.replace(/\/$/, "") ?? "";
+  const normPath = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${prefix}${normPath}${search}`;
+}
+var HOP_BY_HOP = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+]);
+var EgressError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "EgressError";
+  }
+};
+
+export { COMMON_EGRESS_PROVIDERS, DEFAULT_EGRESS_MODES, EgressError, EgressModeRegistry, composeEgressProviders, createDefaultEgressModeRegistry, proxyEgressRequest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/modes.ts","../src/providers.ts","../src/proxy.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * Egress mode registry — describes how outbound traffic from an agent\n * sandbox is controlled at the network boundary.\n *\n * Four canonical modes ship by default; hosts can `extend` with\n * custom modes for their own infra. Bootstrap consumers branch on\n * the mode's **declarative flags**, never on the id, so adding a\n * new mode never edits a switch.\n *\n * # Mode hierarchy (weakest → strongest)\n *   off          — no controls. Real credentials in agent env. Today's default.\n *   cooperative  — agent sees `$$SECRET[NAME]$$` placeholders + BASE_URL envs\n *                  + HTTP_PROXY env. Substituted by host's egress proxy at\n *                  network boundary. Bypassable from inside (libs that\n *                  ignore HTTP_PROXY); but agent has no real credentials.\n *   strict       — cooperative + sandbox-level network enforcement (iptables\n *                  NAT to local sidecar, or HTTP_PROXY enforced by container\n *                  runtime). Agent literally cannot reach the network\n *                  except via the proxy.\n *   paranoid     — strict + TLS-MITM at the sidecar. Even calls to unknown\n *                  destinations get intercepted. Catches anything new the\n *                  agent might attempt.\n *\n * Hosts pick which modes are exposed to which guilds via their own\n * tier/policy system (Guilde uses `PlanPolicy.egressModes`).\n */\n\nexport type EgressModeId = \"off\" | \"cooperative\" | \"strict\" | \"paranoid\"\n\nexport interface EgressModeDefinition {\n  id: EgressModeId\n  label: string\n  description: string\n  /** Surface-level state. UI shows a \"preview\" badge when not stable. */\n  status: \"stable\" | \"preview\" | \"experimental\"\n  /**\n   * Declarative bootstrap behavior. Bootstrap consumers branch on these\n   * flags, not on the id, so adding a new mode never edits a switch.\n   */\n  emitsPlaceholders: boolean\n  emitsBaseUrlEnvs: boolean\n  emitsHttpProxyEnvs: boolean\n  /**\n   * Sandbox runtime requirements. When the host's runtime can't satisfy\n   * these (e.g. managed e2b without NET_ADMIN), the mode is unavailable\n   * AND the bootstrap should refuse to silently degrade — surface the\n   * shortfall so the operator can pick a different mode explicitly.\n   */\n  requiresSandboxNetCap: boolean\n  requiresMitmCa: boolean\n}\n\n/**\n * Composable registry. Mirror of `EntitlementRegistry` shape from\n * `@agstudio/core`/billing — same chainable methods so hosts can\n * customize without forking the default set.\n */\nexport class EgressModeRegistry {\n  private readonly entries = new Map<EgressModeId, EgressModeDefinition>()\n\n  register(def: EgressModeDefinition): this {\n    this.entries.set(def.id, def)\n    return this\n  }\n\n  get(id: EgressModeId): EgressModeDefinition | undefined {\n    return this.entries.get(id)\n  }\n\n  getAll(): EgressModeDefinition[] {\n    return [...this.entries.values()]\n  }\n\n  /** Append entries from another source. Later wins on id collision. */\n  extend(defs: readonly EgressModeDefinition[]): this {\n    for (const def of defs) this.register(def)\n    return this\n  }\n\n  /** Drop entries by id. Useful for hosts that want to forbid a built-in. */\n  without(...ids: readonly EgressModeId[]): this {\n    for (const id of ids) this.entries.delete(id)\n    return this\n  }\n}\n\n/**\n * Default registry pre-loaded with the four canonical modes. Hosts\n * import this directly OR call `new EgressModeRegistry().extend(DEFAULT_EGRESS_MODES)`\n * to start from a clean slate they own.\n */\nexport const DEFAULT_EGRESS_MODES: readonly EgressModeDefinition[] = [\n  {\n    id: \"off\",\n    label: \"Direct (off)\",\n    description:\n      \"No egress controls. Real credentials injected into agent env / files. Lowest latency; widest blast radius if the agent leaks.\",\n    status: \"stable\",\n    emitsPlaceholders: false,\n    emitsBaseUrlEnvs: false,\n    emitsHttpProxyEnvs: false,\n    requiresSandboxNetCap: false,\n    requiresMitmCa: false,\n  },\n  {\n    id: \"cooperative\",\n    label: \"Cooperative\",\n    description:\n      \"Agent sees only $$SECRET[NAME]$$ placeholders. Real credentials substituted at the host's egress proxy. Network bypassable by libs that ignore HTTP_PROXY, but the agent has nothing real to bypass with.\",\n    status: \"stable\",\n    emitsPlaceholders: true,\n    emitsBaseUrlEnvs: true,\n    emitsHttpProxyEnvs: true,\n    requiresSandboxNetCap: false,\n    requiresMitmCa: false,\n  },\n  {\n    id: \"strict\",\n    label: \"Strict\",\n    description:\n      \"Cooperative + sandbox-level enforcement (iptables NAT or runtime-level proxy mandate). Agent cannot reach the network except via the proxy.\",\n    status: \"preview\",\n    emitsPlaceholders: true,\n    emitsBaseUrlEnvs: true,\n    emitsHttpProxyEnvs: true,\n    requiresSandboxNetCap: true,\n    requiresMitmCa: false,\n  },\n  {\n    id: \"paranoid\",\n    label: \"Paranoid\",\n    description:\n      \"Strict + TLS-MITM at the sidecar. Catches any outbound call, including to destinations the host didn't anticipate. Breaks SDKs with cert pinning.\",\n    status: \"preview\",\n    emitsPlaceholders: true,\n    emitsBaseUrlEnvs: true,\n    emitsHttpProxyEnvs: true,\n    requiresSandboxNetCap: true,\n    requiresMitmCa: true,\n  },\n]\n\n/** Convenience factory — most hosts use this directly. */\nexport function createDefaultEgressModeRegistry(): EgressModeRegistry {\n  return new EgressModeRegistry().extend(DEFAULT_EGRESS_MODES)\n}\n","/**\n * Egress provider allowlist — the set of upstream URLs the proxy is\n * willing to forward traffic to. Keeps the route from being a generic\n * \"proxy anywhere\" hole.\n *\n * Hosts pick their own subset and may extend with private upstreams.\n * Each entry is keyed by a stable provider id (`openai`, `anthropic`,\n * …) used in the egress URL: `${apiUrl}/egress/<providerId>/...`.\n *\n * `pathPrefix` lets entries that have a versioned root (`/v1` for\n * openai) match the SDK's default base URL convention — the agent's\n * SDK sends `${BASE_URL}/chat/completions` and the proxy resolves to\n * `${upstream}${pathPrefix}/chat/completions`.\n */\n\nexport interface EgressProvider {\n  id: string\n  /** Public origin (scheme + host). No trailing slash; no path. */\n  upstream: string\n  /** Path prefix appended after the provider id in the egress URL.\n   *  e.g. `/v1` for openai so SDKs configured with\n   *  `OPENAI_BASE_URL=${apiUrl}/egress/openai/v1` work natively. */\n  pathPrefix?: string\n  /** Header name SDKs use to send credentials. Information-only —\n   *  substitution happens on whatever header the agent sends; this\n   *  is for UI hints and audit grouping. */\n  authHeader?: string\n}\n\n/**\n * The shipped allowlist. Hosts compose by spreading this + their own.\n * Kept narrow on purpose — the user-visible decision is \"which providers\n * does my proxy accept\", not \"which providers does the SDK universe\n * support\".\n */\nexport const COMMON_EGRESS_PROVIDERS: Record<string, EgressProvider> = {\n  openai: {\n    id: \"openai\",\n    upstream: \"https://api.openai.com\",\n    pathPrefix: \"/v1\",\n    authHeader: \"Authorization\",\n  },\n  anthropic: {\n    id: \"anthropic\",\n    upstream: \"https://api.anthropic.com\",\n    authHeader: \"x-api-key\",\n  },\n}\n\n/** Convenience: build a registry from a base + extensions. */\nexport function composeEgressProviders(\n  ...sources: Array<Record<string, EgressProvider>>\n): Record<string, EgressProvider> {\n  const out: Record<string, EgressProvider> = {}\n  for (const src of sources) Object.assign(out, src)\n  return out\n}\n","/**\n * Transport-agnostic egress proxy core.\n *\n * Takes a normalized request shape + a provider lookup + a secret\n * resolver, returns a normalized rewritten request ready to forward.\n * Doesn't know about Hono, Express, or any HTTP framework — hosts\n * adapt their server framework to this shape.\n *\n * Why split: keeps the proxy logic testable in isolation + lets new\n * runtime hosts (Bun, Deno, Cloudflare Workers, etc.) reuse the same\n * core without dragging in node:http or similar.\n */\n\nimport {\n  substituteSecrets,\n  SecretSubstitutionError,\n  type SecretResolver,\n  type SubstitutionRecord,\n} from \"@agentproto/secrets/exposure\"\nimport type { EgressProvider } from \"./providers.js\"\n\n/** Body type permissive enough for any reasonable runtime — node `fetch`,\n *  Bun, Deno, Cloudflare Workers, browser. We don't pull in DOM types\n *  (that would expose them to every consumer of this package); the\n *  host's `fetch` call accepts whatever shape it understands. */\nexport type EgressBody =\n  | string\n  | Uint8Array\n  | ArrayBuffer\n  | ReadableStream<Uint8Array>\n  | { stream(): ReadableStream<Uint8Array> }   // Blob-shaped\n\n/** Inbound request shape — host-framework-agnostic. */\nexport interface EgressRequest {\n  /** Provider id from the URL — `/egress/<providerId>/...`. */\n  providerId: string\n  /** Path inside the provider — what comes after `/egress/<providerId>`.\n   *  Should start with `/`. */\n  path: string\n  /** HTTP method, uppercase. */\n  method: string\n  /** Header bag — string values only (multi-value headers should be\n   *  pre-joined by the host framework). */\n  headers: Record<string, string>\n  /** Optional request body. Substitution does NOT scan the body in\n   *  v0 — only headers. Body opt-in per provider lands later. */\n  body?: EgressBody | null\n  /** Query string verbatim (with leading `?`) or empty string. */\n  search: string\n}\n\n/** Outbound, rewritten request shape — what the host fetches. */\nexport interface RewrittenEgressRequest {\n  url: string\n  method: string\n  headers: Record<string, string>\n  body?: EgressBody | null\n  /** Audit record — names of secrets that were substituted into the\n   *  outbound headers, in match order. */\n  substitutions: SubstitutionRecord[]\n}\n\nexport interface ProxyEgressRequestOptions {\n  request: EgressRequest\n  /** Provider allowlist — typically `COMMON_EGRESS_PROVIDERS` merged\n   *  with host-specific entries. Unknown provider id → throws\n   *  EgressError(\"unknown_provider\"). */\n  providers: Record<string, EgressProvider>\n  /** Per-call secret resolver. The host wires its vault here. Returns\n   *  null when a placeholder name doesn't resolve — the proxy keeps\n   *  the placeholder verbatim and the upstream then 401s, which is\n   *  exactly the right surface (agent learns the secret isn't allowed\n   *  via the upstream's own auth-failure response). */\n  resolver: SecretResolver\n}\n\n/**\n * Build the rewritten request for an inbound egress call. The host\n * uses the result with `fetch(rewritten.url, rewritten)` (or its\n * runtime's equivalent). Audit records are returned alongside so the\n * host can log per-call substitutions to its usage_events table.\n *\n * Throws `EgressError` with stable codes for the known failure modes\n * — host framework adapter maps to its own HTTP responses (typically\n * 400 / 404 / 500).\n */\nexport async function proxyEgressRequest(\n  opts: ProxyEgressRequestOptions\n): Promise<RewrittenEgressRequest> {\n  const provider = opts.providers[opts.request.providerId]\n  if (!provider) {\n    throw new EgressError(\n      \"unknown_provider\",\n      `Unknown egress provider '${opts.request.providerId}'.`\n    )\n  }\n\n  const url = buildUpstreamUrl(provider, opts.request.path, opts.request.search)\n\n  // Substitute headers. Body left as-is for v0.\n  const rewrittenHeaders: Record<string, string> = {}\n  const allRecords: SubstitutionRecord[] = []\n  for (const [name, value] of Object.entries(opts.request.headers)) {\n    // Strip per-hop headers — they describe the ingress hop, not the\n    // upstream. Standard reverse-proxy hygiene.\n    if (HOP_BY_HOP.has(name.toLowerCase())) continue\n    try {\n      const result = await substituteSecrets(value, opts.resolver)\n      rewrittenHeaders[name] = result.output\n      allRecords.push(...result.replacements)\n    } catch (err: unknown) {\n      if (err instanceof SecretSubstitutionError) {\n        // Re-raise as EgressError so host framework sees a single\n        // exception class (with the original code preserved). Local\n        // binding annotation works around a tsup-dts narrowing quirk\n        // where `err` stays `unknown` in the d.ts pipeline despite\n        // the runtime `instanceof` narrowing it for esbuild.\n        const sub: SecretSubstitutionError = err\n        throw new EgressError(sub.code, sub.message)\n      }\n      throw err\n    }\n  }\n\n  // Don't drop the upstream Host header — let `fetch` populate it\n  // from the URL. The original Host (the proxy's hostname) is\n  // wrong for the upstream.\n  delete rewrittenHeaders[\"host\"]\n  delete rewrittenHeaders[\"Host\"]\n\n  return {\n    url,\n    method: opts.request.method,\n    headers: rewrittenHeaders,\n    body: opts.request.body ?? null,\n    substitutions: allRecords,\n  }\n}\n\nfunction buildUpstreamUrl(\n  provider: EgressProvider,\n  path: string,\n  search: string\n): string {\n  const base = provider.upstream.replace(/\\/$/, \"\")\n  const prefix = provider.pathPrefix?.replace(/\\/$/, \"\") ?? \"\"\n  // Ensure exactly one slash between prefix and path.\n  const normPath = path.startsWith(\"/\") ? path : `/${path}`\n  return `${base}${prefix}${normPath}${search}`\n}\n\n/** Per-RFC-7230. Filtered before forwarding upstream. */\nconst HOP_BY_HOP = new Set([\n  \"connection\",\n  \"keep-alive\",\n  \"proxy-authenticate\",\n  \"proxy-authorization\",\n  \"te\",\n  \"trailer\",\n  \"transfer-encoding\",\n  \"upgrade\",\n])\n\n/** Stable error class for proxy-level failures. Codes:\n *   - `unknown_provider`        — providerId not in allowlist\n *   - `secret_value_empty`      — resolver returned an empty value\n *   - `secret_value_unsafe`     — resolved value contained CR/LF/NUL\n *   - `invalid_placeholder_name`— placeholder name failed regex\n */\nexport class EgressError extends Error {\n  readonly code: string\n  constructor(code: string, message: string) {\n    super(message)\n    this.code = code\n    this.name = \"EgressError\"\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agentproto/egress",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/egress — outbound traffic control for agent sandboxes. Mode registry (off / cooperative / strict / paranoid), provider allowlist, transport-agnostic proxy core, audit hooks. Cooperative mode delegates substitution to @agentproto/secrets so the agent never sees raw upstream credentials. Strict / paranoid modes (network-level enforcement via NAT or TLS-MITM) ship as conventions; the helpers land per-host as the sandbox runtimes mature.",
+  "keywords": [
+    "agentproto",
+    "egress",
+    "proxy",
+    "secrets",
+    "agent-sandbox",
+    "open-standard"
+  ],
+  "homepage": "https://agentproto.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/egress"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentproto/secrets": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}