@anchrd/intel-api 0.2.0

package/dist/adapters/session-cookie/session-cookie.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { SafeReturnPath } from "../../shared/safe-return-path/safe-return-path.js";
+const PendingSession = z.strictObject({
+    version: z.literal(1),
+    kind: z.literal("pending"),
+    clientId: z.string().min(1),
+    codeVerifier: z.string().min(43),
+    state: z.string().min(16),
+    returnTo: SafeReturnPath,
+    expiresAt: z.number().int().positive(),
+});
+const UserSession = z.strictObject({
+    version: z.literal(1),
+    kind: z.literal("user"),
+    clientId: z.string().min(1),
+    accessToken: z.string().min(1),
+    expiresAt: z.number().int().positive(),
+});
+const ConnectionPendingSession = z.strictObject({
+    version: z.literal(1),
+    kind: z.literal("connection-pending"),
+    clientId: z.string().min(1),
+    codeVerifier: z.string().min(43),
+    state: z.string().min(16),
+    returnTo: SafeReturnPath,
+    issuer: z.url(),
+    resource: z.url(),
+    userId: z.string().min(1),
+    user: UserSession,
+    expiresAt: z.number().int().positive(),
+});
+const Session = z.discriminatedUnion("kind", [
+    PendingSession,
+    ConnectionPendingSession,
+    UserSession,
+]);
+const additionalData = new TextEncoder().encode("anchrd-intel-session-v1");
+function encode(bytes) {
+    let value = "";
+    for (const byte of bytes)
+        value += String.fromCharCode(byte);
+    return btoa(value).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decode(value) {
+    const padded = value
+        .replaceAll("-", "+")
+        .replaceAll("_", "/")
+        .padEnd(Math.ceil(value.length / 4) * 4, "=");
+    return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+}
+export function createSessionCodec(deps) {
+    if (new TextEncoder().encode(deps.secret).byteLength < 32) {
+        throw new Error("INTEL_SESSION_SECRET must contain at least 32 bytes");
+    }
+    const key = deps.crypto.subtle
+        .digest("SHA-256", new TextEncoder().encode(deps.secret))
+        .then((hash) => deps.crypto.subtle.importKey("raw", hash, "AES-GCM", false, ["encrypt", "decrypt"]));
+    return {
+        async seal(value) {
+            const session = Session.parse(value);
+            const iv = deps.crypto.getRandomValues(new Uint8Array(12));
+            const encrypted = new Uint8Array(await deps.crypto.subtle.encrypt({ name: "AES-GCM", iv, additionalData }, await key, new TextEncoder().encode(JSON.stringify(session))));
+            const output = new Uint8Array(iv.byteLength + encrypted.byteLength);
+            output.set(iv);
+            output.set(encrypted, iv.byteLength);
+            return encode(output);
+        },
+        async open(value) {
+            try {
+                const input = decode(value);
+                if (input.byteLength <= 28)
+                    return null;
+                const decrypted = await deps.crypto.subtle.decrypt({ name: "AES-GCM", iv: input.slice(0, 12), additionalData }, await key, input.slice(12));
+                return Session.parse(JSON.parse(new TextDecoder().decode(decrypted)));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/adapters/tool-source-policy/tool-source-policy.d.ts

@@ -0,0 +1 @@
+export declare function createToolSourcePolicy(configuredOrigins: string | undefined): (sourceUrl: string) => boolean;

package/dist/adapters/tool-source-policy/tool-source-policy.js

@@ -0,0 +1,22 @@
+export function createToolSourcePolicy(configuredOrigins) {
+    const origins = new Set((configuredOrigins ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .map((value) => {
+        const url = new URL(value);
+        if (url.username || url.password || (url.pathname !== "/" && url.pathname !== "")) {
+            throw new Error("TOOL_SOURCE_ORIGINS must contain exact origins without credentials or paths");
+        }
+        return url.origin;
+    }));
+    // A malformed URL is not an allowed origin, so the policy answers false instead of throwing.
+    return (sourceUrl) => {
+        try {
+            return origins.has(new URL(sourceUrl).origin);
+        }
+        catch {
+            return false;
+        }
+    };
+}

package/dist/auth/auth.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserAuth, BrowserAuthDeps } from "./auth.types.js";
+export declare function createBrowserAuth(deps: BrowserAuthDeps): BrowserAuth;

package/dist/auth/auth.js

@@ -0,0 +1,176 @@
+import { calculatePKCECodeChallenge, randomPKCECodeVerifier, randomState } from "openid-client";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+import { SafeReturnPath } from "../shared/safe-return-path/safe-return-path.js";
+const cookieName = "intel_session";
+function cookieValue(headers) {
+    const values = headers.get("cookie")?.split(";") ?? [];
+    for (const value of values) {
+        const [name, ...rest] = value.trim().split("=");
+        if (name === cookieName)
+            return rest.join("=") || null;
+    }
+    return null;
+}
+function sessionCookie(value, secure, maxAge) {
+    return `${cookieName}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${Math.max(0, Math.floor(maxAge))}${secure ? "; Secure" : ""}`;
+}
+function redirect(location, cookie) {
+    const headers = new Headers({ location, "cache-control": "no-store" });
+    if (cookie)
+        headers.set("set-cookie", cookie);
+    return new Response(null, { status: 302, headers });
+}
+async function pkce() {
+    for (;;) {
+        const verifier = randomPKCECodeVerifier();
+        const challenge = await calculatePKCECodeChallenge(verifier);
+        if (/^[A-Za-z0-9]/.test(challenge))
+            return { verifier, challenge };
+    }
+}
+export function createBrowserAuth(deps) {
+    const baseUrl = deps.baseUrl.replace(/\/+$/, "");
+    const gateIssuer = deps.gateUrl.replace(/\/+$/, "");
+    const redirectUri = `${baseUrl}/auth/callback`;
+    const secure = new URL(baseUrl).protocol === "https:";
+    async function clientId(issuer, resource) {
+        const registrationKey = `${issuer}#${resource}`;
+        const stored = await deps.clients.get(registrationKey, redirectUri);
+        if (stored)
+            return stored;
+        const registered = await deps.oauth.register({
+            issuer,
+            redirectUri,
+            clientName: "Intel",
+            resource,
+        });
+        return await deps.clients.put({
+            issuer: registrationKey,
+            redirectUri,
+            clientId: registered,
+            createdAt: deps.now().toISOString(),
+        });
+    }
+    async function userSession(client, tokens) {
+        return {
+            version: 1,
+            kind: "user",
+            clientId: client,
+            accessToken: tokens.accessToken,
+            expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+        };
+    }
+    return {
+        async login(requestUrl) {
+            const returnTo = SafeReturnPath.catch("/").parse(requestUrl.searchParams.get("returnTo") ?? "/");
+            const client = await clientId(gateIssuer, deps.resource);
+            const { verifier: codeVerifier, challenge: codeChallenge } = await pkce();
+            const state = randomState();
+            const pending = {
+                version: 1,
+                kind: "pending",
+                clientId: client,
+                codeVerifier,
+                state,
+                returnTo,
+                expiresAt: deps.now().getTime() + 10 * 60 * 1_000,
+            };
+            const authorizationUrl = await deps.oauth.authorizationUrl({
+                issuer: gateIssuer,
+                clientId: client,
+                redirectUri,
+                resource: deps.resource,
+                codeChallenge,
+                state,
+                scope: "openid profile email",
+            });
+            return redirect(authorizationUrl.href, sessionCookie(await deps.sessions.seal(pending), secure, 10 * 60));
+        },
+        async connect(requestUrl, headers, userId) {
+            const encoded = cookieValue(headers);
+            const user = encoded ? await deps.sessions.open(encoded) : null;
+            if (user?.kind !== "user" || user.expiresAt <= deps.now().getTime() + 30_000) {
+                throw new IntelError(401, "authentication_required", "Authentication is required");
+            }
+            const returnTo = SafeReturnPath.catch("/tools").parse(requestUrl.searchParams.get("returnTo") ?? "/tools");
+            if (!deps.portalUrl) {
+                throw new IntelError(503, "portal_not_configured", "No MCP portal is configured for this deployment");
+            }
+            const discovered = await deps.oauth.discoverResource(deps.portalUrl).catch(() => {
+                throw new IntelError(409, "portal_oauth_unavailable", "The MCP portal does not publish usable OAuth metadata");
+            });
+            const connectionClientId = await clientId(discovered.issuer, discovered.resource);
+            const { verifier: codeVerifier, challenge: codeChallenge } = await pkce();
+            const state = randomState();
+            const pending = {
+                version: 1,
+                kind: "connection-pending",
+                clientId: connectionClientId,
+                codeVerifier,
+                state,
+                returnTo,
+                issuer: discovered.issuer,
+                resource: discovered.resource,
+                userId,
+                user,
+                expiresAt: deps.now().getTime() + 10 * 60 * 1_000,
+            };
+            const authorizationUrl = await deps.oauth.authorizationUrl({
+                issuer: discovered.issuer,
+                clientId: connectionClientId,
+                redirectUri,
+                resource: discovered.resource,
+                codeChallenge,
+                state,
+                ...(discovered.scope ? { scope: discovered.scope } : {}),
+            });
+            return redirect(authorizationUrl.href, sessionCookie(await deps.sessions.seal(pending), secure, 10 * 60));
+        },
+        async callback(requestUrl, headers) {
+            const encoded = cookieValue(headers);
+            const pending = encoded ? await deps.sessions.open(encoded) : null;
+            if ((pending?.kind !== "pending" && pending?.kind !== "connection-pending") ||
+                pending.expiresAt <= deps.now().getTime()) {
+                throw new IntelError(400, "oauth_session_invalid", "OAuth session is missing or expired");
+            }
+            const tokens = await deps.oauth.exchange({
+                issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
+                clientId: pending.clientId,
+                callbackUrl: requestUrl,
+                redirectUri,
+                resource: pending.kind === "connection-pending" ? pending.resource : deps.resource,
+                codeVerifier: pending.codeVerifier,
+                state: pending.state,
+            });
+            if (pending.kind === "connection-pending") {
+                await deps.portalTokens.write(pending.userId, {
+                    accessToken: tokens.accessToken,
+                    refreshToken: tokens.refreshToken ?? null,
+                    expiresAt: deps.now().getTime() + Math.max(30, tokens.expiresIn) * 1_000,
+                    issuer: pending.issuer,
+                    clientId: pending.clientId,
+                    resource: pending.resource,
+                });
+                const remaining = (pending.user.expiresAt - deps.now().getTime()) / 1_000;
+                if (remaining <= 0) {
+                    return redirect(`/auth/login?returnTo=${encodeURIComponent(pending.returnTo)}`, sessionCookie("", secure, 0));
+                }
+                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(pending.user), secure, remaining));
+            }
+            const session = await userSession(pending.clientId, tokens);
+            return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));
+        },
+        logout() {
+            return redirect("/", sessionCookie("", secure, 0));
+        },
+        async resolve(headers) {
+            const encoded = cookieValue(headers);
+            const session = encoded ? await deps.sessions.open(encoded) : null;
+            if (session?.kind !== "user")
+                return null;
+            return session.expiresAt > deps.now().getTime() + 30_000
+                ? { bearer: session.accessToken }
+                : null;
+        },
+    };
+}

package/dist/auth/auth.types.d.ts

@@ -0,0 +1,104 @@
+import type { PortalTokenStore } from "../tools/tools.types.js";
+export interface OAuthTokens {
+    accessToken: string;
+    expiresIn: number;
+    refreshToken?: string;
+}
+export interface OAuthPort {
+    discoverResource(resourceUrl: string): Promise<{
+        resource: string;
+        issuer: string;
+        scope?: string;
+    }>;
+    register(input: {
+        issuer: string;
+        redirectUri: string;
+        clientName: string;
+        resource: string;
+    }): Promise<string>;
+    authorizationUrl(input: {
+        issuer: string;
+        clientId: string;
+        redirectUri: string;
+        resource: string;
+        codeChallenge: string;
+        state: string;
+        scope?: string;
+    }): Promise<URL>;
+    exchange(input: {
+        issuer: string;
+        clientId: string;
+        callbackUrl: URL;
+        redirectUri: string;
+        resource: string;
+        codeVerifier: string;
+        state: string;
+    }): Promise<OAuthTokens>;
+    refresh(input: {
+        issuer: string;
+        clientId: string;
+        resource: string;
+        refreshToken: string;
+    }): Promise<OAuthTokens>;
+}
+export interface OAuthClientStore {
+    get(issuer: string, redirectUri: string): Promise<string | null>;
+    put(input: {
+        issuer: string;
+        redirectUri: string;
+        clientId: string;
+        createdAt: string;
+    }): Promise<string>;
+}
+export interface UserAuthSession {
+    version: 1;
+    kind: "user";
+    clientId: string;
+    accessToken: string;
+    expiresAt: number;
+}
+export type AuthSession = {
+    version: 1;
+    kind: "pending";
+    clientId: string;
+    codeVerifier: string;
+    state: string;
+    returnTo: string;
+    expiresAt: number;
+} | {
+    version: 1;
+    kind: "connection-pending";
+    clientId: string;
+    codeVerifier: string;
+    state: string;
+    returnTo: string;
+    issuer: string;
+    resource: string;
+    userId: string;
+    user: UserAuthSession;
+    expiresAt: number;
+} | UserAuthSession;
+export interface SessionCodec {
+    seal(session: AuthSession): Promise<string>;
+    open(value: string): Promise<AuthSession | null>;
+}
+export interface BrowserAuthDeps {
+    baseUrl: string;
+    gateUrl: string;
+    resource: string;
+    oauth: OAuthPort;
+    clients: OAuthClientStore;
+    sessions: SessionCodec;
+    portalUrl: string | null;
+    portalTokens: Pick<PortalTokenStore, "write">;
+    now(): Date;
+}
+export interface BrowserAuth {
+    login(requestUrl: URL): Promise<Response>;
+    connect(requestUrl: URL, headers: Headers, userId: string): Promise<Response>;
+    callback(requestUrl: URL, headers: Headers): Promise<Response>;
+    logout(): Response;
+    resolve(headers: Headers): Promise<{
+        bearer: string;
+    } | null>;
+}

package/dist/auth/auth.types.js

@@ -0,0 +1 @@
+export {};

package/dist/build/build.d.ts

@@ -0,0 +1,2 @@
+import type { BuildDeps, BuildResult } from "./build.types.js";
+export declare function createBuild(deps: BuildDeps): BuildResult;

package/dist/build/build.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+const UiConfig = z.strictObject({
+    theme: z.string().min(1).optional(),
+    logo: z.string().min(1).optional(),
+    favicon: z.string().min(1).optional(),
+    defaultLanguage: z.string().min(1).default("en"),
+    languages: z.record(z.string().min(1), z.string().min(1)).default({}),
+});
+const IntelConfig = z.strictObject({
+    ui: UiConfig.default({ defaultLanguage: "en", languages: {} }),
+});
+const Catalog = z.record(z.string(), z.string());
+const defaultTheme = `/* Generated by \`intel build\`. Intel defaults are active. */\n`;
+const defaultLogo = `export const customLogoUrl: string | null = null;\n`;
+function validationMessage(error) {
+    return error.issues
+        .map((issue) => `${issue.path.join(".") || "intel.json"}: ${issue.message}`)
+        .join("; ");
+}
+function validateCatalog(source, candidate) {
+    const expected = Object.keys(source).sort();
+    const actual = Object.keys(candidate).sort();
+    const missing = expected.filter((key) => !actual.includes(key));
+    const unknown = actual.filter((key) => !expected.includes(key));
+    return { missing, unknown };
+}
+function asSvgDataUrl(svg) {
+    return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+export function createBuild(deps) {
+    async function readRequired(path, field) {
+        const content = await deps.readTextFile(path);
+        if (content === null)
+            throw new Error(`File not found: ${path} (${field})`);
+        return content;
+    }
+    async function readSvg(path, field) {
+        if (!path.toLowerCase().endsWith(".svg")) {
+            throw new Error(`${field} must point to an .svg file`);
+        }
+        return await readRequired(path, field);
+    }
+    return {
+        async build() {
+            const location = await deps.resolveUi();
+            if (!location) {
+                deps.log("Error: @anchrd/intel-ui was not found in node_modules or packages/ui.");
+                return 1;
+            }
+            try {
+                const rawConfig = await deps.readTextFile("intel.json");
+                let value = {};
+                if (rawConfig !== null) {
+                    try {
+                        value = JSON.parse(rawConfig);
+                    }
+                    catch {
+                        throw new Error("intel.json is not valid JSON");
+                    }
+                }
+                const parsed = IntelConfig.safeParse(value);
+                if (!parsed.success)
+                    throw new Error(validationMessage(parsed.error));
+                const config = parsed.data.ui;
+                const englishPath = `${location.dir}/src/i18n/en.json`;
+                const englishRaw = await readRequired(englishPath, "built-in English catalog");
+                const englishParsed = Catalog.safeParse(JSON.parse(englishRaw));
+                if (!englishParsed.success)
+                    throw new Error("Intel's built-in English catalog is invalid");
+                const english = englishParsed.data;
+                const catalogs = {};
+                for (const [language, path] of Object.entries(config.languages)) {
+                    const candidateRaw = await readRequired(path, `ui.languages.${language}`);
+                    let candidateJson;
+                    try {
+                        candidateJson = JSON.parse(candidateRaw);
+                    }
+                    catch {
+                        throw new Error(`${path} is not valid JSON`);
+                    }
+                    const candidateParsed = Catalog.safeParse(candidateJson);
+                    if (!candidateParsed.success)
+                        throw new Error(`${path} must contain only string values`);
+                    const difference = validateCatalog(english, candidateParsed.data);
+                    if (difference.missing.length || difference.unknown.length) {
+                        throw new Error(`${path} does not match en.json; missing: ${difference.missing.join(", ") || "none"}; unknown: ${difference.unknown.join(", ") || "none"}`);
+                    }
+                    catalogs[language] = candidateParsed.data;
+                }
+                if (config.defaultLanguage !== "en" && !(config.defaultLanguage in catalogs)) {
+                    throw new Error(`ui.defaultLanguage ${JSON.stringify(config.defaultLanguage)} is not listed in ui.languages`);
+                }
+                const theme = config.theme
+                    ? `/* Generated by \`intel build\` from ${config.theme}. */\n${await readRequired(config.theme, "ui.theme")}\n`
+                    : defaultTheme;
+                const logoSvg = config.logo ? await readSvg(config.logo, "ui.logo") : null;
+                const faviconPath = config.favicon ?? config.logo;
+                const faviconSvg = faviconPath
+                    ? await readSvg(faviconPath, config.favicon ? "ui.favicon" : "ui.logo")
+                    : await readRequired(`${location.dir}/src/branding/favicon.default.svg`, "default favicon");
+                const logoModule = logoSvg
+                    ? `/* Generated by \`intel build\` from ${config.logo}. */\nexport const customLogoUrl = ${JSON.stringify(asSvgDataUrl(logoSvg))};\n`
+                    : defaultLogo;
+                const languageBundle = `${JSON.stringify({ defaultLanguage: config.defaultLanguage, catalogs }, null, 2)}\n`;
+                await deps.writeTextFile(`${location.dir}/src/theme/custom.css`, theme);
+                await deps.writeTextFile(`${location.dir}/src/branding/custom-logo.ts`, logoModule);
+                await deps.writeTextFile(`${location.dir}/src/branding/favicon.svg`, faviconSvg);
+                await deps.writeTextFile(`${location.dir}/src/i18n/custom.json`, languageBundle);
+                const temporaryOutDir = `${location.outDir}.tmp`;
+                const exitCode = await deps.exec("npm", ["run", "build", "--", "--outDir", temporaryOutDir, "--emptyOutDir"], { cwd: location.dir });
+                if (exitCode !== 0) {
+                    deps.log(`Error: Intel UI build exited with ${exitCode}.`);
+                    return 1;
+                }
+                await deps.replaceDir(temporaryOutDir, location.outDir);
+                deps.log(`Intel UI built at ${location.outDir}.`);
+                return 0;
+            }
+            catch (error) {
+                deps.log(`Error: ${error instanceof Error ? error.message : String(error)}`);
+                return 1;
+            }
+        },
+    };
+}

package/dist/build/build.types.d.ts

@@ -0,0 +1,17 @@
+export interface UiLocation {
+    dir: string;
+    outDir: string;
+}
+export interface BuildDeps {
+    readTextFile(path: string): Promise<string | null>;
+    writeTextFile(path: string, content: string): Promise<void>;
+    resolveUi(): Promise<UiLocation | null>;
+    exec(command: string, args: string[], options: {
+        cwd: string;
+    }): Promise<number>;
+    replaceDir(from: string, to: string): Promise<void>;
+    log(message: string): void;
+}
+export interface BuildResult {
+    build(): Promise<number>;
+}

package/dist/build/build.types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/cli.d.ts

@@ -0,0 +1,4 @@
+import type { CliDeps } from "./cli.types.js";
+export declare function createCli(deps: CliDeps): {
+    run(argv: string[]): Promise<number>;
+};