@topolo/sdk 0.4.1 → 0.4.2

package/README.md

@@ -89,12 +89,15 @@ PlatformApplications metadata, including Worker apps that do not expose a
 callable service. `DEFAULT_SERVICE_URLS` is the bundled callable API service
 snapshot generated from `topolo.cloudcontrol.json`.
 
-For agent-scale fleets, the bundle is a floor, not a cap. `TopoloClient.request`
-accepts bundled service IDs and live Auth-catalog service IDs/slugs. When a
-service is not in the bundled snapshot, the client resolves the selected
-environment's live catalog and only routes entries marked as API/technical
-service surfaces. Browser/runtime surfaces are not treated as generic API
-targets.
+For agent-scale fleets, the bundle is packaging metadata, not an authorization
+source. `TopoloClient.listServices()` always calls the live TopoloAuth catalog
+with the current credential and returns only services that credential can use in
+its organization, including the granted permissions. `TopoloClient.request()`
+uses that credential-scoped catalog before routing any non-Auth service, so a
+bundled service ID is only a convenient alias after Auth confirms access.
+
+`listBundledServices()` is available for packaging/audit tooling that needs the
+generated snapshot. Do not use it to decide what an end user or agent may call.
 
 `APPLICATION_REQUIREMENTS` is the versioned app-build contract agents should
 read before creating or expanding a Topolo app. `requirementsForApplication()`

package/dist/index.cjs

@@ -2258,12 +2258,16 @@ var TopoloClient = class _TopoloClient {
     if (!serviceKey) {
       throw new TopoloSdkError("unknown_service", "service is required");
     }
-    const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-    if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-    const staticUrl = DEFAULT_SERVICE_URLS[serviceKey];
-    if (staticUrl) return { serviceKey, baseUrl: staticUrl };
+    if (serviceKey === "auth") {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS.auth };
+    }
     const live = await this.resolveLiveCallableService(serviceKey);
-    if (live) return live;
+    if (live) {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+    }
     throw new TopoloSdkError(
       "unknown_service",
       `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`
@@ -2273,10 +2277,7 @@ var TopoloClient = class _TopoloClient {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
     if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return {
-      serviceKey: normalizeLookupKey(match.slug || match.name || match.serviceId) || serviceKey,
-      baseUrl: match.baseUrl
-    };
+    return { serviceKey, baseUrl: match.baseUrl };
   }
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
@@ -2338,53 +2339,55 @@ var TopoloClient = class _TopoloClient {
   /**
    * List the platform service catalog from the live registry
    * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-   * caller's credential is attached, so an authenticated caller in an
-   * entitled org also receives the `developer_only` services its role
-   * permits; an unauthenticated/agent caller receives `active` only.
+   * caller's credential is attached, so the result only includes services the
+   * credential's organization and effective permissions can use.
    *
-   * Resilient: on any network/HTTP failure this falls back to the
-   * build-time generated `APPLICATIONS` snapshot so offline/degraded
-   * callers still get a usable (if static) catalog. The live result is
-   * authoritative; the snapshot is a floor, not a cap.
+   * Security boundary: this never falls back to the generated global snapshot.
+   * The live Auth catalog is the authority because it is scoped to the caller's
+   * organization and effective permissions.
    */
   async listServices() {
     const now = Date.now();
     if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
       return this.serviceCatalogCache.entries;
     }
-    try {
-      const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
-      const raw = res.data?.services ?? res.services;
-      if (Array.isArray(raw) && raw.length > 0) {
-        const entries = [];
-        for (const item of raw) {
-          const s = item;
-          const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
-          if (!serviceId) continue;
-          entries.push({
-            serviceId,
-            slug: typeof s.app_slug === "string" ? s.app_slug : null,
-            name: typeof s.name === "string" ? s.name : null,
-            description: typeof s.description === "string" ? s.description : null,
-            baseUrl: typeof s.base_url === "string" ? s.base_url : null,
-            status: typeof s.status === "string" ? s.status : null,
-            surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
-            launchable: s.launchable === true
-          });
-        }
-        if (entries.length > 0) {
-          this.serviceCatalogCache = {
-            entries,
-            expiresAt: now + CATALOG_CACHE_TTL_MS
-          };
-          return entries;
-        }
-      }
-    } catch {
+    const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
+    const raw = res.data?.services ?? res.services;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        "service_catalog_unavailable",
+        "TopoloAuth did not return a service catalog for the current credential."
+      );
+    }
+    const entries = [];
+    for (const item of raw) {
+      const s = item;
+      const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
+      if (!serviceId) continue;
+      const permissions = Array.isArray(s.granted_permissions) ? s.granted_permissions.filter((permission) => typeof permission === "string" && permission.trim().length > 0) : [];
+      entries.push({
+        serviceId,
+        slug: typeof s.app_slug === "string" ? s.app_slug : null,
+        name: typeof s.name === "string" ? s.name : null,
+        description: typeof s.description === "string" ? s.description : null,
+        baseUrl: typeof s.base_url === "string" ? s.base_url : null,
+        status: typeof s.status === "string" ? s.status : null,
+        surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
+        launchable: s.launchable === true,
+        permissions
+      });
     }
-    return this.generatedCatalogFallback();
+    this.serviceCatalogCache = {
+      entries,
+      expiresAt: now + CATALOG_CACHE_TTL_MS
+    };
+    return entries;
   }
