@horizonmedia/blu-sdk 0.0.0-stage → 1.8.4

package/index.js

@@ -0,0 +1,34 @@
+import {
+  ApiError,
+  beginBluSignIn,
+  completeBluSignIn,
+  useApiClient,
+  useAuthToken,
+  useClient,
+  useEnvironment,
+  useEventBus,
+  useHost,
+  useOptionalHost,
+  useRoles,
+  useRoute,
+  useShell,
+  useTheme,
+  useUser
+} from "./chunks/chunk-M7GVSOGQ.js";
+export {
+  ApiError,
+  beginBluSignIn,
+  completeBluSignIn,
+  useApiClient,
+  useAuthToken,
+  useClient,
+  useEnvironment,
+  useEventBus,
+  useHost,
+  useOptionalHost,
+  useRoles,
+  useRoute,
+  useShell,
+  useTheme,
+  useUser
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@horizonmedia/blu-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.8.4",
+  "description": "The Blu SDK: a module's front end (@blu/sdk), isolated iframe modules (@blu/sdk/frame), the module's API (@blu/sdk/server) and running a module on its own (@blu/sdk/dev).",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HorizonMedia/blu-composable-experience.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/HorizonMedia/blu-composable-experience/tree/main/packages/sdk#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "bin": {
+    "blu": "bin/blu.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./frame": {
+      "types": "./types/frame.d.ts",
+      "default": "./frame.js"
+    },
+    "./server": {
+      "types": "./types/server.d.ts",
+      "default": "./server.js"
+    },
+    "./dev": {
+      "types": "./types/dev.d.ts",
+      "default": "./dev.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "jose": "^6.0.0",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  }
+}

package/server.js

@@ -0,0 +1,466 @@
+import {
+  REGISTRY_URL,
+  bluIssuer,
+  bluShellOrigins,
+  buildRoutePath,
+  diffToolsAgainstManifest,
+  isLocalUrl
+} from "./chunks/chunk-CSQHQLB7.js";
+
+// src/server/index.js
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createRemoteJWKSet, decodeJwt, errors as joseErrors, jwtVerify } from "jose";
+
+// src/server/mcp.js
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+var link = (route, params, label) => ({ route, params, label });
+function offeredTo(tools, principal) {
+  return tools.filter((t) => policyAllows(t.policy, principal) && (!principal?.actor || t.annotations?.readOnlyHint === true));
+}
+function policyAllows(policy, principal) {
+  const required = policy[principal.authMode];
+  return Boolean(required) && required.every((p) => principal.permissions.includes("*") || principal.permissions.includes(p));
+}
+function createMcpEndpoint({ name, version, authenticate, tools, manifest }) {
+  if (manifest) {
+    const drift = diffToolsAgainstManifest(tools, manifest);
+    if (drift.length) {
+      throw new Error(`[${name}] MCP tools don't match blu.module.json:
+  - ${drift.join("\n  - ")}`);
+    }
+  }
+  const routes = manifest?.routes ?? [];
+  const validLinks = (links) => links.filter((l) => {
+    const route = routes.find((r) => r.name === l?.route);
+    const ok = Boolean(route && buildRoutePath(route, l.params ?? {}));
+    if (!ok) console.warn(`[${name}] dropped link to undeclared or incomplete route "${l?.route}"`);
+    return ok;
+  });
+  async function handle(req, res) {
+    const principal = req.principal;
+    const server = new McpServer({ name, version });
+    const visible = offeredTo(tools, principal);
+    for (const t of visible) {
+      server.registerTool(
+        t.name,
+        { title: t.title, description: t.description, inputSchema: t.input ?? {}, annotations: t.annotations },
+        async (args) => {
+          try {
+            const out = await t.run(principal, args ?? {});
+            return {
+              content: [
+                { type: "text", text: out.summary },
+                { type: "text", text: `data: ${JSON.stringify(out.data)}` }
+              ],
+              // Links travel as data beside the text (not in it), and only to declared routes.
+              ...out.links?.length ? { _meta: { "blu/links": validLinks(out.links) } } : {}
+            };
+          } catch (e) {
+            return { isError: true, content: [{ type: "text", text: e.message }] };
+          }
+        }
+      );
+    }
+    if (visible.length === 0) {
+      server.server.registerCapabilities({ tools: {} });
+      server.server.setRequestHandler((await import("@modelcontextprotocol/sdk/types.js")).ListToolsRequestSchema, () => ({ tools: [] }));
+    }
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
+    res.on("close", () => {
+      transport.close();
+      server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  }
+  return [
+    authenticate,
+    (req, res, next) => handle(req, res).catch(next)
+  ];
+}
+function createMcpWebHandler({ name, version, verify, tools, manifest }) {
+  if (manifest) {
+    const drift = diffToolsAgainstManifest(tools, manifest);
+    if (drift.length) throw new Error(`[${name}] MCP tools don't match blu.module.json:
+  - ${drift.join("\n  - ")}`);
+  }
+  const routes = manifest?.routes ?? [];
+  const validLinks = (links) => links.filter((l) => {
+    const route = routes.find((r) => r.name === l?.route);
+    return Boolean(route && buildRoutePath(route, l.params ?? {}));
+  });
+  return async function handle(request) {
+    let principal;
+    try {
+      principal = await verify(request);
+    } catch (e) {
+      return Response.json({ error: e.code ?? "unauthorized", detail: e.message }, { status: e.status ?? 401 });
+    }
+    const server = new McpServer({ name, version });
+    const visible = offeredTo(tools, principal);
+    for (const t of visible) {
+      server.registerTool(t.name, { title: t.title, description: t.description, inputSchema: t.input ?? {}, annotations: t.annotations }, async (args) => {
+        try {
+          const out = await t.run(principal, args ?? {});
+          return {
+            content: [
+              { type: "text", text: out.summary },
+              { type: "text", text: `data: ${JSON.stringify(out.data)}` }
+            ],
+            ...out.links?.length ? { _meta: { "blu/links": validLinks(out.links) } } : {}
+          };
+        } catch (e) {
+          return { isError: true, content: [{ type: "text", text: e.message }] };
+        }
+      });
+    }
+    if (visible.length === 0) {
+      server.server.registerCapabilities({ tools: {} });
+      server.server.setRequestHandler((await import("@modelcontextprotocol/sdk/types.js")).ListToolsRequestSchema, () => ({ tools: [] }));
+    }
+    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
+    await server.connect(transport);
+    try {
+      return await transport.handleRequest(request);
+    } finally {
+      queueMicrotask(() => server.close().catch(() => {
+      }));
+    }
+  };
+}
+
+// src/server/index.js
+var ENTRY_POINTS = ["blu", "service", "team", "api-key"];
+var AuthError = class extends Error {
+  constructor(status, code, detail) {
+    super(detail);
+    this.status = status;
+    this.code = code;
+  }
+};
+function jwtFailure(err, issuerLabel) {
+  if (err instanceof AuthError) return err;
+  const detail = err instanceof joseErrors.JWTExpired ? `${issuerLabel} token expired` : err instanceof joseErrors.JWSSignatureVerificationFailed ? `signature does not verify against the ${issuerLabel} JWKS (tampered or foreign token)` : `${issuerLabel}: ${err.code ?? err.message}`;
+  return new AuthError(401, "invalid_token", detail);
+}
+var principalKey = (authMode, issuer, subject) => `${authMode}|${issuer}|${subject}`;
+var isDevIdentity = (payload) => Array.isArray(payload.amr) && payload.amr.includes("mock");
+function bluPlatformAuth({ issuer, jwksUrl, moduleId, roleMap }) {
+  const audience = `blu-module:${moduleId}`;
+  const jwks = createRemoteJWKSet(new URL(jwksUrl), { cooldownDuration: 5e3, cacheMaxAge: 10 * 6e4 });
+  return {
+    mode: "blu",
+    kind: "bearer",
+    issuer,
+    accepts: (claims) => (claims.token_use ?? "user") === "user",
+    async authenticate(token) {
+      let payload;
+      try {
+        ({ payload } = await jwtVerify(token, jwks, { issuer, audience, algorithms: ["RS256"] }));
+      } catch (e) {
+        throw jwtFailure(e, "Blu");
+      }
+      const scope = Array.isArray(payload.tenant_scope) ? payload.tenant_scope : [];
+      if (!payload.cid || !scope.includes(payload.cid)) {
+        throw new AuthError(403, "no_active_client", "Blu token has no active client in scope.");
+      }
+      const roles = payload.roles ?? [];
+      return {
+        authMode: "blu",
+        kind: "user",
+        issuer,
+        subject: payload.sub,
+        key: principalKey("blu", issuer, payload.sub),
+        devIdentity: isDevIdentity(payload),
+        displayName: payload.name ?? payload.email ?? payload.sub,
+        email: payload.email,
+        provider: payload.provider,
+        // how Blu authenticated the user (e.g. "entra")
+        via: payload.azp,
+        actor: payload.act?.sub,
+        clientId: payload.cid,
+        allowedClients: scope,
+        roles,
+        permissions: [...new Set(roles.flatMap((r) => roleMap[r] ?? []))]
+      };
+    }
+  };
+}
+function bluServiceAuth({ issuer, jwksUrl, moduleId }) {
+  const jwks = createRemoteJWKSet(new URL(jwksUrl), { cooldownDuration: 5e3, cacheMaxAge: 10 * 6e4 });
+  return {
+    mode: "service",
+    kind: "bearer",
+    issuer,
+    accepts: (claims) => claims.token_use === "service",
+    async authenticate(token, req) {
+      let payload;
+      try {
+        ({ payload } = await jwtVerify(token, jwks, { issuer, audience: `blu-module:${moduleId}`, algorithms: ["RS256"] }));
+      } catch (e) {
+        throw jwtFailure(e, "Blu service");
+      }
+      const clients = payload.clients ?? [];
+      const asked = req.get("x-client-id") ?? req.query.clientId;
+      const clientId = asked ?? (clients.length === 1 ? clients[0] : null);
+      if (!clientId) throw new AuthError(400, "client_required", "Service calls must name a client with X-Client-Id.");
+      if (!clients.includes(clientId)) {
+        throw new AuthError(403, "client_not_granted", `Module "${moduleId}" isn't enabled for client "${clientId}", so service "${payload.sub}" can't act for it.`);
+      }
+      return {
+        authMode: "service",
+        kind: "service",
+        issuer,
+        subject: payload.sub,
+        key: principalKey("service", issuer, payload.sub),
+        displayName: payload.name ?? payload.sub,
+        clientId,
+        allowedClients: clients,
+        roles: [],
+        permissions: String(payload.scope ?? "").split(" ").filter(Boolean),
+        clientFromRequest: true
+      };
+    }
+  };
+}
+function teamIdpAuth({ issuer, jwksUrl, audience, toPrincipal }) {
+  const jwks = createRemoteJWKSet(new URL(jwksUrl), { cooldownDuration: 5e3 });
+  const map = toPrincipal ?? ((p) => ({
+    subject: p.sub,
+    displayName: p.name ?? p.sub,
+    email: p.email,
+    clientId: p.cid,
+    allowedClients: p.clients ?? [],
+    roles: p.role ? [p.role] : [],
+    permissions: p.perms ?? []
+  }));
+  return {
+    mode: "team",
+    kind: "bearer",
+    issuer,
+    accepts: () => true,
+    async authenticate(token) {
+      let payload;
+      try {
+        ({ payload } = await jwtVerify(token, jwks, { issuer, audience }));
+      } catch (e) {
+        throw jwtFailure(e, "team IdP");
+      }
+      const mapped = map(payload);
+      const principal = { authMode: "team", kind: "user", issuer, key: principalKey("team", issuer, mapped.subject), devIdentity: isDevIdentity(payload), ...mapped };
+      if (!principal.clientId || !principal.allowedClients.includes(principal.clientId)) {
+        throw new AuthError(403, "no_active_client", "Team token has no active client in scope.");
+      }
+      return principal;
+    }
+  };
+}
+var hashApiKey = (key) => createHash("sha256").update(key).digest("hex");
+function apiKeyAuth({ keys }) {
+  const byHash = new Map(keys.map((k) => [k.hash, k]));
+  const windows = /* @__PURE__ */ new Map();
+  return {
+    mode: "api-key",
+    kind: "api-key",
+    async authenticate(presented, req) {
+      if (req.get("origin")) {
+        throw new AuthError(403, "api_key_from_browser", "API keys are server-to-server only; browser requests (with an Origin header) are refused.");
+      }
+      const digest = hashApiKey(presented);
+      let match = null;
+      for (const [hash, entry] of byHash) {
+        if (timingSafeEqual(Buffer.from(hash, "hex"), Buffer.from(digest, "hex"))) match = entry;
+      }
+      if (!match) throw new AuthError(401, "invalid_api_key", "Unknown or revoked API key.");
+      const limit = match.ratePerMinute ?? 60;
+      const now = Date.now();
+      const w = windows.get(match.id);
+      if (!w || now - w.start > 6e4) windows.set(match.id, { start: now, count: 1 });
+      else if (++w.count > limit) throw new AuthError(429, "rate_limited", `API key "${match.id}" exceeded ${limit}/min.`);
+      const asked = req.get("x-client-id") ?? req.query.clientId;
+      const clientId = asked ?? (match.clients.length === 1 ? match.clients[0] : null);
+      if (!clientId) throw new AuthError(400, "client_required", `Key covers [${match.clients.join(", ")}] \u2014 send X-Client-Id.`);
+      if (!match.clients.includes(clientId)) {
+        throw new AuthError(403, "client_not_granted", `API key "${match.id}" is not granted client "${clientId}".`);
+      }
+      return {
+        authMode: "api-key",
+        kind: "service",
+        issuer: "api-key",
+        subject: match.id,
+        key: principalKey("api-key", "api-key", match.id),
+        displayName: match.name,
+        clientId,
+        allowedClients: match.clients,
+        roles: [],
+        permissions: match.permissions,
+        clientFromRequest: true
+      };
+    }
+  };
+}
+function createModuleAuth({ strategies, apiUrl }) {
+  const bearer = strategies.filter((s) => s.kind === "bearer");
+  const apiKey = strategies.find((s) => s.kind === "api-key");
+  const modes = strategies.map((s) => s.mode);
+  const acceptsDevIdentities = Boolean(apiUrl) && isLocalUrl(apiUrl);
+  async function identify(req) {
+    {
+      const key = req.get("x-api-key");
+      const bearerToken = /^Bearer (.+)$/i.exec(req.get("authorization") ?? "")?.[1];
+      if (key && bearerToken) throw new AuthError(400, "ambiguous_credentials", "Send a bearer token OR an API key, not both.");
+      if (key) {
+        if (!apiKey) throw new AuthError(401, "mode_disabled", "API-key access is not enabled on this API.");
+        return apiKey.authenticate(key, req);
+      }
+      if (!bearerToken) {
+        throw new AuthError(401, "missing_credentials", `Send Authorization: Bearer <token> or X-Api-Key. Enabled modes: ${modes.join(", ")}. Cookies are never accepted.`);
+      }
+      let claims;
+      try {
+        claims = decodeJwt(bearerToken);
+      } catch {
+        throw new AuthError(401, "invalid_token", "Bearer token is not a JWT.");
+      }
+      const fromIssuer = bearer.filter((s) => s.issuer === claims.iss);
+      if (fromIssuer.length === 0) {
+        throw new AuthError(401, "untrusted_issuer", `Tokens from "${claims.iss}" are not accepted here. Trusted: ${[...new Set(bearer.map((s) => s.issuer))].join(", ") || "(none)"}.`);
+      }
+      const strategy = fromIssuer.find((s) => s.accepts(claims));
+      if (!strategy) {
+        throw new AuthError(401, "mode_disabled", `"${claims.token_use ?? "user"}" tokens from ${claims.iss} are not enabled on this API.`);
+      }
+      const principal = await strategy.authenticate(bearerToken, req);
+      if (principal.devIdentity && !acceptsDevIdentities) {
+        throw new AuthError(401, "dev_identity_refused", "This token comes from a local-only sign-in (no password). Only APIs running on a developer's machine accept it.");
+      }
+      return principal;
+    }
+  }
+  async function authenticate(req, res, next) {
+    try {
+      req.principal = await identify(req);
+      return next();
+    } catch (e) {
+      if (!(e instanceof AuthError)) return next(e);
+      return res.status(e.status).json({ error: e.code, detail: e.message });
+    }
+  }
+  function verifyRequest(request) {
+    const url = new URL(request.url);
+    return identify({ get: (h) => request.headers.get(h) ?? void 0, query: Object.fromEntries(url.searchParams) });
+  }
+  function allows(policy, principal, askedClientId) {
+    const required = policy[principal.authMode];
+    if (!required) return false;
+    if (!principal.clientFromRequest && askedClientId && askedClientId !== principal.clientId) return false;
+    return required.every((perm) => principal.permissions.includes("*") || principal.permissions.includes(perm));
+  }
+  function authorize(policy) {
+    for (const k of Object.keys(policy)) if (!ENTRY_POINTS.includes(k)) throw new Error(`authorize(): unknown entry point "${k}"`);
+    return (req, res, next) => {
+      const p = req.principal;
+      const required = policy[p.authMode];
+      if (!required) {
+        return res.status(403).json({
+          error: "entry_point_not_allowed",
+          detail: `This endpoint doesn't accept ${p.authMode} callers (allowed: ${Object.keys(policy).join(", ")}).`
+        });
+      }
+      const asked = req.query.clientId ?? req.get("x-client-id");
+      if (!p.clientFromRequest && asked && asked !== p.clientId) {
+        return res.status(403).json({
+          error: "client_mismatch",
+          detail: `Request asked for client "${asked}" but the credential is scoped to "${p.clientId}".`
+        });
+      }
+      const missing = required.filter((perm) => !p.permissions.includes("*") && !p.permissions.includes(perm));
+      if (missing.length) {
+        const via = p.authMode === "blu" ? ` (Blu role "${p.roles.join(", ")}")` : "";
+        return res.status(403).json({
+          error: "forbidden",
+          detail: `${p.authMode} principal "${p.subject}"${via} lacks "${missing.join(", ")}" on client "${p.clientId}".`
+        });
+      }
+      return next();
+    };
+  }
+  const requirePermission = (permission) => authorize(Object.fromEntries(modes.map((m) => [m, [permission]])));
+  return { authenticate, verifyRequest, allows, authorize, requirePermission, modes };
+}
+function createPrincipalDirectory() {
+  const people = /* @__PURE__ */ new Map();
+  function remember(req, _res, next) {
+    const p = req.principal;
+    if (p?.kind === "user") {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      let entry = people.get(p.key);
+      p.isNew = !entry;
+      if (!entry) {
+        entry = { key: p.key, authMode: p.authMode, issuer: p.issuer, subject: p.subject, firstSeen: now };
+        people.set(p.key, entry);
+      }
+      Object.assign(entry, { displayName: p.displayName, email: p.email, lastSeen: now });
+      p.firstSeen = entry.firstSeen;
+    }
+    next();
+  }
+  return { remember, get: (key) => people.get(key) ?? null, list: () => [...people.values()] };
+}
+function enabledModes(value, all = ENTRY_POINTS) {
+  const set = new Set((value ?? all.join(",")).split(",").map((s) => s.trim()).filter(Boolean));
+  for (const m of set) if (!all.includes(m)) throw new Error(`Unknown auth mode "${m}"`);
+  return set;
+}
+function corsAllowlist({ origins, credentials = false }) {
+  const resolve = typeof origins === "function" ? origins : () => origins;
+  return async (req, res, next) => {
+    const origin = req.get("origin");
+    res.append("Vary", "Origin");
+    const allowed = origin ? new Set(await resolve()).has(origin) : false;
+    if (allowed) {
+      res.set("Access-Control-Allow-Origin", origin);
+      if (credentials) res.set("Access-Control-Allow-Credentials", "true");
+      if (req.method === "OPTIONS") {
+        res.set("Access-Control-Allow-Methods", "GET,POST,PUT,PATCH,DELETE,OPTIONS");
+        res.set("Access-Control-Allow-Headers", "Authorization, Content-Type, X-Client-Id");
+        res.set("Access-Control-Max-Age", "600");
+        return res.status(204).end();
+      }
+    } else if (req.method === "OPTIONS") {
+      return res.status(403).end();
+    }
+    return next();
+  };
+}
+function originLogger(name) {
+  return (req, _res, next) => {
+    const origin = req.get("origin") ?? "(no origin / server-to-server)";
+    const auth = req.get("x-api-key") ? "api-key" : req.get("authorization") ? "bearer" : "no-auth";
+    if (req.method === "OPTIONS") return next();
+    console.log(`[${name}] ${req.method} ${req.originalUrl}  origin=${origin}  ${auth}`);
+    next();
+  };
+}
+export {
+  AuthError,
+  REGISTRY_URL,
+  apiKeyAuth,
+  bluIssuer,
+  bluPlatformAuth,
+  bluServiceAuth,
+  bluShellOrigins,
+  corsAllowlist,
+  createMcpEndpoint,
+  createMcpWebHandler,
+  createModuleAuth,
+  createPrincipalDirectory,
+  enabledModes,
+  hashApiKey,
+  link,
+  originLogger,
+  policyAllows,
+  teamIdpAuth
+};

package/types/dev.d.ts

@@ -0,0 +1,48 @@
+import { ComponentType } from 'react';
+
+/**
+ * Sign-in providers for a module's standalone app. Both end in the same thing:
+ * a bearer token the module's own API accepts.
+ *
+ *   team — the team's own IdP (personas, signed in right here)
+ *   blu  — "Sign in with Blu": a redirect to Blu's own sign-in page (OAuth code
+ *          + PKCE). The app gets a token for THIS module only and a refresh
+ *          token bound to it — never a Blu session.
+ *
+ * Two runtime files configure the standalone app (no rebuild to change either):
+ *   standalone.config.json — team-authored: title, which sign-in options to offer
+ *   deployment.json        — written per deployment: stage + this stage's URLs
+ */
+
+interface StandaloneConfig {
+    moduleId: string;
+    title: string;
+    auth: {
+        /** The team's own IdP. Omit to disable. */
+        team?: {
+            label: string;
+        };
+        /** "Sign in with Blu" (Blu's sign-in page: Entra, or mock accounts locally). Omit to disable. */
+        blu?: {
+            label: string;
+        };
+    };
+}
+interface Deployment {
+    stage: string;
+    apiBaseUrl: string;
+    teamAuthUrl: string;
+    bluHostApi: string;
+}
+
+/**
+ * Mount the standalone app. Both config files are fetched at runtime, so the
+ * same build runs in every stage and auth options change without a rebuild.
+ */
+declare function mountStandalone({ Page, rootId }: {
+    Page: ComponentType;
+    rootId?: string;
+}): Promise<void>;
+
+export { mountStandalone };
+export type { Deployment, StandaloneConfig };