@manta-eu/horns-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manta AI AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/action-plan-routes.d.ts

@@ -0,0 +1,22 @@
+import { Hono } from "hono";
+import type { HornRoutesEnv } from "./horn-routes.ts";
+import type { MantaSessionState } from "./session.ts";
+export declare const planNotFoundMessage = "There is no plan like that in this datastore.";
+export type PlanRunResult = {
+    ok: true;
+    workflowId?: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export declare function executeActionPlan(args: {
+    agentsUrl: string | undefined;
+    session: MantaSessionState;
+    datastoreId: string;
+    plan: string;
+    preview: boolean;
+}): Promise<PlanRunResult>;
+export declare function actionPlanRoutes<Env extends HornRoutesEnv>(): Hono<{
+    Bindings: Env;
+}, import("hono/types").BlankSchema, "/">;

package/dist/action-plan-routes.js

@@ -0,0 +1,85 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { isPresent } from "@manta-eu/lib/present";
+import { absoluteIri, isRealm } from "@manta-eu/horns";
+import { isPlanQuery } from "@manta-eu/horns/render";
+import { agentsGraphql } from "./agents-proxy.js";
+import { authorize, parseBody, refuse } from "./authorize.js";
+import { agentsSparqlSelect } from "./sparql-select.js";
+// Running an action plan is agents' `executeActionPlan`, called by this worker as the viewer: agents authorizes
+// it with the viewer's own token and hands it to Manta's workflow, which validates every change against its
+// shape before anything reaches a platform. The browser never gets a GraphQL route; it asks for exactly this one
+// mutation, for a plan this datastore holds.
+export const planNotFoundMessage = "There is no plan like that in this datastore.";
+const runRequestSchema = z.object({
+    // Written into a query as a term, so nothing that could close it gets that far.
+    plan: z.string().regex(absoluteIri),
+    /** A preview checks every change and makes none. A real run is only ever asked for explicitly. */
+    preview: z.boolean(),
+});
+const executeActionPlanMutation = "mutation ExecuteActionPlan($input: ExecuteActionPlanInput!) { executeActionPlan(input: $input) { success workflowId error } }";
+const executeAnswerSchema = z.object({
+    success: z.boolean(),
+    workflowId: z.string().nullish(),
+    error: z.string().nullish(),
+});
+export async function executeActionPlan(args) {
+    const sent = await agentsGraphql({ agentsUrl: args.agentsUrl, session: args.session, datastoreId: args.datastoreId }, executeActionPlanMutation, { input: { namedGraphIri: args.plan, dryRun: args.preview } }, "executeActionPlan");
+    // Being signed out and having no address are about the caller, so they are said plainly. What agents
+    // answered is about the plan, so it is said as such.
+    if (!sent.ok) {
+        return sent.status === 502 ? { ...sent, error: `The plan could not be started: ${sent.error}` } : sent;
+    }
+    const parsed = executeAnswerSchema.safeParse(sent.value);
+    if (!parsed.success) {
+        return { ok: false, status: 502, error: "The plan could not be started: Manta said nothing about it." };
+    }
+    if (!parsed.data.success) {
+        const said = parsed.data.error ?? "Manta refused it.";
+        return { ok: false, status: 502, error: `The plan could not be started: ${said}` };
+    }
+    const answer = parsed.data;
+    return isPresent(answer.workflowId) ? { ok: true, workflowId: answer.workflowId } : { ok: true };
+}
+export function actionPlanRoutes() {
+    const routes = new Hono();
+    routes.post("/api/d/:datastoreId/action-plans/run", 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;
+        const body = await parseBody(c.req.raw, runRequestSchema);
+        if (!body.ok)
+            return body.response;
+        // 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,
+            })(isPlanQuery(realm, body.data.plan), undefined);
+            if (!isPresent(found.results.bindings))
+                return refuse(404, planNotFoundMessage).response;
+        }
+        catch (caught) {
+            return refuse(502, caught instanceof Error ? caught.message : String(caught)).response;
+        }
+        const started = await executeActionPlan({
+            agentsUrl: c.env.MANTA_AGENTS_URL,
+            session: authorized.session,
+            datastoreId,
+            plan: body.data.plan,
+            preview: body.data.preview,
+        });
+        if (!started.ok)
+            return refuse(started.status, started.error).response;
+        return c.json({ started: true, ...(started.workflowId ? { workflowId: started.workflowId } : {}) }, 202, {
+            "cache-control": "no-store",
+        });
+    });
+    return routes;
+}

