@stigmer/server 3.18.0 → 3.18.1-dev.20260919070736

package/src/extensions/__tests__/outbound-egress-points.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Pins the outboundEgress driver point in the single-instance shape the
+ * registry already enforces for policyGrantScope and licenseStatus:
+ *
+ *   - `drivers.outboundEgress` — the address policy the composition root
+ *     builds the McpServer slice's one guarded fetch from; single instance;
+ *     absent = open source's relaxed posture installs at the compose.ts
+ *     consumption site.
+ *
+ * And the two exported postures: relaxed refuses only the link-local
+ * (cloud metadata) range, strict refuses loopback, private and unspecified
+ * too, and neither owns a copy of the ranges (both read the shared table).
+ */
+import { describe, expect, it } from "vitest";
+
+import { relaxedEgressPolicy, strictEgressPolicy } from "../outbound-egress.js";
+import { resolveExtensions } from "../registry.js";
+
+describe("the outboundEgress driver point", () => {
+  it("is undefined with no extensions — the relaxed posture installs at the consumption site", () => {
+    expect(resolveExtensions([]).drivers.outboundEgress).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const policy = strictEgressPolicy();
+    const resolved = resolveExtensions([{ name: "cloud-core", drivers: { outboundEgress: policy } }]);
+    expect(resolved.drivers.outboundEgress).toBe(policy);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "egress-a", drivers: { outboundEgress: strictEgressPolicy() } },
+        { name: "egress-b", drivers: { outboundEgress: relaxedEgressPolicy() } },
+      ]),
+    ).toThrowError(/extension 'egress-b' registers an OutboundEgressPolicy, but 'egress-a' already did/);
+  });
+});
+
+describe("the two postures", () => {
+  it("relaxed refuses only the link-local range, so a local MCP server stays reachable", () => {
+    const relaxed = relaxedEgressPolicy();
+    expect(relaxed.name).toBe("relaxed");
+    expect(relaxed.blockedReason("127.0.0.1")).toBeNull();
+    expect(relaxed.blockedReason("10.0.0.1")).toBeNull();
+    expect(relaxed.blockedReason("169.254.169.254")).toBe("link-local (cloud metadata)");
+  });
+
+  it("strict refuses loopback, private, link-local and unspecified addresses", () => {
+    const strict = strictEgressPolicy();
+    expect(strict.name).toBe("strict");
+    expect(strict.blockedReason("127.0.0.1")).toBe("loopback");
+    expect(strict.blockedReason("10.0.0.1")).toBe("private (RFC 1918)");
+    expect(strict.blockedReason("169.254.169.254")).toBe("link-local (cloud metadata)");
+    expect(strict.blockedReason("0.0.0.0")).toBe("unspecified");
+    expect(strict.blockedReason("104.16.0.1")).toBeNull();
+  });
+});

package/src/extensions/drivers.ts

@@ -31,6 +31,10 @@
  *     port, which kinds an edition grants on, and the tuple-half query
  *     engine only an authorization backend can answer) — landed with
  *     20260913.01, gate ruling Q-OR-10
+ *   - outbound egress (which addresses the control plane may dial when
+ *     it reaches a URL a user supplied: the MCP endpoint it probes at save
+ *     time and the login server it reaches on Sign in) — landed with the
+ *     save-time OAuth completion for URL-only MCP servers, 2026-09-19
  *
  * Merge rules (enforced by resolveExtensions, DD-006 §2b): the two
  * provider kinds are single-instance points — a second declaring unit is
@@ -54,6 +58,7 @@ import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { LicenseStatusProvider } from "./license-status.js";
+import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
@@ -230,4 +235,16 @@ export interface ExtensionDrivers {
    * way (extensions/license-status.ts carries the contract).
    */
   readonly licenseStatus?: LicenseStatusProvider;
+  /**
+   * The outbound-egress policy (single-instance point): which addresses
+   * this edition's control plane may dial when it reaches a URL a user
+   * supplied. The composition root builds one guarded fetch from it and
+   * hands it to the McpServer connect slice, the only fetch its OAuth code
+   * and its save-time endpoint probe hold. When absent, open source's
+   * `relaxedEgressPolicy()` installs at the compose.ts consumption site:
+   * everything but the link-local (cloud metadata) range is allowed, so a
+   * server beside a self-hosted control plane keeps working
+   * (extensions/outbound-egress.ts carries the contract).
+   */
+  readonly outboundEgress?: OutboundEgressPolicy;
 }

package/src/extensions/outbound-egress.ts

