@manta-eu/horns-server 0.1.0

package/dist/session.js

@@ -0,0 +1,166 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { isRecord } from "@manta-eu/horns";
+export const agentsJwtCookieName = "auth";
+export const sessionCookiePrefix = "mh_session";
+export const maxSessionCookieChunks = 8;
+const chunkSize = 3500;
+// RFC 6265 token and cookie-octets: a stored pair can never add a `;` and smuggle a second cookie upstream.
+const cookieNamePattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const cookieValuePattern = /^(?:[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*|"[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*")$/;
+export function isForwardableCookie(name, value) {
+    return cookieNamePattern.test(name) && cookieValuePattern.test(value);
+}
+export function parseCookieHeader(header) {
+    const jar = {};
+    if (!isPresent(header))
+        return jar;
+    for (const pair of header.split(";")) {
+        const index = pair.indexOf("=");
+        if (index <= 0)
+            continue;
+        const name = pair.slice(0, index).trim();
+        if (!isPresent(name))
+            continue;
+        jar[name] = pair.slice(index + 1).trim();
+    }
+    return jar;
+}
+export function serializeCookie(name, value, attributes) {
+    const parts = [`${name}=${value}`, "Path=/", "HttpOnly", "SameSite=Lax"];
+    if (attributes.secure)
+        parts.push("Secure");
+    if (attributes.maxAge !== undefined)
+        parts.push(`Max-Age=${attributes.maxAge}`);
+    return parts.join("; ");
+}
+export function requestIsSecure(requestUrl) {
+    return new URL(requestUrl).protocol === "https:";
+}
+function encodeJson(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeJson(encoded) {
+    const padded = encoded.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (encoded.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+function chunk(value) {
+    const chunks = [];
+    for (let i = 0; i < value.length; i += chunkSize)
+        chunks.push(value.slice(i, i + chunkSize));
+    return chunks;
+}
+export function sessionSetCookies(state, attributes) {
+    const chunks = chunk(encodeJson(state));
+    if (chunks.length > maxSessionCookieChunks) {
+        throw new Error(`Horns session does not fit in ${maxSessionCookieChunks} cookies.`);
+    }
+    const written = chunks.map((value, index) => serializeCookie(`${sessionCookiePrefix}${index}`, value, attributes));
+    const cleared = Array.from({ length: maxSessionCookieChunks - chunks.length }, (_unused, offset) => serializeCookie(`${sessionCookiePrefix}${chunks.length + offset}`, "", { ...attributes, maxAge: 0 }));
+    return [...written, ...cleared];
+}
+export function clearSessionSetCookies(attributes) {
+    return Array.from({ length: maxSessionCookieChunks }, (_unused, index) => serializeCookie(`${sessionCookiePrefix}${index}`, "", { ...attributes, maxAge: 0 }));
+}
+export function readSessionState(cookieHeader) {
+    const jar = parseCookieHeader(cookieHeader);
+    let encoded = "";
+    for (let index = 0; index < maxSessionCookieChunks; index += 1) {
+        const part = jar[`${sessionCookiePrefix}${index}`];
+        if (!isPresent(part))
+            break;
+        encoded += part;
+    }
+    if (!isPresent(encoded))
+        return undefined;
+    let parsed;
+    try {
+        parsed = decodeJson(encoded);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    const candidate = parsed.upstreamCookies;
+    if (!isRecord(candidate))
+        return undefined;
+    const upstreamCookies = Object.fromEntries(Object.entries(candidate).flatMap(([name, value]) => typeof value === "string" && isForwardableCookie(name, value) ? [[name, value]] : []));
+    if (!isPresent(Object.keys(upstreamCookies)))
+        return undefined;
+    return { upstreamCookies };
+}
+export function isSignedIn(state) {
+    return isPresent(state) && isPresent(state.upstreamCookies[agentsJwtCookieName]);
+}
+export function upstreamCookieHeader(state) {
+    return Object.entries(state.upstreamCookies)
+        .filter(([name, value]) => isForwardableCookie(name, value))
+        .map(([name, value]) => `${name}=${value}`)
+        .join("; ");
+}
+export function setCookieHeadersOf(response) {
+    const { headers } = response;
+    if (typeof headers.getSetCookie === "function")
+        return headers.getSetCookie();
+    const single = headers.get("set-cookie");
+    return isPresent(single) ? [single] : [];
+}
+function attributeExpiresCookie(attribute, now) {
+    const index = attribute.indexOf("=");
+    if (index <= 0)
+        return false;
+    const name = attribute.slice(0, index).trim().toLowerCase();
+    const value = attribute.slice(index + 1).trim();
+    if (name === "max-age") {
+        const seconds = Number(value);
+        return isPresent(value) && Number.isFinite(seconds) && seconds <= 0;
+    }
+    if (name === "expires") {
+        const at = Date.parse(value);
+        return Number.isFinite(at) && at <= now;
+    }
+    return false;
+}
+export function captureUpstreamCookies(state, response, now = Date.now()) {
+    const jar = { ...state.upstreamCookies };
+    let changed = false;
+    for (const header of setCookieHeadersOf(response)) {
+        const [pair = "", ...attributes] = header.split(";");
+        const index = pair.indexOf("=");
+        if (index <= 0)
+            continue;
+        const name = pair.slice(0, index).trim();
+        const value = pair.slice(index + 1).trim();
+        if (!isForwardableCookie(name, value))
+            continue;
+        const expired = attributes.some((attribute) => attributeExpiresCookie(attribute, now));
+        if (expired || !isPresent(value)) {
+            if (name in jar) {
+                delete jar[name];
+                changed = true;
+            }
+            continue;
+        }
+        if (jar[name] !== value) {
+            jar[name] = value;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return state;
+    return { upstreamCookies: jar };
+}
+function fingerprint(state) {
+    return JSON.stringify(Object.entries(state.upstreamCookies).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function sessionsDiffer(before, after) {
+    return fingerprint(before) !== fingerprint(after);
+}

package/dist/shared.d.ts

@@ -0,0 +1,4 @@
+export { signedInParam } from "./auth-params.ts";
+export { onlyDiagnosticExtra, withoutPiiErrorEvent } from "./pii.ts";
+export { redactedUrl, redactShareTokens } from "./redact.ts";
+export { readNdjson } from "./ndjson-reader.ts";

package/dist/shared.js

@@ -0,0 +1,9 @@
+// The little that both halves of Horns need.
+//
+// Its own entry so the browser can import it without the worker coming too: everything else in this package
+// pulls Hono and `@sentry/cloudflare`, which do not belong in a page bundle. Nothing here has a runtime
+// dependency on either.
+export { signedInParam } from "./auth-params.js";
+export { onlyDiagnosticExtra, withoutPiiErrorEvent } from "./pii.js";
+export { redactedUrl, redactShareTokens } from "./redact.js";
+export { readNdjson } from "./ndjson-reader.js";

package/dist/sparql-select.d.ts

@@ -0,0 +1,8 @@
+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;

package/dist/sparql-select.js

@@ -0,0 +1,23 @@
+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.
+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);
+    };
+}

package/dist/sparql-update.d.ts

@@ -0,0 +1,13 @@
+import { type WritePurpose } from "@manta-eu/horns";
+export declare const updateKeyHeader = "x-sparql-update-key";
+export declare const missingUpdateKeyMessage = "SPARQL_UPDATE_PSK is not set \u2014 this deployment cannot write.";
+export declare class WriteRefusedError extends Error {
+    constructor(message: string);
+}
+export type SparqlUpdate = (update: string) => Promise<void>;
+export declare function agentsSparqlUpdate(args: {
+    agentsUrl: string | undefined;
+    datastoreId: string;
+    updateKey: string | undefined;
+    purpose: WritePurpose;
+}): SparqlUpdate;

package/dist/sparql-update.js

@@ -0,0 +1,47 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { checkWrite } from "@manta-eu/horns";
+import { agentsPathUrl, missingAgentsUrlMessage } from "./agents-proxy.js";
+// Agents' `/d/:ds/sparql-update` authorizes on the pre-shared key alone and does not restrict `GRAPH`, so this
+// worker is the write-authorization boundary. The guard runs here rather than at each call site: there is one
+// way to send an update and it cannot be the way that forgot to check.
+export const updateKeyHeader = "x-sparql-update-key";
+export const missingUpdateKeyMessage = "SPARQL_UPDATE_PSK is not set — this deployment cannot write.";
+export class WriteRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WriteRefusedError";
+    }
+}
+export function agentsSparqlUpdate(args) {
+    return async (update) => {
+        // Before the key is looked at: a refused update is not a request.
+        const verdict = checkWrite(update, args.purpose);
+        if (!verdict.ok)
+            throw new WriteRefusedError(verdict.reason);
+        if (args.agentsUrl === undefined)
+            throw new Error(missingAgentsUrlMessage);
+        if (args.updateKey === undefined)
+            throw new Error(missingUpdateKeyMessage);
+        const url = agentsPathUrl(args.agentsUrl, `/d/${encodeURIComponent(args.datastoreId)}/sparql-update`);
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                [updateKeyHeader]: args.updateKey,
+                "content-type": "application/sparql-update",
+                origin: url.origin,
+            },
+            body: update,
+        });
+        if (!response.ok) {
+            const detail = (await response.text().catch(() => "")).slice(0, 200);
+            // agents' PSK middleware answers 503 before it looks at the key, so this is a deployment with no
+            // SPARQL_UPDATE_PSK set — not a key of ours being wrong (that is a 401). Saying so here saves the next
+            // person from reading the raw body and wondering which side to look at.
+            if (response.status === 503) {
+                throw new Error(`Writes are off in this realm: the deployment does not serve the write endpoint` +
+                    `${isPresent(detail) ? ` (${detail})` : ""}. An operator has to set SPARQL_UPDATE_PSK on the agents worker.`);
+            }
+            throw new Error(`Manta answered ${response.status}${isPresent(detail) ? `: ${detail}` : ""}`);
+        }
+    };
+}

package/dist/studio-routes.d.ts

@@ -0,0 +1,43 @@
+import { Hono } from "hono";
+import { type Realm } from "@manta-eu/horns";
+import { type Shape } from "@manta-eu/horns/shapes";
+import { type StudioModelEnv, type StudioModelResult } from "./llm.ts";
+import { type DevSessionEnv } from "./dev-session.ts";
+export type StudioRoutesEnv = DevSessionEnv & StudioModelEnv & {
+    MANTA_AGENTS_URL?: string;
+    VITE_KEYCLOAK_REALM?: string;
+};
+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[];
+    /** Overridden by tests with a scripted model; the deployment builds Qwen through the AI Gateway. */
+    model?: (env: Env, context: {
+        feature: string;
+        datastoreId: string;
+    }) => StudioModelResult;
+    /** The critic's model, which can look at a picture. Absent, the critic reads the card as text instead. */
+    criticModel?: (env: Env, context: {
+        feature: string;
+        datastoreId: string;
+    }) => StudioModelResult;
+};
+/**
+ * How much of the conversation goes back to the model.
+ *
+ * The draft itself is in `<useful-context>`, so the history is there for intent, not for state — and every
+ * message of it is context the turn cannot spend on work. dyad keeps three turns by default; this keeps six,
+ * because our messages are short and the earlier ones carry what someone wants the Horn to look like.
+ */
+export declare const maxHistoryTurns = 6;
+export declare const maxReviewImageChars: number;
+/**
+ * One turn of talking to a Horn. The draft arrives in the body and comes back changed — nothing is stored
+ * here: saving is the save route's job, with its own lock check and its own authorization.
+ *
+ * Prior turns travel as their text alone. Their tool calls described a draft the user has since changed, and
+ * re-sending them would ask the model to reason from a Horn that no longer exists; useful-context carries the
+ * one that does.
+ */
+export declare function studioRoutes<Env extends StudioRoutesEnv>(deps: StudioRoutesDeps<Env>): Hono<{
+    Bindings: Env;
+}, import("hono/types").BlankSchema, "/">;