@vellumai/cli 0.8.12-staging.2 → 0.9.0-staging.1

package/src/__tests__/wake.test.ts

@@ -272,12 +272,23 @@ describe("vellum wake", () => {
     expect(leaseGuardianTokenMock).not.toHaveBeenCalled();
   });
 
-  test("skips re-provision when a guardian token already exists", async () => {
+  test("re-provisions even when a guardian token already exists", async () => {
+    // A connect can 401 off a token whose local state looks healthy
+    // (revoked, mis-seeded, wrong principal). The user explicitly confirmed
+    // the destructive repair, so the flag forces a re-lease instead of
+    // guessing from local token state and recreating the no-op loop.
     process.argv = ["bun", "vellum", "wake", "--repair-guardian", "local-assistant"];
-    // loadGuardianToken returns a token by default — recovery must not run.
+    // loadGuardianToken returns a healthy-looking token by default.
     await wake();
 
-    expect(resetGuardianBootstrapMock).not.toHaveBeenCalled();
-    expect(leaseGuardianTokenMock).not.toHaveBeenCalled();
+    expect(resetGuardianBootstrapMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:7830",
+      "generated-bootstrap-secret",
+    );
+    expect(leaseGuardianTokenMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:7830",
+      "local-assistant",
+      "generated-bootstrap-secret",
+    );
   });
 });

package/src/__tests__/workos-pkce.test.ts

