@stigmer/server 3.40.1 → 3.41.0

package/src/boot/__tests__/compose.test.ts

@@ -12,7 +12,14 @@
  *     cannot bind fails start() with the address and the setting named and
  *     the server never reports itself serving (stigmer#1089), and a server
  *     on an ephemeral port gets an ephemeral lane whose minted download
- *     URLs reach it.
+ *     URLs reach it;
+ *   - the skill transfer lane's capability URLs on an ephemeral unified
+ *     port name the port the server bound, and a PUT to one reaches it
+ *     (stigmer#1386);
+ *   - a served console's MCP OAuth callback is derived on the public
+ *     origin the operator named in SKILL_TRANSFER_BASE_URL, whatever the
+ *     port, and without one an ephemeral port still derives nothing
+ *     (stigmer#1200).
  */
 import { createClient } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
@@ -22,6 +29,7 @@ import {
 } from "@stigmer/protos/grpc/health/v1/health_pb";
 import { ArtifactCommandController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/command_pb";
 import { ArtifactQueryController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/query_pb";
+import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
 import {
   createServer as netCreateServer,
   connect as netConnect,
@@ -29,13 +37,15 @@ import {
 import type { AddressInfo } from "node:net";
 import { describe, expect, it } from "vitest";
 
-import { mkdtempSync } from "node:fs";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
 import { loadConfig } from "../config.js";
 import { composeServer } from "../compose.js";
 import { createLogger } from "../logger.js";
+import type { LogEntry, Logger } from "../logger.js";
+import { seedOrganizations } from "../../domain/organization/__tests__/support.js";
 
 const silentLogger = createLogger({
   level: "error",
@@ -43,7 +53,7 @@ const silentLogger = createLogger({
   write: () => {},
 });
 
-function compose(env: NodeJS.ProcessEnv = {}) {
+function compose(env: NodeJS.ProcessEnv = {}, logger: Logger = silentLogger) {
   // Each composed server gets a throwaway database — the storage stage
   // opens DB_PATH for real (never the developer's ~/.stigmer).
   const testDir = mkdtempSync(path.join(tmpdir(), "compose-test-"));
@@ -63,7 +73,7 @@ function compose(env: NodeJS.ProcessEnv = {}) {
   });
   return composeServer({
     config,
-    logger: silentLogger,
+    logger,
     portOverride: 0,
     host: "127.0.0.1",
   });
@@ -165,3 +175,109 @@ describe("the artifact download lane", () => {
     }
   });
 });
+
+describe("the skill transfer lane", () => {
+  it("mints upload URLs for the port an ephemeral unified listener bound, and a PUT to one reaches it", async () => {
+    const server = await compose();
+    const port = await server.start();
+    try {
+      const transport = createGrpcTransport({
+        baseUrl: `http://127.0.0.1:${port}`,
+      });
+      await seedOrganizations(transport, ["acme"]);
+      const command = createClient(SkillCommandController, transport);
+      // The lane stages bytes as given; the archive is validated at push,
+      // which this case does not reach.
+      const body = new TextEncoder().encode("staged skill bytes\n");
+      const minted = await command.createArtifactUploadUrl({
+        org: "acme",
+        sizeBytes: BigInt(body.length),
+      });
+
+      // The bound port, never localhost:0 or the config default 7234.
+      expect(Number(new URL(minted.url).port)).toBe(port);
+      const put = await fetch(minted.url, {
+        method: "PUT",
+        body,
+        headers: { "content-type": "application/zip" },
+      });
+      expect(put.status).toBe(204);
+    } finally {
+      await server.shutdown();
+    }
+  });
+});
+
+describe("the MCP OAuth callback", () => {
+  /** A console export the console lane discovers: the app shell alone. */
+  function consoleExport(): string {
+    const dir = path.join(
+      mkdtempSync(path.join(tmpdir(), "compose-console-")),
+      "console",
+    );
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, "index.html"), "<html>app shell</html>");
+    return dir;
+  }
+
+  /** A logger that keeps every entry at or above info, for the wiring-time lines. */
+  function capturingLogger(): { logger: Logger; entries: LogEntry[] } {
+    const entries: LogEntry[] = [];
+    const logger = createLogger({
+      level: "info",
+      pretty: false,
+      write: () => {},
+      sink: (entry) => entries.push(entry),
+    });
+    return { logger, entries };
+  }
+
+  it("derives the served console's callback on the named public origin, on an ephemeral port too", async () => {
+    const { logger, entries } = capturingLogger();
+    const server = await compose(
+      {
+        STIGMER_CONSOLE_DIR: consoleExport(),
+        SKILL_TRANSFER_BASE_URL: "https://stigmer.example.test/",
+      },
+      logger,
+    );
+    await server.start();
+    try {
+      const derived = entries.find((entry) =>
+        entry.message.startsWith(
+          "STIGMER_OAUTH_REDIRECT_URI is not set — deriving",
+        ),
+      );
+      expect(derived?.fields).toEqual({
+        redirectUri: "https://stigmer.example.test/auth/oauth/callback",
+        from: "public-origin",
+      });
+    } finally {
+      await server.shutdown();
+    }
+  });
+
+  it("derives nothing on an ephemeral port when no public origin is named", async () => {
+    const { logger, entries } = capturingLogger();
+    const server = await compose(
+      { STIGMER_CONSOLE_DIR: consoleExport() },
+      logger,
+    );
+    await server.start();
+    try {
+      const redirectLines = entries.filter((entry) =>
+        entry.message.startsWith("STIGMER_OAUTH_REDIRECT_URI is not set"),
+      );
+      expect(
+        redirectLines.map((entry) => [entry.level, entry.message]),
+      ).toEqual([
+        [
+          "warn",
+          "STIGMER_OAUTH_REDIRECT_URI is not set — OAuth Connect flows for MCP servers are unavailable (initiateOAuthConnect will refuse)",
+        ],
+      ]);
+    } finally {
+      await server.shutdown();
+    }
+  });
+});

package/src/boot/__tests__/list-indexes.test.ts

@@ -31,6 +31,10 @@ const PINNED: Readonly<
     revision: 1,
     fingerprint: "iam_policy{principal=field:spec.principal.id}",
   },
+  memory: {
+    revision: 1,
+    fingerprint: "memory{subject=field:spec.subject_identity_account_id}",
+  },
   session: {
     revision: 1,
     fingerprint:

package/src/boot/__tests__/oauth-redirect-uri.test.ts

@@ -1,38 +1,149 @@
 /**
  * Pins the OAuth redirect-URI posture: a configured value wins, a served
- * console on a known port derives the console's callback page at
- * localhost, and a server with no console or no known port derives nothing
- * (today's warn and refusal stand).
+ * console derives the console's callback page on the unified port's public
+ * origin when one is named (stigmer#1200) and on localhost at a known port
+ * otherwise, and a server with no console, or with neither an origin nor a
+ * known port, derives nothing (today's warn and refusal stand).
  */
 import { describe, expect, it } from "vitest";
 
-import { CONSOLE_OAUTH_CALLBACK_PATH, resolveOAuthRedirectUri } from "../oauth-redirect-uri.js";
+import {
+  CONSOLE_OAUTH_CALLBACK_PATH,
+  resolveOAuthRedirectUri,
+} from "../oauth-redirect-uri.js";
 
 describe("resolveOAuthRedirectUri", () => {
   it("keeps a configured value whatever else is true", () => {
-    expect(resolveOAuthRedirectUri({ configured: "https://app.stigmer.test/auth/oauth/callback", servesConsole: true, port: 7777 })).toEqual({
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "https://app.stigmer.test/auth/oauth/callback",
+        servesConsole: true,
+        publicOrigin: "",
+        port: 7777,
+      }),
+    ).toEqual({
       kind: "configured",
       uri: "https://app.stigmer.test/auth/oauth/callback",
     });
-    expect(resolveOAuthRedirectUri({ configured: "https://app.stigmer.test/cb", servesConsole: false, port: 0 })).toEqual({
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "https://app.stigmer.test/cb",
+        servesConsole: false,
+        publicOrigin: "",
+        port: 0,
+      }),
+    ).toEqual({
       kind: "configured",
       uri: "https://app.stigmer.test/cb",
     });
   });
 
+  it("keeps a configured value over a named public origin", () => {
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "https://console.stigmer.test/auth/oauth/callback",
+        servesConsole: true,
+        publicOrigin: "https://api.stigmer.test",
+        port: 7777,
+      }),
+    ).toEqual({
+      kind: "configured",
+      uri: "https://console.stigmer.test/auth/oauth/callback",
+    });
+  });
+
   it("derives the console's callback page at localhost on the unified port when the console is served", () => {
-    expect(resolveOAuthRedirectUri({ configured: "", servesConsole: true, port: 7777 })).toEqual({
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: true,
+        publicOrigin: "",
+        port: 7777,
+      }),
+    ).toEqual({
       kind: "derived",
       uri: `http://localhost:7777${CONSOLE_OAUTH_CALLBACK_PATH}`,
+      from: "loopback",
     });
     expect(CONSOLE_OAUTH_CALLBACK_PATH).toBe("/auth/oauth/callback");
   });
 
+  it("derives the callback on the named public origin rather than localhost", () => {
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: true,
+        publicOrigin: "https://stigmer.example.test",
+        port: 7234,
+      }),
+    ).toEqual({
+      kind: "derived",
+      uri: "https://stigmer.example.test/auth/oauth/callback",
+      from: "public-origin",
+    });
+  });
+
+  it("reads an origin written with a trailing slash as the same origin", () => {
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: true,
+        publicOrigin: "https://stigmer.example.test/",
+        port: 7234,
+      }),
+    ).toEqual({
+      kind: "derived",
+      uri: "https://stigmer.example.test/auth/oauth/callback",
+      from: "public-origin",
+    });
+  });
+
+  it("derives on a named public origin even when the port is not known until listen", () => {
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: true,
+        publicOrigin: "https://stigmer.example.test",
+        port: 0,
+      }),
+    ).toEqual({
+      kind: "derived",
+      uri: "https://stigmer.example.test/auth/oauth/callback",
+      from: "public-origin",
+    });
+  });
+
   it("derives nothing for a server that serves no console", () => {
-    expect(resolveOAuthRedirectUri({ configured: "", servesConsole: false, port: 7777 })).toEqual({ kind: "absent" });
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: false,
+        publicOrigin: "",
+        port: 7777,
+      }),
+    ).toEqual({
+      kind: "absent",
+    });
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: false,
+        publicOrigin: "https://stigmer.example.test",
+        port: 7777,
+      }),
+    ).toEqual({ kind: "absent" });
   });
 