package/dist/agents-proxy.d.ts

@@ -0,0 +1,35 @@
+import { type MantaSessionState } from "./session.ts";
+export { checkReadOnlySparql, crossOriginBlockedMessage, evaluateProxyPolicy, isAllowedProxyPath, isAuthProxyPath, isReadOnlySparql, originAllowsRequest, proxyMethodBlockedMessage, proxyPathBlockedMessage, sameOriginDeniedResponse, sparqlEmptyMessage, sparqlFederationBlockedMessage, sparqlParseFailedMessage, sparqlWriteBlockedMessage, } from "./manta-proxy-policy.ts";
+export declare const missingAgentsUrlMessage = "MANTA_AGENTS_URL is not set \u2014 the live data source has no address.";
+export declare const signedOutMessage = "Not signed in \u2014 sign in to Manta to reach the live data source.";
+export type AgentsCaller = {
+    agentsUrl: string | undefined;
+    session: MantaSessionState;
+    datastoreId: string;
+};
+export type AgentsGraphqlResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export declare function agentsGraphql(caller: AgentsCaller, query: string, variables: Record<string, unknown>, field: string): Promise<AgentsGraphqlResult>;
+export type ProxyToMantaAgentsArgs = {
+    request: Request;
+    agentsUrl?: string;
+    session?: MantaSessionState;
+};
+export declare function agentsPathUrl(agentsUrl: string, pathAndQuery: string): URL;
+export declare function agentsUpstreamUrl(agentsUrl: string, requestUrl: string): URL;
+type BuildAgentsProxyRequestArgs = {
+    request: Request;
+    agentsUrl: string;
+    session?: MantaSessionState;
+};
+export declare function buildAgentsProxyRequest(args: BuildAgentsProxyRequestArgs): {
+    url: URL;
+    init: RequestInit;
+};
+export declare function proxyToMantaAgents(args: ProxyToMantaAgentsArgs): Promise<Response>;