@@ -0,0 +1,314 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  buildAuthorizeUrl,
+  exchangeAccessTokenForSession,
+  exchangeCodeWithWorkos,
+  fetchWorkosClientId,
+  generatePkcePair,
+  selectWorkosClientId,
+} from "../lib/workos-pkce.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+/**
+ * Route fetch responses by URL substring so each WorkOS/platform call can be
+ * inspected. The module talks to remote hosts via loopbackSafeFetch, which
+ * delegates to globalThis.fetch.
+ */
+function mockFetchByUrl(responses: Record<string, () => Response>) {
+  const calls: Array<{ url: string; init?: RequestInit }> = [];
+  globalThis.fetch = mock(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = String(input);
+      calls.push({ url, init });
+      const match = Object.entries(responses).find(([prefix]) =>
+        url.includes(prefix),
+      );
+      if (!match) throw new Error(`Unexpected fetch: ${url}`);
+      return match[1]();
+    },
+  ) as unknown as typeof globalThis.fetch;
+  return calls;
+}
+
+describe("generatePkcePair", () => {
+  test("challenge is the base64url sha256 of the verifier", async () => {
+    const { verifier, challenge } = generatePkcePair();
+    const digest = await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(verifier),
+    );
+    const expected = Buffer.from(digest).toString("base64url");
+    expect(challenge).toBe(expected);
+  });
+
+  test("verifiers are unique", () => {
+    expect(generatePkcePair().verifier).not.toBe(generatePkcePair().verifier);
+  });
+});
+
+describe("buildAuthorizeUrl", () => {
+  const base = {
+    clientId: "client_123",
+    redirectUri: "http://127.0.0.1:4242/auth/callback",
+    challenge: "chal",
+    state: "st",
+  };
+
+  test("targets user_management/authorize with PKCE and authkit defaults", () => {
+    const url = new URL(buildAuthorizeUrl(base));
+    expect(url.origin).toBe("https://api.workos.com");
+    expect(url.pathname).toBe("/user_management/authorize");
+    expect(url.searchParams.get("client_id")).toBe("client_123");
+    expect(url.searchParams.get("redirect_uri")).toBe(base.redirectUri);
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("scope")).toBe("openid profile email");
+    expect(url.searchParams.get("code_challenge")).toBe("chal");
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(url.searchParams.get("state")).toBe("st");
+    expect(url.searchParams.get("provider")).toBe("authkit");
+    // Session reuse: never force a fresh IdP login.
+    expect(url.searchParams.has("prompt")).toBe(false);
+  });
+
+  test("provider hint replaces authkit", () => {
+    const url = new URL(
+      buildAuthorizeUrl({ ...base, providerHint: "GoogleOAuth" }),
+    );
+    expect(url.searchParams.get("provider")).toBe("GoogleOAuth");
+  });
+
+  test("login hint is forwarded", () => {
+    // generic-examples:ignore-next-line — reason: test fixture for URL encoding, not a real email
+    const url = new URL(buildAuthorizeUrl({ ...base, loginHint: "a@b.co" }));
+    // generic-examples:ignore-next-line — reason: test fixture for URL encoding, not a real email
+    expect(url.searchParams.get("login_hint")).toBe("a@b.co");
+
+    const noHint = new URL(buildAuthorizeUrl(base));
+    expect(noHint.searchParams.has("login_hint")).toBe(false);
+  });
+});
+
+describe("selectWorkosClientId", () => {
+  // During coexistence the platform lists two providers that share the
+  // "workos-oidc" id; only the OAuth2 one (no discovery URL) is usable.
+  const legacy = {
+    id: "workos-oidc",
+    name: "WorkOS OIDC",
+    client_id: "client_connect",
+    flows: ["provider_redirect", "provider_token"],
+    openid_configuration_url:
+      "https://x.authkit.app/.well-known/openid-configuration",
+  };
+  const modern = {
+    id: "workos-oidc",
+    name: "WorkOS",
+    client_id: "client_um",
+    flows: ["provider_redirect", "provider_token"],
+  };
+
+  test("picks the OAuth2 entry during coexistence", () => {
+    expect(selectWorkosClientId([legacy, modern])).toBe("client_um");
+    expect(selectWorkosClientId([modern, legacy])).toBe("client_um");
+  });
+
+  test("returns null when the platform lacks token auth", () => {
+    const preTokenAuth = { ...modern, flows: ["provider_redirect"] };
+    expect(selectWorkosClientId([legacy, preTokenAuth])).toBeNull();
+    expect(selectWorkosClientId([])).toBeNull();
+  });
+
+  test("ignores an entry missing client_id", () => {
+    const noClientId = { id: "workos-oidc", flows: ["provider_token"] };
+    expect(selectWorkosClientId([noClientId])).toBeNull();
+  });
+});
+
+describe("fetchWorkosClientId", () => {
+  test("resolves the client id from the headless config", async () => {
+    const calls = mockFetchByUrl({
+      "/_allauth/app/v1/config": () =>
+        new Response(
+          JSON.stringify({
+            data: {
+              socialaccount: {
+                providers: [
+                  {
+                    id: "workos-oidc",
+                    client_id: "client_um",
+                    flows: ["provider_token"],
+                  },
+                ],
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+    });
+
+    expect(await fetchWorkosClientId("https://platform.example")).toBe(
+      "client_um",
+    );
+    expect(calls[0]!.url).toBe(
+      "https://platform.example/_allauth/app/v1/config",
+    );
+  });
+
+  test("derives the config URL from the origin, ignoring any path", async () => {
+    const calls = mockFetchByUrl({
+      "/_allauth/app/v1/config": () =>
+        new Response(
+          JSON.stringify({
+            data: {
+              socialaccount: {
+                providers: [
+                  { client_id: "client_um", flows: ["provider_token"] },
+                ],
+              },
+            },
+          }),
+          { status: 200 },
+        ),
+    });
+
+    await fetchWorkosClientId("https://platform.example/some/path");
+    expect(calls[0]!.url).toBe(
+      "https://platform.example/_allauth/app/v1/config",
+    );
+  });
+
+  test("throws a clear error when no token-auth provider is advertised", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/config": () =>
+        new Response(
+          JSON.stringify({ data: { socialaccount: { providers: [] } } }),
+          { status: 200 },
+        ),
+    });
+
+    await expect(
+      fetchWorkosClientId("https://platform.example"),
+    ).rejects.toThrow(/does not advertise/);
+  });
+
+  test("throws on a non-OK config response", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/config": () => new Response("nope", { status: 500 }),
+    });
+
+    await expect(
+      fetchWorkosClientId("https://platform.example"),
+    ).rejects.toThrow(/500/);
+  });
+});
+
+describe("exchangeCodeWithWorkos", () => {
+  test("posts a public-client PKCE exchange and returns the access token", async () => {
+    const calls = mockFetchByUrl({
+      "/user_management/authenticate": () =>
+        new Response(JSON.stringify({ access_token: "at_1", user: {} }), {
+          status: 200,
+        }),
+    });
+
+    const token = await exchangeCodeWithWorkos({
+      clientId: "client_um",
+      code: "c",
+      verifier: "v",
+    });
+
+    expect(token).toBe("at_1");
+    expect(calls[0]!.url).toBe(
+      "https://api.workos.com/user_management/authenticate",
+    );
+    const body = JSON.parse(String(calls[0]!.init?.body));
+    // Public client: no secret, no API key.
+    expect(body).toEqual({
+      client_id: "client_um",
+      grant_type: "authorization_code",
+      code: "c",
+      code_verifier: "v",
+    });
+  });
+
+  test("throws with upstream detail on failure", async () => {
+    mockFetchByUrl({
+      "/user_management/authenticate": () =>
+        new Response(JSON.stringify({ error: "invalid_grant" }), {
+          status: 400,
+        }),
+    });
+
+    await expect(
+      exchangeCodeWithWorkos({ clientId: "c", code: "x", verifier: "v" }),
+    ).rejects.toThrow(/400/);
+  });
+
+  test("throws when the exchange returns no access token", async () => {
+    mockFetchByUrl({
+      "/user_management/authenticate": () =>
+        new Response(JSON.stringify({}), { status: 200 }),
+    });
+
+    await expect(
+      exchangeCodeWithWorkos({ clientId: "c", code: "x", verifier: "v" }),
+    ).rejects.toThrow(/no access token/);
+  });
+});
+
+describe("exchangeAccessTokenForSession", () => {
+  test("posts the headless token payload and returns the session token", async () => {
+    const calls = mockFetchByUrl({
+      "/_allauth/app/v1/auth/provider/token": () =>
+        new Response(JSON.stringify({ meta: { session_token: "sess_1" } }), {
+          status: 200,
+        }),
+    });
+
+    const token = await exchangeAccessTokenForSession(
+      "https://platform.example",
+      "client_um",
+      "at_1",
+    );
+
+    expect(token).toBe("sess_1");
+    expect(calls[0]!.url).toBe(
+      "https://platform.example/_allauth/app/v1/auth/provider/token",
+    );
+    const body = JSON.parse(String(calls[0]!.init?.body));
+    expect(body).toEqual({
+      provider: "workos",
+      process: "login",
+      token: { client_id: "client_um", access_token: "at_1" },
+    });
+  });
+
+  test("throws on a rejected token", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/auth/provider/token": () =>
+        new Response(JSON.stringify({ errors: [{ code: "invalid_token" }] }), {
+          status: 400,
+        }),
+    });
+
+    await expect(
+      exchangeAccessTokenForSession("https://platform.example", "c", "bad"),
+    ).rejects.toThrow(/400/);
+  });
+
+  test("throws when the session exchange returns no session token", async () => {
+    mockFetchByUrl({
+      "/_allauth/app/v1/auth/provider/token": () =>
+        new Response(JSON.stringify({ meta: {} }), { status: 200 }),
+    });
+
+    await expect(
+      exchangeAccessTokenForSession("https://platform.example", "c", "at"),
+    ).rejects.toThrow(/no session token/);
+  });
+});