-  it("derives nothing when the port is not known until listen", () => {
-    expect(resolveOAuthRedirectUri({ configured: "", servesConsole: true, port: 0 })).toEqual({ kind: "absent" });
+  it("derives nothing when neither a public origin is named nor the port known", () => {
+    expect(
+      resolveOAuthRedirectUri({
+        configured: "",
+        servesConsole: true,
+        publicOrigin: "",
+        port: 0,
+      }),
+    ).toEqual({
+      kind: "absent",
+    });
   });
 });

package/src/boot/__tests__/skill-transfer-origin.test.ts

@@ -1,25 +1,84 @@
 /**
- * Pins the skill transfer origin verdict (boot/skill-transfer-origin.ts):
- * loopback on the relay is fine for a single-operator install and a
- * warning under the require-authentication posture; a public origin is
- * reachable whatever the posture; a bucket driver makes the base URL
- * unused; an unparseable base URL is not mistaken for loopback.
+ * Pins the skill transfer lane's origin (boot/skill-transfer-origin.ts).
+ *
+ * The base: a configured value wins over any port; a known unified port
+ * renders the loopback origin every fixed-port install has always had; an
+ * ephemeral one reads the port the listener bound, and a read before the
+ * bind throws instead of minting a URL for a port nothing listens on
+ * (stigmer#1386).
+ *
+ * The verdict: loopback on the relay is fine for a single-operator install
+ * and a warning under the require-authentication posture, an unset base
+ * counting as loopback; a public origin is reachable whatever the posture;
+ * a bucket driver makes the base URL unused; an unparseable base URL is
+ * not mistaken for loopback.
  */
 import { describe, expect, it } from "vitest";
 