-  generatedCatalogFallback() {
+  /**
+   * Bundled generated registry for tooling that audits platform packaging, not
+   * for deciding what the current credential may use.
+   */
+  listBundledServices() {
     const apps = Object.values(APPLICATIONS);
     return apps.map((app) => ({
       serviceId: app.id,
@@ -2392,9 +2395,10 @@ var TopoloClient = class _TopoloClient {
       name: app.name ?? app.id,
       description: null,
       baseUrl: app.productionUrl ?? null,
-      status: "active",
+      status: "bundled",
       surfaceKind: "application",
-      launchable: Boolean(app.productionUrl)
+      launchable: Boolean(app.productionUrl),
+      permissions: []
     }));
   }
   /**
@@ -2464,7 +2468,7 @@ function serviceKeyCandidates(slug) {
   ])];
 }
 function normalizeLookupKey(value) {
-  return String(value || "").trim().toLowerCase();
+  return String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
 }
 function catalogEntryMatches(entry, needle) {
   return catalogEntryLookupKeys(entry).includes(needle);
@@ -2475,12 +2479,8 @@ function catalogEntryLookupKeys(entry) {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    keys.add(normalized);
-    keys.add(normalized.replace(/-/g, "_"));
-    if (normalized.startsWith("topolo-")) {
-      const withoutTopolo = normalized.slice("topolo-".length);
-      keys.add(withoutTopolo);
-      keys.add(withoutTopolo.replace(/-/g, "_"));
+    for (const candidate of serviceKeyCandidates(normalized)) {
+      keys.add(candidate);
     }
   }
   return [...keys];
@@ -2488,7 +2488,9 @@ function catalogEntryLookupKeys(entry) {
 function isCallableCatalogEntry(entry) {
   const kind = normalizeLookupKey(entry.surfaceKind || "");
   if (kind === "api" || kind === "technical_service" || kind === "service") return true;
-  return Boolean(entry.slug && Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, catalogEntryLookupKeys(entry)[0] ?? ""));
+  return Boolean(
+    entry.baseUrl && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
+  );
 }
 function describeError(body, fallback) {
   if (body && typeof body === "object") {

package/dist/index.d.cts

@@ -108,6 +108,7 @@ interface TopoloServiceCatalogEntry {
     status: string | null;
     surfaceKind: string | null;
     launchable: boolean;
+    permissions: string[];
 }
 declare class TopoloClient {
     private readonly credential;
@@ -157,17 +158,19 @@ declare class TopoloClient {
     /**
      * List the platform service catalog from the live registry
      * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-     * caller's credential is attached, so an authenticated caller in an
-     * entitled org also receives the `developer_only` services its role
-     * permits; an unauthenticated/agent caller receives `active` only.
+     * caller's credential is attached, so the result only includes services the
+     * credential's organization and effective permissions can use.
      *
-     * Resilient: on any network/HTTP failure this falls back to the
-     * build-time generated `APPLICATIONS` snapshot so offline/degraded
-     * callers still get a usable (if static) catalog. The live result is
-     * authoritative; the snapshot is a floor, not a cap.
+     * Security boundary: this never falls back to the generated global snapshot.
+     * The live Auth catalog is the authority because it is scoped to the caller's
+     * organization and effective permissions.
      */
     listServices(): Promise<TopoloServiceCatalogEntry[]>;
-    private generatedCatalogFallback;
+    /**
+     * Bundled generated registry for tooling that audits platform packaging, not
+     * for deciding what the current credential may use.
+     */
+    listBundledServices(): TopoloServiceCatalogEntry[];
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/dist/index.d.ts

@@ -108,6 +108,7 @@ interface TopoloServiceCatalogEntry {
     status: string | null;
     surfaceKind: string | null;
     launchable: boolean;
+    permissions: string[];
 }
 declare class TopoloClient {
     private readonly credential;
@@ -157,17 +158,19 @@ declare class TopoloClient {
     /**
      * List the platform service catalog from the live registry
      * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-     * caller's credential is attached, so an authenticated caller in an
-     * entitled org also receives the `developer_only` services its role
-     * permits; an unauthenticated/agent caller receives `active` only.
+     * caller's credential is attached, so the result only includes services the
+     * credential's organization and effective permissions can use.
      *
-     * Resilient: on any network/HTTP failure this falls back to the
-     * build-time generated `APPLICATIONS` snapshot so offline/degraded
-     * callers still get a usable (if static) catalog. The live result is
-     * authoritative; the snapshot is a floor, not a cap.
+     * Security boundary: this never falls back to the generated global snapshot.
+     * The live Auth catalog is the authority because it is scoped to the caller's
+     * organization and effective permissions.
      */
     listServices(): Promise<TopoloServiceCatalogEntry[]>;
-    private generatedCatalogFallback;
+    /**
+     * Bundled generated registry for tooling that audits platform packaging, not
+     * for deciding what the current credential may use.
+     */
+    listBundledServices(): TopoloServiceCatalogEntry[];
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate

package/dist/index.js

@@ -2204,12 +2204,16 @@ var TopoloClient = class _TopoloClient {
     if (!serviceKey) {
       throw new TopoloSdkError("unknown_service", "service is required");
     }
-    const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-    if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-    const staticUrl = DEFAULT_SERVICE_URLS[serviceKey];
-    if (staticUrl) return { serviceKey, baseUrl: staticUrl };
+    if (serviceKey === "auth") {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS.auth };
+    }
     const live = await this.resolveLiveCallableService(serviceKey);
-    if (live) return live;
+    if (live) {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+    }
     throw new TopoloSdkError(
       "unknown_service",
       `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`
@@ -2219,10 +2223,7 @@ var TopoloClient = class _TopoloClient {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
     if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return {
-      serviceKey: normalizeLookupKey(match.slug || match.name || match.serviceId) || serviceKey,
-      baseUrl: match.baseUrl
-    };
+    return { serviceKey, baseUrl: match.baseUrl };
   }
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
@@ -2284,53 +2285,55 @@ var TopoloClient = class _TopoloClient {
   /**
    * List the platform service catalog from the live registry
    * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-   * caller's credential is attached, so an authenticated caller in an
-   * entitled org also receives the `developer_only` services its role
-   * permits; an unauthenticated/agent caller receives `active` only.
+   * caller's credential is attached, so the result only includes services the
+   * credential's organization and effective permissions can use.
    *
-   * Resilient: on any network/HTTP failure this falls back to the
-   * build-time generated `APPLICATIONS` snapshot so offline/degraded
-   * callers still get a usable (if static) catalog. The live result is
-   * authoritative; the snapshot is a floor, not a cap.
+   * Security boundary: this never falls back to the generated global snapshot.
+   * The live Auth catalog is the authority because it is scoped to the caller's
+   * organization and effective permissions.
    */
   async listServices() {
     const now = Date.now();
     if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
       return this.serviceCatalogCache.entries;
     }
-    try {
-      const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
-      const raw = res.data?.services ?? res.services;
-      if (Array.isArray(raw) && raw.length > 0) {
-        const entries = [];
-        for (const item of raw) {
-          const s = item;
-          const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
-          if (!serviceId) continue;
-          entries.push({
-            serviceId,
-            slug: typeof s.app_slug === "string" ? s.app_slug : null,
-            name: typeof s.name === "string" ? s.name : null,
-            description: typeof s.description === "string" ? s.description : null,
-            baseUrl: typeof s.base_url === "string" ? s.base_url : null,
-            status: typeof s.status === "string" ? s.status : null,
-            surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
-            launchable: s.launchable === true
-          });
-        }
-        if (entries.length > 0) {
-          this.serviceCatalogCache = {
-            entries,
-            expiresAt: now + CATALOG_CACHE_TTL_MS
-          };
-          return entries;
-        }
-      }
-    } catch {
+    const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
+    const raw = res.data?.services ?? res.services;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        "service_catalog_unavailable",
+        "TopoloAuth did not return a service catalog for the current credential."
+      );
+    }
+    const entries = [];
+    for (const item of raw) {
+      const s = item;
+      const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
+      if (!serviceId) continue;
+      const permissions = Array.isArray(s.granted_permissions) ? s.granted_permissions.filter((permission) => typeof permission === "string" && permission.trim().length > 0) : [];
+      entries.push({
+        serviceId,
+        slug: typeof s.app_slug === "string" ? s.app_slug : null,
+        name: typeof s.name === "string" ? s.name : null,
+        description: typeof s.description === "string" ? s.description : null,
+        baseUrl: typeof s.base_url === "string" ? s.base_url : null,
+        status: typeof s.status === "string" ? s.status : null,
+        surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
+        launchable: s.launchable === true,
+        permissions
+      });
     }
-    return this.generatedCatalogFallback();
+    this.serviceCatalogCache = {
+      entries,
+      expiresAt: now + CATALOG_CACHE_TTL_MS
+    };
+    return entries;
   }
-  generatedCatalogFallback() {
+  /**
+   * Bundled generated registry for tooling that audits platform packaging, not
+   * for deciding what the current credential may use.
+   */
+  listBundledServices() {
     const apps = Object.values(APPLICATIONS);
     return apps.map((app) => ({
       serviceId: app.id,
@@ -2338,9 +2341,10 @@ var TopoloClient = class _TopoloClient {
       name: app.name ?? app.id,
       description: null,
       baseUrl: app.productionUrl ?? null,
-      status: "active",
+      status: "bundled",
       surfaceKind: "application",
-      launchable: Boolean(app.productionUrl)
+      launchable: Boolean(app.productionUrl),
+      permissions: []
     }));
   }
   /**
@@ -2410,7 +2414,7 @@ function serviceKeyCandidates(slug) {
   ])];
 }
 function normalizeLookupKey(value) {
-  return String(value || "").trim().toLowerCase();
+  return String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
 }
 function catalogEntryMatches(entry, needle) {
   return catalogEntryLookupKeys(entry).includes(needle);
@@ -2421,12 +2425,8 @@ function catalogEntryLookupKeys(entry) {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    keys.add(normalized);
-    keys.add(normalized.replace(/-/g, "_"));
-    if (normalized.startsWith("topolo-")) {
-      const withoutTopolo = normalized.slice("topolo-".length);
-      keys.add(withoutTopolo);
-      keys.add(withoutTopolo.replace(/-/g, "_"));
+    for (const candidate of serviceKeyCandidates(normalized)) {
+      keys.add(candidate);
     }
   }
   return [...keys];
@@ -2434,7 +2434,9 @@ function catalogEntryLookupKeys(entry) {
 function isCallableCatalogEntry(entry) {
   const kind = normalizeLookupKey(entry.surfaceKind || "");
   if (kind === "api" || kind === "technical_service" || kind === "service") return true;
-  return Boolean(entry.slug && Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, catalogEntryLookupKeys(entry)[0] ?? ""));
+  return Boolean(
+    entry.baseUrl && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
+  );
 }
 function describeError(body, fallback) {
   if (body && typeof body === "object") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.test.ts

@@ -17,9 +17,29 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown; contentTy
 
 const AGENT = { clientName: 'topolo-test', clientVersion: '0.0.0' };
 const SERVICE_LOOKUP = { body: { success: true, data: { service_id: 'service_test' } } };
+const CRM_CATALOG = {
+  body: {
+    data: {
+      services: [
+        {
+          service_id: 'srv_crm',
+          app_slug: 'topolo-crm',
+          name: 'Topolo CRM',
+          base_url: 'https://crm-api.topolo.app',
+          surface_kind: 'api',
+          status: 'active',
+          granted_permissions: ['srv_crm.contacts:read'],
+        },
+      ],
+    },
+  },
+};
 
 function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
-  return calls.filter((call) => !call.url.includes('/api/services/by-slug/'));
+  return calls.filter((call) =>
+    !call.url.includes('/api/services/by-slug/') &&
+    !call.url.includes('/api/services/catalog')
+  );
 }
 
 beforeEach(() => {
@@ -28,7 +48,7 @@ beforeEach(() => {
 
 describe('TopoloClient.request', () => {
   it('injects Bearer auth + audit headers for access_token credentials', async () => {
-    const { impl, calls } = stubFetch([{ body: { ok: true } }]);
+    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { ok: true } }]);
     const client = new TopoloClient({
       credential: { kind: 'access_token', accessToken: 'tok_abc' },
       agent: AGENT,
@@ -44,7 +64,7 @@ describe('TopoloClient.request', () => {
   });
 
   it('uses X-Api-Key header for api_key credentials', async () => {
-    const { impl, calls } = stubFetch([{ body: { ok: true } }]);
+    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { ok: true } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
@@ -69,7 +89,7 @@ describe('TopoloClient.request', () => {
   });
 
   it('allows mutating requests with confirm: true', async () => {
-    const { impl, calls } = stubFetch([{ body: { id: 'c_1' } }]);
+    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { id: 'c_1' } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
@@ -122,6 +142,7 @@ describe('TopoloClient.request', () => {
 
   it('maps 403 → TopoloPermissionError with required scopes extracted', async () => {
     const { impl } = stubFetch([
+      CRM_CATALOG,
       { status: 403, body: { error: 'forbidden', required: ['crm.contacts:write'] } },
     ]);
     const client = new TopoloClient({
@@ -135,7 +156,7 @@ describe('TopoloClient.request', () => {
   });
 
   it('maps non-401/403 failures → TopoloHttpError with status preserved', async () => {
-    const { impl } = stubFetch([{ status: 500, body: { error: 'boom' } }]);
+    const { impl } = stubFetch([CRM_CATALOG, { status: 500, body: { error: 'boom' } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
@@ -148,7 +169,7 @@ describe('TopoloClient.request', () => {
   });
 
   it('appends query params as search string', async () => {
-    const { impl, calls } = stubFetch([{ body: { contacts: [] } }]);
+    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { contacts: [] } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
@@ -369,6 +390,7 @@ describe('TopoloClient.listServices', () => {
                 status: 'active',
                 surface_kind: 'application',
                 launchable: true,
+                granted_permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
               },
             ],
           },
@@ -392,6 +414,7 @@ describe('TopoloClient.listServices', () => {
         status: 'active',
         surfaceKind: 'application',
         launchable: true,
+        permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
       },
     ]);
     expect(calls[0]!.url).toBe(
@@ -402,7 +425,7 @@ describe('TopoloClient.listServices', () => {
     );
   });
 
-  it('falls back to the generated snapshot on HTTP failure', async () => {
+  it('does not fall back to the generated global snapshot on HTTP failure', async () => {
     const { impl } = stubFetch([{ status: 503, body: { error: 'down' } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
@@ -410,25 +433,23 @@ describe('TopoloClient.listServices', () => {
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com' },
     });
-    const out = await client.listServices();
-    expect(out.length).toBeGreaterThan(10);
-    expect(out.some((e) => e.serviceId === 'admin')).toBe(true);
-    expect(out.every((e) => typeof e.serviceId === 'string')).toBe(true);
+    await expect(client.listServices()).rejects.toBeInstanceOf(TopoloHttpError);
   });
 
-  it('resolves future API services from the live catalog during request routing', async () => {
+  it('routes bundled service aliases only after the scoped live catalog grants access', async () => {
     const { impl, calls } = stubFetch([
       {
         body: {
           data: {
             services: [
               {
-                service_id: 'srv_future',
-                app_slug: 'topolo-warehouse',
-                name: 'Warehouse',
-                base_url: 'https://warehouse.topolo.app',
-                surface_kind: 'api',
+                service_id: 'srv_mail',
+                app_slug: 'topolo-mail',
+                name: 'Topolo Mail',
+                base_url: 'https://mail.topolo.app',
+                surface_kind: 'application',
                 status: 'active',
+                granted_permissions: ['srv_mail.messages:read'],
               },
             ],
           },
@@ -443,10 +464,43 @@ describe('TopoloClient.listServices', () => {
       serviceUrls: { auth: 'https://auth.example.com' },
     });
 
-    await client.request({ service: 'warehouse', path: '/api/health' });
+    await client.request({ service: 'mail', path: '/api/health' });
 
     expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
-    expect(calls[1]!.url).toBe('https://warehouse.topolo.app/api/health');
+    expect(calls[1]!.url).toBe('https://mail.topolo.app/api/health');
+  });
+
+  it('refuses a bundled static service that is absent from the scoped live catalog', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_crm',
+                app_slug: 'topolo-crm',
+                name: 'Topolo CRM',
+                base_url: 'https://crm-api.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+                granted_permissions: ['srv_crm.contacts:read'],
+              },
+            ],
+          },
+        },
+      },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+
+    await expect(client.request({ service: 'mail', path: '/api/health' })).rejects.toMatchObject({
+      code: 'unknown_service',
+    });
+    expect(calls).toHaveLength(1);
   });
 
   it('does not treat live browser applications as generic API services', async () => {
@@ -462,6 +516,7 @@ describe('TopoloClient.listServices', () => {
                 base_url: 'https://future-app.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
+                granted_permissions: ['srv_future_app.launch:read'],
                 launchable: true,
               },
             ],
@@ -494,6 +549,7 @@ describe('TopoloClient.listServices', () => {
                 base_url: 'https://warehouse.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
+                granted_permissions: ['srv_future.read:all'],
               },
             ],
           },

package/src/client.ts

@@ -107,6 +107,7 @@ export interface TopoloServiceCatalogEntry {
   status: string | null;
   surfaceKind: string | null;
   launchable: boolean;
+  permissions: string[];
 }
 
 export class TopoloClient {
@@ -278,14 +279,17 @@ export class TopoloClient {
       throw new TopoloSdkError('unknown_service', 'service is required');
     }
 
-    const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-    if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-
-    const staticUrl = DEFAULT_SERVICE_URLS[serviceKey as ServiceId];
-    if (staticUrl) return { serviceKey, baseUrl: staticUrl };
+    if (serviceKey === 'auth') {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS.auth };
+    }
 
     const live = await this.resolveLiveCallableService(serviceKey);
-    if (live) return live;
+    if (live) {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+    }
 
     throw new TopoloSdkError(
       'unknown_service',
@@ -297,10 +301,7 @@ export class TopoloClient {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
     if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return {
-      serviceKey: normalizeLookupKey(match.slug || match.name || match.serviceId) || serviceKey,
-      baseUrl: match.baseUrl,
-    };
+    return { serviceKey, baseUrl: match.baseUrl };
   }
 
   /**
@@ -374,14 +375,12 @@ export class TopoloClient {
   /**
    * List the platform service catalog from the live registry
    * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-   * caller's credential is attached, so an authenticated caller in an
-   * entitled org also receives the `developer_only` services its role
-   * permits; an unauthenticated/agent caller receives `active` only.
+   * caller's credential is attached, so the result only includes services the
+   * credential's organization and effective permissions can use.
    *
-   * Resilient: on any network/HTTP failure this falls back to the
-   * build-time generated `APPLICATIONS` snapshot so offline/degraded
-   * callers still get a usable (if static) catalog. The live result is
-   * authoritative; the snapshot is a floor, not a cap.
+   * Security boundary: this never falls back to the generated global snapshot.
+   * The live Auth catalog is the authority because it is scoped to the caller's
+   * organization and effective permissions.
    */
   async listServices(): Promise<TopoloServiceCatalogEntry[]> {
     const now = Date.now();
@@ -389,53 +388,60 @@ export class TopoloClient {
       return this.serviceCatalogCache.entries;
     }
 
-    try {
-      const res = await this.request<
-        | { data?: { services?: unknown[] } }
-        | { services?: unknown[] }
-      >({ service: 'auth', method: 'GET', path: '/api/services/catalog' });
-      const raw =
-        (res as { data?: { services?: unknown[] } }).data?.services ??
-        (res as { services?: unknown[] }).services;
-      if (Array.isArray(raw) && raw.length > 0) {
-        const entries: TopoloServiceCatalogEntry[] = [];
-        for (const item of raw) {
-          const s = item as Record<string, unknown>;
-          const serviceId =
-            typeof s.service_id === 'string'
-              ? s.service_id
-              : typeof s.id === 'string'
-                ? s.id
-                : null;
-          if (!serviceId) continue;
-          entries.push({
-            serviceId,
-            slug: typeof s.app_slug === 'string' ? s.app_slug : null,
-            name: typeof s.name === 'string' ? s.name : null,
-            description:
-              typeof s.description === 'string' ? s.description : null,
-            baseUrl: typeof s.base_url === 'string' ? s.base_url : null,
-            status: typeof s.status === 'string' ? s.status : null,
-            surfaceKind:
-              typeof s.surface_kind === 'string' ? s.surface_kind : null,
-            launchable: s.launchable === true,
-          });
-        }
-        if (entries.length > 0) {
-          this.serviceCatalogCache = {
-            entries,
-            expiresAt: now + CATALOG_CACHE_TTL_MS,
-          };
-          return entries;
-        }
-      }
-    } catch {
-      // Fall through to the generated snapshot.
+    const res = await this.request<
+      | { data?: { services?: unknown[] } }
+      | { services?: unknown[] }
+    >({ service: 'auth', method: 'GET', path: '/api/services/catalog' });
+    const raw =
+      (res as { data?: { services?: unknown[] } }).data?.services ??
+      (res as { services?: unknown[] }).services;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        'service_catalog_unavailable',
+        'TopoloAuth did not return a service catalog for the current credential.',
+      );
+    }
+
+    const entries: TopoloServiceCatalogEntry[] = [];
+    for (const item of raw) {
+      const s = item as Record<string, unknown>;
+      const serviceId =
+        typeof s.service_id === 'string'
+          ? s.service_id
+          : typeof s.id === 'string'
+            ? s.id
+            : null;
+      if (!serviceId) continue;
+      const permissions = Array.isArray(s.granted_permissions)
+        ? s.granted_permissions
+            .filter((permission): permission is string => typeof permission === 'string' && permission.trim().length > 0)
+        : [];
+      entries.push({
+        serviceId,
+        slug: typeof s.app_slug === 'string' ? s.app_slug : null,
+        name: typeof s.name === 'string' ? s.name : null,
+        description:
+          typeof s.description === 'string' ? s.description : null,
+        baseUrl: typeof s.base_url === 'string' ? s.base_url : null,
+        status: typeof s.status === 'string' ? s.status : null,
+        surfaceKind:
+          typeof s.surface_kind === 'string' ? s.surface_kind : null,
+        launchable: s.launchable === true,
+        permissions,
+      });
     }
-    return this.generatedCatalogFallback();
+    this.serviceCatalogCache = {
+      entries,
+      expiresAt: now + CATALOG_CACHE_TTL_MS,
+    };
+    return entries;
   }
 
-  private generatedCatalogFallback(): TopoloServiceCatalogEntry[] {
+  /**
+   * Bundled generated registry for tooling that audits platform packaging, not
+   * for deciding what the current credential may use.
+   */
+  listBundledServices(): TopoloServiceCatalogEntry[] {
     const apps = Object.values(APPLICATIONS) as ReadonlyArray<{
       id: string;
       name?: string;
@@ -447,9 +453,10 @@ export class TopoloClient {
       name: app.name ?? app.id,
       description: null,
       baseUrl: app.productionUrl ?? null,
-      status: 'active',
+      status: 'bundled',
       surfaceKind: 'application',
       launchable: Boolean(app.productionUrl),
+      permissions: [],
     }));
   }
 
@@ -543,7 +550,7 @@ function serviceKeyCandidates(slug: string): string[] {
 }
 
 function normalizeLookupKey(value: string): string {
-  return String(value || '').trim().toLowerCase();
+  return String(value || '').trim().toLowerCase().replace(/\s+/g, '-');
 }
 
 function catalogEntryMatches(entry: TopoloServiceCatalogEntry, needle: string): boolean {
@@ -558,12 +565,8 @@ function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    keys.add(normalized);
-    keys.add(normalized.replace(/-/g, '_'));
-    if (normalized.startsWith('topolo-')) {
-      const withoutTopolo = normalized.slice('topolo-'.length);
-      keys.add(withoutTopolo);
-      keys.add(withoutTopolo.replace(/-/g, '_'));
+    for (const candidate of serviceKeyCandidates(normalized)) {
+      keys.add(candidate);
     }
   }
   return [...keys];
@@ -572,7 +575,10 @@ function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
 function isCallableCatalogEntry(entry: TopoloServiceCatalogEntry): boolean {
   const kind = normalizeLookupKey(entry.surfaceKind || '');
   if (kind === 'api' || kind === 'technical_service' || kind === 'service') return true;
-  return Boolean(entry.slug && Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, catalogEntryLookupKeys(entry)[0] ?? ''));
+  return Boolean(
+    entry.baseUrl &&
+    catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key)),
+  );
 }
 
 interface AuthMePayload {

package/src/modules/p2p.test.ts

@@ -14,6 +14,26 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
         headers: { 'Content-Type': 'application/json' },
       });
     }
+    if (String(url).includes('/api/services/catalog')) {
+      return new Response(JSON.stringify({
+        data: {
+          services: [
+            {
+              service_id: 'srv_p2p',
+              app_slug: 'topolo-p2p',
+              name: 'Topolo P2P',
+              base_url: 'https://p2p.topolo.app',
+              surface_kind: 'api',
+              status: 'active',
+              granted_permissions: ['srv_p2p.directory:read'],
+            },
+          ],
+        },
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
     const next = responses.shift() ?? { status: 200, body: { success: true, data: {} } };
     return new Response(JSON.stringify(next.body ?? { success: true, data: {} }), {
       status: next.status ?? 200,
@@ -24,7 +44,10 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
 }
 
 function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
-  return calls.filter((call) => !call.url.includes('/api/services/by-slug/'));
+  return calls.filter((call) =>
+    !call.url.includes('/api/services/by-slug/') &&
+    !call.url.includes('/api/services/catalog')
+  );
 }
 
 function clientWith(impl: typeof fetch) {
@@ -138,7 +161,7 @@ describe('P2PModule.publishCapability', () => {
     expect(sent.trust_level).toBe('standard');
     const url = new URL(call.url);
     expect(url.pathname).toBe('/api/p2p/internal/capabilities/sync');
-    expect((calls[0]!.init.method ?? '').toUpperCase()).toBe('POST');
+    expect((call.init.method ?? '').toUpperCase()).toBe('POST');
   });
 
   it('honours an explicit acting_for_org_id when the platform key is publishing for another org', async () => {