package/src/commands/flags.ts

@@ -1,3 +1,4 @@
+import { extractAssistantFlag } from "../lib/arg-utils.js";
 import { AssistantClient } from "../lib/assistant-client.js";
 import {
   formatAssistantLookupError,
@@ -199,28 +200,6 @@ async function setFlag(
   console.log(`Flag "${key}" set to ${value}`);
 }
 
-/**
- * Strip `--assistant <name>` from argv and return the captured value.
- *
- * Mutates the input array so positional parsing downstream sees a clean
- * shape (subcommand + key + value). Returns `undefined` if the flag is
- * absent. Error-reports a missing value so the user gets a clear message
- * rather than the flag being silently swallowed as a positional.
- */
-function extractAssistantFlag(args: string[]): string | undefined {
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] !== "--assistant") continue;
-    const value = args[i + 1];
-    if (!value || value.startsWith("-")) {
-      console.error("Missing value for --assistant <name>");
-      process.exit(1);
-    }
-    args.splice(i, 2);
-    return value;
-  }
-  return undefined;
-}
-
 export async function flags(): Promise<void> {
   const args = process.argv.slice(3);
 

package/src/commands/hatch.ts

@@ -5,7 +5,6 @@ import cliPkg from "../../package.json";
 
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
 import {
-  normalizeVersion,
   saveAssistantEntry,
   setActiveAssistant,
 } from "../lib/assistant-config";
@@ -183,6 +182,9 @@ interface HatchArgs {
   flagEnvVars: Record<string, string>;
   analyze: boolean;
   disablePlatform: boolean;
+  netnsContainer: string | null;
+  gatewayPort: number | null;
+  assistantCaCert: string | null;
 }
 
 function parseArgs(): HatchArgs {
@@ -190,8 +192,10 @@ function parseArgs(): HatchArgs {
     process.argv.slice(3),
   );
   const flagEnvVars = { ...readAmbientFlagEnvVars(), ...cliFlagVars };
-  const disablePlatformAmbient = process.env.VELLUM_DISABLE_PLATFORM?.trim().toLowerCase();
-  let disablePlatform = disablePlatformAmbient === "true" || disablePlatformAmbient === "1";
+  const disablePlatformAmbient =
+    process.env.VELLUM_DISABLE_PLATFORM?.trim().toLowerCase();
+  let disablePlatform =
+    disablePlatformAmbient === "true" || disablePlatformAmbient === "1";
   let species: Species = DEFAULT_SPECIES;
   let detached = false;
   let keepAlive = false;
@@ -201,6 +205,9 @@ function parseArgs(): HatchArgs {
   let sourcePath: string | null = null;
   const configValues: Record<string, string> = {};
   let analyze = false;
+  let netnsContainer: string | null = null;
+  let gatewayPort: number | null = null;
+  let assistantCaCert: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -240,6 +247,15 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --disable-platform        Suppress all outbound platform API calls",
       );
+      console.log(
+        "  --netns-container <name>  Join an existing container's network namespace (docker target only) instead of creating a per-instance network. The namespace owner publishes host ports, so --gateway-port is required.",
+      );
+      console.log(
+        "  --gateway-port <port>     Use an explicit host port for the gateway runtime URL instead of auto-allocating. Required with --netns-container.",
+      );
+      console.log(
+        "  --assistant-ca-cert <path>  Trust an extra PEM CA bundle in the assistant container (NODE_EXTRA_CA_CERTS) from process start. Useful behind a TLS-terminating egress proxy.",
+      );
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
@@ -302,11 +318,38 @@ function parseArgs(): HatchArgs {
       i++;
     } else if (arg === "--disable-platform") {
       disablePlatform = true;
+    } else if (arg === "--netns-container") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --netns-container requires a container name");
+        process.exit(1);
+      }
+      netnsContainer = next;
+      i++;
+    } else if (arg === "--gateway-port") {
+      const next = args[i + 1];
+      const parsed = next ? Number(next) : NaN;
+      if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        console.error(
+          "Error: --gateway-port requires an integer port in 1-65535",
+        );
+        process.exit(1);
+      }
+      gatewayPort = parsed;
+      i++;
+    } else if (arg === "--assistant-ca-cert") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --assistant-ca-cert requires a path argument");
+        process.exit(1);
+      }
+      assistantCaCert = next;
+      i++;
     } else if (VALID_SPECIES.includes(arg as Species)) {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --flag <key=value>, --analyze, --disable-platform`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --flag <key=value>, --analyze, --disable-platform, --netns-container <name>, --gateway-port <port>, --assistant-ca-cert <path>`,
       );
       process.exit(1);
     }
