@unson/brainbase-mcp 0.7.0 → 0.9.0

package/dist/foundation-authenticated-tools.js

@@ -0,0 +1,347 @@
+import { randomUUID } from 'node:crypto';
+import { foundationPublicToolDefinitions } from './foundation-public-provider.js';
+import { philosophyRevisionDigest, } from './philosophy-revision-reader.js';
+const FOUNDATION_READ_TYPES = new Set(['objective', 'variable', 'model', 'constraint', 'philosophy']);
+const FOUNDATION_TOOL_NAMES = new Set([
+    'foundation_describe',
+    'foundation_read',
+    'foundation_validate_reference',
+    'foundation_validate_problem',
+]);
+const REVISION_PATTERN = /^[1-9]\d*$/u;
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const MAX_SCOPE_ID_LENGTH = 256;
+/**
+ * The public provider owns the contract and schemas.  The Host adds the
+ * authenticated Graph scope to every public tool because a provider cannot
+ * select a tenant on behalf of the caller.
+ */
+function withScopeSchema(definition) {
+    const inputSchema = definition.inputSchema;
+    const properties = inputSchema.properties && typeof inputSchema.properties === 'object'
+        ? inputSchema.properties
+        : {};
+    const required = Array.isArray(inputSchema.required)
+        ? inputSchema.required.filter((value) => typeof value === 'string')
+        : [];
+    return {
+        ...definition,
+        inputSchema: {
+            ...inputSchema,
+            properties: {
+                ...properties,
+                scope_id: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: MAX_SCOPE_ID_LENGTH,
+                    description: 'Authenticated project scope used for this read or validation.',
+                },
+            },
+            required: [...new Set([...required, 'scope_id'])],
+            additionalProperties: inputSchema.additionalProperties ?? false,
+        },
+    };
+}
+export const foundationPublicTools = foundationPublicToolDefinitions.map(withScopeSchema);
+export function isFoundationPublicToolName(name) {
+    return FOUNDATION_TOOL_NAMES.has(name);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Scope IDs are copied into x-brainbase-projects.  Reject delimiters and
+ * control characters before authentication so a caller cannot turn one
+ * selected project into an arbitrary project list.
+ */
+function readScopeId(args) {
+    if (typeof args.scope_id !== 'string')
+        return null;
+    const scopeId = args.scope_id.trim();
+    if (!scopeId || scopeId.length > MAX_SCOPE_ID_LENGTH)
+        return null;
+    if (/[\u0000-\u001f\u007f,]/u.test(scopeId))
+        return null;
+    return scopeId;
+}
+function invalidInput(message, dependencies) {
+    return dependencies.auth.toolError('error', 'foundation_request_invalid', message, []);
+}
+function rejectUnexpectedKeys(args, allowed, dependencies) {
+    const allowedKeys = new Set(allowed);
+    const unexpected = Object.keys(args).find((key) => !allowedKeys.has(key));
+    return unexpected ? invalidInput(`unexpected Foundation argument: ${unexpected}`, dependencies) : null;
+}
+function readRequiredString(args, key) {
+    return isNonEmptyString(args[key]) ? String(args[key]).trim() : null;
+}
+function validateReadArgs(args, dependencies) {
+    const type = readRequiredString(args, 'type');
+    const id = readRequiredString(args, 'id');
+    const revision = readRequiredString(args, 'revision');
+    if (!type || !FOUNDATION_READ_TYPES.has(type))
+        return invalidInput('foundation type is invalid', dependencies);
+    if (!id)
+        return invalidInput('foundation id is required', dependencies);
+    if (!revision || !REVISION_PATTERN.test(revision))
+        return invalidInput('foundation revision is invalid', dependencies);
+    if (args.digest !== undefined && (!isNonEmptyString(args.digest) || !DIGEST_PATTERN.test(String(args.digest)))) {
+        return invalidInput('foundation digest is invalid', dependencies);
+    }
+    return null;
+}
+function validateReferenceArgs(args, dependencies) {
+    if (!isRecord(args.reference))
+        return invalidInput('foundation reference is required', dependencies);
+    const reference = args.reference;
+    if (!isNonEmptyString(reference.kind) || !['objective', 'variable', 'model', 'constraint', 'philosophy'].includes(reference.kind)) {
+        return invalidInput('foundation reference kind is invalid', dependencies);
+    }
+    if (!isNonEmptyString(reference.id) || !isNonEmptyString(reference.revision) || !REVISION_PATTERN.test(String(reference.revision))) {
+        return invalidInput('foundation reference identity is invalid', dependencies);
+    }
+    if (!isNonEmptyString(reference.digest) || !DIGEST_PATTERN.test(String(reference.digest))) {
+        return invalidInput('foundation reference digest is invalid', dependencies);
+    }
+    if (!isRecord(reference.scope) || !isNonEmptyString(reference.scope.type) || !isNonEmptyString(reference.scope.id)) {
+        return invalidInput('foundation reference scope is invalid', dependencies);
+    }
+    if (!['personal', 'project', 'organization'].includes(reference.scope.type)) {
+        return invalidInput('foundation reference scope type is invalid', dependencies);
+    }
+    if (!isNonEmptyString(reference.valid_from))
+        return invalidInput('foundation reference valid_from is required', dependencies);
+    if (args.phase !== undefined && args.phase !== 'read' && args.phase !== 'historical_read') {
+        return invalidInput('foundation validation phase is invalid', dependencies);
+    }
+    return null;
+}
+function validateProblemArgs(args, dependencies) {
+    if (!isRecord(args.snapshot))
+        return invalidInput('foundation snapshot is required', dependencies);
+    return null;
+}
+function selectedContext(context, scopeId) {
+    // authenticateProject proves membership against both the token and the
+    // configured allow-list.  Restrict the outbound header to the selected
+    // project instead of forwarding every project in the token.
+    return { token: context.token, scope: [scopeId] };
+}
+function requestFor(name, args, scopeId) {
+    const query = new URLSearchParams({ scope_id: scopeId });
+    if (name === 'foundation_describe') {
+        return { path: `/api/foundation/contract?${query.toString()}`, method: 'GET' };
+    }
+    if (name === 'foundation_read') {
+        const type = String(args.type);
+        const id = String(args.id);
+        query.set('revision', String(args.revision));
+        if (args.digest !== undefined)
+            query.set('digest', String(args.digest));
+        return {
+            path: `/api/foundation/definitions/${encodeURIComponent(type)}/${encodeURIComponent(id)}?${query.toString()}`,
+            method: 'GET',
+        };
+    }
+    if (name === 'foundation_validate_reference') {
+        const { scope_id: _scopeId, ...body } = args;
+        return {
+            path: `/api/foundation/judgment-references/validate?${query.toString()}`,
+            method: 'POST',
+            body,
+        };
+    }
+    const { scope_id: _scopeId, ...body } = args;
+    return {
+        path: `/api/foundation/judgment-problems/validate?${query.toString()}`,
+        method: 'POST',
+        body,
+    };
+}
+async function fetchFoundationCsrfToken(dependencies, context) {
+    const sessionId = `brainbase-mcp-foundation-${randomUUID()}`;
+    let response;
+    try {
+        response = await (dependencies.fetch || globalThis.fetch)(`${dependencies.apiUrl.replace(/\/+$/, '')}/api/csrf-token`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${context.token}`,
+                'x-brainbase-projects': context.scope.join(','),
+                'x-session-id': sessionId,
+            },
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            result: dependencies.auth.toolError('unavailable', 'foundation_csrf_unavailable', error instanceof Error ? error.message : String(error), context.scope),
+        };
+    }
+    let payload = null;
+    let payloadParsed = false;
+    try {
+        payload = await response.json();
+        payloadParsed = true;
+    }
+    catch {
+        // Keep the response fail-closed below; a 200 without a token is not a
+        // usable CSRF handshake.
+    }
+    if (!response.ok) {
+        return { ok: false, result: errorFromResponse(response, payload, context.scope, dependencies) };
+    }
+    const token = isRecord(payload) && typeof payload.token === 'string' ? payload.token.trim() : '';
+    if (!payloadParsed || !token) {
+        return {
+            ok: false,
+            result: dependencies.auth.toolError('error', 'foundation_csrf_response_invalid', 'Brainbase API returned an invalid CSRF response', context.scope, response.status),
+        };
+    }
+    return { ok: true, sessionId, token };
+}
+async function fetchFoundationRequest(dependencies, context, request) {
+    if (request.method !== 'POST') {
+        return dependencies.auth.fetchAuthenticatedJson(context, request);
+    }
+    const csrf = await fetchFoundationCsrfToken(dependencies, context);
+    if (!csrf.ok)
+        return csrf;
+    return dependencies.auth.fetchAuthenticatedJson(context, {
+        ...request,
+        headers: {
+            'x-session-id': csrf.sessionId,
+            'x-csrf-token': csrf.token,
+        },
+    });
+}
+function errorFromResponse(response, payload, scope, dependencies) {
+    const error = isRecord(payload) && isRecord(payload.error) ? payload.error : null;
+    const code = typeof error?.code === 'string' && error.code.trim()
+        ? error.code
+        : response.status === 404
+            ? 'foundation_api_unavailable'
+            : response.status >= 500
+                ? 'foundation_api_unavailable'
+                : 'foundation_api_error';
+    const message = typeof error?.message === 'string' && error.message.trim()
+        ? error.message
+        : `${response.status} ${response.statusText}`.trim();
+    const status = response.status === 404 || response.status >= 500 ? 'unavailable' : 'error';
+    return dependencies.auth.toolError(status, code, message, scope, response.status, error?.details);
+}
+function isFoundationScope(value) {
+    return isRecord(value)
+        && (value.type === 'personal' || value.type === 'project' || value.type === 'organization')
+        && isNonEmptyString(value.id);
+}
+function isFoundationAcl(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.ownerId)
+        && (value.visibility === 'private'
+            || value.visibility === 'project'
+            || value.visibility === 'organization'
+            || value.visibility === 'public')
+        && Array.isArray(value.readerIds)
+        && value.readerIds.every((readerId) => isNonEmptyString(readerId))
+        && new Set(value.readerIds).size === value.readerIds.length
+        && Array.isArray(value.writerIds)
+        && value.writerIds.every((writerId) => isNonEmptyString(writerId))
+        && new Set(value.writerIds).size === value.writerIds.length;
+}
+function isValidPhilosophyRevisionPayload(args, payload) {
+    if (payload.kind !== 'philosophy'
+        || payload.id !== args.id
+        || payload.revision !== args.revision
+        || !isNonEmptyString(payload.digest)
+        || !DIGEST_PATTERN.test(payload.digest)
+        || !Object.prototype.hasOwnProperty.call(payload, 'payload')
+        || !isRecord(payload.applicability)
+        || !isFoundationScope(payload.applicability.scope)
+        || !isFoundationAcl(payload.currentAcl)
+        || !isFoundationScope(payload.currentScope)
+        || (args.digest !== undefined && payload.digest !== args.digest)) {
+        return false;
+    }
+    try {
+        // The canonical helper validates the JSON payload and applicability, and
+        // excludes read-time ACL/scope metadata from the immutable digest.
+        return philosophyRevisionDigest(payload) === payload.digest;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidSuccessPayload(name, args, payload) {
+    if (!isRecord(payload))
+        return false;
+    if (name === 'foundation_describe') {
+        return payload.contractVersion === 'foundation-public.v1'
+            && payload.connection === 'configured'
+            && isRecord(payload.foundation)
+            && payload.executionPermission === 'none';
+    }
+    if (name === 'foundation_read') {
+        if (args.type === 'philosophy') {
+            return isValidPhilosophyRevisionPayload(args, payload);
+        }
+        const definition = isRecord(payload.definition) ? payload.definition : null;
+        return definition !== null
+            && isNonEmptyString(payload.digest)
+            && DIGEST_PATTERN.test(payload.digest)
+            && definition.id === args.id
+            && definition.type === args.type
+            && definition.revision === args.revision
+            && (args.digest === undefined || payload.digest === args.digest);
+    }
+    // The canonical HTTP route returns 200 only for a resolved validation.  A
+    // non-resolved result must remain an error/unavailable response even if an
+    // incorrectly connected upstream serializes it with HTTP 200.
+    return payload.status === 'resolved';
+}
+export async function handleFoundationPublicToolCall(name, args, dependencies) {
+    if (!isFoundationPublicToolName(name))
+        return null;
+    const scopeId = readScopeId(args);
+    if (!scopeId)
+        return invalidInput('scope_id is required and must be a safe project identifier', dependencies);
+    const unexpected = rejectUnexpectedKeys(args, name === 'foundation_describe'
+        ? ['scope_id']
+        : name === 'foundation_read'
+            ? ['scope_id', 'type', 'id', 'revision', 'digest']
+            : name === 'foundation_validate_reference'
+                ? ['scope_id', 'reference', 'phase']
+                : ['scope_id', 'snapshot'], dependencies);
+    if (unexpected)
+        return unexpected;
+    if (name === 'foundation_read') {
+        const invalid = validateReadArgs(args, dependencies);
+        if (invalid)
+            return invalid;
+    }
+    else if (name === 'foundation_validate_reference') {
+        const invalid = validateReferenceArgs(args, dependencies);
+        if (invalid)
+            return invalid;
+    }
+    else if (name === 'foundation_validate_problem') {
+        const invalid = validateProblemArgs(args, dependencies);
+        if (invalid)
+            return invalid;
+    }
+    const authenticated = await dependencies.auth.authenticateProject({ project_code: scopeId }, { requireProject: true });
+    if ('status' in authenticated)
+        return authenticated;
+    const context = selectedContext(authenticated, scopeId);
+    const fetched = await fetchFoundationRequest(dependencies, context, requestFor(name, args, scopeId));
+    if (!fetched.ok)
+        return fetched.result;
+    if (!fetched.response.ok)
+        return errorFromResponse(fetched.response, fetched.payload, context.scope, dependencies);
+    if (!fetched.payloadParsed || !isValidSuccessPayload(name, args, fetched.payload)) {
+        return dependencies.auth.toolError('error', 'foundation_api_response_invalid', 'Brainbase API returned an invalid Foundation response', context.scope, fetched.response.status);
+    }
+    return { status: 'ok', scope: { project_codes: context.scope }, data: fetched.payload };
+}

package/dist/foundation-graph-http.d.ts

@@ -0,0 +1,43 @@
+import { type FoundationHttpCsrfVerifier, type FoundationHttpRouter } from './foundation-http.js';
+/**
+ * Readiness probe for the Graph history contract used by the public adapter.
+ *
+ * The query is deliberately kept in the reusable adapter.  Hosts provide the
+ * transaction-bound query port, while the migration remains the authority for
+ * RLS and immutable-history trigger state.
+ */
+export declare const FOUNDATION_GRAPH_READY_SQL = "SELECT\n    EXISTS (SELECT 1 FROM pg_class WHERE oid = to_regclass('public.graph_foundation_revisions') AND relrowsecurity)\n    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_entities')\n        AND tgname = 'graph_entities_foundation_history_capture' AND tgenabled = 'O' AND tgtype = 21\n        AND tgfoid = to_regprocedure('public.capture_graph_foundation_revision()'))\n    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')\n        AND tgname = 'graph_foundation_revisions_guard' AND tgenabled = 'O' AND tgtype = 31\n        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()'))\n    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')\n        AND tgname = 'graph_foundation_revisions_truncate_guard' AND tgenabled = 'O' AND tgtype = 34\n        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()')) AS ready";
+export declare const FOUNDATION_GRAPH_CONTRACT_VERSION: "foundation-graph-http.v1";
+type MaybePromise<T> = T | Promise<T>;
+export interface FoundationGraphTrustedIdentity {
+    /** Canonical principal supplied by the host authentication boundary. */
+    readonly principal: string;
+    /** Canonical organization scope supplied by the host authentication boundary. */
+    readonly organizationId: string;
+    /** Project scopes the authenticated principal may select. `*` is supported by hosts. */
+    readonly projectScopeIds: readonly string[];
+}
+export interface FoundationGraphQueryResult {
+    readonly rows: readonly Record<string, unknown>[];
+}
+export interface FoundationGraphQueryClient {
+    query(text: string, values?: readonly unknown[]): FoundationGraphQueryResult | Promise<FoundationGraphQueryResult>;
+}
+export interface FoundationGraphHttpOptions {
+    /** Resolve only trusted identity; request body and query values are never used for identity. */
+    readonly resolveTrustedIdentity: (request: Request) => MaybePromise<FoundationGraphTrustedIdentity | null>;
+    /** Run the shared provider inside the host's authenticated transaction/context. */
+    readonly withAccessContext: <T>(identity: FoundationGraphTrustedIdentity, callback: (client: FoundationGraphQueryClient) => Promise<T>) => Promise<T>;
+    /** Host-owned CSRF verification port for mutation requests. */
+    readonly csrf?: FoundationHttpCsrfVerifier;
+    readonly bodyLimitBytes?: number;
+}
+/**
+ * Create the reusable Graph-backed public Foundation handler.
+ *
+ * This is a native Fetch-style adapter. It has no Express, authentication, or
+ * organization dependency: a host injects a trusted identity resolver, an
+ * already-authenticated transaction port, and its CSRF verifier.
+ */
+export declare function createFoundationGraphHttpHandler(options: FoundationGraphHttpOptions): FoundationHttpRouter;
+export {};

package/dist/foundation-graph-http.js

@@ -0,0 +1,243 @@
+import { FOUNDATION_HTTP_CONTRACT_VERSION, createFoundationHttpRouter } from './foundation-http.js';
+import { createFoundationPublicProvider, createFoundationPublicRoute } from './foundation-public-provider.js';
+import { createGraphFoundationReaders } from './graph-foundation-reader.js';
+/**
+ * Readiness probe for the Graph history contract used by the public adapter.
+ *
+ * The query is deliberately kept in the reusable adapter.  Hosts provide the
+ * transaction-bound query port, while the migration remains the authority for
+ * RLS and immutable-history trigger state.
+ */
+export const FOUNDATION_GRAPH_READY_SQL = `SELECT
+    EXISTS (SELECT 1 FROM pg_class WHERE oid = to_regclass('public.graph_foundation_revisions') AND relrowsecurity)
+    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_entities')
+        AND tgname = 'graph_entities_foundation_history_capture' AND tgenabled = 'O' AND tgtype = 21
+        AND tgfoid = to_regprocedure('public.capture_graph_foundation_revision()'))
+    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')
+        AND tgname = 'graph_foundation_revisions_guard' AND tgenabled = 'O' AND tgtype = 31
+        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()'))
+    AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = to_regclass('public.graph_foundation_revisions')
+        AND tgname = 'graph_foundation_revisions_truncate_guard' AND tgenabled = 'O' AND tgtype = 34
+        AND tgfoid = to_regprocedure('public.guard_graph_foundation_revision_mutation()')) AS ready`;
+export const FOUNDATION_GRAPH_CONTRACT_VERSION = 'foundation-graph-http.v1';
+const DEFAULT_BODY_LIMIT_BYTES = 65_536;
+const DIRECT_FOUNDATION_REFERENCE_KINDS = new Set(['objective', 'variable', 'model', 'constraint', 'philosophy']);
+const SNAPSHOT_REFERENCE_KINDS = new Set([
+    'entity', 'edge', 'objective', 'criterion', 'variable', 'observation', 'model', 'constraint',
+    'philosophy', 'authority', 'resource', 'deadline', 'dag', 'evidence'
+]);
+const FOUNDATION_SCOPE_TYPES = new Set(['personal', 'project', 'organization']);
+function jsonResponse(status, value) {
+    return new Response(JSON.stringify(value), {
+        status,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Return true only for the canonical scope shape. Incomplete or extended
+ * shapes stay on the shared validator path so it remains the source of
+ * malformed-input errors.
+ */
+function isCanonicalFoundationScope(value) {
+    return isRecord(value)
+        && Object.keys(value).length === 2
+        && typeof value.type === 'string'
+        && typeof value.id === 'string'
+        && value.type.length > 0
+        && value.id.length > 0
+        && value.type === value.type.trim()
+        && value.id === value.id.trim();
+}
+function isSelectedProjectScope(value, scopeId) {
+    return isCanonicalFoundationScope(value) && value.type === 'project' && value.id === scopeId;
+}
+function isAllowedFoundationReference(reference, scopeId, organizationId, knownKinds) {
+    if (!isRecord(reference) || !isCanonicalFoundationScope(reference.scope))
+        return true;
+    // Let the common validator report a missing/non-string kind as malformed;
+    // every present non-philosophy kind remains project-scoped.
+    if (typeof reference.kind !== 'string' || reference.kind.length === 0 || reference.kind !== reference.kind.trim())
+        return true;
+    // Unknown kinds and scope types remain the shared validator's responsibility.
+    // This boundary only narrows otherwise valid references.
+    if (!knownKinds.has(reference.kind) || !FOUNDATION_SCOPE_TYPES.has(reference.scope.type))
+        return true;
+    return isSelectedProjectScope(reference.scope, scopeId)
+        || (reference.kind === 'philosophy'
+            && reference.scope.type === 'organization'
+            && reference.scope.id === organizationId);
+}
+/**
+ * Reject scope widening before the common provider sees a request. The
+ * provider receives both the selected project and trusted organization so an
+ * organization philosophy can resolve, but all other foundation references
+ * remain project-scoped and measurements remain project-only.
+ */
+function hasFoundationScopeOverride(request, body, scopeId, organizationId) {
+    const method = (request.method || 'GET').toUpperCase();
+    if (!['POST', 'PUT', 'PATCH'].includes(method) || !isRecord(body))
+        return false;
+    const pathname = new URL(request.url).pathname;
+    if (pathname.endsWith('/judgment-references/validate')) {
+        return isRecord(body.reference)
+            && !isAllowedFoundationReference(body.reference, scopeId, organizationId, DIRECT_FOUNDATION_REFERENCE_KINDS);
+    }
+    if (!pathname.endsWith('/judgment-problems/validate'))
+        return false;
+    const snapshot = body.snapshot;
+    if (!isRecord(snapshot))
+        return false;
+    if (Object.hasOwn(snapshot, 'owner_scope')
+        && isCanonicalFoundationScope(snapshot.owner_scope)
+        && FOUNDATION_SCOPE_TYPES.has(snapshot.owner_scope.type)
+        && !isSelectedProjectScope(snapshot.owner_scope, scopeId)) {
+        return true;
+    }
+    if (!Array.isArray(snapshot.references))
+        return false;
+    return snapshot.references.some((reference) => {
+        if (!isRecord(reference))
+            return false;
+        if (Object.hasOwn(reference, 'scope')
+            && !isAllowedFoundationReference(reference, scopeId, organizationId, SNAPSHOT_REFERENCE_KINDS)) {
+            return true;
+        }
+        const measurement = reference.measurement;
+        const measurementScope = isRecord(measurement) ? measurement.scope : undefined;
+        const subjectIds = isRecord(measurementScope) ? measurementScope.subjectIds : undefined;
+        // Incomplete subjectIds remain the shared validator's responsibility.
+        return Array.isArray(subjectIds)
+            && subjectIds.length > 0
+            && subjectIds.every((subjectId) => typeof subjectId === 'string'
+                && subjectId === subjectId.trim()
+                && subjectId.length > 0)
+            && subjectIds.some((subjectId) => subjectId !== scopeId);
+    });
+}
+async function readJsonForScopeCheck(request, bodyLimitBytes) {
+    const method = (request.method || 'GET').toUpperCase();
+    const pathname = new URL(request.url).pathname;
+    if (!['POST', 'PUT', 'PATCH'].includes(method)
+        || (!pathname.endsWith('/judgment-references/validate') && !pathname.endsWith('/judgment-problems/validate'))) {
+        return null;
+    }
+    try {
+        const body = await request.clone().text();
+        if (new TextEncoder().encode(body).byteLength > bodyLimitBytes)
+            return null;
+        return JSON.parse(body);
+    }
+    catch {
+        // The shared route owns malformed JSON errors. A failed preflight must not
+        // turn malformed input into an authorization decision.
+        return null;
+    }
+}
+function identityIsValid(identity) {
+    if (!identity)
+        return false;
+    return typeof identity.principal === 'string'
+        && identity.principal.trim().length > 0
+        && typeof identity.organizationId === 'string'
+        && identity.organizationId.trim().length > 0
+        && Array.isArray(identity.projectScopeIds);
+}
+function selectedScopeIsAllowed(identity, scopeId) {
+    return identity.projectScopeIds.includes('*') || identity.projectScopeIds.includes(scopeId);
+}
+function readyResult(result) {
+    return result.rows[0]?.ready === true;
+}
+/**
+ * Create the reusable Graph-backed public Foundation handler.
+ *
+ * This is a native Fetch-style adapter. It has no Express, authentication, or
+ * organization dependency: a host injects a trusted identity resolver, an
+ * already-authenticated transaction port, and its CSRF verifier.
+ */
+export function createFoundationGraphHttpHandler(options) {
+    if (!options || typeof options.resolveTrustedIdentity !== 'function') {
+        throw new TypeError('resolveTrustedIdentity is required');
+    }
+    if (typeof options.withAccessContext !== 'function') {
+        throw new TypeError('withAccessContext is required');
+    }
+    const bodyLimitBytes = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes <= 0) {
+        throw new TypeError('bodyLimitBytes must be a positive integer');
+    }
+    return {
+        contractVersion: FOUNDATION_HTTP_CONTRACT_VERSION,
+        routes: [],
+        async handle(request) {
+            let identity;
+            try {
+                identity = await options.resolveTrustedIdentity(request);
+            }
+            catch {
+                identity = null;
+            }
+            if (!identityIsValid(identity)) {
+                return jsonResponse(403, { error: { code: 'foundation_trusted_context_required' } });
+            }
+            const url = new URL(request.url);
+            const scopeIds = url.searchParams.getAll('scope_id');
+            if (scopeIds.length !== 1 || !scopeIds[0]?.trim() || scopeIds[0] !== scopeIds[0].trim()) {
+                return jsonResponse(400, { error: { code: 'scope_id_required' } });
+            }
+            const scopeId = scopeIds[0];
+            if (!selectedScopeIsAllowed(identity, scopeId)) {
+                return jsonResponse(403, { error: { code: 'scope_not_allowed' } });
+            }
+            const body = await readJsonForScopeCheck(request, bodyLimitBytes);
+            if (hasFoundationScopeOverride(request, body, scopeId, identity.organizationId)) {
+                return jsonResponse(403, { error: { code: 'scope_not_allowed' } });
+            }
+            const context = {
+                principal: identity.principal,
+                scope: {
+                    subjectIds: [scopeId, identity.organizationId],
+                    validFrom: '1970-01-01T00:00:00Z'
+                }
+            };
+            try {
+                const response = await options.withAccessContext(identity, async (client) => {
+                    let ready;
+                    try {
+                        ready = await client.query(FOUNDATION_GRAPH_READY_SQL);
+                    }
+                    catch {
+                        return jsonResponse(503, { error: { code: 'foundation_provider_unavailable' } });
+                    }
+                    if (!readyResult(ready)) {
+                        return jsonResponse(503, { error: { code: 'foundation_migration_required' } });
+                    }
+                    const readers = createGraphFoundationReaders({
+                        context,
+                        query: async (text, values) => ({
+                            rows: (await client.query(text, values ?? [])).rows
+                        })
+                    });
+                    const provider = createFoundationPublicProvider(readers);
+                    const route = createFoundationPublicRoute(provider);
+                    const handler = createFoundationHttpRouter({
+                        resolveContext: () => context,
+                        csrf: options.csrf,
+                        routes: [route],
+                        bodyLimitBytes
+                    });
+                    return handler.handle(request);
+                });
+                return response instanceof Response
+                    ? response
+                    : jsonResponse(503, { error: { code: 'foundation_provider_unavailable' } });
+            }
+            catch {
+                return jsonResponse(503, { error: { code: 'foundation_provider_unavailable' } });
+            }
+        }
+    };
+}