@horizonmedia/blu-sdk 0.0.0-stage → 1.8.3

package/README.md

@@ -1,3 +1,553 @@
-# Temporary Holding Version
+# @blu/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Everything a team needs to build a module for Blu: its front end, its API, and running it on its own. It's published on npm as **`@horizonmedia/blu-sdk`**; your code imports it as **`@blu/sdk`**.
+
+| Import | For |
+|---|---|
+| `@blu/sdk` | your module's **front end**: who the user is, their client, the theme, routing, calling your API |
+| `@blu/sdk/frame` | front ends mounted **isolated**, in their own iframe (`mountIsolated`) |
+| `@blu/sdk/server` | your module's **API**: verifying Blu callers, route policies, CORS, tools for the Blu Concierge |
+| `@blu/sdk/dev` | running your module **on its own**, outside the Blu shell (`mountStandalone`) |
+
+A Next.js app adds **[`@blu/next-adapter`](../next-adapter/README.md)** on top of this.
+
+**Contents:** [Install](#install) · [Front end](#front-end-blusdk) · [Isolated modules](#isolated-modules-blusdkframe) · [Running on its own](#running-on-its-own-blusdkdev) · [Your API](#your-api-blusdkserver) · [Checking your integration](#checking-your-integration-blu-check) · [Versions](#versions)
+
+---
+
+## Install
+
+The package is public on npm (registry.npmjs.org), so installing needs no `.npmrc`, login or token: not on your machine, in CI or in Docker builds.
+
+**Moving from GitHub Packages** (versions up to 1.8.2 were published there): remove the `@horizonmedia:registry=https://npm.pkg.github.com` line from your `.npmrc`, and any token you set up for it, then reinstall so your lockfile points at registry.npmjs.org. `blu check` warns while the line is still there.
+
+**Add it under the name your code imports:**
+
+```sh
+npm install @blu/sdk@npm:@horizonmedia/blu-sdk@^1.8.3
+```
+
+which writes:
+
+```json
+"dependencies": {
+  "@blu/sdk": "npm:@horizonmedia/blu-sdk@^1.8.3"
+}
+```
+
+The API part needs nothing else. The front-end parts need `react` and `react-dom` 18.2+ or 19, which your app already has.
+
+**React 18:** fine for building and for running your app on its own. Inside Blu, though, an inline (federated) module runs on the **shell's React 19**: the page shares one copy of React. React 18 code generally works there, but avoid what React 19 removed:
+- `ReactDOM.render` / `hydrate`;
+- string refs;
+- legacy context (`contextTypes`);
+- `defaultProps` on function components;
+- `findDOMNode`.
+
+`blu check` warns when a module declares React 18. Test the module in the shell before you release it. Isolated (iframe) modules use their own React.
+
+---
+
+## Front end: `@blu/sdk`
+
+Inside Blu, your module's page is rendered by the Blu shell. These hooks read what the shell provides: the same values whether your module is mounted inline, in an iframe, or running on its own.
+
+```tsx
+import { useEffect, useState } from "react";
+import { useApiClient, useClient, useTheme, useUser } from "@blu/sdk";
+
+export default function Page() {
+  const user = useUser();          // { id, email, displayName, provider }
+  const client = useClient();      // { id, name }: the client chosen in Blu's header
+  const theme = useTheme();        // Blu's colours, radius and font
+  const api = useApiClient();      // your OWN API, with a token for it
+
+  const [rows, setRows] = useState([]);
+  useEffect(() => { api.get("/api/campaigns").then(setRows); }, [api, client.id]);
+  return <h1 style={{ color: theme.primary }}>Hello {user.displayName} · {client.name}</h1>;
+}
+```
+
+| Hook | Gives you |
+|---|---|
+| `useUser()` | the signed-in person |
+| `useClient()` | the active client. Your page re-renders when it changes; refetch then. |
+| `useRoles()` | the user's Blu roles on that client (`viewer`, `analyst`, `owner`) |
+| `useTheme()` | Blu's theme tokens, so your module matches the shell |
+| `useEnvironment()` | `{ stage, apiBaseUrl, moduleId }`: which environment, and **your** API's URL in it |
+| `useShell()` | who's hosting you: `kind`, `label`, `mount` (`inline`, `isolated` or `standalone`), and who chose the client |
+| `useApiClient()` | `get(path)` / `post(path, body)` to your own API with a token for it; non-2xx responses throw `ApiError` (`status`, `body`) |
+| `useAuthToken()` | the token getter itself, for a client library of your own |
+| `useRoute()` | where the user is in your module: `path`, `search`, and `navigate(path, { replace? })` |
+| `useEventBus()` | `emit(type, payload)` and `on(type, handler)` on the shell's event bus |
+| `useHost()` | all of the above in one object |
+| `useOptionalHost()` | the same, or `null` when your code runs outside Blu (handy in code shared with a standalone app) |
+
+**Tokens.** `useApiClient()` sends a short-lived token issued for **your module's API only**, renewed automatically. It refuses to send it to any other address.
+
+**Routing.** Blu keeps the URL. `useRoute().path` is your module-relative path (`/campaigns/acme-2`), shown in the address bar under your module's place in Blu (`/pacing/campaigns/acme-2`). Navigate with `navigate()`, and the back button and deep links just work. List the paths other people may link to (the Concierge's answers, for example) under `routes` in your `blu.module.json`.
+
+**Sign in with Blu**, for your own standalone app: `beginBluSignIn({ hostApi, clientId, redirectUri })` sends the user to Blu's sign-in page, and `completeBluSignIn()` finishes it when they come back. The token you get is for your module only. (`@blu/sdk/dev` does this for you.)
+
+---
+
+## Isolated modules: `@blu/sdk/frame`
+
+A module that runs on its own site, in a sandboxed iframe inside the Blu shell (typically a partner's), uses the same hooks. Only the entry point changes:
+
+```tsx
+// frame.tsx: the page the Blu shell loads in the iframe
+import { mountIsolated } from "@blu/sdk/frame";
+import Page from "./Page";
+
+mountIsolated({ Page });
+```
+
+- **The bridge.** `mountIsolated` connects to the Blu shell over `postMessage`: context, tokens for your API, resizing and routing. It accepts messages only from the shell origins listed in your site's `./deployment.json` (`hostOrigins`).
+- **Your own router?** Use `connectToBluShell(hostOrigins)` directly: it gives you the same context the hooks provide, and the connection's `reportRoute()` keeps Blu's address bar in step with your router.
+- **What the frame can't see.** It never sees Blu's page, session or other modules, and receives tokens for your API only.
+
+---
+
+## Running on its own: `@blu/sdk/dev`
+
+Run your module's unchanged page outside Blu, on its own origin, for development or as a standalone app:
+
+```tsx
+// standalone.tsx: your standalone index.html's entry
+import { mountStandalone } from "@blu/sdk/dev";
+import Page from "./Page";
+
+mountStandalone({ Page });
+```
+
+It reads two files next to the page at runtime, so one build serves every environment:
+
+- **`standalone.config.json`:** `{ "moduleId": "pacing", "title": "Pacing", "auth": { "team": { "label": "Sign in" }, "blu": { "label": "Sign in with Blu" } } }`. Each sign-in option is optional.
+- **`deployment.json`:** `{ "stage": "dev", "apiBaseUrl": "…", "teamAuthUrl": "…", "bluHostApi": "…" }`
+
+It provides the same context the Blu shell does, so `useUser()`, `useApiClient()` and the rest behave the same.
+
+---
+
+## Your API: `@blu/sdk/server`
+
+Server-side helpers for your module's API, called by Blu users, other services and the Blu Concierge. On every request they answer two questions:
+
+1. **Who is calling?** A verified, normalized caller (the *principal*), whichever way they authenticated.
+2. **May they do this?** A per-route policy that **your team** writes.
+
+It can only **verify** Blu tokens; it can never create them. Blu's signing keys never leave Blu.
+
+Works with Express, and with Web-standard handlers (Next.js route handlers, Hono, workers).
+
+### Quick start (Express)
+
+```js
+import express from "express";
+import { bluPlatformAuth, corsAllowlist, createModuleAuth } from "@blu/sdk/server";
+
+const BLU_ISSUER = process.env.BLU_ISSUER;           // this environment's Blu, e.g. https://api.blu.example.com
+const MODULE_ID = "pacing";                          // your module's id in Blu
+
+const { authenticate, authorize } = createModuleAuth({
+  apiUrl: process.env.PUBLIC_URL,                    // this API's own URL, as configured
+  strategies: [
+    bluPlatformAuth({
+      issuer: BLU_ISSUER,
+      jwksUrl: `${BLU_ISSUER}/.well-known/jwks.json`,
+      moduleId: MODULE_ID,
+      // YOUR mapping: a user's Blu role → this API's permissions.
+      roleMap: {
+        viewer: ["pacing:read"],
+        analyst: ["pacing:read", "pacing:write"],
+        owner: ["pacing:read", "pacing:write"],
+      },
+    }),
+  ],
+});
+
+const app = express();
+app.use(corsAllowlist({ origins: [process.env.BLU_SHELL_ORIGIN] }));
+app.use(express.json());
+
+app.get("/api/campaigns", authenticate, authorize({ blu: ["pacing:read"] }), async (req, res) => {
+  const { clientId, displayName } = req.principal;   // the client comes from the token, never the request
+  res.json(await campaignsFor(clientId));
+});
+
+app.listen(8080);
+```
+
+That's a complete Blu-ready API:
+- Requests without a valid Blu token for `pacing` get a `401`.
+- Users whose role lacks `pacing:read` get a `403`.
+- Every handler sees the user and their client.
+
+### Who can call your API
+
+Each way of calling is a **strategy**. Enable the ones your API needs; one API can serve all of them at once.
+
+| Entry point | Who | Strategy | Credential |
+|---|---|---|---|
+| `blu` | A user signed in to Blu, in the Blu shell, through the Concierge, or in your standalone app via "Sign in with Blu" | `bluPlatformAuth` | `Authorization: Bearer <Blu token>` |
+| `service` | Another backend that Blu has granted access to your module | `bluServiceAuth` | `Authorization: Bearer <Blu service token>` plus `X-Client-Id` |
+| `team` | A user of your own app, signed in with your own identity provider (Cognito, Auth0, Entra, homegrown…) | `teamIdpAuth` | `Authorization: Bearer <your token>` |
+| `api-key` | An outside system you issue keys to (never a browser) | `apiKeyAuth` | `X-Api-Key: <key>` plus `X-Client-Id` |
+
+#### `bluPlatformAuth({ issuer, jwksUrl, moduleId, roleMap })`
+
+Accepts Blu user tokens issued **for your module only** (audience `blu-module:<moduleId>`). Blu issues them only while your module is enabled for that client.
+
+| Option | Meaning |
+|---|---|
+| `issuer` | This environment's Blu token issuer. |
+| `jwksUrl` | Blu's public keys, normally `<issuer>/.well-known/jwks.json`. Keys are cached and refetched when Blu rotates them; no redeploy needed. |
+| `moduleId` | Your module's id in Blu. |
+| `roleMap` | **Yours.** Each Blu role (`viewer`, `analyst`, `owner`) → your API's permissions. Blu says who the user is and their role; you decide what that role may do. A role you don't list gets no permissions. |
+
+#### `bluServiceAuth({ issuer, jwksUrl, moduleId })`
+
+Accepts service tokens that another backend got from Blu, with the scopes a Blu admin granted it on your module. The caller names the client with `X-Client-Id`. It must be one of the clients your module is enabled for; a single-client grant needs no header.
+
+#### `teamIdpAuth({ issuer, jwksUrl, audience, toPrincipal? })`
+
+Accepts tokens from **your own** identity provider, so your standalone app's users keep signing in the way they do today. By default it reads these claims:
+
+| Claim | Meaning |
+|---|---|
+| `sub` | the user |
+| `name`, `email` | display details |
+| `cid` | the active client |
+| `clients` | the clients they may use |
+| `role` | their role |
+| `perms` | their permissions |
+
+If your tokens look different, pass `toPrincipal(payload)` to map them.
+
+#### `apiKeyAuth({ keys })`
+
+Server-to-server keys **you** issue. Store only a hash: `hashApiKey(key)` gives the SHA-256 the strategy compares against.
+
+```js
+apiKeyAuth({
+  keys: [{ id: "acme-bi", name: "Acme BI export", hash: process.env.ACME_BI_KEY_HASH,
+           clients: ["acme"], permissions: ["pacing:read"], ratePerMinute: 60 }],
+});
+```
+
+- **Browsers are refused:** a request with an `Origin` header gets a `403`, because a key in a web page is a key anyone can copy.
+- **Rate-limited per key:** 60 requests a minute by default.
+- **Client scope:** a key covering several clients must name one with `X-Client-Id`.
+
+#### Choosing entry points per deployment
+
+`enabledModes("blu,team")` parses a comma-separated setting (such as an `AUTH_MODES` environment variable) into a set, and rejects unknown names. Use it to turn entry points on or off per environment without code changes.
+
+```js
+const modes = enabledModes(process.env.AUTH_MODES);   // default: all four
+const strategies = [];
+if (modes.has("blu")) strategies.push(bluPlatformAuth({ ... }));
+if (modes.has("team")) strategies.push(teamIdpAuth({ ... }));
+```
+
+### The principal
+
+After `authenticate`, `req.principal` describes the caller the same way whatever the entry point:
+
+| Field | Meaning |
+|---|---|
+| `authMode` | `"blu"`, `"service"`, `"team"` or `"api-key"` |
+| `kind` | `"user"` or `"service"` |
+| `subject` | the user id (or service / key id) |
+| `key` | a stable identity across requests: `<authMode>\|<issuer>\|<subject>`. Key your own records on it (see [Remembering Blu users](#remembering-blu-users)). |
+| `displayName`, `email` | for display |
+| `clientId` | **the active client**, from the verified credential |
+| `allowedClients` | every client the credential covers |
+| `roles` | Blu or team roles |
+| `permissions` | resolved permissions (may include `"*"`) |
+| `provider` | Blu users: how Blu signed them in (e.g. `"entra"`) |
+| `via` | Blu users: the app that obtained the token (the Blu shell, the Concierge, or your own standalone app) |
+| `actor` | Blu users: software acting for the user, e.g. `"blu-concierge"` |
+
+**Always scope data by `req.principal.clientId`.** For user tokens it comes from the credential only, never from a query parameter or body.
+
+### Route policies
+
+`authorize(policy)` names which entry points may call a route, and the permissions each needs (all listed are required):
+
+```js
+app.get("/api/campaigns", authenticate,
+  authorize({ blu: ["pacing:read"], team: ["pacing:read"], service: ["pacing:read"] }), handler);
+
+app.post("/api/campaigns/:id/flag", authenticate,
+  authorize({ blu: ["pacing:write"], team: ["pacing:write"] }), handler);   // no services, no API keys
+
+app.post("/api/admin/recompute", authenticate,
+  authorize({ team: ["pacing:admin"] }), handler);                          // your own users only
+```
+
+- **Unlisted entry points are refused** (`403 entry_point_not_allowed`), even if the caller authenticated. That's how you keep an admin route away from Blu.
+- **Clients can't be swapped.** A user token scoped to client A asking for client B (`?clientId=` or `X-Client-Id`) gets `403 client_mismatch`; it's never an override.
+- **Missing permissions** get `403 forbidden`, naming what's missing.
+- **`authorize({ blu: [], team: [] })`** allows those entry points with no particular permission.
+- **`requirePermission("pacing:read")`** is shorthand for the same permission from every enabled entry point.
+- **`allows(policy, principal, askedClientId?)`** is the same check as a boolean, for code outside Express.
+
+### Next.js and other Web-standard handlers
+
+`createModuleAuth` also returns `verifyRequest(request)`. It takes a standard `Request` and returns the principal, or throws an `AuthError` (with `status` and `code`).
+
+```ts
+// app/api/campaigns/route.ts
+import { AuthError, createModuleAuth } from "@blu/sdk/server";
+
+const { verifyRequest, allows } = createModuleAuth({ apiUrl: process.env.PUBLIC_URL, strategies: [ /* … */ ] });
+
+export async function GET(request: Request) {
+  let caller;
+  try {
+    caller = await verifyRequest(request);
+  } catch (e) {
+    if (!(e instanceof AuthError)) throw e;
+    return Response.json({ error: e.code, detail: e.message }, { status: e.status });
+  }
+  if (!allows({ blu: ["pacing:read"], team: ["pacing:read"] }, caller)) {
+    return Response.json({ error: "forbidden" }, { status: 403 });
+  }
+  return Response.json(await campaignsFor(caller.clientId));
+}
+```
+
+For a whole Next.js app (pages, server actions, `auth()`), use `@blu/next-adapter`, which is built on this.
+
+### Remembering Blu users
+
+A Blu user needs **no account in your system first**. `principal.key` is stable for that person, so you can attach your own data to it the first time you see them: who flagged a campaign, audit trails, preferences.
+
+`createPrincipalDirectory()` shows the pattern: an Express middleware that records users on first sight.
+
+```js
+const people = createPrincipalDirectory();
+app.post("/api/campaigns/:id/flag", [authenticate, people.remember], authorize({ blu: ["pacing:write"] }), (req, res) => {
+  // req.principal.isNew is true on their first request; req.principal.firstSeen is when that was.
+});
+people.get(key);   // one person
+people.list();     // everyone seen
+```
+
+It keeps people in memory. In production, store the same records in your own database, keyed on `principal.key`.
+
+A Blu user and a user from your own identity provider are **different principals**, even if they're the same person. If you need to link them, do it in your own data, deliberately.
+
+### CORS
+
+`corsAllowlist({ origins, credentials? })` is an explicit-allowlist CORS middleware:
+
+- It echoes back only allowlisted origins and sets `Vary: Origin`.
+- It answers preflights for the `Authorization`, `Content-Type` and `X-Client-Id` headers.
+- Unlisted origins get no CORS headers, so the browser refuses to give the response to that page.
+
+```js
+app.use(corsAllowlist({ origins: ["https://app.blu.example.com"] }));
+// or from live config:
+app.use(corsAllowlist({ origins: async () => loadAllowedOrigins() }));
+```
+
+List your environment's Blu shell origins, plus your own standalone app if it calls this API from another origin. `bluShellOrigins(stage)` gives the shell's origin for `"dev"`, `"staging"` or `"prod"` (`https://dev.blu-ce.horizonmedia.com`; prod: `https://blu-ce.horizonmedia.com`). It's a list, so if the shell ever answers at a second name, your API picks it up with an SDK update and no code change:
+
+```js
+import { bluShellOrigins } from "@blu/sdk/server";
+app.use(corsAllowlist({ origins: [...bluShellOrigins(process.env.BLU_STAGE), "https://pacing.example.com"] }));
+```
+
+`originLogger(name)` is a small request logger that prints each request's origin and credential type, which helps while setting this up.
+
+### Tools for the Blu Concierge (MCP)
+
+The Blu Concierge answers users' questions by calling tools that modules expose over [MCP](https://modelcontextprotocol.io). Each tool is a small function that **your API runs, with your checks**:
+
+- **Per-caller lists:** a caller only *sees* the tools their policy allows; tool lists differ per caller.
+- **Client-scoped:** every call is for the caller's client, from the verified token.
+- **Acting for the user:** the Concierge calls with a token for **your module**, on the user's behalf (`principal.actor` is `"blu-concierge"`), so it can never reach more than the user could.
+
+```js
+import { z } from "zod";
+import { createMcpEndpoint, link } from "@blu/sdk/server";
+import manifest from "../blu.module.json" with { type: "json" };
+
+const tools = [
+  {
+    name: "list_campaign_pacing",
+    title: "Campaigns with pacing",
+    description: "Pacing team: the current client's campaigns with spend vs budget and pacing status. Use for 'which campaigns are over/under pacing'.",
+    input: { status: z.enum(["over", "under", "on_track"]).optional() },
+    policy: { blu: ["pacing:read"] },
+    annotations: { readOnlyHint: true },
+    run: async (principal, { status }) => {
+      const rows = await campaignsFor(principal.clientId, { status });
+      return {
+        summary: rows.map((c) => `${c.name}: ${c.pacing}% paced`).join("\n"),   // what the model reads
+        data: rows,                                                                // structured detail
+        links: rows.map((c) => link("campaign", { campaignId: c.id }, c.name)),   // deep links into your module
+      };
+    },
+  },
+];
+
+app.post("/mcp", ...createMcpEndpoint({ name: "pacing", version: "1.0.0", authenticate, tools, manifest }));
+```
+
+For Web-standard handlers (for example a Next.js route), use `createMcpWebHandler`, which is the same thing:
+
+```ts
+export const POST = createMcpWebHandler({ name: "pacing", version: "1.0.0", verify: verifyRequest, tools, manifest });
+```
+
+**Writing a tool:**
+
+| Field | Purpose |
+|---|---|
+| `description` | Written **for the model**: when to use the tool and what it returns. |
+| `input` | Arguments, as a [zod](https://zod.dev) shape: Zod 4.6.6 or later (3.25+ still works, but earlier versions can exhaust memory validating oversized input, GHSA-mrhx-c7xc-m3w5; `blu check` warns). |
+| `policy` | The same format as `authorize()`. |
+| `annotations.readOnlyHint` | Marks a tool that doesn't change anything. The Blu Concierge only ever uses these: for a caller acting for a user (`principal.actor`, e.g. the Concierge) the endpoint doesn't list or run any other tool. |
+| `run(principal, args)` | Returns `summary` (text for the model), `data` (structured), and optional `links`. |
+
+If `run` throws, the error message goes back to the Concierge as a tool error; nothing crashes.
+
+**Links name routes, never URLs.** `link(routeName, params, label)` refers to a route in your `blu.module.json` `routes`. Blu builds the URL, so links can only point at routes you declared. Links to undeclared routes, or with missing parameters, are dropped.
+
+**Your manifest is enforced.** Pass `manifest` (your `blu.module.json`), and the tools in code must match its `mcp.tools` exactly: names, read-only flags and required permissions. If they don't, the endpoint refuses to start, so the tools a Blu admin reviewed are the tools that run.
+
+```json
+"mcp": {
+  "tools": [
+    { "name": "list_campaign_pacing", "title": "Campaigns with pacing", "readOnly": true, "requires": { "blu": ["pacing:read"] } }
+  ]
+}
+```
+
+### Errors
+
+Refusals are JSON: `{ "error": "<code>", "detail": "<readable explanation>" }`. With `verifyRequest`, the same codes arrive as an `AuthError` with `status` and `code`.
+
+| Status | `error` | When |
+|---|---|---|
+| 400 | `ambiguous_credentials` | both a bearer token and an API key were sent |
+| 400 | `client_required` | a service or multi-client API key didn't send `X-Client-Id` |
+| 401 | `missing_credentials` | no `Authorization: Bearer` or `X-Api-Key`. **Cookies are never accepted.** |
+| 401 | `invalid_token` | not a JWT, a bad signature, or expired |
+| 401 | `untrusted_issuer` | the token's issuer isn't one you configured |
+| 401 | `mode_disabled` | that kind of credential isn't enabled on this API |
+| 401 | `invalid_api_key` | unknown or revoked key |
+| 401 | `dev_identity_refused` | a local-only test sign-in, sent to a non-local API |
+| 403 | `no_active_client` | the token has no active client in its scope |
+| 403 | `client_not_granted` | the service or key isn't granted that client |
+| 403 | `api_key_from_browser` | an API key sent from a web page |
+| 403 | `entry_point_not_allowed` | this route doesn't accept this kind of caller |
+| 403 | `client_mismatch` | the request asked for a client other than the token's |
+| 403 | `forbidden` | permissions missing (named in `detail`) |
+| 429 | `rate_limited` | an API key exceeded its rate |
+
+### Configuration per environment
+
+Each environment (dev, staging, prod) has its own Blu. Configure your API per environment:
+
+| Setting | Example |
+|---|---|
+| Blu issuer | `bluIssuer(stage)`: `https://api.dev.blu-ce.horizonmedia.com` (prod: `https://api.blu-ce.horizonmedia.com`) |
+| Blu public keys | `<issuer>/.well-known/jwks.json` |
+| Your module id | the `id` in your `blu.module.json` |
+| Blu shell origins for CORS | `bluShellOrigins(stage)`: `https://dev.blu-ce.horizonmedia.com` (prod: `https://blu-ce.horizonmedia.com`) |
+| This API's public URL (`apiUrl`) | `https://pacing-api.dev.example.com` |
+| Enabled entry points | `AUTH_MODES=blu,service,team` |
+
+A token from one environment's Blu is refused by another environment's API, because the issuer differs.
+
+### Security behaviour you get for free
+
+- **Fails closed.** Each of these is refused rather than allowed:
+  - an unknown issuer;
+  - a disabled entry point;
+  - a module that isn't enabled for the client;
+  - an unresolved client;
+  - an entry point the route doesn't list.
+- **Your module only.** Blu tokens are checked for your module's audience. A token Blu issued for another module, or for Blu's own use, is refused.
+- **Short-lived tokens.** Blu tokens expire in about a minute, so a user whose access is removed in Blu is refused within about a minute, with no session store on your side.
+- **No cookies.** Credentials come only from headers, so other websites can't make requests on a user's behalf (cross-site request forgery).
+- **Key rotation without redeploys.** Blu's public keys are cached and refetched automatically when Blu rotates them.
+- **Local test sign-ins stay local.** Blu's password-free sign-ins for developers' machines produce tokens marked as such. `createModuleAuth` accepts them only when `apiUrl` points at the local machine, so a deployed API always refuses them. Leave `apiUrl` out and they're always refused.
+- **API keys:** stored as hashes, compared in constant time, rate-limited, and never accepted from browsers.
+
+### Server reference
+
+| Export | Use |
+|---|---|
+| `createModuleAuth({ strategies, apiUrl? })` | Combines strategies. Returns `{ authenticate, authorize, requirePermission, verifyRequest, allows, modes }`. |
+| `bluPlatformAuth({ issuer, jwksUrl, moduleId, roleMap })` | Blu users. |
+| `bluServiceAuth({ issuer, jwksUrl, moduleId })` | Backends granted access by Blu. |
+| `teamIdpAuth({ issuer, jwksUrl, audience, toPrincipal? })` | Your own identity provider's users. |
+| `apiKeyAuth({ keys })` | Keys you issue to outside systems. |
+| `hashApiKey(key)` | The SHA-256 to store for a key. |
+| `enabledModes(value)` | Parse `"blu,team,…"` into a set of entry points. |
+| `createPrincipalDirectory()` | Remember the people who call you (`remember`, `get`, `list`). |
+| `corsAllowlist({ origins, credentials? })` | Explicit-allowlist CORS for Express. |
+| `originLogger(name)` | Log each request's origin and credential type. |
+| `createMcpEndpoint({ name, version, authenticate, tools, manifest? })` | MCP tools for the Concierge, on Express. |
+| `createMcpWebHandler({ name, version, verify, tools, manifest? })` | The same, for Web-standard handlers. |
+| `link(route, params, label)` | A deep link from a tool result into your module. |
+| `policyAllows(policy, principal)` | True when a policy admits the principal (as used for tool lists). |
+| `AuthError` | What `verifyRequest` throws: `status`, `code`, `message`. |
+
+---
+
+## Checking your integration: `blu check`
+
+The SDK comes with a `blu` command. Run it in your module's folder (where `blu.module.json` is):
+
+```sh
+npx blu check            # or: pnpm exec blu check
+npx blu check --json     # machine-readable
+```
+
+It checks your manifest with the same rules Blu Admin applies, then your code against it:
+- only public `@blu/sdk` entry points are imported (nothing internal or renamed);
+- `@blu/sdk` is installed under its alias, and no `.npmrc` still sends it to GitHub Packages;
+- inline modules share `@blu/sdk` as a singleton, with the manifest's federation name and exposed key;
+- isolated modules connect with `mountIsolated` / `connectToBluShell`;
+- your API's `moduleId` is the manifest's `id`;
+- every declared Concierge tool is defined, and the MCP endpoint is given the manifest;
+- tool links only name declared routes.
+
+- your bundle addresses name the release's folder (`{version}`), so every release keeps its own files and rollback works (a warning).
+
+It exits with 1 when something fails, so add it to CI. It's static: it reads your code but doesn't run it, so keep your own build and tests too.
+
+## Registering a release: `blu register`
+
+Once per release, after uploading its files to their versioned folder, your pipeline registers it with Blu:
+
+```sh
+BLU_CI_TOKEN=${{ secrets.BLU_CI_TOKEN }} npx blu register
+```
+
+It sends `blu.module.json` to the Blu registry, `https://registry.blu-ce.horizonmedia.com` (`REGISTRY_URL`; `BLU_REGISTRY_URL` or `--registry` overrides it). The token is your module's CI token, from the Blu team. Releases are immutable: the same release again is a no-op, and different content under an existing version is refused, so bump `version` for every release. Registering runs it nowhere; Blu admins approve it environment by environment.
+
+What happens next:
+- **Blu copies your release** (inline modules) into its own module store and serves it from there, so keep your folder up until the copy is made (minutes); after that, Blu keeps every version it might need (30 days after it last ran anywhere, and always the current and previous one). Build with relative asset paths (`base: "./"` in Vite) so the copied files work from Blu's address. Isolated (iframe) modules keep loading from your origin: keep those folders up for 30 days after a version last ran.
+- **Blu reviews it:** known-vulnerable shared packages, code rules (no code built at runtime, no reaching into the Blu page, no undeclared hosts), and an AI review. Read the report with your CI token: `GET https://registry.blu-ce.horizonmedia.com/v1/modules/<id>/versions/<version>/report`.
+- **Keep your API backward-compatible** for about 30 days: an environment can be rolled back to an earlier front end, which calls your current API.
+
+**Using Claude Code?** The Blu plugin (`plugins/blu` in the Blu repository) has an `/blu:integrate` skill that walks the whole integration and finishes with `blu check`, and `/blu:check`.
+
+---
+
+## Versions
+
+- **Inside Blu, your front end runs Blu's copy of `@blu/sdk`.** The shell shares one instance with every module, so they all read the same context. Your installed version only affects types, your build, and running on your own.
+- **Use a range:** `^1.5.0` means "1.5.0 or newer, within 1.x". If your module needs a newer feature than the shell provides, Blu's loader warns at runtime. Upgrade within a major version whenever you like; Blu keeps 1.x compatible.
+
+## Access
+
+The packages are public on npm, in the **horizonmedia** npm organization, so anyone can install them. Only this repository's workflow (`.github/workflows/publish-sdks.yml`) publishes them. It uses npm's trusted publishing: each package names that workflow as its trusted publisher (npmjs.com → package → **Settings** → **Trusted Publisher**: GitHub Actions, organization `HorizonMedia`, repository `blu-composable-experience`, workflow `publish-sdks.yml`), and publishing access is set to require 2FA and disallow tokens. Until that's set up, the workflow uses the `NPM_TOKEN` Actions secret.