@@ -324,6 +367,9 @@ function parseArgs(): HatchArgs {
     flagEnvVars,
     analyze,
     disablePlatform,
+    netnsContainer,
+    gatewayPort,
+    assistantCaCert,
   };
 }
 
@@ -560,6 +606,9 @@ export async function hatch(): Promise<void> {
     flagEnvVars,
     analyze,
     disablePlatform,
+    netnsContainer,
+    gatewayPort,
+    assistantCaCert,
   } = parseArgs();
 
   if (disablePlatform) {
@@ -581,6 +630,25 @@ export async function hatch(): Promise<void> {
     process.exit(1);
   }
 
+  if (
+    (netnsContainer !== null ||
+      gatewayPort !== null ||
+      assistantCaCert !== null) &&
+    remote !== "docker"
+  ) {
+    console.error(
+      "Error: --netns-container, --gateway-port, and --assistant-ca-cert are only supported for docker hatch targets.",
+    );
+    process.exit(1);
+  }
+
+  if (netnsContainer !== null && gatewayPort === null) {
+    console.error(
+      "Error: --gateway-port is required with --netns-container (the namespace owner publishes the port before hatch runs).",
+    );
+    process.exit(1);
+  }
+
   if (UNSUPPORTED_REMOTE_HATCH_TARGETS.has(remote)) {
     console.error(
       `Error: \`vellum hatch --remote ${remote}\` is not a supported provisioning target yet.`,
@@ -592,14 +660,30 @@ export async function hatch(): Promise<void> {
   }
 
   if (remote === "local") {
-    await hatchLocal(species, name, watch, keepAlive, configValues, flagEnvVars);
+    await hatchLocal(
+      species,
+      name,
+      watch,
+      keepAlive,
+      configValues,
+      flagEnvVars,
+    );
     return;
   }
 
   if (remote === "docker") {
-    await hatchDocker(species, detached, name, watch, configValues, flagEnvVars, {
+    await hatchDocker({
+      species,
+      detached,
+      name,
+      watch,
+      configValues,
+      flagEnvVars,
       sourcePath,
       analyze,
+      netnsContainer: netnsContainer ?? undefined,
+      gatewayPort: gatewayPort ?? undefined,
+      assistantCaCertPath: assistantCaCert ?? undefined,
     });
     return;
   }
@@ -639,9 +723,6 @@ async function hatchVellumPlatform(): Promise<void> {
     cloud: "vellum",
     species: "vellum",
     hatchedAt: new Date().toISOString(),
-    ...(result.current_release_version != null && {
-      version: normalizeVersion(result.current_release_version),
-    }),
   });
   setActiveAssistant(result.id);