@arcote.tech/arc-map 0.7.31 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-map",
   "type": "module",
-  "version": "0.7.31",
+  "version": "0.8.0",
   "private": false,
   "author": "Przemysław Krasiński [arcote.tech]",
   "description": "Arc Context Map — interactive map of context spaces, elements, event-flow and React useScope usages (dev tool)",
@@ -9,7 +9,8 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./app": "./src/app/index.tsx"
+    "./app": "./src/app/index.tsx",
+    "./types": "./src/types.ts"
   },
   "scripts": {
     "type-check": "tsc --noEmit",
@@ -19,11 +20,11 @@
     "ts-morph": "^24.0.0",
     "@xyflow/react": "^12.0.0",
     "elkjs": "^0.9.3",
-    "@arcote.tech/arc-process": "^0.7.31"
+    "@arcote.tech/arc-process": "^0.8.0"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.31",
-    "@arcote.tech/platform": "^0.7.31",
+    "@arcote.tech/arc": "^0.8.0",
+    "@arcote.tech/platform": "^0.8.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "typescript": "^5.0.0"

package/src/app/api.ts

@@ -0,0 +1,28 @@
+/**
+ * Fetch do API serwera mapy z tokenem parowania. Serwer (gdy uruchomiony
+ * z `authToken`) wymaga `X-Arc-Map-Token` na `/api/*`; własny front dostaje
+ * token wstrzyknięty do shella jako `window.__ARC_MAP_TOKEN__`. SSE nie umie
+ * nagłówków — tam token idzie w query (`sseUrl`).
+ */
+
+declare global {
+  interface Window {
+    __ARC_MAP_TOKEN__?: string;
+  }
+}
+
+const token = (): string | undefined =>
+  typeof window === "undefined" ? undefined : window.__ARC_MAP_TOKEN__;
+
+export function apiFetch(path: string, init?: RequestInit): Promise<Response> {
+  const t = token();
+  const headers = new Headers(init?.headers);
+  if (t) headers.set("X-Arc-Map-Token", t);
+  return fetch(path, { ...init, headers });
+}
+
+/** URL strumienia SSE z tokenem w query (EventSource nie wysyła nagłówków). */
+export function sseUrl(path: string): string {
+  const t = token();
+  return t ? `${path}${path.includes("?") ? "&" : "?"}token=${encodeURIComponent(t)}` : path;
+}

package/src/app/index.tsx

@@ -4,6 +4,7 @@ import "@xyflow/react/dist/style.css";
 import { StrictMode, useEffect, useState } from "react";
 import { createRoot } from "react-dom/client";
 import type { MapJson, UseCaseEntry } from "../types";
+import { apiFetch, sseUrl } from "./api";
 import { MapView } from "./map-view";
 import { UseCaseView } from "./usecase-view";
 import { GLASS } from "./theme";
@@ -54,11 +55,11 @@ function App() {
   const [mode, setMode] = useState<Mode>("use-cases");
 
   const load = () => {
-    fetch("/api/map")
+    apiFetch("/api/map")
       .then((r) => r.json())
       .then((data) => (data?.error ? setError(data.error) : (setMap(data), setError(null))))
       .catch((e) => setError(String(e)));
-    fetch("/api/use-cases")
+    apiFetch("/api/use-cases")
       .then((r) => r.json())
       .then((d) => setUseCases(d.useCases ?? []))
       .catch(() => setUseCases([]));
@@ -66,7 +67,7 @@ function App() {
 
   useEffect(() => {
     load();
-    const es = new EventSource("/api/reload-stream");
+    const es = new EventSource(sseUrl("/api/reload-stream"));
     es.onmessage = (ev) => {
       if (ev.data && ev.data !== "connected") load();
     };

package/src/app/usecase-view.tsx

@@ -16,6 +16,7 @@ import {
 } from "@arcote.tech/arc-process";
 import { ProcessDiagram, type SourceProvider } from "@arcote.tech/arc-process/react";
 import type { MapJson, UseCaseEntry } from "../types";
+import { apiFetch } from "./api";
 import { UseCaseTree } from "./usecase-tree";
 import { GLASS } from "./theme";
 
@@ -24,7 +25,7 @@ const sourceProvider: SourceProvider = async (node: ProcessNode) => {
   const source = (node.meta as { source?: { file: string; line?: number } })
     ?.source;
   if (!source?.file) return null;
-  const res = await fetch(`/api/source?file=${encodeURIComponent(source.file)}`);
+  const res = await apiFetch(`/api/source?file=${encodeURIComponent(source.file)}`);
   if (!res.ok) return null;
   return { file: source.file, line: source.line, code: await res.text() };
 };
@@ -42,7 +43,7 @@ export function UseCaseView({ map, useCases }: { map: MapJson; useCases: UseCase
   useEffect(() => {
     if (!selectedId) return;
     setMdx("");
-    fetch(`/api/use-cases/raw?id=${encodeURIComponent(selectedId)}`)
+    apiFetch(`/api/use-cases/raw?id=${encodeURIComponent(selectedId)}`)
       .then((r) => (r.ok ? r.text() : Promise.reject(new Error(`HTTP ${r.status}`))))
       .then(setMdx)
       .catch((e) => setMdx(`# Błąd\n\nNie udało się wczytać: ${String(e)}`));

package/src/mapper.ts

@@ -29,6 +29,7 @@ import {
   type MapElement,
   type MapElementMethod,
   type MapJson,
+  type MapMeta,
   type MapSpace,
 } from "./types";
 
@@ -52,6 +53,8 @@ export interface BuildMapInput {
   catalog?: CatalogEntry[];
   /** ISO timestamp; injected so the function stays deterministic for tests. */
   generatedAt?: string;
+  /** Tożsamość aplikacji + wersja kontraktu — przechodzi 1:1 do `MapJson.meta`. */
+  meta?: MapMeta;
 }
 
 // ---------------------------------------------------------------------------
@@ -400,6 +403,7 @@ export function buildMapJson(input: BuildMapInput): MapJson {
   const resolvedComponents = components.filter((c) => usedComponentIds.has(c.id));
 
   return {
+    meta: input.meta,
     spaces: [...spaceIndex.values()],
     elements,
     edges,

package/src/server.ts

@@ -21,7 +21,7 @@ import { buildMapJson, type ModuleInfo } from "./mapper";
 import { loadCatalog } from "./catalog";
 import { scanScopeUsages, type ScanInput } from "./scan";
 import { discoverUseCases, type UseCasePackage } from "./use-cases/discover";
-import type { MapJson, UseCaseEntry } from "./types";
+import type { MapJson, MapMeta, UseCaseEntry } from "./types";
 
 export interface MapServerOptions {
   /** Returns the current live context (recomputed by the host on rebuild). */
@@ -39,6 +39,28 @@ export interface MapServerOptions {
   appEntry?: string;
   /** Packages to scan for `use-cases/**\/*.mdx`. Enables the use-case mode. */
   useCasePackages?: UseCasePackage[];
+  /**
+   * Pairing token. When set, every `/api/*` request (except OPTIONS) must
+   * carry `X-Arc-Map-Token: <token>` — otherwise 401. `/api/reload-stream`
+   * additionally accepts `?token=` (EventSource cannot send headers). The
+   * map's own front gets the token injected into the shell HTML (served
+   * locally only), so its UX is unchanged. This closes the standing hole
+   * where ANY web page open in the developer's browser could read the whole
+   * map and source code via CORS `*`.
+   */
+  authToken?: string;
+  /** Tożsamość aplikacji + wersja kontraktu — trafia do `MapJson.meta`. */
+  meta?: MapMeta;
+  /**
+   * Discovery (spec/platform-headless.md): informacje o serwerze PLATFORMY
+   * tej aplikacji (komendy/query/WS + chunki federowane) — konsument
+   * (host federacji, np. BMF) dostaje je z `GET /api/discovery`.
+   */
+  platform?: {
+    platformUrl: string;
+    federation?: unknown;
+    peers?: Readonly<Record<string, string>>;
+  };
 }
 
 export interface MapServer {
@@ -53,13 +75,19 @@ export interface MapServer {
 const DEFAULT_PORT = 5006;
 const MAX_PORT_TRIES = 20;
 
-function shellHtml(): string {
+function shellHtml(authToken?: string): string {
+  // Token dla własnego frontu mapy — shell serwowany jest tylko lokalnie
+  // (localhost), więc wstrzyknięcie nie poszerza powierzchni: kto może
+  // odczytać ten HTML, ten i tak siedzi na maszynie z serwerem.
+  const tokenScript = authToken
+    ? `\n  <script>window.__ARC_MAP_TOKEN__ = ${JSON.stringify(authToken)};</script>`
+    : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Arc Context Map</title>
+  <title>Arc Context Map</title>${tokenScript}
   <link rel="stylesheet" href="/app.css" />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" />
@@ -110,7 +138,17 @@ async function buildApp(appEntry: string): Promise<{ js: string; css: string }>
 const CORS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, OPTIONS",
-  "Access-Control-Allow-Headers": "Content-Type",
+  "Access-Control-Allow-Headers": "Content-Type, X-Arc-Map-Token",
+};
+
+/**
+ * Preflight z publicznej strony (https) do localhost wymaga w Chrome zgody
+ * Private Network Access — bez tego nagłówka fetch z hostowanego BMF do
+ * lokalnego serwera mapy jest blokowany zanim w ogóle dojdzie do requestu.
+ */
+const PREFLIGHT = {
+  ...CORS,
+  "Access-Control-Allow-Private-Network": "true",
 };
 
 export async function startMapServer(opts: MapServerOptions): Promise<MapServer> {
@@ -140,7 +178,14 @@ export async function startMapServer(opts: MapServerOptions): Promise<MapServer>
   const buildPayload = (): MapJson => {
     const context = opts.getContext();
     if (!context) {
-      return { spaces: [], elements: [], edges: [], components: [], componentEdges: [] };
+      return {
+        meta: opts.meta,
+        spaces: [],
+        elements: [],
+        edges: [],
+        components: [],
+        componentEdges: [],
+      };
     }
     const scan = getScan();
     const moduleByElement = (opts.getModuleIndex ?? buildModuleIndex)();
@@ -152,6 +197,7 @@ export async function startMapServer(opts: MapServerOptions): Promise<MapServer>
       pages: buildPageNodes(),
       catalog: getCatalog(),
       generatedAt: new Date().toISOString(),
+      meta: opts.meta,
     });
   };
 
@@ -178,7 +224,24 @@ export async function startMapServer(opts: MapServerOptions): Promise<MapServer>
 
   const handler = (req: Request): Response => {
     const url = new URL(req.url);
-    if (req.method === "OPTIONS") return new Response(null, { headers: CORS });
+    if (req.method === "OPTIONS") return new Response(null, { headers: PREFLIGHT });
+
+    // Guard tokenu parowania na całym /api/* (patrz MapServerOptions.authToken).
+    // 401 wychodzi Z nagłówkami CORS, żeby zewnętrzny konsument (BMF) umiał
+    // odróżnić „zły token" od „serwer nie żyje" (network error).
+    if (opts.authToken && url.pathname.startsWith("/api/")) {
+      const header = req.headers.get("X-Arc-Map-Token");
+      const query =
+        url.pathname === "/api/reload-stream"
+          ? url.searchParams.get("token")
+          : null;
+      if (header !== opts.authToken && query !== opts.authToken) {
+        return new Response(JSON.stringify({ error: "invalid pairing token" }), {
+          status: 401,
+          headers: { ...CORS, "Content-Type": "application/json" },
+        });
+      }
+    }
 
     switch (url.pathname) {
       case "/app.js":
@@ -203,6 +266,25 @@ export async function startMapServer(opts: MapServerOptions): Promise<MapServer>
           headers: { ...CORS, "Content-Type": "application/json", "Cache-Control": "no-cache" },
         });
       }
+      case "/api/discovery": {
+        // Discovery dla zewnętrznego konsumenta (za tokenem parowania):
+        // gdzie żyje serwer platformy, czy federacja jest dostępna i z
+        // jakimi peers (polityka kompatybilności hosta) — bez konieczności
+        // zgadywania portów.
+        const platform = opts.platform;
+        const body = {
+          meta: opts.meta ?? null,
+          platformUrl: platform?.platformUrl ?? null,
+          federation: (platform?.federation as object | undefined) ?? null,
+          peers: platform?.peers ?? null,
+          federationManifestUrl: platform
+            ? `${platform.platformUrl}/api/federation/manifest`
+            : null,
+        };
+        return new Response(JSON.stringify(body), {
+          headers: { ...CORS, "Content-Type": "application/json", "Cache-Control": "no-cache" },
+        });
+      }
       case "/api/use-cases": {
         const list: UseCaseEntry[] = getUseCases().map(
           ({ absPath, ...e }) => e,
@@ -278,7 +360,7 @@ export async function startMapServer(opts: MapServerOptions): Promise<MapServer>
         });
       }
       default:
-        return new Response(shellHtml(), {
+        return new Response(shellHtml(opts.authToken), {
           headers: { "Content-Type": "text/html" },
         });
     }

package/src/types.ts

@@ -150,8 +150,25 @@ export interface MapComponentEdge {
   line?: number;
 }
 
+/**
+ * Meta zbudowanej mapy — tożsamość aplikacji dla zewnętrznych konsumentów
+ * (np. import kontekstu do BMF). `schemaVersion` wersjonuje kontrakt MapJson;
+ * konsument odrzuca nieznaną wersję major z czytelnym komunikatem.
+ */
+export interface MapMeta {
+  schemaVersion: number;
+  /** Nazwa aplikacji (root package.json workspace'u). */
+  name: string;
+  version?: string;
+}
+
+/** Bieżąca wersja kontraktu MapJson serwowanego przez `/api/map`. */
+export const MAP_SCHEMA_VERSION = 1;
+
 /** Full payload returned by `GET /api/map`. */
 export interface MapJson {
+  /** Tożsamość aplikacji + wersja kontraktu (dla zewnętrznych konsumentów). */
+  meta?: MapMeta;
   spaces: MapSpace[];
   elements: MapElement[];
   edges: MapEdge[];

package/tests/fixtures/app-entry.ts

@@ -0,0 +1,2 @@
+// Minimal front entry for server tests — avoids bundling the real React app.
+export {};

package/tests/server-auth.test.ts

@@ -0,0 +1,110 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+import { startMapServer, type MapServer } from "../src/server";
+
+/**
+ * Testy parowania tokenem serwera arc-map (konsumpcja przez zewnętrzną
+ * aplikację, np. BMF): guard `X-Arc-Map-Token` na `/api/*`, nagłówki CORS +
+ * Private Network Access na preflight, fallback `?token=` na SSE oraz meta
+ * aplikacji w `/api/map`.
+ */
+
+const APP_ENTRY = join(import.meta.dir, "fixtures/app-entry.ts");
+const TOKEN = "sekret-parowania-123";
+
+const servers: MapServer[] = [];
+afterAll(() => {
+  for (const s of servers) s.stop();
+});
+
+async function boot(opts: { authToken?: string } = {}): Promise<MapServer> {
+  const server = await startMapServer({
+    getContext: () => null,
+    scan: { globs: [], workspaceRoot: import.meta.dir, packageOf: () => undefined },
+    port: 45810 + servers.length * 25,
+    appEntry: APP_ENTRY,
+    meta: { schemaVersion: 1, name: "@x/test-app", version: "1.2.3" },
+    ...opts,
+  });
+  servers.push(server);
+  return server;
+}
+
+describe("startMapServer bez authToken (backward compat)", () => {
+  test("/api/map odpowiada bez tokenu", async () => {
+    const s = await boot();
+    const res = await fetch(`${s.url}/api/map`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { meta?: { name: string } };
+    expect(body.meta?.name).toBe("@x/test-app");
+  });
+});
+
+describe("startMapServer z authToken", () => {
+  let s: MapServer;
+  test("boot", async () => {
+    s = await boot({ authToken: TOKEN });
+  });
+
+  test("/api/map bez tokenu → 401 z nagłówkami CORS", async () => {
+    const res = await fetch(`${s.url}/api/map`);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("*");
+  });
+
+  test("/api/map ze złym tokenem → 401", async () => {
+    const res = await fetch(`${s.url}/api/map`, {
+      headers: { "X-Arc-Map-Token": "zly" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("/api/map z tokenem → 200 + meta", async () => {
+    const res = await fetch(`${s.url}/api/map`, {
+      headers: { "X-Arc-Map-Token": TOKEN },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      meta?: { schemaVersion: number; name: string; version?: string };
+    };
+    expect(body.meta).toEqual({
+      schemaVersion: 1,
+      name: "@x/test-app",
+      version: "1.2.3",
+    });
+  });
+
+  test("OPTIONS przechodzi bez tokenu: PNA + Allow-Headers z X-Arc-Map-Token", async () => {
+    const res = await fetch(`${s.url}/api/map`, { method: "OPTIONS" });
+    expect(res.status).toBeLessThan(300);
+    expect(res.headers.get("Access-Control-Allow-Private-Network")).toBe("true");
+    expect(res.headers.get("Access-Control-Allow-Headers")).toContain(
+      "X-Arc-Map-Token",
+    );
+  });
+
+  test("/api/reload-stream przyjmuje ?token= (EventSource bez nagłówków)", async () => {
+    const res = await fetch(
+      `${s.url}/api/reload-stream?token=${encodeURIComponent(TOKEN)}`,
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toContain("text/event-stream");
+    const reader = res.body!.getReader();
+    const first = await reader.read();
+    expect(new TextDecoder().decode(first.value)).toContain("connected");
+    await reader.cancel();
+  });
+
+  test("/api/reload-stream bez tokenu → 401", async () => {
+    const res = await fetch(`${s.url}/api/reload-stream`);
+    expect(res.status).toBe(401);
+  });
+
+  test("shell HTML (/) działa bez tokenu i wstrzykuje token dla własnego frontu", async () => {
+    const res = await fetch(`${s.url}/`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain("__ARC_MAP_TOKEN__");
+    expect(html).toContain(TOKEN);
+  });
+});

package/use-cases/parowanie-tokenem.mdx

@@ -0,0 +1,48 @@
+---
+title: Parowanie zewnętrznego konsumenta tokenem
+description: Serwer mapy chroni /api/* tokenem parowania; zewnętrzna aplikacja (np. BMF) wysyła go w nagłówku X-Arc-Map-Token
+order: 1
+---
+
+## Cel
+
+Zamknąć API serwera mapy (kontekst + kod źródłowy przez `/api/source`) przed
+obcymi stronami w przeglądarce dewelopera, a jednocześnie dać zewnętrznym
+konsumentom (BMF) prosty sposób podłączenia się: token wypisany w konsoli
+(wzór Jupyter).
+
+## Aktorzy
+
+- **Deweloper** — uruchamia `arc platform dev --map`, wkleja token w BMF.
+- **Zewnętrzny konsument (BMF)** — fetchuje `/api/map`, `/api/source`,
+  `/api/use-cases`, SSE `/api/reload-stream` z tokenem.
+- **Obca strona w przeglądarce** — bez tokenu dostaje 401.
+
+## Przepływ kroków
+
+<Step id="start" title="Start serwera z tokenem">
+Deweloper uruchamia `arc platform dev --map`. CLI generuje token parowania
+(`ARC_MAP_TOKEN` w env → token stały) i wypisuje go w konsoli obok adresu mapy.
+Serwer dostaje `authToken` oraz `meta` (nazwa + wersja aplikacji z root
+`package.json`, `schemaVersion` kontraktu MapJson).
+</Step>
+
+<Step id="wlasny-front" title="Własny front mapy działa bez zmian">
+Shell HTML (serwowany tylko lokalnie) niesie wstrzyknięty
+`window.__ARC_MAP_TOKEN__`; helper `apiFetch` dokłada nagłówek
+`X-Arc-Map-Token`, a `EventSource` dostaje token w query (`sseUrl`).
+</Step>
+
+<Step id="konsument" title="Parowanie zewnętrznego konsumenta">
+Deweloper wkleja adres i token w BMF. Konsument wysyła
+`X-Arc-Map-Token` na każde `/api/*`; preflight OPTIONS przechodzi bez tokenu
+i odpowiada nagłówkami CORS + `Access-Control-Allow-Private-Network: true`
+(Chrome PNA dla https→localhost). `GET /api/map` zwraca `meta` — konsument
+waliduje `schemaVersion` i pokazuje nazwę aplikacji.
+</Step>
+
+<Step id="odmowa" title="Odmowa bez tokenu">
+Request na `/api/*` bez tokenu lub ze złym tokenem dostaje **401 z nagłówkami
+CORS** — konsument odróżnia „zły token" od „serwer nie żyje" (network error).
+Strony spoza parowania nie odczytają mapy ani kodu źródłowego.
+</Step>