package/dist/agents-proxy.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { isPresent } from "@manta-eu/lib/present";
+import { evaluateProxyPolicy, isAuthProxyPath } from "./manta-proxy-policy.js";
+import { forwardedOriginHeader, logoutPath } from "./auth-routes.js";
+import { captureUpstreamCookies, clearSessionSetCookies, isSignedIn, requestIsSecure, sessionSetCookies, sessionsDiffer, setCookieHeadersOf, upstreamCookieHeader, } from "./session.js";
+export { checkReadOnlySparql, crossOriginBlockedMessage, evaluateProxyPolicy, isAllowedProxyPath, isAuthProxyPath, isReadOnlySparql, originAllowsRequest, proxyMethodBlockedMessage, proxyPathBlockedMessage, sameOriginDeniedResponse, sparqlEmptyMessage, sparqlFederationBlockedMessage, sparqlParseFailedMessage, sparqlWriteBlockedMessage, } from "./manta-proxy-policy.js";
+export const missingAgentsUrlMessage = "MANTA_AGENTS_URL is not set — the live data source has no address.";
+export const signedOutMessage = "Not signed in — sign in to Manta to reach the live data source.";
+// 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) {
+    if (!isPresent(caller.agentsUrl))
+        return { ok: false, status: 500, error: missingAgentsUrlMessage };
+    const url = agentsPathUrl(caller.agentsUrl, "/graphql");
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            cookie: upstreamCookieHeader(caller.session),
+            origin: url.origin,
+            "content-type": "application/json",
+            accept: "application/json",
+            "x-manta-datastore": caller.datastoreId,
+        },
+        body: JSON.stringify({ query, variables }),
+    });
+    if (response.status === 401)
+        return { ok: false, status: 401, error: signedOutMessage };
+    const body = await response.json().catch(() => undefined);
+    const parsed = z
+        .object({
+        data: z.record(z.string(), z.unknown()).nullish(),
+        errors: z.array(z.object({ message: z.string() })).optional(),
+    })
+        .safeParse(body);
+    const said = parsed.success ? parsed.data.errors?.[0]?.message : undefined;
+    const value = parsed.success ? parsed.data.data?.[field] : undefined;
+    if (!response.ok || !isPresent(value) || isPresent(said)) {
+        return { ok: false, status: 502, error: said ?? `Manta answered ${response.status}` };
+    }
+    return { ok: true, value };
+}
+// Not `new URL(path, base)`: that discards the base's own pathname, breaking a prefixed MANTA_AGENTS_URL.
+export function agentsPathUrl(agentsUrl, pathAndQuery) {
+    return new URL(`${agentsUrl.replace(/\/+$/, "")}${pathAndQuery}`);
+}
+// Horns routes datastore-scoped calls under agents' own `/d/:datastoreId` prefix, so paths pass through.
+export function agentsUpstreamUrl(agentsUrl, requestUrl) {
+    const incoming = new URL(requestUrl);
+    return agentsPathUrl(agentsUrl, `${incoming.pathname}${incoming.search}`);
+}
+export function buildAgentsProxyRequest(args) {
+    const { request, agentsUrl, session } = args;
+    const url = agentsUpstreamUrl(agentsUrl, request.url);
+    const headers = new Headers(request.headers);
+    headers.delete("host");
+    headers.delete("cookie");
+    headers.delete("authorization");
+    headers.set("origin", url.origin);
+    headers.delete("referer");
+    headers.delete("sec-fetch-site");
+    headers.set(forwardedOriginHeader, new URL(request.url).origin);
+    if (isPresent(session))
+        headers.set("cookie", upstreamCookieHeader(session));
+    const init = { method: request.method, headers, redirect: "manual" };
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        init.body = request.body;
+        Object.assign(init, { duplex: "half" });
+    }
+    return { url, init };
+}
+function sessionCookiesToWrite(args) {
+    const { request, session, clearSession } = args;
+    const secure = requestIsSecure(request.url);
+    if (clearSession)
+        return clearSessionSetCookies({ secure });
+    if (!sessionsDiffer(session.before, session.after))
+        return [];
+    return isPresent(Object.keys(session.after.upstreamCookies))
+        ? sessionSetCookies(session.after, { secure })
+        : clearSessionSetCookies({ secure });
+}
+// Agents' cookies never reach the browser: they are folded into this worker's own session cookies.
+function withSessionCookies(args) {
+    const { response } = args;
+    const written = sessionCookiesToWrite(args);
+    if (!isPresent(written) && !isPresent(setCookieHeadersOf(response)))
+        return response;
+    const headers = new Headers(response.headers);
+    headers.delete("set-cookie");
+    headers.delete("content-encoding");
+    headers.delete("content-length");
+    for (const cookie of written)
+        headers.append("set-cookie", cookie);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+export async function proxyToMantaAgents(args) {
+    const { request, agentsUrl, session } = args;
+    const decision = await evaluateProxyPolicy(request);
+    if (!decision.allow) {
+        return Response.json({ error: decision.error }, { status: decision.status });
+    }
+    if (!isPresent(agentsUrl)) {
+        return Response.json({ error: missingAgentsUrlMessage }, { status: 500 });
+    }
+    if (!isSignedIn(session) && !isAuthProxyPath(new URL(request.url).pathname)) {
+        return Response.json({ error: signedOutMessage }, { status: 401 });
+    }
+    const outbound = decision.bodyText === undefined
+        ? request
+        : new Request(request.url, {
+            method: request.method,
+            headers: request.headers,
+            body: decision.bodyText,
+        });
+    const { url, init } = buildAgentsProxyRequest({
+        request: outbound,
+        agentsUrl,
+        ...(isPresent(session) ? { session } : {}),
+    });
+    const response = await fetch(url, init);
+    const before = session ?? { upstreamCookies: {} };
+    return withSessionCookies({
+        response,
+        request,
+        session: { before, after: captureUpstreamCookies(before, response) },
+        clearSession: new URL(request.url).pathname === logoutPath,
+    });
+}

package/dist/auth-params.d.ts

@@ -0,0 +1,2 @@
+/** The query parameter agents sets on the way back from a sign-in. Read by the worker and by the browser. */
+export declare const signedInParam = "signed_in";

package/dist/auth-params.js

@@ -0,0 +1,2 @@
+/** The query parameter agents sets on the way back from a sign-in. Read by the worker and by the browser. */
+export const signedInParam = "signed_in";

package/dist/auth-routes.d.ts

@@ -0,0 +1,12 @@
+import { signedInParam } from "./auth-params.ts";
+export { signedInParam };
+export declare const loginPath = "/login";
+export declare const callbackPath = "/auth/callback";
+export declare const logoutPath = "/logout";
+export declare const forwardedOriginHeader = "x-manta-forwarded-origin";
+export declare function safeRedirect(raw: string | null | undefined): string;
+export declare function logoutResponseReturningTo(response: Response, request: Request): Response;
+export declare function localSignOutResponse(request: Request): Response;
+export declare const authUnavailableMessage = "Manta could not be reached, so signing in is not possible right now.";
+export declare function authUnavailableResponse(request: Request): Response;
+export declare function loginRequestWithMarker(request: Request): Request;

package/dist/auth-routes.js

@@ -0,0 +1,75 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { signedInParam } from "./auth-params.js";
+import { clearSessionSetCookies, requestIsSecure } from "./session.js";
+export { signedInParam };
+export const loginPath = "/login";
+export const callbackPath = "/auth/callback";
+export const logoutPath = "/logout";
+export const forwardedOriginHeader = "x-manta-forwarded-origin";
+const redirectBase = "https://horns.invalid";
+export function safeRedirect(raw) {
+    if (!isPresent(raw))
+        return "/";
+    if (!raw.startsWith("/"))
+        return "/";
+    let resolved;
+    try {
+        resolved = new URL(raw, redirectBase);
+    }
+    catch {
+        return "/";
+    }
+    if (resolved.origin !== redirectBase)
+        return "/";
+    if (resolved.pathname.startsWith("//"))
+        return "/";
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+}
+export function logoutResponseReturningTo(response, request) {
+    const target = safeRedirect(new URL(request.url).searchParams.get("redirect"));
+    const location = response.headers.get("location");
+    if (target === "/" || !isPresent(location))
+        return response;
+    const rewritten = rewrittenLogoutLocation(location, new URL(request.url).origin + target);
+    if (!isPresent(rewritten))
+        return response;
+    const headers = new Headers(response.headers);
+    headers.set("location", rewritten);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+function rewrittenLogoutLocation(location, returnTo) {
+    if (location.startsWith("/"))
+        return returnTo;
+    let keycloak;
+    try {
+        keycloak = new URL(location);
+    }
+    catch {
+        return undefined;
+    }
+    if (!keycloak.searchParams.has("post_logout_redirect_uri"))
+        return undefined;
+    keycloak.searchParams.set("post_logout_redirect_uri", returnTo);
+    return keycloak.toString();
+}
+export function localSignOutResponse(request) {
+    const url = new URL(request.url);
+    const headers = new Headers({ location: url.origin + safeRedirect(url.searchParams.get("redirect")) });
+    for (const cookie of clearSessionSetCookies({ secure: requestIsSecure(request.url) })) {
+        headers.append("set-cookie", cookie);
+    }
+    return new Response(null, { status: 302, headers });
+}
+export const authUnavailableMessage = "Manta could not be reached, so signing in is not possible right now.";
+export function authUnavailableResponse(request) {
+    const target = new URL("/", new URL(request.url).origin);
+    target.searchParams.set("auth_error", authUnavailableMessage);
+    return new Response(null, { status: 302, headers: { location: target.toString() } });
+}
+export function loginRequestWithMarker(request) {
+    const url = new URL(request.url);
+    const target = new URL(safeRedirect(url.searchParams.get("redirect")), url);
+    target.searchParams.set(signedInParam, "1");
+    url.searchParams.set("redirect", `${target.pathname}${target.search}`);
+    return new Request(url, request);
+}

package/dist/authorize.d.ts

@@ -0,0 +1,24 @@
+import type { z } from "zod";
+import { type DatastoreAccessEnv } from "./datastore-access.ts";
+import { type DevSessionEnv } from "./dev-session.ts";
+import { type MantaSessionState } from "./session.ts";
+/** Everything the two questions read from the environment, and nothing a route happens to need besides. */
+export type AuthorizedEnv = DevSessionEnv & DatastoreAccessEnv;
+export type Refusal = {
+    ok: false;
+    response: Response;
+};
+export declare function refuse(status: number, error: string): Refusal;
+/**
+ * Same origin, a signed-in session, and a datastore that session was granted. Agents takes the datastore from
+ * the path and authorizes on the PSK alone, so the grant check here is the boundary rather than a convenience;
+ * a refusal drops the memoised grants, because they name a datastore the caller has just been refused.
+ */
+export declare function authorize(request: Request, env: AuthorizedEnv, datastoreId: string): Promise<{
+    ok: true;
+    session: MantaSessionState;
+} | Refusal>;
+export declare function parseBody<Schema extends z.ZodType>(request: Request, schema: Schema): Promise<{
+    ok: true;
+    data: z.output<Schema>;
+} | Refusal>;

package/dist/authorize.js

@@ -0,0 +1,43 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { sameOriginDeniedResponse, signedOutMessage } from "./agents-proxy.js";
+import { datastoreAccessFor, datastoreAccessUnavailableMessage, datastoreNotGrantedMessage, forgetDatastoreAccess, grantsDatastore, } from "./datastore-access.js";
+import { requestSession } from "./dev-session.js";
+import { isSignedIn } from "./session.js";
+export function refuse(status, error) {
+    return { ok: false, response: Response.json({ error }, { status }) };
+}
+/**
+ * Same origin, a signed-in session, and a datastore that session was granted. Agents takes the datastore from
+ * the path and authorizes on the PSK alone, so the grant check here is the boundary rather than a convenience;
+ * a refusal drops the memoised grants, because they name a datastore the caller has just been refused.
+ */
+export async function authorize(request, env, datastoreId) {
+    const denied = sameOriginDeniedResponse(request);
+    if (denied)
+        return { ok: false, response: denied };
+    const session = requestSession(request, env);
+    if (!isPresent(session) || !isSignedIn(session))
+        return refuse(401, signedOutMessage);
+    const resolved = await datastoreAccessFor(env, session);
+    if (!resolved.ok) {
+        return resolved.reason === "unauthenticated"
+            ? refuse(401, signedOutMessage)
+            : refuse(502, datastoreAccessUnavailableMessage);
+    }
+    if (!grantsDatastore(resolved.access, datastoreId)) {
+        forgetDatastoreAccess(session);
+        return refuse(403, datastoreNotGrantedMessage);
+    }
+    return { ok: true, session };
+}
+export async function parseBody(request, schema) {
+    const body = await request.json().catch(() => undefined);
+    const parsed = schema.safeParse(body);
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    const issues = parsed.error.issues
+        .slice(0, 5)
+        .map((issue) => `${issue.path.join(".") || "body"}: ${issue.message}`)
+        .join("; ");
+    return refuse(400, `The request is invalid — ${issues}`);
+}

package/dist/datastore-access.d.ts

@@ -0,0 +1,23 @@
+import { type MantaSessionState } from "./session.ts";
+export type DatastoreAccessEnv = {
+    MANTA_AGENTS_URL?: string;
+};
+export type DatastoreAccess = {
+    active?: string;
+    granted: readonly string[];
+};
+export type DatastoreAccessDenial = "unauthenticated" | "unavailable";
+export type DatastoreAccessResult = {
+    ok: true;
+    access: DatastoreAccess;
+} | {
+    ok: false;
+    reason: DatastoreAccessDenial;
+};
+export declare const datastoreNotGrantedMessage = "That datastore is not one this session can open.";
+export declare const noDatastoreMessage = "This session has no datastore to open.";
+export declare const datastoreAccessUnavailableMessage = "Could not check this session's datastore access.";
+export declare function resetDatastoreAccessCache(): void;
+export declare function forgetDatastoreAccess(session: MantaSessionState): void;
+export declare function datastoreAccessFor(env: DatastoreAccessEnv, session: MantaSessionState): Promise<DatastoreAccessResult>;
+export declare function grantsDatastore(access: DatastoreAccess, datastoreId: string): boolean;

package/dist/datastore-access.js

@@ -0,0 +1,74 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { isRecord } from "@manta-eu/horns";
+import { agentsPathUrl } from "./agents-proxy.js";
+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.";
+export const datastoreAccessUnavailableMessage = "Could not check this session's datastore access.";
+const accessMemoTtlMs = 30_000;
+const accessMemoLimit = 500;
+const accessMemo = new Map();
+function memoizedAccess(cookie) {
+    const hit = accessMemo.get(cookie);
+    if (!isPresent(hit))
+        return undefined;
+    if (Date.now() - hit.at > accessMemoTtlMs) {
+        accessMemo.delete(cookie);
+        return undefined;
+    }
+    return hit.access;
+}
+function rememberAccess(cookie, access) {
+    if (accessMemo.size >= accessMemoLimit) {
+        const oldest = accessMemo.keys().next();
+        if (!oldest.done)
+            accessMemo.delete(oldest.value);
+    }
+    accessMemo.set(cookie, { access, at: Date.now() });
+}
+export function resetDatastoreAccessCache() {
+    accessMemo.clear();
+}
+// Grants ride in the token, and agents re-issues it only after provisioning finishes, so a datastore
+// minted seconds ago is legitimately absent from one answer and present from the next. Dropping the
+// memo on a refusal is what keeps that a retry rather than a 30s wall.
+export function forgetDatastoreAccess(session) {
+    accessMemo.delete(upstreamCookieHeader(session));
+}
+function readableAccess(body) {
+    const user = isRecord(body) && isRecord(body.user) ? body.user : undefined;
+    const active = isRecord(user?.datastore) ? user.datastore.id : undefined;
+    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 };
+}
+// 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.
+export async function datastoreAccessFor(env, session) {
+    if (!isPresent(env.MANTA_AGENTS_URL))
+        return { ok: false, reason: "unavailable" };
+    const cookie = upstreamCookieHeader(session);
+    const memoized = memoizedAccess(cookie);
+    if (isPresent(memoized))
+        return { ok: true, access: memoized };
+    const url = agentsPathUrl(env.MANTA_AGENTS_URL, "/api/data/context");
+    let response;
+    try {
+        response = await fetch(url, { headers: { cookie, accept: "application/json" } });
+    }
+    catch {
+        return { ok: false, reason: "unavailable" };
+    }
+    if (!response.ok) {
+        const denied = response.status === 401 || response.status === 403;
+        return { ok: false, reason: denied ? "unauthenticated" : "unavailable" };
+    }
+    const body = await response.json().catch(() => undefined);
+    const access = readableAccess(body);
+    rememberAccess(cookie, access);
+    return { ok: true, access };
+}
+export function grantsDatastore(access, datastoreId) {
+    return access.granted.includes(datastoreId);
+}

package/dist/dev-session.d.ts

@@ -0,0 +1,5 @@
+import { type MantaSessionState } from "./session.ts";
+export type DevSessionEnv = {
+    DEV_AGENTS_COOKIE?: string;
+};
+export declare function requestSession(request: Request, env: DevSessionEnv): MantaSessionState | undefined;

package/dist/dev-session.js

@@ -0,0 +1,15 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { agentsJwtCookieName, parseCookieHeader, readSessionState } from "./session.js";
+const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
+// HireManta staging will not send a sign-in back to localhost, so `pnpm dev` can borrow a staging agents session
+// captured by `dev:borrow-session`. It stands in only for requests to this machine that carry no Horns session
+// yet (agents' token refreshes then land in a real one), and production builds drop it with import.meta.env.DEV.
+export function requestSession(request, env) {
+    const session = readSessionState(request.headers.get("cookie"));
+    if (isPresent(session) || !import.meta.env.DEV || !isPresent(env.DEV_AGENTS_COOKIE))
+        return session;
+    if (!loopbackHosts.has(new URL(request.url).hostname))
+        return undefined;
+    const upstreamCookies = parseCookieHeader(env.DEV_AGENTS_COOKIE);
+    return isPresent(upstreamCookies[agentsJwtCookieName]) ? { upstreamCookies } : undefined;
+}

package/dist/entity-links.d.ts

@@ -0,0 +1,10 @@
+/** The request agents gets: the caller's own, but asking for JSON so a failure comes back as one. */
+export declare function asJsonRequest(request: Request): Request;
+export declare function signInFirst(request: Request): Response;
+/**
+ * Where agents sent the caller, made to work from this site. A platform's own URL is left alone; a path on
+ * agents (an operator's record page) is made absolute there, because this site has no such page.
+ */
+export declare function followedLink(response: Response, agentsUrl: string): Response | undefined;
+/** A page a person can read when there is nowhere to go, with the way back to their Horns. */
+export declare function noPageToOpen(datastoreId: string, status: number): Response;

package/dist/entity-links.js

@@ -0,0 +1,51 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { agentsPathUrl } from "./agents-proxy.js";
+import { loginPath } from "./auth-routes.js";
+// A row in a Horn links to the thing it shows — the campaign in Google Ads, the ad set in Meta Ads Manager —
+// through agents' `/redirect` (`entityLinkPath` in `@manta-eu/horns/render`), which reads the entity's type and `schema:identifier` from the graph and knows
+// each platform's URL. The link is `/d/:datastoreId/redirect?iri=…` on this site, the same path agents serves
+// on its own, so a Horn embedded in agents links the same way.
+//
+// Agents answers a browser that asks for HTML with redirects to its own error pages, which are not pages here;
+// this asks for JSON and turns a refusal into a sentence instead.
+/** The request agents gets: the caller's own, but asking for JSON so a failure comes back as one. */
+export function asJsonRequest(request) {
+    const headers = new Headers(request.headers);
+    headers.set("accept", "application/json");
+    return new Request(request.url, { method: "GET", headers });
+}
+export function signInFirst(request) {
+    const url = new URL(request.url);
+    const back = `${url.pathname}${url.search}`;
+    return new Response(null, {
+        status: 302,
+        headers: { location: `${loginPath}?redirect=${encodeURIComponent(back)}` },
+    });
+}
+/**
+ * Where agents sent the caller, made to work from this site. A platform's own URL is left alone; a path on
+ * agents (an operator's record page) is made absolute there, because this site has no such page.
+ */
+export function followedLink(response, agentsUrl) {
+    const location = response.headers.get("location");
+    if (response.status < 300 || response.status >= 400 || !isPresent(location))
+        return undefined;
+    const target = /^https?:\/\//i.test(location) ? location : agentsPathUrl(agentsUrl, location).toString();
+    const headers = new Headers(response.headers);
+    headers.set("location", target);
+    return new Response(null, { status: 302, headers });
+}
+const escapeHtml = (text) => text.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
+/** A page a person can read when there is nowhere to go, with the way back to their Horns. */
+export function noPageToOpen(datastoreId, status) {
+    const title = status === 404 ? "There is no page to open for this" : "That page could not be opened";
+    const hint = status === 404
+        ? "It has no page in the platform it came from, or it has been removed there."
+        : "Something went wrong while looking it up. Try again in a moment.";
+    const back = `/d/${encodeURIComponent(datastoreId)}/horns`;
+    const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escapeHtml(title)}</title></head><body style="margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0c;color:#f3f4f6;font-family:system-ui,sans-serif"><main style="max-width:28rem;padding:24px;text-align:center"><h1 style="font-size:20px;margin:0 0 8px">${escapeHtml(title)}</h1><p style="color:#9ca3af;margin:0 0 20px;line-height:1.5">${escapeHtml(hint)}</p><a href="${escapeHtml(back)}" style="color:#a5b4fc">Back to your Horns</a></main></body></html>`;
+    return new Response(html, {
+        status,
+        headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+    });
+}