@agent-native/dispatch 0.24.6 → 0.25.1

package/src/server/lib/mcp-gateway.spec.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
   discoverAgents: vi.fn(),
+  listWorkspaceApps: vi.fn(),
   getUserSetting: vi.fn(),
   getOrgSetting: vi.fn(),
   createEmbedSessionTicket: vi.fn(),
@@ -18,12 +19,26 @@ const mocks = vi.hoisted(() => ({
   signA2AToken: vi.fn(),
   getOrgA2ASecret: vi.fn(),
   getOrgDomain: vi.fn(),
+  isFeatureFlagEnabled: vi.fn(),
 }));
 
 vi.mock("@agent-native/core/server/agent-discovery", () => ({
   discoverAgents: mocks.discoverAgents,
 }));
 
+vi.mock("./app-creation-store.js", () => ({
+  listWorkspaceApps: mocks.listWorkspaceApps,
+}));
+
+vi.mock("@agent-native/core/feature-flags", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@agent-native/core/feature-flags")>();
+  return {
+    ...actual,
+    isFeatureFlagEnabled: mocks.isFeatureFlagEnabled,
+  };
+});
+
 vi.mock("@agent-native/core/settings", () => ({
   getUserSetting: mocks.getUserSetting,
   getOrgSetting: mocks.getOrgSetting,
@@ -89,6 +104,7 @@ import { runWithRequestContext } from "@agent-native/core/server";
 
 import {
   createGrantedDispatchMcpEmbedSession,
+  createWorkspaceSsoEmbedSession,
   askGrantedDispatchMcpApp,
   getGrantedDispatchMcpAppTask,
   listGrantedDispatchMcpApps,
@@ -111,6 +127,7 @@ beforeEach(() => {
   mocks.a2aGetTask.mockReset();
   mocks.signA2AToken.mockReset();
   mocks.discoverAgents.mockResolvedValue([analyticsAgent]);
+  mocks.listWorkspaceApps.mockResolvedValue([]);
   mocks.getUserSetting.mockResolvedValue({ mode: "all-apps" });
   mocks.getOrgSetting.mockResolvedValue({ mode: "all-apps" });
   mocks.createEmbedSessionTicket.mockResolvedValue({
@@ -138,6 +155,7 @@ beforeEach(() => {
   mocks.signA2AToken.mockResolvedValue("signed-token");
   mocks.getOrgA2ASecret.mockResolvedValue(null);
   mocks.getOrgDomain.mockResolvedValue(null);
+  mocks.isFeatureFlagEnabled.mockResolvedValue(true);
 });
 
 afterEach(() => {
@@ -864,6 +882,129 @@ describe("createGrantedDispatchMcpEmbedSession", () => {
     });
   });
 
+  it("keeps workspace sign-in behind the rollout flag", async () => {
+    mocks.isFeatureFlagEnabled.mockResolvedValueOnce(false);
+
+    await expect(
+      runWithRequestContext(
+        {
+          userEmail: "owner@example.test",
+          requestOrigin: "http://localhost:8092",
+        },
+        () =>
+          createWorkspaceSsoEmbedSession({
+            app: "analytics",
+            path: "/overview",
+          }),
+      ),
+    ).rejects.toThrow(/not enabled/);
+    expect(mocks.managerConstructor).not.toHaveBeenCalled();
+  });
+
+  it("allows an exact canonical app without requiring an MCP app grant", async () => {
+    mocks.getUserSetting.mockResolvedValue({
+      mode: "selected-apps",
+      selectedAppIds: [],
+    });
+    mocks.discoverAgents.mockResolvedValue([
+      {
+        ...analyticsAgent,
+        url: "https://analytics.agent-native.com",
+      },
+    ]);
+    mocks.managerCallTool.mockResolvedValueOnce({
+      structuredContent: {
+        startUrl:
+          "https://analytics.agent-native.com/_agent-native/embed/start?ticket=remote",
+      },
+    });
+
+    const result = await runWithRequestContext(
+      {
+        userEmail: "owner@example.test",
+        requestOrigin: "https://dispatch.agent-native.com",
+      },
+      () =>
+        createWorkspaceSsoEmbedSession({
+          app: "analytics",
+          path: "/overview",
+          chrome: "minimal",
+        }),
+    );
+
+    expect(result).toMatchObject({
+      app: "analytics",
+      startUrl:
+        "https://analytics.agent-native.com/_agent-native/embed/start?ticket=remote",
+    });
+    expect(mocks.managerConstructor).toHaveBeenCalled();
+  });
+
+  it("allows an exact custom registry entry and rejects an unregistered external app", async () => {
+    vi.stubEnv(
+      "IDENTITY_SSO_APP_REGISTRY_JSON",
+      JSON.stringify([
+        {
+          appId: "workspace",
+          clientId: "workspace-client",
+          origin: "https://workspace.example.com",
+          callbackPath: "/_agent-native/identity/callback",
+          capabilities: ["identity-sso"],
+        },
+      ]),
+    );
+    mocks.discoverAgents.mockResolvedValue([
+      {
+        id: "workspace",
+        name: "Workspace",
+        description: "Custom workspace app",
+        url: "https://workspace.example.com",
+        color: "#111827",
+      },
+      {
+        id: "unregistered",
+        name: "Unregistered",
+        description: "External app without registration",
+        url: "https://unregistered.example.com",
+        color: "#111827",
+      },
+    ]);
+    mocks.managerCallTool.mockResolvedValueOnce({
+      structuredContent: {
+        startUrl:
+          "https://workspace.example.com/_agent-native/embed/start?ticket=remote",
+      },
+    });
+
+    await expect(
+      runWithRequestContext(
+        {
+          userEmail: "owner@example.test",
+          requestOrigin: "https://dispatch.agent-native.com",
+        },
+        () =>
+          createWorkspaceSsoEmbedSession({
+            app: "workspace",
+            path: "/home",
+          }),
+      ),
+    ).resolves.toMatchObject({ app: "workspace" });
+
+    await expect(
+      runWithRequestContext(
+        {
+          userEmail: "owner@example.test",
+          requestOrigin: "https://dispatch.agent-native.com",
+        },
+        () =>
+          createWorkspaceSsoEmbedSession({
+            app: "unregistered",
+            path: "/home",
+          }),
+      ),
+    ).rejects.toThrow(/not registered/);
+  });
+
   it("rejects traversal into Dispatch-owned embed routes on sibling apps", async () => {
     await expect(
       runWithRequestContext(

package/src/server/lib/mcp-gateway.ts

@@ -1,4 +1,5 @@
 import { A2AClient, signA2AToken, type Task } from "@agent-native/core/a2a";
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import {
   buildMcpToolName,
   McpClientManager,
@@ -17,6 +18,15 @@ import {
   type DiscoveredAgent,
 } from "@agent-native/core/server/agent-discovery";
 
+import {
+  CANONICAL_WORKSPACE_SSO_APP_ORIGINS,
+  DISPATCH_WORKSPACE_SSO_FLAG,
+  parseWorkspaceSsoAppRegistrations,
+} from "../../shared/workspace-sso.js";
+import {
+  listWorkspaceApps,
+  type WorkspaceAppSummary,
+} from "./app-creation-store.js";
 import {
   getDispatchMcpAppAccessSettings,
   isAppAllowedByMcpAccess,
@@ -447,6 +457,17 @@ function safeAppOrigin(app: DispatchMcpAccessibleApp): string | null {
   }
 }
 
+function isLoopbackOrigin(origin: string): boolean {
+  try {
+    const hostname = new URL(origin).hostname;
+    return ["localhost", "127.0.0.1", "::1"].includes(hostname);
+  } catch {
+    // coercion-ok: only a previously validated app origin reaches this helper;
+    // malformed values are ineligible for the loopback development exception.
+    return false;
+  }
+}
+
 function appBaseUrl(app: DispatchMcpAccessibleApp): string {
   return app.url.replace(/\/+$/, "");
 }
@@ -588,6 +609,116 @@ export async function resolveGrantedDispatchMcpApp(
   return match;
 }
 
+function workspaceSsoOriginForApp(appId: string): string | null {
+  const canonical =
+    CANONICAL_WORKSPACE_SSO_APP_ORIGINS[
+      appId as keyof typeof CANONICAL_WORKSPACE_SSO_APP_ORIGINS
+    ];
+  if (canonical) return canonical;
+  const custom = parseWorkspaceSsoAppRegistrations(
+    process.env.IDENTITY_SSO_APP_REGISTRY_JSON,
+  ).find((registration) => registration.appId === appId);
+  return custom?.origin ?? null;
+}
+
+function isWorkspaceSsoCanonicalApp(app: DispatchMcpAccessibleApp): boolean {
+  const origin = safeAppOrigin(app);
+  if (!origin) return false;
+  const registeredOrigin = workspaceSsoOriginForApp(app.id);
+  if (origin === registeredOrigin) return true;
+  // The built-in discovery table intentionally points at local dev ports when
+  // running outside production. Keep local development usable without ever
+  // weakening the production exact-origin check.
+  return process.env.NODE_ENV !== "production" && isLoopbackOrigin(origin)
+    ? Object.prototype.hasOwnProperty.call(
+        CANONICAL_WORKSPACE_SSO_APP_ORIGINS,
+        app.id,
+      )
+    : false;
+}
+
+function sameWorkspaceApp(
+  candidate: DispatchMcpAccessibleApp,
+  mounted: WorkspaceAppSummary,
+): boolean {
+  if (candidate.id !== mounted.id || !mounted.url) return false;
+  return candidate.url.replace(/\/+$/, "") === mounted.url.replace(/\/+$/, "");
+}
+
+async function isEligibleWorkspaceSsoApp(
+  candidate: DispatchMcpAccessibleApp,
+  mountedApps: WorkspaceAppSummary[],
+): Promise<boolean> {
+  const origin = safeAppOrigin(candidate);
+  if (!origin) return false;
+  if (isWorkspaceSsoCanonicalApp(candidate)) return true;
+
+  const customOrigin = workspaceSsoOriginForApp(candidate.id);
+  if (customOrigin === origin) return true;
+
+  const dispatchOrigin = safeAppOrigin({
+    id: DISPATCH_APP_ID,
+    name: DISPATCH_NAME,
+    description: DISPATCH_DESCRIPTION,
+    url: dispatchSelfBaseUrl(),
+    color: DISPATCH_COLOR,
+    granted: true,
+  });
+  if (origin !== dispatchOrigin) return false;
+  return mountedApps.some((mounted) => sameWorkspaceApp(candidate, mounted));
+}
+
+async function listWorkspaceSsoApps(): Promise<DispatchMcpAccessibleApp[]> {
+  const [agents, mountedApps] = await Promise.all([
+    discoverAgents("dispatch"),
+    listWorkspaceApps({ includeAgentCards: false }),
+  ]);
+  const candidates = agents
+    .filter((agent) => normalizeAppId(agent.id) !== DISPATCH_APP_ID)
+    .map((agent) => ({
+      ...toAccessibleApp(agent, {
+        mode: "all-apps",
+        selectedAppIds: [],
+      }),
+      granted: true,
+    }));
+  const eligible = [] as DispatchMcpAccessibleApp[];
+  for (const candidate of candidates) {
+    if (await isEligibleWorkspaceSsoApp(candidate, mountedApps)) {
+      eligible.push(candidate);
+    }
+  }
+  return [
+    {
+      id: DISPATCH_APP_ID,
+      name: DISPATCH_NAME,
+      description: DISPATCH_DESCRIPTION,
+      url: dispatchSelfBaseUrl(),
+      color: DISPATCH_COLOR,
+      granted: true,
+    },
+    ...eligible,
+  ];
+}
+
+async function resolveWorkspaceSsoApp(
+  app: string,
+): Promise<DispatchMcpAccessibleApp> {
+  const target = normalizeAppId(app);
+  if (!target) throw new Error("app is required");
+  const apps = await listWorkspaceSsoApps();
+  const match = apps.find(
+    (candidate) =>
+      candidate.id === target || candidate.name.toLowerCase() === target,
+  );
+  if (!match) {
+    throw new Error(
+      `Workspace app "${app}" is not registered for workspace sign-in.`,
+    );
+  }
+  return match;
+}
+
 export async function askGrantedDispatchMcpApp(
   app: string,
   message: string,
@@ -860,13 +991,20 @@ async function callTargetCreateEmbedSession(input: {
   }
 }
 
-async function resolveDispatchEmbedTarget(input: {
-  app?: string;
-  url?: string;
-  path?: string;
-}): Promise<{ app: DispatchMcpAccessibleApp; path: string; url: string }> {
+async function resolveEmbedTarget(
+  input: {
+    app?: string;
+    url?: string;
+    path?: string;
+  },
+  options: {
+    resolveApp: (app: string) => Promise<DispatchMcpAccessibleApp>;
+    listApps: () => Promise<DispatchMcpAccessibleApp[]>;
+    urlError: string;
+  },
+): Promise<{ app: DispatchMcpAccessibleApp; path: string; url: string }> {
   const explicitApp = input.app?.trim()
-    ? await resolveGrantedDispatchMcpApp(input.app)
+    ? await options.resolveApp(input.app)
     : null;
   if (explicitApp && input.path) {
     const path = safeAppPath(input.path);
@@ -899,14 +1037,12 @@ async function resolveDispatchEmbedTarget(input: {
     };
   }
 
-  const apps = explicitApp ? [explicitApp] : await listGrantedDispatchMcpApps();
+  const apps = explicitApp ? [explicitApp] : await options.listApps();
   const target = apps
     .filter((app) => appMatchesUrlPath(app, parsed))
     .sort((a, b) => appPathSpecificity(b) - appPathSpecificity(a))[0];
   if (!target) {
-    throw new Error(
-      "Embed URL must belong to an app granted through Dispatch.",
-    );
+    throw new Error(options.urlError);
   }
   const path = safeAppPath(appRelativePath(target, parsed));
   if (!path) throw new Error("Embed URL path is not safe.");
@@ -914,6 +1050,31 @@ async function resolveDispatchEmbedTarget(input: {
   return { app: target, path, url: `${appBaseUrl(target)}${path}` };
 }
 
+async function resolveDispatchEmbedTarget(input: {
+  app?: string;
+  url?: string;
+  path?: string;
+}): Promise<{ app: DispatchMcpAccessibleApp; path: string; url: string }> {
+  return resolveEmbedTarget(input, {
+    resolveApp: resolveGrantedDispatchMcpApp,
+    listApps: listGrantedDispatchMcpApps,
+    urlError: "Embed URL must belong to an app granted through Dispatch.",
+  });
+}
+
+async function resolveWorkspaceSsoEmbedTarget(input: {
+  app?: string;
+  url?: string;
+  path?: string;
+}): Promise<{ app: DispatchMcpAccessibleApp; path: string; url: string }> {
+  return resolveEmbedTarget(input, {
+    resolveApp: resolveWorkspaceSsoApp,
+    listApps: listWorkspaceSsoApps,
+    urlError:
+      "Embed URL must belong to an app registered for Dispatch workspace sign-in.",
+  });
+}
+
 async function createDispatchSelfEmbedSession(input: {
   ownerEmail: string;
   orgId?: string;
@@ -956,14 +1117,34 @@ export async function createGrantedDispatchMcpEmbedSession(input: {
   if (!userEmail) throw new Error("no authenticated user");
   const target = await resolveDispatchEmbedTarget(input);
 
-  const orgId = getRequestOrgId();
+  return createEmbedSessionForResolvedApp({
+    ownerEmail: userEmail,
+    orgId: getRequestOrgId(),
+    target,
+    chrome: input.chrome,
+  });
+}
+
+async function createEmbedSessionForResolvedApp(input: {
+  ownerEmail: string;
+  orgId?: string;
+  target: { app: DispatchMcpAccessibleApp; path: string; url: string };
+  chrome?: "full" | "minimal";
+}): Promise<{
+  startUrl: string;
+  targetPath?: string;
+  expiresAt?: number;
+  app: string;
+}> {
+  const { ownerEmail, orgId, target, chrome } = input;
+
   if (target.app.id === DISPATCH_APP_ID) {
     return createDispatchSelfEmbedSession({
-      ownerEmail: userEmail,
+      ownerEmail,
       orgId,
       path: target.path,
       baseUrl: appBaseUrl(target.app),
-      chrome: input.chrome,
+      chrome,
     });
   }
 
@@ -980,7 +1161,7 @@ export async function createGrantedDispatchMcpEmbedSession(input: {
   const useOrgSigning = usableOrgDomain && usableOrgSecret;
   const signedOrgDomain = usableOrgDomain ? orgDomain.trim() : undefined;
   const token = await signA2AToken(
-    userEmail,
+    ownerEmail,
     signedOrgDomain,
     useOrgSigning ? orgSecret.trim() : undefined,
     {
@@ -996,7 +1177,7 @@ export async function createGrantedDispatchMcpEmbedSession(input: {
     app: target.app,
     token,
     url: target.url,
-    chrome: input.chrome,
+    chrome,
   });
   const parsed = parseMcpToolTextResult(result) as {
     startUrl?: string;
@@ -1019,3 +1200,34 @@ export async function createGrantedDispatchMcpEmbedSession(input: {
   if (typeof parsed.expiresAt === "number") output.expiresAt = parsed.expiresAt;
   return output;
 }
+
+export async function createWorkspaceSsoEmbedSession(input: {
+  app?: string;
+  url?: string;
+  path?: string;
+  chrome?: "full" | "minimal";
+}): Promise<{
+  startUrl: string;
+  targetPath?: string;
+  expiresAt?: number;
+  app: string;
+}> {
+  const ownerEmail = getRequestUserEmail();
+  if (!ownerEmail) throw new Error("no authenticated user");
+  const enabled = await isFeatureFlagEnabled(DISPATCH_WORKSPACE_SSO_FLAG, {
+    userEmail: ownerEmail,
+    userKey: ownerEmail,
+    orgId: getRequestOrgId(),
+  });
+  if (!enabled) {
+    throw new Error("Dispatch workspace sign-in is not enabled.");
+  }
+
+  const target = await resolveWorkspaceSsoEmbedTarget(input);
+  return createEmbedSessionForResolvedApp({
+    ownerEmail,
+    orgId: getRequestOrgId(),
+    target,
+    chrome: input.chrome,
+  });
+}

package/src/server/lib/workspace-resources-store.ts

@@ -83,7 +83,13 @@ interface MaterializableWorkspaceResource {
 function mimeTypeForWorkspaceResource(
   resource: MaterializableWorkspaceResource,
 ) {
-  return resource.path.endsWith(".json") ? "application/json" : "text/markdown";
+  if (resource.path.endsWith(".json")) return "application/json";
+  if (resource.path.endsWith(".txt")) return "text/plain";
+  if (resource.path.endsWith(".csv")) return "text/csv";
+  if (resource.path.endsWith(".yaml") || resource.path.endsWith(".yml")) {
+    return "text/yaml";
+  }
+  return "text/markdown";
 }
 
 function parseResourceMetadata(metadata: string | null): Record<string, any> {
@@ -188,6 +194,7 @@ export type WorkspaceResourceKind =
   | "skill"
   | "instruction"
   | "agent"
+  | "agent-file"
   | "knowledge"
   | "mcp-server";
 export type WorkspaceResourceScope = "all" | "selected";
@@ -526,7 +533,7 @@ async function writeStarterSeedMarker(ctx: WorkspaceResourceCtx) {
   }
 }
 
-async function getWorkspaceResourceByPath(
+export async function getWorkspaceResourceByPath(
   resourcePath: string,
   ctx: WorkspaceResourceCtx,
 ) {

package/src/server/plugins/agent-chat.ts

@@ -13,6 +13,10 @@ const INITIAL_TOOL_NAMES = [
   "list-workspace-resources",
   "create-workspace-resource",
   "update-workspace-resource",
+  "import-agent",
+  "import-agent-pack",
+  "list-agent-pack",
+  "connect-external-agent",
   "list-vault-secrets",
   "request-vault-secret",
   "create-vault-secret",
@@ -62,6 +66,15 @@ Use the standard workspace primitives:
 - Read and update resources like AGENTS.md, LEARNINGS.md, jobs/*.md, agents/*.md, and remote-agents/*.json when appropriate.
 - Use recurring jobs for scheduled behavior.
 - Use custom agent profiles in agents/*.md for local spawned work and remote-agents/*.json for remote A2A apps.
+- For a Claude-style Markdown or JSON agent setup, use import-agent so the
+  profile is normalized into agents/<slug>.md. Never import credentials, hooks,
+  shell commands, or local environment settings.
+- For a folder of agent instructions, references, or skills, use
+  import-agent-pack. It preserves the text files under agents/<slug>/ and
+  creates the normalized profile alongside them. Use list-agent-pack to inspect
+  the pack before editing or handing it off to an app.
+- For an existing HTTP/A2A endpoint, use connect-external-agent and let the
+  normal A2A/MCP connection flow handle authentication.
 - You receive a compact available-apps block with sibling workspace app names and descriptions. Use it to pick the right A2A target, and call list-connected-agents or tool-search only when you need fresh details.
 - Hosted/connected A2A neighbors such as Analytics and Content come from the available-apps context or list-connected-agents. list-workspace-apps only inventories apps mounted inside this workspace deployment; never use a missing row there to conclude that a connected agent is unavailable.
 - When answering whether a mounted workspace app exposes an agent card or A2A endpoint, call list-workspace-apps with includeAgentCards=true. If you have not requested that probe, absence of agent-card fields means unchecked, not unavailable.

package/src/shared/feature-flags.ts

@@ -0,0 +1,13 @@
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+/**
+ * Browser-only rollout for app-scoped sessions in Dispatch panes. The server
+ * action checks this flag too; the client hook only selects the presentation
+ * path and keeps the legacy embed route available while the flag is off.
+ */
+export const DISPATCH_WORKSPACE_SSO_FLAG = defineFeatureFlag({
+  key: "dispatch.workspace-sso",
+  displayName: "Dispatch workspace sign-in",
+  description:
+    "Let Dispatch use the signed-in workspace identity for exact registered app panes.",
+});

package/src/shared/workspace-sso.ts

@@ -0,0 +1,118 @@
+import { DISPATCH_WORKSPACE_SSO_FLAG } from "./feature-flags.js";
+
+export { DISPATCH_WORKSPACE_SSO_FLAG };
+
+/** Exact first-party origins. Never replace this with a suffix or wildcard. */
+export const CANONICAL_WORKSPACE_SSO_APP_ORIGINS = {
+  analytics: "https://analytics.agent-native.com",
+  assets: "https://assets.agent-native.com",
+  brain: "https://brain.agent-native.com",
+  calendar: "https://calendar.agent-native.com",
+  chat: "https://chat.agent-native.com",
+  clips: "https://clips.agent-native.com",
+  content: "https://content.agent-native.com",
+  crm: "https://crm.agent-native.com",
+  design: "https://design.agent-native.com",
+  dispatch: "https://dispatch.agent-native.com",
+  forms: "https://forms.agent-native.com",
+  macros: "https://macros.agent-native.com",
+  mail: "https://mail.agent-native.com",
+  plan: "https://plan.agent-native.com",
+  slides: "https://slides.agent-native.com",
+  tasks: "https://tasks.agent-native.com",
+} as const;
+
+export const WORKSPACE_SSO_CALLBACK_PATH =
+  "/_agent-native/identity/callback" as const;
+
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const APP_ID = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const CLIENT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+export interface WorkspaceSsoAppRegistration {
+  appId: string;
+  clientId: string;
+  origin: string;
+  callbackPath: typeof WORKSPACE_SSO_CALLBACK_PATH;
+}
+
+export function exactWorkspaceSsoOrigin(raw: unknown): string | null {
+  if (typeof raw !== "string" || !raw || CONTROL_CHARS.test(raw)) return null;
+  try {
+    const url = new URL(raw);
+    if (
+      url.protocol !== "https:" &&
+      !(url.protocol === "http:" && LOCALHOST_HOSTS.has(url.hostname))
+    ) {
+      return null;
+    }
+    if (
+      url.username ||
+      url.password ||
+      url.pathname !== "/" ||
+      url.search ||
+      url.hash
+    ) {
+      return null;
+    }
+    return url.origin;
+  } catch {
+    // coercion-ok: malformed registry origins are rejected as absent.
+    return null;
+  }
+}
+
+/**
+ * Parse the same additive custom registry used by browser identity SSO. The
+ * raw value is passed in so this shared module stays safe to import in the
+ * browser bundle.
+ */
+export function parseWorkspaceSsoAppRegistrations(
+  raw: unknown,
+): WorkspaceSsoAppRegistration[] {
+  if (typeof raw !== "string" || !raw.trim()) return [];
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    // coercion-ok: malformed custom registry data must fail closed.
+    return [];
+  }
+  if (!Array.isArray(value)) return [];
+
+  const registrations: WorkspaceSsoAppRegistration[] = [];
+  const seen = new Set<string>();
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object") continue;
+    const candidate = entry as Record<string, unknown>;
+    const appId = candidate.appId;
+    const clientId = candidate.clientId;
+    const origin = exactWorkspaceSsoOrigin(candidate.origin);
+    if (
+      typeof appId !== "string" ||
+      !APP_ID.test(appId) ||
+      typeof clientId !== "string" ||
+      !CLIENT_ID.test(clientId) ||
+      !origin ||
+      candidate.callbackPath !== WORKSPACE_SSO_CALLBACK_PATH ||
+      !Array.isArray(candidate.capabilities) ||
+      !candidate.capabilities.includes("identity-sso") ||
+      seen.has(appId) ||
+      Object.prototype.hasOwnProperty.call(
+        CANONICAL_WORKSPACE_SSO_APP_ORIGINS,
+        appId,
+      )
+    ) {
+      continue;
+    }
+    seen.add(appId);
+    registrations.push({
+      appId,
+      clientId,
+      origin,
+      callbackPath: WORKSPACE_SSO_CALLBACK_PATH,
+    });
+  }
+  return registrations;
+}