@horizonmedia/blu-sdk 0.0.0-stage → 1.8.4

package/types/server.d.ts

@@ -0,0 +1,448 @@
+/** True when `policy` admits this principal's entry point with all required permissions. */
+declare function policyAllows(policy: any, principal: any): any;
+/**
+ * @param {{ name: string, version: string, authenticate: Function | Function[], tools: ModuleTool[], manifest?: object }} opts
+ *   manifest — the module's blu.module.json. When given, the tools in code must
+ *   match its `mcp.tools` exactly (name, read-only flag, requirements) or this
+ *   throws at start-up: the API won't run with an undeclared or mis-declared
+ *   tool, so what the Admin approved is what actually runs.
+ * @returns {import("express").Router-like handlers} mount with `app.post("/mcp", ...createMcpEndpoint(...))`
+ */
+declare function createMcpEndpoint({ name, version, authenticate, tools, manifest }: {
+    name: string;
+    version: string;
+    authenticate: Function | Function[];
+    tools: ModuleTool[];
+    manifest?: object;
+}): any;
+/**
+ * The same MCP endpoint for Web-standard handlers — e.g. a Next.js route
+ * handler: `export const POST = createMcpWebHandler({ … })`. Same tools shape,
+ * same per-caller tool filtering, same manifest drift check and link checks.
+ *
+ * @param {{ name: string, version: string, verify: (request: Request) => Promise<object>, tools: ModuleTool[], manifest?: object }} opts
+ *   verify — e.g. createModuleAuth(…).verifyRequest; throws an error with `status`/`code` to refuse
+ * @returns {(request: Request) => Promise<Response>}
+ */
+declare function createMcpWebHandler({ name, version, verify, tools, manifest }: {
+    name: string;
+    version: string;
+    verify: (request: Request) => Promise<object>;
+    tools: ModuleTool[];
+    manifest?: object;
+}): (request: Request) => Promise<Response>;
+declare function link(route: any, params: any, label: any): {
+    route: any;
+    params: any;
+    label: any;
+};
+/**
+ * A Zod schema, from Zod 3.25+ or Zod 4: whichever your API uses (the MCP SDK accepts both). Use Zod
+ * 4.6.6 or later: earlier versions can exhaust memory validating oversized input (GHSA-mrhx-c7xc-m3w5).
+ */
+type ZodSchema = {
+    parse(data: unknown): unknown;
+    safeParse(data: unknown): unknown;
+};
+type ModuleTool = {
+    name: string;
+    title: string;
+    /**
+     * Written for the model: when to use it, what it returns.
+     */
+    description: string;
+    /**
+     * zod raw shape for arguments (Zod 4.6.6+ recommended; 3.25+ works)
+     */
+    input?: Record<string, ZodSchema>;
+    policy: Partial<Record<"blu" | "service" | "team" | "api-key", string[]>>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+    };
+    /**
+     * principal: the normalized caller (req.principal)
+     */
+    run: (principal: any, args: any) => Promise<{
+        summary: string;
+        data: unknown;
+        links?: ReturnType<typeof link>[];
+    }>;
+};
+
+/**
+ * A user signed in with Blu — in a Blu shell, through the Concierge, or in this
+ * module's own standalone app ("Sign in with Blu"). Blu mints these tokens for
+ * ONE module (audience `blu-module:<moduleId>`), only while the module is
+ * enabled for the token's client, so a token issued for another module — or
+ * the shell's own session token — is refused here. The token carries the
+ * user's global Blu role on that client; `roleMap` turns it into permissions.
+ *
+ * @param {{ issuer: string, jwksUrl: string, moduleId: string,
+ *           roleMap: Record<string, string[]> }} opts
+ *   roleMap — TEAM-OWNED: Blu role ("viewer" | "analyst" | "owner") → this API's permissions.
+ */
+declare function bluPlatformAuth({ issuer, jwksUrl, moduleId, roleMap }: {
+    issuer: string;
+    jwksUrl: string;
+    moduleId: string;
+    roleMap: Record<string, string[]>;
+}): {
+    mode: string;
+    kind: string;
+    issuer: string;
+    accepts: (claims: any) => boolean;
+    authenticate(token: any): Promise<{
+        authMode: string;
+        kind: string;
+        issuer: string;
+        subject: any;
+        key: string;
+        devIdentity: any;
+        displayName: any;
+        email: any;
+        provider: any;
+        via: any;
+        actor: any;
+        clientId: any;
+        allowedClients: any;
+        roles: any;
+        permissions: any[];
+    }>;
+};
+/**
+ * Another backend calling with a Blu-issued client-credentials token. Its scopes
+ * are exactly what the Blu Admin granted it on THIS module (audience
+ * `blu-module:<moduleId>`). It names the client per call with X-Client-Id, from
+ * the clients this module is enabled for.
+ *
+ * @param {{ issuer: string, jwksUrl: string, moduleId: string }} opts
+ */
+declare function bluServiceAuth({ issuer, jwksUrl, moduleId }: {
+    issuer: string;
+    jwksUrl: string;
+    moduleId: string;
+}): {
+    mode: string;
+    kind: string;
+    issuer: string;
+    accepts: (claims: any) => boolean;
+    authenticate(token: any, req: any): Promise<{
+        authMode: string;
+        kind: string;
+        issuer: string;
+        subject: any;
+        key: string;
+        displayName: any;
+        clientId: any;
+        allowedClients: any;
+        roles: any[];
+        permissions: string[];
+        clientFromRequest: boolean;
+    }>;
+};
+/**
+ * The team owns this IdP (Cognito, Auth0, homegrown — anything that issues JWTs
+ * with a JWKS). `toPrincipal` maps the team's claim shape onto the common one.
+ *
+ * @param {{ issuer: string, jwksUrl: string, audience: string,
+ *           toPrincipal?: (payload: object) => Partial<Principal> }} opts
+ */
+declare function teamIdpAuth({ issuer, jwksUrl, audience, toPrincipal }: {
+    issuer: string;
+    jwksUrl: string;
+    audience: string;
+    toPrincipal?: (payload: object) => Partial<Principal>;
+}): {
+    mode: string;
+    kind: string;
+    issuer: string;
+    accepts: () => boolean;
+    authenticate(token: any): Promise<{
+        authMode: string;
+        kind: string;
+        issuer: string;
+        /**
+         * user id, or api-key id
+         */
+        subject?: string;
+        /**
+         * stable identity across requests: `<authMode>|<issuer>|<subject>`.
+         * Key your own records (audit, ownership, preferences) on this —
+         * a Blu user needs no account in your system first.
+         */
+        key: string;
+        displayName?: string;
+        email?: string;
+        /**
+         * Blu only: the app that obtained the token ("blu-host",
+         *              "blu-concierge", or your own standalone app)
+         */
+        via?: string;
+        /**
+         * Blu only: software acting for the user (e.g. "blu-concierge")
+         */
+        actor?: string;
+        /**
+         * active client (from the credential, never the request — except see api keys)
+         */
+        clientId?: string | null;
+        allowedClients?: string[];
+        roles?: string[];
+        /**
+         * resolved; may contain "*"
+         */
+        permissions?: string[];
+        devIdentity: any;
+    } | {
+        subject: any;
+        displayName: any;
+        email: any;
+        clientId: any;
+        allowedClients: any;
+        roles: any[];
+        permissions: any;
+        authMode: string;
+        kind: string;
+        issuer: string;
+        key: string;
+        devIdentity: any;
+    }>;
+};
+/**
+ * Keys are stored only as SHA-256 hashes, each scoped to clients + permissions
+ * and rate-limited. Browsers are refused outright: a key in a web page is a key
+ * anyone can copy.
+ *
+ * @param {{ keys: { id: string, name: string, hash: string, clients: string[],
+ *                   permissions: string[], ratePerMinute?: number }[] }} opts
+ */
+declare function apiKeyAuth({ keys }: {
+    keys: {
+        id: string;
+        name: string;
+        hash: string;
+        clients: string[];
+        permissions: string[];
+        ratePerMinute?: number;
+    }[];
+}): {
+    mode: string;
+    kind: string;
+    authenticate(presented: any, req: any): Promise<{
+        authMode: string;
+        kind: string;
+        issuer: string;
+        subject: string;
+        key: string;
+        displayName: string;
+        clientId: any;
+        allowedClients: string[];
+        roles: any[];
+        permissions: string[];
+        clientFromRequest: boolean;
+    }>;
+};
+/**
+ * @param {{ strategies: ReturnType<typeof bluPlatformAuth|typeof teamIdpAuth|typeof apiKeyAuth>[], apiUrl?: string }} opts
+ *   apiUrl — this API's own public URL, as configured. Tokens from local-only
+ *   (passwordless) sign-ins are accepted only when it's on this machine; leave
+ *   it out and they're always refused.
+ */
+declare function createModuleAuth({ strategies, apiUrl }: {
+    strategies: ReturnType<typeof bluPlatformAuth | typeof teamIdpAuth | typeof apiKeyAuth>[];
+    apiUrl?: string;
+}): {
+    authenticate: (req: any, res: any, next: any) => Promise<any>;
+    verifyRequest: (request: any) => Promise<{
+        authMode: string;
+        kind: string;
+        issuer: string;
+        subject: any;
+        key: string;
+        devIdentity: any;
+        displayName: any;
+        email: any;
+        provider: any;
+        via: any;
+        actor: any;
+        clientId: any;
+        allowedClients: any;
+        roles: any;
+        permissions: any[];
+    } | {
+        authMode: string;
+        kind: string;
+        issuer: string;
+        /**
+         * user id, or api-key id
+         */
+        subject?: string;
+        /**
+         * stable identity across requests: `<authMode>|<issuer>|<subject>`.
+         * Key your own records (audit, ownership, preferences) on this —
+         * a Blu user needs no account in your system first.
+         */
+        key: string;
+        displayName?: string;
+        email?: string;
+        /**
+         * Blu only: the app that obtained the token ("blu-host",
+         *              "blu-concierge", or your own standalone app)
+         */
+        via?: string;
+        /**
+         * Blu only: software acting for the user (e.g. "blu-concierge")
+         */
+        actor?: string;
+        /**
+         * active client (from the credential, never the request — except see api keys)
+         */
+        clientId?: string | null;
+        allowedClients?: string[];
+        roles?: string[];
+        /**
+         * resolved; may contain "*"
+         */
+        permissions?: string[];
+        devIdentity: any;
+    } | {
+        subject: any;
+        displayName: any;
+        email: any;
+        clientId: any;
+        allowedClients: any;
+        roles: any[];
+        permissions: any;
+        authMode: string;
+        kind: string;
+        issuer: string;
+        key: string;
+        devIdentity: any;
+    } | {
+        authMode: string;
+        kind: string;
+        issuer: string;
+        subject: string;
+        key: string;
+        displayName: string;
+        clientId: any;
+        allowedClients: string[];
+        roles: any[];
+        permissions: string[];
+        clientFromRequest: boolean;
+    }>;
+    allows: (policy: any, principal: any, askedClientId: any) => any;
+    authorize: (policy: Partial<Record<"blu" | "service" | "team" | "api-key", string[]>>) => (req: any, res: any, next: any) => any;
+    requirePermission: (permission: any) => (req: any, res: any, next: any) => any;
+    modes: string[];
+};
+/**
+ * Who this API has seen, keyed by `principal.key` — so a person signed in with
+ * Blu needs no account in the team's own user store first. The team records
+ * them on first sight (just-in-time) and can attach its own data to that key:
+ * "flagged by", audit trails, preferences. Nothing is linked to the team's own
+ * users; a Blu user and a team-IdP user are different principals.
+ *
+ * In-memory here; a real team keeps this in its own database.
+ *
+ *   const people = createPrincipalDirectory();
+ *   app.get("/x", [authenticate, people.remember], authorize({...}), handler)
+ */
+declare function createPrincipalDirectory(): {
+    remember: (req: any, _res: any, next: any) => void;
+    get: (key: any) => any;
+    list: () => any[];
+};
+/** Parse AUTH_MODES="blu,service,team,api-key" into a Set (defaults to all). */
+declare function enabledModes(value: any, all?: string[]): Set<any>;
+/**
+ * Explicit-allowlist CORS. Written out (rather than `cors()`) so the mechanics
+ * are visible: echo only allowlisted origins, `Vary: Origin`, answer preflights
+ * for the Authorization header. Unlisted origins get no CORS headers at all, so
+ * the *browser* refuses to hand the response to the calling page.
+ *
+ * `origins` may be an array or a (possibly async) function, for allowlists that
+ * come from live config such as the registry.
+ *
+ * @param {{ origins: string[] | (() => string[] | Promise<string[]>), credentials?: boolean }} opts
+ */
+declare function corsAllowlist({ origins, credentials }: {
+    origins: string[] | (() => string[] | Promise<string[]>);
+    credentials?: boolean;
+}): (req: any, res: any, next: any) => Promise<any>;
+/** Tiny request logger that shows who is calling and how — handy in the demo. */
+declare function originLogger(name: any): (req: any, _res: any, next: any) => any;
+/**
+ * @typedef {object} Principal
+ * @property {"blu"|"service"|"team"|"api-key"} authMode
+ * @property {"user"|"service"} kind
+ * @property {string} issuer
+ * @property {string} subject           user id, or api-key id
+ * @property {string} key               stable identity across requests: `<authMode>|<issuer>|<subject>`.
+ *                                      Key your own records (audit, ownership, preferences) on this —
+ *                                      a Blu user needs no account in your system first.
+ * @property {string} displayName
+ * @property {string} [email]
+ * @property {string} [via]             Blu only: the app that obtained the token ("blu-host",
+ *                                      "blu-concierge", or your own standalone app)
+ * @property {string} [actor]           Blu only: software acting for the user (e.g. "blu-concierge")
+ * @property {string|null} clientId     active client (from the credential, never the request — except see api keys)
+ * @property {string[]} allowedClients
+ * @property {string[]} roles
+ * @property {string[]} permissions     resolved; may contain "*"
+ */
+declare class AuthError extends Error {
+    constructor(status: any, code: any, detail: any);
+    status: any;
+    code: any;
+}
+declare function hashApiKey(key: any): any;
+type Principal = {
+    authMode: "blu" | "service" | "team" | "api-key";
+    kind: "user" | "service";
+    issuer: string;
+    /**
+     * user id, or api-key id
+     */
+    subject: string;
+    /**
+     * stable identity across requests: `<authMode>|<issuer>|<subject>`.
+     * Key your own records (audit, ownership, preferences) on this —
+     * a Blu user needs no account in your system first.
+     */
+    key: string;
+    displayName: string;
+    email?: string;
+    /**
+     * Blu only: the app that obtained the token ("blu-host",
+     *              "blu-concierge", or your own standalone app)
+     */
+    via?: string;
+    /**
+     * Blu only: software acting for the user (e.g. "blu-concierge")
+     */
+    actor?: string;
+    /**
+     * active client (from the credential, never the request — except see api keys)
+     */
+    clientId: string | null;
+    allowedClients: string[];
+    roles: string[];
+    /**
+     * resolved; may contain "*"
+     */
+    permissions: string[];
+};
+
+/**
+ * Blu's public addresses, per environment ("dev", "staging" or "prod"). Configure your API from these
+ * instead of copying URLs: what to trust (the issuer), who may call you (the shell origins), and where your
+ * pipeline registers releases (the registry).
+ */
+/** Where every module's pipeline registers its releases, for every environment. Permanent. */
+declare const REGISTRY_URL: "https://registry.blu-ce.horizonmedia.com";
+declare function bluShellOrigins(stage: "dev" | "staging" | "prod"): string[];
+declare function bluIssuer(stage: "dev" | "staging" | "prod"): string;
+
+export { AuthError, REGISTRY_URL, apiKeyAuth, bluIssuer, bluPlatformAuth, bluServiceAuth, bluShellOrigins, corsAllowlist, createMcpEndpoint, createMcpWebHandler, createModuleAuth, createPrincipalDirectory, enabledModes, hashApiKey, link, originLogger, policyAllows, teamIdpAuth };