@@ -0,0 +1,55 @@
+/**
+ * The outbound-egress driver point: WHICH addresses this edition's control
+ * plane may dial when it reaches a URL a user supplied. Single instance,
+ * registered as `drivers.outboundEgress` (the policyGrantScope shape: a
+ * driver point whose absence is open source's own behaviour). Absent, the
+ * composition root installs `relaxedEgressPolicy()`: everything but the
+ * link-local range is allowed, because a server beside a self-hosted
+ * control plane (`http://localhost:3000/mcp`, the proto's own example) is
+ * the normal case and the link-local range, which carries the cloud
+ * metadata endpoint, costs a local user nothing to refuse. The cloud
+ * registers `strictEgressPolicy()`: loopback, private, link-local and
+ * unspecified refused, because its control plane sits on infrastructure
+ * with reach to internal services.
+ *
+ * Who reads it: nobody in the domains directly. The composition root builds
+ * ONE guarded fetch from the policy (`@stigmer/outbound/egress`
+ * `guardedFetch`, which judges the first URL and every redirect hop) and
+ * hands it to the McpServer connect slice as `outboundFetch`, the only
+ * fetch the McpServer domain's OAuth code and its save-time endpoint probe
+ * hold. Before this point existed every OAuth fetch (discovery, dynamic
+ * client registration, the authorize preflight, token exchange and
+ * refresh) defaulted to the raw global `fetch` in every edition, which is
+ * the exposure the point closes.
+ *
+ * The contract every policy is held to:
+ *
+ *   - It judges ADDRESSES, not names: the check resolves a hostname and
+ *     asks about every address it has, so a name with one public and one
+ *     private record is refused. A policy that wanted a hostname allowlist
+ *     would be a different seam.
+ *   - It is TOTAL: an unparseable address is refused ("unrecognized"),
+ *     never a throw.
+ *   - It is SYNCHRONOUS: an edition's egress posture is a fact about where
+ *     it runs, never I/O.
+ *
+ * Both constructors are thin over the shared classification in
+ * `@stigmer/outbound/egress`, so a composition registers a posture and owns
+ * no copy of the ranges; the runner's `web_fetch` guard reads the same
+ * table, so the two processes refuse the same addresses under the same
+ * posture name.
+ */
+import { egressPolicyForPosture, type EgressPolicy } from "@stigmer/outbound/egress";
+
+/** The egress contract (single-instance point, ExtensionDrivers.outboundEgress). */
+export type OutboundEgressPolicy = EgressPolicy;
+
+/** Open source's own posture: only the link-local (cloud metadata) range is refused. */
+export function relaxedEgressPolicy(): OutboundEgressPolicy {
+  return egressPolicyForPosture("relaxed");
+}
+
+/** The managed-cloud posture: loopback, private, link-local and unspecified addresses refused. */
+export function strictEgressPolicy(): OutboundEgressPolicy {
+  return egressPolicyForPosture("strict");
+}

package/src/extensions/registry.ts

@@ -54,6 +54,7 @@ import { V1_VERSION } from "../encryption/v1-codec.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { LicenseStatusProvider } from "./license-status.js";
+import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
@@ -278,6 +279,11 @@ export interface ResolvedExtensionDrivers {
    * built-in `absent` answer, so every edition serves getLicenseStatus.
    */
   readonly licenseStatus: LicenseStatusProvider | undefined;
+  /**
+   * The outbound-egress policy — undefined = compose.ts installs open
+   * source's relaxed posture (only the link-local range refused).
+   */
+  readonly outboundEgress: OutboundEgressPolicy | undefined;
 }
 
 /**
@@ -333,6 +339,8 @@ export function resolveExtensions(
   let authorizationQueriesDeclaredBy: string | undefined;
   let licenseStatus: LicenseStatusProvider | undefined;
   let licenseStatusDeclaredBy: string | undefined;
+  let outboundEgress: OutboundEgressPolicy | undefined;
+  let outboundEgressDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -534,6 +542,16 @@ export function resolveExtensions(
       licenseStatusDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.outboundEgress !== undefined) {
+      if (outboundEgressDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers an OutboundEgressPolicy, but '${outboundEgressDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      outboundEgress = unit.drivers.outboundEgress;
+      outboundEgressDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -660,6 +678,7 @@ export function resolveExtensions(
       policyGrantScope,
       authorizationQueries,
       licenseStatus,
+      outboundEgress,
     },
     services,
     workers,

package/src/index.ts

@@ -119,6 +119,16 @@ export type {
   LicenseStatusProvider,
   LicenseStatusReport,
 } from "./extensions/license-status.js";
+// The outbound-egress seam (drivers.outboundEgress): which addresses the
+// control plane may dial when it reaches a URL a user supplied. Both
+// postures are exported so a composition registers one line and owns no
+// copy of the address ranges (the classification lives in
+// @stigmer/outbound/egress, shared with the runner's web_fetch guard).
+export type { OutboundEgressPolicy } from "./extensions/outbound-egress.js";
+export {
+  relaxedEgressPolicy,
+  strictEgressPolicy,
+} from "./extensions/outbound-egress.js";
 // The 20260911.11 identity-account seams (Q-IA-9): the store PORT a
 // composition drives the domain through (drivers.identityAccountStore;
 // a driver throws DuplicateAccountError for a held id), the federation

package/src/pipeline/apiresource-labels.ts

@@ -82,6 +82,22 @@ export const PLUGIN_LABEL = `${RESERVED_LABEL_PREFIX}plugin`;
  */
 export const PLUGIN_VERSION_LABEL = `${RESERVED_LABEL_PREFIX}plugin-version`;
 
+/**
+ * How an MCP server's `spec.auth` came to be. The one value, `endpoint`,
+ * says the server itself completed it: the author supplied a URL and
+ * nothing about authentication, the endpoint answered the save-time probe
+ * with an OAuth challenge, and the server wrote the token variable, its
+ * declaration and the Bearer header (domain/mcpserver/complete-endpoint-auth.ts).
+ * The label is provenance, not permission: it lets the next save tell a
+ * completion it may reuse from an author's own `auth` it must not touch.
+ * Stamped through the server-stamped mechanism; dropped when the author
+ * writes their own `auth`.
+ */
+export const MCP_AUTH_LABEL = `${RESERVED_LABEL_PREFIX}mcp-auth`;
+
+/** The MCP_AUTH_LABEL value for a completion the endpoint's own challenge produced. */
+export const MCP_AUTH_ENDPOINT = "endpoint";
+
 /** The plugin id a resource's labels claim, or undefined when unlabelled. */
 export function pluginIdOf(
   metadata: ApiResourceMetadata | undefined,