@manta-eu/horns-server 0.1.0 → 0.1.1

package/dist/action-plan-routes.js

@@ -57,7 +57,6 @@ export function actionPlanRoutes() {
         // Read as the viewer, so a plan they cannot see is a plan that is not there.
         try {
             const found = await agentsSparqlSelect({
-                requestUrl: c.req.raw.url,
                 agentsUrl: c.env.MANTA_AGENTS_URL,
                 session: authorized.session,
                 datastoreId,

package/dist/agents-proxy.d.ts

@@ -15,7 +15,7 @@ export type AgentsGraphqlResult = {
     status: number;
     error: string;
 };
-export declare function agentsGraphql(caller: AgentsCaller, query: string, variables: Record<string, unknown>, field: string): Promise<AgentsGraphqlResult>;
+export declare function agentsGraphql(caller: AgentsCaller, query: string, variables: Record<string, unknown>, field: string, signal?: AbortSignal): Promise<AgentsGraphqlResult>;
 export type ProxyToMantaAgentsArgs = {
     request: Request;
     agentsUrl?: string;

package/dist/agents-proxy.js

@@ -9,7 +9,7 @@ export const signedOutMessage = "Not signed in — sign in to Manta to reach the
 // The one viewer-attributed GraphQL call. Both writers the worker has — staging a rule, uploading a file —
 // go through it, so a timeout or a request id is added once. `status` is carried for the caller that answers
 // with one; the caller that answers a model drops it.
-export async function agentsGraphql(caller, query, variables, field) {
+export async function agentsGraphql(caller, query, variables, field, signal) {
     if (!isPresent(caller.agentsUrl))
         return { ok: false, status: 500, error: missingAgentsUrlMessage };
     const url = agentsPathUrl(caller.agentsUrl, "/graphql");
@@ -23,6 +23,8 @@ export async function agentsGraphql(caller, query, variables, field) {
             "x-manta-datastore": caller.datastoreId,
         },
         body: JSON.stringify({ query, variables }),
+        // A read the caller walked away from should not go on costing agents the query.
+        ...(signal ? { signal } : {}),
     });
     if (response.status === 401)
         return { ok: false, status: 401, error: signedOutMessage };

package/dist/csp.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `connect-src` is the point of this. Everything else is the cheap part of the same idea.
+ *
+ * `'unsafe-eval'` is not an oversight: the written-view runtime compiles a view with `new Function`, and
+ * without it no written view draws at all. That is the trade the realm-sharing design already made, and the
+ * reason `connect-src` carries the weight here.
+ */
+export declare function contentSecurityPolicy(sentryDsn: string | undefined): string;

package/dist/csp.js

@@ -0,0 +1,41 @@
+// What the page may do, as a header.
+//
+// A written view runs in the page's own realm (ARCHITECTURE.md §9), so if its source gets past the gate and
+// the shadowed globals, this is what is left between it and somewhere to send the data. It is the only
+// layer that does not depend on reading the source.
+/**
+ * `connect-src` is the point of this. Everything else is the cheap part of the same idea.
+ *
+ * `'unsafe-eval'` is not an oversight: the written-view runtime compiles a view with `new Function`, and
+ * without it no written view draws at all. That is the trade the realm-sharing design already made, and the
+ * reason `connect-src` carries the weight here.
+ */
+export function contentSecurityPolicy(sentryDsn) {
+    const report = ingestOrigin(sentryDsn);
+    return [
+        "default-src 'self'",
+        // Styles and fonts are the design system's; images include the screenshots a Horn stores as data URLs.
+        "style-src 'self' 'unsafe-inline'",
+        "font-src 'self' data:",
+        "img-src 'self' data: blob:",
+        // Neither word is doing any work, and pretending otherwise would be worse than saying so: the realm
+        // shim is an inline script the SDK needs before anything else runs, and the written-view runtime
+        // compiles with `new Function`. `connect-src` is the directive that matters here.
+        "script-src 'self' 'unsafe-eval' 'unsafe-inline'",
+        `connect-src 'self'${report === undefined ? "" : ` ${report}`}`,
+        "object-src 'none'",
+        "base-uri 'self'",
+        "form-action 'self'",
+    ].join("; ");
+}
+/** Where the browser's Sentry posts, which is the one place off this origin the app talks to. */
+function ingestOrigin(dsn) {
+    if (dsn === undefined || dsn === "")
+        return undefined;
+    try {
+        return new URL(dsn).origin;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/datastore-access.js

@@ -1,6 +1,7 @@
 import { isPresent } from "@manta-eu/lib/present";
 import { isRecord } from "@manta-eu/horns";
 import { agentsPathUrl } from "./agents-proxy.js";
+import { CustomerDatastoresDocument } from "@manta-eu/client";
 import { upstreamCookieHeader } from "./session.js";
 export const datastoreNotGrantedMessage = "That datastore is not one this session can open.";
 export const noDatastoreMessage = "This session has no datastore to open.";
@@ -38,10 +39,47 @@ export function forgetDatastoreAccess(session) {
 function readableAccess(body) {
     const user = isRecord(body) && isRecord(body.user) ? body.user : undefined;
     const active = isRecord(user?.datastore) ? user.datastore.id : undefined;
+    const isOperator = user?.isOperator === true;
     const datastores = isRecord(body) && Array.isArray(body.datastores) ? body.datastores : [];
     const listed = datastores.flatMap((datastore) => isRecord(datastore) && typeof datastore.id === "string" ? [datastore.id] : []);
     const granted = [...new Set([...(typeof active === "string" ? [active] : []), ...listed])];
-    return { ...(typeof active === "string" ? { active } : {}), granted };
+    return { isOperator, ...(typeof active === "string" ? { active } : {}), granted };
+}
+/**
+ * The datastores an operator can reach.
+ *
+ * `/api/data/context` answers the ones a member *belongs* to, which for an operator is none — so on its own
+ * it grants them their own datastore and refuses every other, including ones agents would happily serve.
+ * This is agents' own answer to what this session can address, so it widens the grant to exactly that and
+ * no further. A failure answers nothing rather than everything.
+ */
+async function customerDatastores(env, cookie, active) {
+    if (!isPresent(env.MANTA_AGENTS_URL))
+        return [];
+    try {
+        const response = await fetch(agentsPathUrl(env.MANTA_AGENTS_URL, "/graphql"), {
+            method: "POST",
+            headers: {
+                cookie,
+                "content-type": "application/json",
+                accept: "application/json",
+                "x-manta-datastore": active,
+            },
+            body: JSON.stringify({ query: CustomerDatastoresDocument }),
+        });
+        if (!response.ok)
+            return [];
+        const body = await response.json();
+        if (!isRecord(body) || !isRecord(body.data))
+            return [];
+        const listed = body.data.customerDatastores;
+        if (!Array.isArray(listed))
+            return [];
+        return listed.flatMap((entry) => (isRecord(entry) && typeof entry.id === "string" ? [entry.id] : []));
+    }
+    catch {
+        return [];
+    }
 }
 // Agents authenticates SPARQL updates with the shared PSK and takes the datastore from the path, so
 // nothing upstream checks that the caller was granted it. This lookup is that check.
@@ -65,7 +103,10 @@ export async function datastoreAccessFor(env, session) {
         return { ok: false, reason: denied ? "unauthenticated" : "unavailable" };
     }
     const body = await response.json().catch(() => undefined);
-    const access = readableAccess(body);
+    const { isOperator, ...read } = readableAccess(body);
+    // An operator's reach is the customer list, which costs a second call — so only they pay for it.
+    const reach = isOperator && isPresent(read.active) ? await customerDatastores(env, cookie, read.active) : [];
+    const access = { ...read, granted: [...new Set([...read.granted, ...reach])] };
     rememberAccess(cookie, access);
     return { ok: true, access };
 }

package/dist/horn-routes.js

@@ -1,13 +1,17 @@
 import { Hono } from "hono";
 import { z } from "zod";
 import { isPresent } from "@manta-eu/lib/present";
-import { contentHash, deskolemize, hornBySlugQuery, hornsInDatastoreQuery, itemLookup, libraryItemsQuery, readItemRevisions, hornFromTriples, hornSchema, isRealm, hornRevisionIri, hornToTriples, legacyRevisionTriples, iri, mintHornIri, revisionReadQuery, revisionSaveUpdate, screenshotSaveUpdate, skolemize, verifyLock, sourceOf, triplesOfResults, } from "@manta-eu/horns";
+import { contentHash, deskolemize, hornBySlugQuery, hornsAboutQuery, hornsInDatastoreQuery, itemLookup, libraryItemsQuery, readItemRevisions, hornFromTriples, hornSchema, isAbsoluteIri, isRealm, hornRevisionIri, maxTsxSource, hornToTriples, legacyRevisionTriples, iri, mintHornIri, revisionReadQuery, revisionSaveUpdate, screenshotSaveUpdate, skolemize, verifyLock, sourceOf, triplesOfResults, } from "@manta-eu/horns";
 import { buildHornSnapshot, HornSnapshotError, unreviewedMessage, unreviewedWrittenViews, } from "@manta-eu/horns/render";
 import { describeLockProblem } from "@manta-eu/horns/studio";
 import { agentsSparqlUpdate, WriteRefusedError } from "./sparql-update.js";
 import { uploadPng } from "./manta-upload.js";
 import { hornTemplatePath, renderHornDocument } from "./render-document.js";
+import { ruleCoverage, ruleHornView, ruleTitle, ruleViewId } from "@manta-eu/horns/rules";
+import { planEntitiesQuery, planNameFromIri, planStatusQuery, readPlanEntities, readPlanStatus, } from "@manta-eu/horns/render";
+import { readRules, ruleQuery, standaloneHorn } from "@manta-eu/horns/shapes";
 import { agentsSparqlSelect } from "./sparql-select.js";
+import { datastoreAccessFor, grantsDatastore } from "./datastore-access.js";
 import { authorize, parseBody, refuse } from "./authorize.js";
 // A picture of a Horn at the capture width is tens of kilobytes; past this it is not a Horn's picture.
 export const maxScreenshotBytes = 4 * 1024 * 1024;
@@ -25,11 +29,19 @@ const saveRequestSchema = z.object({
  * The realm library, read from the realm's root datastore — the one whose id is the realm name. A datastore
  * installs from it, so a pin resolves there and not here; a library that cannot be read answers no revisions,
  * which refuses a Horn that pins and leaves one that pins nothing alone.
+ *
+ * The grant is checked here rather than left to agents. This read used to travel through this worker's own
+ * `/d/:realm/sparql`, whose grant check answered 403 for a session that does not hold the realm datastore,
+ * and the `catch` below turned that into "no revisions". Over GraphQL the datastore is a header, and agents
+ * answers from the caller's own datastore instead of refusing — so without this a caller's own library items
+ * would stand in for the realm's, and a pinned Horn would verify its lock against the wrong library.
  */
 async function realmLibraryLookup(args) {
+    const resolved = await datastoreAccessFor(args.env, args.session);
+    if (!resolved.ok || !grantsDatastore(resolved.access, args.realm))
+        return () => undefined;
     try {
         const results = await agentsSparqlSelect({
-            requestUrl: args.requestUrl,
             agentsUrl: args.env.MANTA_AGENTS_URL,
             session: args.session,
             datastoreId: args.realm,
@@ -39,7 +51,6 @@ async function realmLibraryLookup(args) {
     catch {
         return () => undefined;
     }
-    void args.datastoreId;
 }
 function hornMismatch(horn, datastoreId, env) {
     if (horn.datastoreId !== datastoreId)
@@ -79,7 +90,6 @@ export function hornRoutes(deps = {}) {
             const snapshot = await buildHornSnapshot({
                 horn: args.body.horn,
                 select: agentsSparqlSelect({
-                    requestUrl: args.request.url,
                     agentsUrl: args.env.MANTA_AGENTS_URL,
                     session: args.session,
                     datastoreId: args.datastoreId,
@@ -96,6 +106,20 @@ export function hornRoutes(deps = {}) {
             throw caught;
         }
     };
+    /**
+     * The Horn a revision row names, read whole.
+     *
+     * Shared by the slug lookup and the `about` one: the row differs, the reading does not.
+     */
+    const hornAtRevision = async (args) => {
+        const answer = await args.select(revisionReadQuery(args.realm, args.revision), undefined);
+        const stored = triplesOfResults(answer.results.bindings);
+        // A revision is rooted at itself. One saved before that was rooted at the Horn, which its other
+        // revisions share, so what that root says about other revisions is set aside before it is read.
+        const horn = hornFromTriples(sourceOf(deskolemize(stored, args.revision)), iri(args.revision), args.hornIri) ??
+            hornFromTriples(sourceOf(deskolemize(legacyRevisionTriples(stored, { root: args.hornIri, revision: args.revision, number: args.number }), args.revision)), iri(args.hornIri));
+        return isPresent(horn) ? { horn, stored } : undefined;
+    };
     // What this datastore holds. Without it nothing can show a Horn without already knowing its slug.
     routes.get("/api/d/:datastoreId/horns", async (c) => {
         const datastoreId = c.req.param("datastoreId");
@@ -107,7 +131,6 @@ export function hornRoutes(deps = {}) {
             return refuse(500, "This deployment has no realm configured.").response;
         try {
             const found = await agentsSparqlSelect({
-                requestUrl: c.req.raw.url,
                 agentsUrl: c.env.MANTA_AGENTS_URL,
                 session: authorized.session,
                 datastoreId,
@@ -148,7 +171,6 @@ export function hornRoutes(deps = {}) {
         if (!isPresent(realm) || !isRealm(realm))
             return refuse(500, "This deployment has no realm configured.").response;
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session: authorized.session,
             datastoreId,
@@ -161,17 +183,17 @@ export function hornRoutes(deps = {}) {
             const hornIri = row?.["horn"]?.value;
             if (!isPresent(revision) || !isPresent(hornIri))
                 return refuse(404, `No Horn here is called "${slug}".`).response;
-            const answer = await select(revisionReadQuery(realm, revision), undefined);
-            const stored = triplesOfResults(answer.results.bindings);
-            // A revision is rooted at itself. One saved before that was rooted at the Horn, which its other revisions
-            // share, so what that root says about other revisions is set aside before it is read.
-            const number = Number(row?.["number"]?.value);
-            const horn = hornFromTriples(sourceOf(deskolemize(stored, revision)), iri(revision), hornIri) ??
-                hornFromTriples(sourceOf(deskolemize(legacyRevisionTriples(stored, { root: hornIri, revision, number }), revision)), iri(hornIri));
+            const read = await hornAtRevision({
+                select,
+                realm,
+                hornIri,
+                revision,
+                number: Number(row?.["number"]?.value),
+            });
             // A revision that holds no Horn is a bug in whatever wrote it, not a missing Horn.
-            if (!isPresent(horn))
+            if (read === undefined)
                 return refuse(500, `Revision ${revision} of "${slug}" is not a Horn.`).response;
-            return Response.json({ horn, revision, contentHash: await contentHash(stored) }, { headers: noStore });
+            return Response.json({ horn: read.horn, revision, contentHash: await contentHash(read.stored) }, { headers: noStore });
         }
         catch (caught) {
             return refuse(502, caught instanceof Error ? caught.message : String(caught)).response;
@@ -192,7 +214,6 @@ export function hornRoutes(deps = {}) {
             return body.response;
         const slug = c.req.param("slug");
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session: authorized.session,
             datastoreId,
@@ -225,7 +246,6 @@ export function hornRoutes(deps = {}) {
             // resolved IRI is the root, not whatever the body claimed, because the route owns the IRI.
             const locked = verifyLock(hornIri, body.data.horn.dependencies, body.data.horn.lock, deps.libraryLookup ??
                 (await realmLibraryLookup({
-                    requestUrl: c.req.raw.url,
                     env: c.env,
                     session: authorized.session,
                     datastoreId,
@@ -262,6 +282,266 @@ export function hornRoutes(deps = {}) {
             return refuse(502, caught instanceof Error ? caught.message : String(caught)).response;
         }
     });
+    /**
+     * A Horn built from a rule, for a thing nobody has curated one for.
+     *
+     * The rule already describes a view — its body is a query — so this is the same construction the rules
+     * page does in the browser, run here instead. Nothing is saved: it is a document to draw, and `about`
+     * says what it answers for so a curated one can replace it later.
+     */
+    /**
+     * What to call a Horn nobody named.
+     *
+     * A rule is named as a condition — "Name off convention" — which reads as a rule and not as a page. This
+     * says what the page is of. A first pass: worth judging against a real list of rules rather than here.
+     */
+    const nameForRule = (spec) => spec.kind === "plan" ? `${spec.title}: what it would change` : `${spec.title}: what it flags`;
+    /** What a refusal may take up in the view before the rule itself does. */
+    const maxRuleWhy = 400;
+    /** The longest body that still leaves `source` inside `maxTsxSource`, with an ellipsis when it was cut. */
+    const fitted = (body, budget) => {
+        if (JSON.stringify(body).length <= budget)
+            return body;
+        let text = body;
+        while (text.length > 1 && JSON.stringify(`${text}…`).length > budget) {
+            text = text.slice(0, Math.max(1, Math.ceil(text.length * 0.9) - 1));
+        }
+        return `${text}…`;
+    };
+    /**
+     * A short, stable key for a thing, for the one place a built Horn needs a kebab id.
+     *
+     * Derived, not read: the IRI goes in whole and comes out as a number, so nothing here depends on an IRI
+     * having parts (AGENTS.md §IRIs are opaque). Two things collide only if they hash alike.
+     */
+    const opaqueId = (iri) => {
+        let hash = 0x811c9dc5;
+        for (let at = 0; at < iri.length; at += 1) {
+            hash = Math.imul(hash ^ iri.charCodeAt(at), 0x01000193) >>> 0;
+        }
+        return hash.toString(36);
+    };
+    /** A view that shows the rule itself, for a rule there is no drawing. */
+    const datalogView = (rule, said) => {
+        const why = said.length > maxRuleWhy ? `${said.slice(0, maxRuleWhy)}…` : said;
+        const sourceFor = (body) => [
+            'import { Separator } from "@manta-eu/react";',
+            "",
+            "const muted = { opacity: 0.7 };",
+            "",
+            "export default function View() {",
+            "  return (",
+            '    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>',
+            `      <p style={{ ...muted, margin: 0, fontSize: 14 }}>{${JSON.stringify(why)}}</p>`,
+            "      <Separator />",
+            "      <pre",
+            "        style={{",
+            "          ...muted,",
+            "          margin: 0,",
+            '          overflow: "auto",',
+            '          fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",',
+            "          fontSize: 12,",
+            '          whiteSpace: "pre-wrap",',
+            "        }}",
+            "      >",
+            `        {${JSON.stringify(body)}}`,
+            "      </pre>",
+            "    </div>",
+            "  );",
+            "}",
+        ].join("\n");
+        return {
+            // Per rule, because `standaloneHorn` makes the Horn's IRI and slug out of this: two rules with no
+            // view would otherwise be the same Horn, which is what naming them apart was for.
+            id: ruleViewId(rule.iri),
+            title: "The rule itself",
+            // Safe to write: the route checked the IRI before anything was built for it.
+            binding: {
+                kind: "select",
+                sparql: `SELECT ?this WHERE { VALUES ?this { <${rule.iri}> } }`,
+                params: [],
+                limit: 1,
+                derivations: [],
+                columns: [{ name: "this", type: "iri" }],
+            },
+            // A rule is as long as somebody wrote it, and a hand-drafted plan rule is pages; the schema caps the
+            // source, so what is shown is cut to fit rather than answered with a Horn nothing will parse.
+            render: { kind: "tsx", source: sourceFor(fitted(rule.body, Math.max(2, maxTsxSource - sourceFor("").length))) },
+        };
+    };
+    /**
+     * A Horn built from a rule, for a rule nobody has curated one for.
+     *
+     * A rule whose body translates to a query describes its own view, and that is the Horn. One whose body
+     * does not — the parser could not read it, or it mints IRIs with `SKOLEM`, which a query cannot ask for —
+     * gets a Horn that says so and shows the Datalog. A card that opens on an explanation is worth more than
+     * one that opens on a 404, and the caller does not have to know the difference.
+     */
+    const hornForRule = async (args) => {
+        const rules = readRules(await args.select(ruleQuery(args.realm, args.about), undefined));
+        const entry = ruleCoverage({ rules, realm: args.realm }).entries.find((one) => one.rule.iri === args.about);
+        if (entry === undefined)
+            return undefined;
+        const drawn = entry.spec === undefined ? undefined : ruleHornView(entry.spec);
+        const view = drawn ??
+            datalogView(entry.rule, entry.issues?.[0] ??
+                "Its body does not translate to a query, so there is nothing to draw from it — the rule is below.");
+        // Named after the rule either way: a Horn's address is made from its title, so two Horns built for two
+        // rules must not arrive at the same words.
+        const title = entry.spec === undefined ? `${ruleTitle(entry.rule.iri, undefined)}: the rule itself` : nameForRule(entry.spec);
+        return {
+            ...standaloneHorn({
+                id: view.id,
+                title,
+                views: [view],
+                realm: args.realm,
+                datastoreId: args.datastoreId,
+            }),
+            about: [args.about],
+        };
+    };
+    /** What the graph calls a plan, when it calls it anything. A name is a nicety and never fails the Horn. */
+    const planName = async (args) => {
+        try {
+            const status = readPlanStatus(await args.select(planStatusQuery(args.realm, [args.plan]), undefined));
+            return status.get(args.plan)?.name;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const hornForPlan = async (args) => {
+        // The things the plan carries an action shape for, which is what a plan concerns — not the rows that
+        // survive `readPlanValues`, which drops a value that already holds and one pointing at another thing.
+        // The same query refuses a run's copy of a plan, so a record of a run does not get a Horn.
+        const entities = readPlanEntities(await args.select(planEntitiesQuery(args.realm, args.about), undefined));
+        if (entities.length === 0)
+            return undefined;
+        // The graph names almost no plan, so this is mostly the name agents shows — which is also what keeps
+        // two plans from arriving at one title, and so at one slug.
+        const name = (await planName({ select: args.select, realm: args.realm, plan: args.about })) ?? planNameFromIri(args.about);
+        const view = {
+            id: "suggested-changes",
+            title: "Suggested changes",
+            // `readPlanEntities` answers with IRIs that can be written into a query and nothing else.
+            binding: {
+                kind: "select",
+                sparql: `SELECT ?this WHERE { VALUES ?this { ${entities.map((one) => `<${one}>`).join(" ")} } }`,
+                params: [],
+                limit: entities.length,
+                derivations: [],
+                columns: [{ name: "this", type: "iri" }],
+            },
+            render: {
+                kind: "tsx",
+                source: [
+                    'import { SuggestedChanges, usePlansBehindView } from "@manta-eu/horns-kit/plan";',
+                    'import { Nothing } from "@manta-eu/horns-kit/view";',
+                    // This Horn is about one plan. Other plans touching the same things are behind the view too, and
+                    // showing them here would put another plan's changes under this one's name.
+                    `const about = ${JSON.stringify(args.about)};`,
+                    "export default function View() {",
+                    "  const plans = usePlansBehindView().filter((plan) => plan.iri === about);",
+                    "  if (plans.length === 0) {",
+                    '    return <Nothing title="Nothing to change" hint="This plan proposes no changes right now." />;',
+                    "  }",
+                    "  return (",
+                    '    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>',
+                    "      {plans.map((plan) => (",
+                    "        <SuggestedChanges key={plan.iri} plan={plan.iri} />",
+                    "      ))}",
+                    "    </div>",
+                    "  );",
+                    "}",
+                ].join("\n"),
+            },
+        };
+        return {
+            ...standaloneHorn({
+                id: `plan-${opaqueId(args.about)}`,
+                // Named after the plan, for the same reason a rule's Horn is: the address comes from the title.
+                title: isPresent(name) ? `${name}: what it would change` : "Suggested changes",
+                views: [view],
+                realm: args.realm,
+                datastoreId: args.datastoreId,
+            }),
+            about: [args.about],
+        };
+    };
+    /**
+     * The Horn kept for a thing, by that thing's IRI.
+     *
+     * A host embedding beside a rule or an action plan holds the IRI and never a slug. `about` is a list, so
+     * several Horns can answer for one thing; the first by slug is the one, and the rest are reported so a
+     * caller can tell "one" from "one of several" rather than guessing.
+     *
+     * Two segments because one would not be safe: `about` is a legal slug, so `/horns/about` is a Horn
+     * somebody may have saved, and `/horns/:slug` would answer for it either way.
+     */
+    routes.get("/api/d/:datastoreId/horns/by/about", async (c) => {
+        const datastoreId = c.req.param("datastoreId");
+        const authorized = await authorize(c.req.raw, c.env, datastoreId);
+        if (!authorized.ok)
+            return authorized.response;
+        const realm = c.env.VITE_KEYCLOAK_REALM;
+        if (!isPresent(realm) || !isRealm(realm))
+            return refuse(500, "This deployment has no realm configured.").response;
+        // A query parameter, not a path segment: an IRI is opaque and carries slashes of its own.
+        const about = c.req.query("iri");
+        if (!isPresent(about))
+            return refuse(400, "Ask with ?iri=<the thing's IRI>.").response;
+        // Checked here rather than where it is written into a query: a caller's malformed IRI is a bad request,
+        // and refused further down it would be reported as the store having failed.
+        if (!isAbsoluteIri(about))
+            return refuse(400, `"${about}" is not an IRI.`).response;
+        const select = agentsSparqlSelect({
+            agentsUrl: c.env.MANTA_AGENTS_URL,
+            session: authorized.session,
+            datastoreId,
+        });
+        try {
+            const found = await select(hornsAboutQuery(realm, about), undefined);
+            const rows = found.results.bindings;
+            const row = rows[0];
+            const revision = row?.["revision"]?.value;
+            const hornIri = row?.["horn"]?.value;
+            const slug = row?.["slug"]?.value;
+            if (!isPresent(revision) || !isPresent(hornIri)) {
+                // Nobody has made one. A rule describes a view on its own, so one is built rather than refused —
+                // a host with an IRI gets something to draw whether or not anyone has been here before.
+                const made = (await hornForRule({ select, realm, datastoreId, about })) ??
+                    (await hornForPlan({ select, realm, datastoreId, about }));
+                return made === undefined
+                    ? refuse(404, "No Horn here says it is about that, and nothing could be built for it.").response
+                    : Response.json({ horn: made, kept: false }, { headers: noStore });
+            }
+            const read = await hornAtRevision({
+                select,
+                realm,
+                hornIri,
+                revision,
+                number: Number(row?.["number"]?.value),
+            });
+            if (read === undefined)
+                return refuse(500, `Revision ${revision} is not a Horn.`).response;
+            const others = new Set(rows.flatMap((one) => (one["horn"]?.value === undefined ? [] : [one["horn"].value]))).size - 1;
+            // `kept` on both answers, and the slug with it: a caller editing this Horn has to save it back where it
+            // is, and a caller that only learned it was built would open a second Horn about the same thing.
+            return Response.json({
+                horn: read.horn,
+                kept: true,
+                ...(isPresent(slug) ? { slug } : {}),
+                revision,
+                contentHash: await contentHash(read.stored),
+                // Horns, not rows: `DISTINCT` leaves one row per revision, and a Horn could still bring two if a
+                // revision carried two titles. What a caller is asking is how many other Horns say this.
+                ...(others > 0 ? { others } : {}),
+            }, { headers: noStore });
+        }
+        catch (caught) {
+            return refuse(502, caught instanceof Error ? caught.message : String(caught)).response;
+        }
+    });
     routes.post("/d/:datastoreId/horns/render", async (c) => {
         const datastoreId = c.req.param("datastoreId");
         const accepted = await accept(c.req.raw, c.env, datastoreId, hornRequestSchema);
@@ -309,7 +589,6 @@ export function hornRoutes(deps = {}) {
         }
         const slug = c.req.param("slug");
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session: authorized.session,
             datastoreId,

package/dist/llm.js

@@ -54,9 +54,7 @@ export function studioModelFromEnv(env, context, fetcher) {
             baseURL,
             model,
             dialect,
-            ...(dialect === "vllm" && isPresent(env.VLLM_PRIMARY_AUTH_TOKEN)
-                ? { apiKey: env.VLLM_PRIMARY_AUTH_TOKEN }
-                : {}),
+            ...(dialect === "vllm" && isPresent(env.VLLM_PRIMARY_AUTH_TOKEN) ? { apiKey: env.VLLM_PRIMARY_AUTH_TOKEN } : {}),
             gatewayToken: env.CLOUDFLARE_AI_GATEWAY_TOKEN,
             maxTokens: maxTokensOf(env.HORNS_LLM_MAX_TOKENS),
             // No user identifiers: the gateway log is shared with agents.

package/dist/manta-proxy-policy.js

@@ -39,10 +39,21 @@ export function sameOriginDeniedResponse(request) {
 }
 export const isDatastoreId = (value) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
 // The proxy's own boundary: nothing reaches agents that is not named here. There is deliberately no
-// sparql-update route — every write is built and guarded by the worker itself (ARCHITECTURE.md §11) — and no
-// GraphQL route: the worker calls the one mutation Horns needs, running an action plan, itself.
+// sparql-update route — every write is built and guarded by the worker itself (ARCHITECTURE.md §11).
+//
+// `/graphql` and `/sparql` are the SDK's own endpoints, which the browser now reaches as the viewer: the
+// GraphQL client posts to the first and LDkit to the second, both against this worker's origin because the
+// browser holds its cookies and none of agents'. Neither names a datastore in its path — agents takes it from
+// `x-manta-datastore` — so the route handlers check the grant themselves rather than trusting the header, or a
+// caller could name another datastore and be quietly answered from their own.
+//
+// `/graphql` is not filtered by operation. The browser can therefore reach every mutation the viewer could,
+// `executeActionPlan` among them, so the preview-then-confirm gate on a plan run is this app's manners rather
+// than a boundary the transport enforces. Do not add UI that goes around it.
 const proxyRoutes = [
     { path: "/d/:datastoreId/sparql", methods: ["POST"], params: { datastoreId: isDatastoreId }, body: "sparql" },
+    { path: "/sparql", methods: ["POST"], body: "sparql" },
+    { path: "/graphql", methods: ["POST"] },
     // Where a Horn's row links: agents resolves an entity to its platform's page. A read, and a navigation.
     { path: "/d/:datastoreId/redirect", methods: ["GET"], params: { datastoreId: isDatastoreId } },
     { path: "/login", methods: ["GET"] },

package/dist/sparql-select.d.ts

@@ -1,8 +1,10 @@
 import { type SparqlSelect } from "@manta-eu/horns";
-import type { MantaSessionState } from "./session.ts";
-export declare function agentsSparqlSelect(args: {
-    requestUrl: string;
-    agentsUrl: string | undefined;
-    session: MantaSessionState;
-    datastoreId: string;
-}): SparqlSelect;
+import { type AgentsCaller } from "./agents-proxy.ts";
+/**
+ * Server-side reads, as the viewer.
+ *
+ * The read-only check is this worker's, not agents': it is the write-authorization boundary
+ * (ARCHITECTURE.md §11), and a SELECT that is not one must not reach agents merely because it travelled as a
+ * GraphQL variable rather than a request body.
+ */
+export declare function agentsSparqlSelect(args: AgentsCaller): SparqlSelect;

package/dist/sparql-select.js

@@ -1,23 +1,22 @@
-import { sparqlResultsSchema } from "@manta-eu/horns";
-import { proxyToMantaAgents } from "./agents-proxy.js";
-// Server-side reads go through the same proxy, read-only policy and session as the browser's /d/:ds/sparql,
-// so rendering on the server can reach nothing the viewer could not query themselves.
+import { checkReadOnlySparql } from "./manta-proxy-policy.js";
+import { SparqlReadError, sparqlResultsOfGraphqlField } from "@manta-eu/horns";
+import { agentsGraphql } from "./agents-proxy.js";
+import { SparqlQueryDocument } from "@manta-eu/client";
+/**
+ * Server-side reads, as the viewer.
+ *
+ * The read-only check is this worker's, not agents': it is the write-authorization boundary
+ * (ARCHITECTURE.md §11), and a SELECT that is not one must not reach agents merely because it travelled as a
+ * GraphQL variable rather than a request body.
+ */
 export function agentsSparqlSelect(args) {
-    const origin = new URL(args.requestUrl).origin;
-    const url = `${origin}/d/${encodeURIComponent(args.datastoreId)}/sparql`;
     return async (query, signal) => {
-        const request = new Request(url, {
-            method: "POST",
-            headers: { origin, "content-type": "application/sparql-query", accept: "application/sparql-results+json" },
-            body: query,
-            ...(signal ? { signal } : {}),
-        });
-        const response = await proxyToMantaAgents({ request, agentsUrl: args.agentsUrl, session: args.session });
-        if (!response.ok) {
-            const detail = (await response.text().catch(() => "")).slice(0, 200);
-            throw new Error(`Manta answered ${response.status}${detail ? `: ${detail}` : ""}`);
-        }
-        const body = await response.json();
-        return sparqlResultsSchema.parse(body);
+        const verdict = checkReadOnlySparql(query);
+        if (!verdict.ok)
+            throw new SparqlReadError(verdict.error);
+        const answer = await agentsGraphql(args, SparqlQueryDocument, { query }, "sparqlQuery", signal);
+        if (!answer.ok)
+            throw new SparqlReadError(answer.error);
+        return sparqlResultsOfGraphqlField(answer.value);
     };
 }

package/dist/studio-routes.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { type Realm } from "@manta-eu/horns";
+import { type ComponentApiLookup, type TypeProblem } from "@manta-eu/horns/studio";
 import { type Shape } from "@manta-eu/horns/shapes";
 import { type StudioModelEnv, type StudioModelResult } from "./llm.ts";
 import { type DevSessionEnv } from "./dev-session.ts";
@@ -10,6 +11,10 @@ export type StudioRoutesEnv = DevSessionEnv & StudioModelEnv & {
 export type StudioRoutesDeps<Env extends StudioRoutesEnv> = {
     /** The realm's SHACL shapes, which is what a turn reads classes from. Absent shapes answer no classes. */
     shapes: (realm: Realm) => readonly Shape[];
+    /** The surfaced components' declarations, read at build time. Absent, `read_component_api` is not offered. */
+    componentApi?: ComponentApiLookup;
+    /** A compiler over a written view. Absent, a proposal is judged on its shape alone. */
+    typecheck?: (source: string) => readonly TypeProblem[];
     /** Overridden by tests with a scripted model; the deployment builds Qwen through the AI Gateway. */
     model?: (env: Env, context: {
         feature: string;

package/dist/studio-routes.js

@@ -123,7 +123,6 @@ export function studioRoutes(deps) {
         if (!model.ok)
             return c.json({ error: model.reason }, 503);
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session,
             datastoreId,
@@ -166,6 +165,7 @@ export function studioRoutes(deps) {
                         shapes,
                         views: shapeViewSpecs,
                         model: model.model,
+                        ...(deps.componentApi ? { componentApi: deps.componentApi } : {}),
                         // The investigation is a loop of its own; without this it is one line that takes a minute.
                         onEvent: (event) => emit({ type: "progress", event }),
                     }),
@@ -174,6 +174,7 @@ export function studioRoutes(deps) {
                         select,
                         catalog: mantaReactCatalog,
                         lookup: () => undefined,
+                        ...(deps.typecheck ? { typecheck: deps.typecheck } : {}),
                         // As the viewer: staging a rule is attributed to a person, and agents refuses it otherwise.
                         stageRule: (rule) => stageRule({ agentsUrl: c.env.MANTA_AGENTS_URL, session, datastoreId }, rule),
                     }),
@@ -238,7 +239,6 @@ export function studioRoutes(deps) {
             return c.json({ error: `This Horn belongs to the "${horn.datastoreId}" datastore.` }, 400);
         }
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session,
             datastoreId,
@@ -275,7 +275,6 @@ export function studioRoutes(deps) {
         // a shape's card is drawn by a browser now, and a coverage run has none.
         const critic = deps.criticModel?.(c.env, { feature: "shape-critic", datastoreId });
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session,
             datastoreId,
@@ -339,7 +338,6 @@ export function studioRoutes(deps) {
         if (!model.ok)
             return c.json({ error: model.reason }, 503);
         const select = agentsSparqlSelect({
-            requestUrl: c.req.raw.url,
             agentsUrl: c.env.MANTA_AGENTS_URL,
             session,
             datastoreId,

package/dist/typecheck.d.ts

@@ -0,0 +1,10 @@
+import type { TypeProblem } from "@manta-eu/horns/studio";
+/** Every `.d.ts` the check needs, keyed by the path the compiler should find it at. */
+export type TypecheckFs = Readonly<Record<string, string>>;
+/**
+ * A check over one view's source, reusing the parsed library across calls.
+ *
+ * Every `.d.ts` is parsed once and kept: a turn checks a view several times, and re-reading four megabytes
+ * of declarations each time is the whole cost.
+ */
+export declare function createTypecheck(fs: TypecheckFs): (source: string) => readonly TypeProblem[];

package/dist/typecheck.js

@@ -0,0 +1,67 @@
+import ts from "typescript";
+const viewPath = "/view.tsx";
+const options = {
+    jsx: ts.JsxEmit.ReactJSX,
+    strict: true,
+    noEmit: true,
+    // The SDK's own typings are not ours to police, and checking them costs more than the view does.
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2022,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    // Without this every `@types/*` package in the tree is pulled in, and none of them is the view's business.
+    types: [],
+};
+/**
+ * A check over one view's source, reusing the parsed library across calls.
+ *
+ * Every `.d.ts` is parsed once and kept: a turn checks a view several times, and re-reading four megabytes
+ * of declarations each time is the whole cost.
+ */
+export function createTypecheck(fs) {
+    const parsed = new Map();
+    const paths = new Set(Object.keys(fs));
+    return (source) => {
+        const files = { ...fs, [viewPath]: source };
+        const host = {
+            fileExists: (path) => path === viewPath || paths.has(path),
+            readFile: (path) => files[path],
+            directoryExists: (path) => {
+                const prefix = path.endsWith("/") ? path : `${path}/`;
+                return [...paths].some((one) => one.startsWith(prefix));
+            },
+            getDirectories: () => [],
+            realpath: (path) => path,
+            getSourceFile: (path, language) => {
+                if (path !== viewPath) {
+                    const already = parsed.get(path);
+                    if (already !== undefined)
+                        return already;
+                }
+                const text = files[path];
+                if (text === undefined)
+                    return undefined;
+                const file = ts.createSourceFile(path, text, language, true);
+                if (path !== viewPath)
+                    parsed.set(path, file);
+                return file;
+            },
+            getDefaultLibFileName: () => "/lib.es2022.full.d.ts",
+            writeFile: () => { },
+            getCurrentDirectory: () => "/",
+            getCanonicalFileName: (path) => path,
+            useCaseSensitiveFileNames: () => true,
+            getNewLine: () => "\n",
+        };
+        const program = ts.createProgram([viewPath], options, host);
+        const view = program.getSourceFile(viewPath);
+        if (view === undefined)
+            return [];
+        return [...program.getSemanticDiagnostics(view), ...program.getSyntacticDiagnostics(view)].map((diagnostic) => {
+            const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, " ");
+            if (diagnostic.start === undefined)
+                return { message };
+            const { line } = view.getLineAndCharacterOfPosition(diagnostic.start);
+            return { message, line: line + 1 };
+        });
+    };
+}

package/dist/worker.d.ts

@@ -2,12 +2,12 @@ import { Hono } from "hono";
 import type { Env } from "./env.ts";
 import { type StudioRoutesDeps } from "./studio-routes.ts";
 export type { Env };
-export type HornsWorkerOptions = Pick<StudioRoutesDeps<Env>, "shapes"> & Partial<Pick<StudioRoutesDeps<Env>, "criticModel">>;
+export type HornsWorkerOptions = Pick<StudioRoutesDeps<Env>, "shapes" | "componentApi" | "typecheck"> & Partial<Pick<StudioRoutesDeps<Env>, "criticModel">>;
 /**
  * The Horns worker as a Hono app. `shapes` is the host's: the catalog describes a realm's data model, so
  * Horns takes it rather than shipping one.
  */
-export declare function createHornsApp({ shapes, criticModel }: HornsWorkerOptions): Hono<{
+export declare function createHornsApp({ shapes, componentApi, typecheck, criticModel, }: HornsWorkerOptions): Hono<{
     Bindings: Env;
 }, import("hono/types").BlankSchema, "/">;
 /** The same app behind Sentry, ready to be a Worker's default export. */

package/dist/worker.js

@@ -7,6 +7,7 @@ import { datastoreAccessFor, datastoreAccessUnavailableMessage, datastoreNotGran
 import { hornRoutes } from "./horn-routes.js";
 import { actionPlanRoutes } from "./action-plan-routes.js";
 import { studioRoutes } from "./studio-routes.js";
+import { contentSecurityPolicy } from "./csp.js";
 import { criticModelFromEnv } from "./llm.js";
 import { requestSession } from "./dev-session.js";
 import { asJsonRequest, followedLink, noPageToOpen, signInFirst } from "./entity-links.js";
@@ -16,8 +17,20 @@ import { sentryOptionsForDeploy } from "./sentry.js";
  * The Horns worker as a Hono app. `shapes` is the host's: the catalog describes a realm's data model, so
  * Horns takes it rather than shipping one.
  */
-export function createHornsApp({ shapes, criticModel = criticModelFromEnv }) {
+export function createHornsApp({ shapes, componentApi, typecheck, criticModel = criticModelFromEnv, }) {
     const app = new Hono();
+    // On the document only: a JSON answer nobody renders has nothing to protect, and the header is not small.
+    app.use("*", async (c, next) => {
+        await next();
+        if (c.res.headers.get("content-type")?.includes("text/html") !== true)
+            return;
+        // Rebuilt rather than mutated: what `ASSETS` hands back carries immutable headers.
+        const headers = new Headers(c.res.headers);
+        headers.set("content-security-policy", contentSecurityPolicy(c.env.SENTRY_DSN));
+        headers.set("x-content-type-options", "nosniff");
+        headers.set("referrer-policy", "same-origin");
+        c.res = new Response(c.res.body, { status: c.res.status, statusText: c.res.statusText, headers });
+    });
     app.use("*", async (c, next) => {
         if (import.meta.env.DEV)
             return next();
@@ -106,8 +119,12 @@ export function createHornsApp({ shapes, criticModel = criticModelFromEnv }) {
         return new Request(request.url, init);
     }
     // Agents answers a read for a datastore the caller lacks from the caller's own datastore instead of
-    // refusing, so the path means what it says only if the session's grants are what decided it.
-    app.post("/d/:datastoreId/sparql", async (c) => {
+    // refusing, so a datastore the caller *names* means what it says only if the session's grants decided it.
+    //
+    // A request naming none is let through: it claims nothing to be mislabelled, and agents scopes it to the
+    // session's own datastore, which is the caller's to read. The session itself is asked for this way — on a
+    // page with no datastore chosen there is nothing to name yet.
+    async function proxyForGrantedDatastore(c, datastoreId) {
         const denied = sameOriginDeniedResponse(c.req.raw);
         if (denied)
             return denied;
@@ -120,12 +137,18 @@ export function createHornsApp({ shapes, criticModel = criticModelFromEnv }) {
                 return c.json({ error: signedOutMessage }, 401);
             return c.json({ error: datastoreAccessUnavailableMessage }, 502);
         }
-        if (!grantsDatastore(resolved.access, c.req.param("datastoreId"))) {
+        if (isPresent(datastoreId) && !grantsDatastore(resolved.access, datastoreId)) {
             forgetDatastoreAccess(session);
             return c.json({ error: datastoreNotGrantedMessage }, 403);
         }
         return proxyRequest(c, withoutTrustHeaders(c.req.raw));
-    });
+    }
+    app.post("/d/:datastoreId/sparql", (c) => proxyForGrantedDatastore(c, c.req.param("datastoreId")));
+    // The SDK's own two endpoints, which the browser reaches as the viewer. Neither names a datastore in its
+    // path — the client sends `x-manta-datastore`, and sends none before one is chosen.
+    const datastoreHeader = (c) => c.req.header("x-manta-datastore");
+    app.post("/sparql", (c) => proxyForGrantedDatastore(c, datastoreHeader(c)));
+    app.post("/graphql", (c) => proxyForGrantedDatastore(c, datastoreHeader(c)));
     // A link from a Horn's row to the thing it shows, opened as the viewer in a new tab.
     app.get("/d/:datastoreId/redirect", async (c) => {
         const datastoreId = c.req.param("datastoreId");
@@ -149,7 +172,12 @@ export function createHornsApp({ shapes, criticModel = criticModelFromEnv }) {
     });
     app.route("/", hornRoutes());
     app.route("/", actionPlanRoutes());
-    app.route("/", studioRoutes({ shapes, criticModel }));
+    app.route("/", studioRoutes({
+        shapes,
+        criticModel,
+        ...(componentApi ? { componentApi } : {}),
+        ...(typecheck ? { typecheck } : {}),
+    }));
     app.all("*", (c) => c.env.ASSETS.fetch(c.req.raw));
     app.onError((err, c) => {
         captureException(err, { tags: { path: c.req.routePath, method: c.req.method } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manta-eu/horns-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The Manta Horns worker as a library: Hono routes a Cloudflare host mounts on its own app.",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,10 @@
     "./llm": {
       "types": "./dist/llm.d.ts",
       "default": "./dist/llm.js"
+    },
+    "./typecheck": {
+      "types": "./dist/typecheck.d.ts",
+      "default": "./dist/typecheck.js"
     }
   },
   "publishConfig": {
@@ -36,15 +40,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@manta-eu/lib": "0.1.4",
+    "@manta-eu/client": "0.1.5",
+    "@manta-eu/lib": "0.1.5",
     "@sentry/cloudflare": "^10.70.0",
     "@sentry/core": "^10.70.0",
     "hono": "^4.9.8",
-    "ldkit": "2.8.0",
+    "ldkit": "2.9.0",
     "sparqljs": "^3.7.4",
+    "typescript": "^5.9.0",
     "zod": "^4.5.4",
-    "@manta-eu/horns": "0.1.0",
-    "@manta-eu/horns-kit": "0.1.0"
+    "@manta-eu/horns": "0.1.1",
+    "@manta-eu/horns-kit": "0.1.1"
   },
   "devDependencies": {
     "@cloudflare/vite-plugin": "1.47.0",