-import { assessSkillTransferOrigin } from "../skill-transfer-origin.js";
+import {
+  assessSkillTransferOrigin,
+  resolveSkillTransferBaseUrl,
+  UNSET_BASE_URL_NOTE,
+} from "../skill-transfer-origin.js";
 
-describe("assessSkillTransferOrigin", () => {
-  it("the default loopback on a single-operator install is correct", () => {
+describe("resolveSkillTransferBaseUrl", () => {
+  const neverBound = (): number | undefined => undefined;
+
+  it.each([0, 7234])(
+    "a configured base wins over a unified port of %d, as given",
+    (unifiedPort) => {
+      expect(
+        resolveSkillTransferBaseUrl({
+          configured: "https://api.example.com/",
+          unifiedPort,
+          boundPort: neverBound,
+        }),
+      ).toBe("https://api.example.com/");
+    },
+  );
+
+  it("a known unified port renders the loopback origin once, byte-identical to the retired config default", () => {
     expect(
-      assessSkillTransferOrigin({
-        baseUrl: "http://localhost:7234",
-        relaysThroughServer: true,
-        requireAuthentication: false,
+      resolveSkillTransferBaseUrl({
+        configured: "",
+        unifiedPort: 7234,
+        boundPort: neverBound,
       }),
-    ).toEqual({ kind: "loopback-local" });
+    ).toBe("http://localhost:7234");
   });
 
+  it("an ephemeral unified port reads the bound port, and throws before the bind", () => {
+    let bound: number | undefined;
+    const base = resolveSkillTransferBaseUrl({
+      configured: "",
+      unifiedPort: 0,
+      boundPort: () => bound,
+    });
+    if (typeof base !== "function") {
+      throw new Error("an ephemeral unified port must resolve per mint");
+    }
+    expect(() => base()).toThrow(
+      "skill transfer URL requested before the unified port bound",
+    );
+    bound = 49152;
+    expect(base()).toBe("http://localhost:49152");
+  });
+});
+
+describe("assessSkillTransferOrigin", () => {
+  it.each(["", "http://localhost:7234"])(
+    "loopback (%j) on a single-operator install is correct",
+    (configured) => {
+      expect(
+        assessSkillTransferOrigin({
+          configured,
+          relaysThroughServer: true,
+          requireAuthentication: false,
+        }),
+      ).toEqual({ kind: "loopback-local" });
+    },
+  );
+
   it.each([
     "http://localhost:7234",
     "http://127.0.0.1:7234",
@@ -27,22 +86,32 @@ describe("assessSkillTransferOrigin", () => {
     "http://0.0.0.0:7234",
   ])(
     "loopback (%s) under the require-authentication posture is the warning, naming the URL",
-    (baseUrl) => {
+    (configured) => {
       expect(
         assessSkillTransferOrigin({
-          baseUrl,
+          configured,
           relaysThroughServer: true,
           requireAuthentication: true,
         }),
-      ).toEqual({ kind: "loopback-hosted", baseUrl });
+      ).toEqual({ kind: "loopback-hosted", baseUrl: configured });
     },
   );
 
+  it("an unset base under the require-authentication posture is the warning, naming it unset", () => {
+    expect(
+      assessSkillTransferOrigin({
+        configured: "",
+        relaysThroughServer: true,
+        requireAuthentication: true,
+      }),
+    ).toEqual({ kind: "loopback-hosted", baseUrl: UNSET_BASE_URL_NOTE });
+  });
+
   it("a public origin is reachable under either posture", () => {
     for (const requireAuthentication of [true, false]) {
       expect(
         assessSkillTransferOrigin({
-          baseUrl: "https://api.example.com",
+          configured: "https://api.example.com",
           relaysThroughServer: true,
           requireAuthentication,
         }),
@@ -51,19 +120,21 @@ describe("assessSkillTransferOrigin", () => {
   });
 
   it("a driver that signs its own URLs makes the base URL unused, loopback or not", () => {
-    expect(
-      assessSkillTransferOrigin({
-        baseUrl: "http://localhost:7234",
-        relaysThroughServer: false,
-        requireAuthentication: true,
-      }),
-    ).toEqual({ kind: "unused" });
+    for (const configured of ["", "http://localhost:7234"]) {
+      expect(
+        assessSkillTransferOrigin({
+          configured,
+          relaysThroughServer: false,
+          requireAuthentication: true,
+        }),
+      ).toEqual({ kind: "unused" });
+    }
   });
 
   it("an unparseable base URL is not loopback; its failure is loud on the first mint instead", () => {
     expect(
       assessSkillTransferOrigin({
-        baseUrl: "not a url",
+        configured: "not a url",
         relaysThroughServer: true,
         requireAuthentication: true,
       }),