@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/foundation-http.js

@@ -0,0 +1,439 @@
+import { FoundationStoreError } from './foundation-store.js';
+/**
+ * HTTP boundary shared by the OSS Objective UI and organization adapters.
+ *
+ * This module intentionally exposes a Fetch-style route handler instead of
+ * opening a listener.  A local host can mount it beside Reservation,
+ * Decision, or another Company OS route on one server.  Authentication,
+ * tenant scope, and CSRF are supplied by that host; none of them are read
+ * from a JSON request body.
+ */
+export const FOUNDATION_HTTP_CONTRACT_VERSION = 'brainbase.foundation-http.v1';
+export const FOUNDATION_HTTP_PREFIX = '/api/foundation';
+export const FOUNDATION_OBJECTIVE_ROUTE_PREFIX = `${FOUNDATION_HTTP_PREFIX}/objectives`;
+export const FOUNDATION_OBJECTIVE_ROUTES = Object.freeze([
+    'GET /api/foundation/objectives',
+    'GET /api/foundation/objectives/:id',
+    'GET /api/foundation/objectives/:id/readiness',
+    'GET /api/foundation/objectives/:id/constraints',
+    'PUT /api/foundation/objectives/:id/constraints',
+    'POST /api/foundation/objectives',
+    'PUT /api/foundation/objectives/:id',
+    'GET /api/foundation/stories/:id/objectives',
+]);
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const AUTHORITY_FIELDS = new Set([
+    'acl',
+    'scope',
+    'storage',
+    'provenance',
+    'authorizedUses',
+    'authorized_uses',
+    'ownerId',
+    'owner_id',
+    'userId',
+    'user_id',
+    'memberId',
+    'member_id',
+    'readerIds',
+    'reader_ids',
+    'writerIds',
+    'writer_ids',
+    'tenant',
+    'subjectIds',
+    'subject_ids',
+    'tenantId',
+    'tenant_id',
+    'organization',
+    'organization_id',
+    'organizationId',
+    'org',
+    'orgId',
+    'org_id',
+    'workspace',
+    'workspaceId',
+    'workspace_id',
+    'principal',
+    'actor',
+    'actorId',
+    'actor_id',
+    'role',
+    'roles',
+    'raci',
+    'authorization',
+    'permission',
+    'permissions',
+]);
+class FoundationHttpError extends Error {
+    status;
+    code;
+    currentRevision;
+    constructor(status, code, message, options = {}) {
+        super(message);
+        this.name = 'FoundationHttpError';
+        this.status = status;
+        this.code = code;
+        this.currentRevision = options.currentRevision;
+    }
+}
+/**
+ * Compose OSS Company OS routes under one local server boundary.  The
+ * resolver is called only for a matching route and the resulting trusted
+ * context is passed to that route.  Unknown routes remain an ordinary 404 so
+ * the host can mount this handler beside other app routes.
+ */
+export function createFoundationHttpRouter(options) {
+    if (!options || typeof options.resolveContext !== 'function') {
+        throw new TypeError('resolveContext is required');
+    }
+    if (!Array.isArray(options.routes) || options.routes.length === 0) {
+        throw new TypeError('at least one Foundation HTTP route 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');
+    }
+    const routes = Object.freeze([...options.routes]);
+    return {
+        contractVersion: FOUNDATION_HTTP_CONTRACT_VERSION,
+        routes,
+        async handle(request) {
+            const route = routes.find((candidate) => candidate.matches(request));
+            if (!route)
+                return jsonResponse(404, { error: { code: 'not_found', message: 'Route not found' } });
+            let context;
+            try {
+                context = await options.resolveContext(request);
+            }
+            catch {
+                context = null;
+            }
+            if (!context)
+                return jsonResponse(401, { error: { code: 'authorization_required', message: 'A trusted context is required' } });
+            if (MUTATING_METHODS.has((request.method || 'GET').toUpperCase())) {
+                if (!options.csrf) {
+                    return jsonResponse(501, { error: { code: 'csrf_unconfigured', message: 'A CSRF verifier is required for mutations' } });
+                }
+                try {
+                    const verified = await options.csrf.verify(request, context);
+                    if (verified === false) {
+                        return jsonResponse(403, { error: { code: 'csrf_failed', message: 'CSRF verification failed' } });
+                    }
+                }
+                catch {
+                    return jsonResponse(403, { error: { code: 'csrf_failed', message: 'CSRF verification failed' } });
+                }
+            }
+            try {
+                return await route.handle(request, { context, request });
+            }
+            catch (error) {
+                return errorResponse(error);
+            }
+        },
+    };
+}
+/** Convenience constructor for a local/organization host with Objective routes only. */
+export function createObjectiveFoundationHttpHandler(options) {
+    return createFoundationHttpRouter({
+        ...options,
+        bodyLimitBytes: options.bodyLimitBytes,
+        routes: [createObjectiveFoundationRoute(options)],
+    });
+}
+export function createObjectiveFoundationRoute(options) {
+    if (!options?.objectives)
+        throw new TypeError('objectives service 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');
+    const route = {
+        name: 'foundation-objectives',
+        methods: FOUNDATION_OBJECTIVE_ROUTES.map((value) => value.split(' ', 1)[0]),
+        paths: FOUNDATION_OBJECTIVE_ROUTES,
+        matches(request) {
+            const path = requestUrl(request).pathname;
+            return path === FOUNDATION_OBJECTIVE_ROUTE_PREFIX
+                || path.startsWith(`${FOUNDATION_OBJECTIVE_ROUTE_PREFIX}/`)
+                || /^\/api\/foundation\/stories\/[^/]+\/objectives$/.test(path);
+        },
+        async handle(request, input) {
+            const url = requestUrl(request);
+            const path = url.pathname;
+            const method = (request.method || 'GET').toUpperCase();
+            if (path === FOUNDATION_OBJECTIVE_ROUTE_PREFIX) {
+                if (method === 'GET') {
+                    const list = options.objectives.list;
+                    if (!list)
+                        throw new FoundationHttpError(501, 'api_unavailable', 'Objective list API is not configured');
+                    const records = await list.call(options.objectives, 'objective', input.context);
+                    return jsonResponse(200, { state: records.length ? 'ready' : 'empty', records, absence_confirmed: true });
+                }
+                if (method === 'POST') {
+                    const body = await readJsonBody(request, bodyLimitBytes);
+                    const definition = await buildObjectiveDefinition(options, body, {
+                        operation: 'create',
+                        context: input.context,
+                    });
+                    const reference = await options.objectives.createObjective(definition, input.context);
+                    return jsonResponse(201, { state: 'saved_unverified', reference, ref: reference });
+                }
+                return methodNotAllowed(['GET', 'POST']);
+            }
+            const storyMatch = path.match(/^\/api\/foundation\/stories\/([^/]+)\/objectives$/);
+            if (storyMatch) {
+                if (method !== 'GET')
+                    return methodNotAllowed(['GET']);
+                if (!options.listStoryObjectiveLinks)
+                    throw new FoundationHttpError(501, 'api_unavailable', 'Story relation API is not configured');
+                const storyId = decodePathPart(storyMatch[1]);
+                const links = await options.listStoryObjectiveLinks(storyId, input.context);
+                return jsonResponse(200, normalizeCollectionPayload(links, 'links'));
+            }
+            const objectiveMatch = path.match(/^\/api\/foundation\/objectives\/([^/]+)(?:\/(readiness|constraints))?$/);
+            if (!objectiveMatch)
+                throw new FoundationHttpError(404, 'not_found', 'Route not found');
+            const id = decodePathPart(objectiveMatch[1]);
+            const suffix = objectiveMatch[2] ?? null;
+            const revision = positiveRevision(url.searchParams.get('revision') ?? undefined);
+            if (suffix === 'readiness') {
+                if (method !== 'GET')
+                    return methodNotAllowed(['GET']);
+                const readiness = await options.objectives.checkObjectiveReadiness(id, input.context, revision);
+                return jsonResponse(200, readinessPayload(readiness));
+            }
+            if (suffix === 'constraints') {
+                const objectiveReference = await readObjectiveReference(options, id, revision, input.context);
+                if (method === 'GET') {
+                    if (!options.listObjectiveConstraintRefs)
+                        throw new FoundationHttpError(501, 'api_unavailable', 'Constraint relation API is not configured');
+                    return jsonResponse(200, normalizeCollectionPayload(await options.listObjectiveConstraintRefs(objectiveReference, input.context), 'refs'));
+                }
+                if (method === 'PUT') {
+                    if (!options.replaceObjectiveConstraintRefs)
+                        throw new FoundationHttpError(501, 'api_unavailable', 'Constraint relation API is not configured');
+                    const body = await readJsonBody(request, bodyLimitBytes);
+                    // Validate the raw envelope before extracting `refs` so an
+                    // authority field cannot hide beside an otherwise valid collection.
+                    assertNoAuthorityFields(body);
+                    const refs = parseConstraintReferences(body);
+                    const result = await options.replaceObjectiveConstraintRefs(objectiveReference, refs, input.context);
+                    return jsonResponse(200, { state: 'saved_unverified', reference: objectiveReference, refs: result ?? refs });
+                }
+                return methodNotAllowed(['GET', 'PUT']);
+            }
+            if (method === 'GET') {
+                const record = await options.objectives.readObjective(id, input.context, revision);
+                if (!record)
+                    throw new FoundationHttpError(404, 'not_found', `Objective ${id} was not found`);
+                return jsonResponse(200, { state: 'ready', record, objective: record });
+            }
+            if (method === 'PUT') {
+                const current = await options.objectives.readObjective(id, input.context, revision);
+                if (!current || current.definition.type !== 'objective')
+                    throw new FoundationHttpError(404, 'not_found', `Objective ${id} was not found`);
+                const body = await readJsonBody(request, bodyLimitBytes);
+                const parsed = parseUpdateBody(body, request);
+                const definition = await buildObjectiveDefinition(options, parsed.body, {
+                    operation: 'update',
+                    context: input.context,
+                    current: current.definition,
+                    expectedRevision: parsed.expectedRevision,
+                });
+                const reference = await options.objectives.updateObjective(id, parsed.expectedRevision, definition, input.context);
+                return jsonResponse(200, { state: 'saved_unverified', reference, ref: reference });
+            }
+            return methodNotAllowed(['GET', 'PUT']);
+        },
+    };
+    return route;
+}
+async function readObjectiveReference(options, id, revision, context) {
+    const record = await options.objectives.readObjective(id, context, revision);
+    if (!record || record.definition.type !== 'objective')
+        throw new FoundationHttpError(404, 'not_found', `Objective ${id} was not found`);
+    return {
+        id: record.definition.id,
+        type: 'objective',
+        revision: record.definition.revision,
+        digest: record.digest,
+    };
+}
+async function buildObjectiveDefinition(options, payload, input) {
+    if (!options.buildDefinition)
+        throw new FoundationHttpError(501, 'api_unavailable', 'Objective definition builder is not configured');
+    const body = sanitizeMutationBody(payload);
+    const definition = await options.buildDefinition({ ...input, body });
+    if (!definition || definition.type !== 'objective') {
+        throw new FoundationHttpError(400, 'invalid_input', 'Objective builder returned a non-Objective definition');
+    }
+    if (!definition.id || !definition.revision)
+        throw new FoundationHttpError(400, 'invalid_input', 'Objective definition identity is incomplete');
+    if (input.operation === 'update') {
+        if (!input.current || definition.id !== input.current.id || definition.type !== input.current.type) {
+            throw new FoundationHttpError(400, 'invalid_input', 'An Objective update cannot change its logical identity');
+        }
+        if (JSON.stringify(definition.acl) !== JSON.stringify(input.current.acl)
+            || JSON.stringify(definition.scope) !== JSON.stringify(input.current.scope)
+            || JSON.stringify(definition.storage) !== JSON.stringify(input.current.storage)
+            || JSON.stringify(definition.provenance) !== JSON.stringify(input.current.provenance)
+            || JSON.stringify(definition.authorizedUses) !== JSON.stringify(input.current.authorizedUses)) {
+            throw new FoundationHttpError(403, 'authority_field_change', 'Objective authority and provenance fields are host-controlled');
+        }
+    }
+    return definition;
+}
+function parseUpdateBody(payload, request) {
+    // A PUT may carry a CAS envelope (`{ expectedRevision, definition }`).
+    // Check the envelope itself before unwrapping it; otherwise an authority
+    // field beside `definition` would be silently ignored by the builder.
+    assertNoAuthorityFields(payload);
+    const object = asRecord(payload);
+    const expectedRevision = positiveRevision(firstString(object, 'expectedRevision', 'expected_revision')
+        ?? request.headers.get('if-match')?.replace(/^W\//, '').replace(/^"|"$/g, ''));
+    if (!expectedRevision)
+        throw new FoundationHttpError(400, 'invalid_input', 'expectedRevision or If-Match is required for a CAS update');
+    return { body: object?.definition ?? payload, expectedRevision };
+}
+function sanitizeMutationBody(payload) {
+    const object = asRecord(payload);
+    if (!object)
+        throw new FoundationHttpError(400, 'invalid_input', 'JSON object body is required');
+    assertNoAuthorityFields(object);
+    const definition = { ...object };
+    delete definition.revision;
+    delete definition.expectedRevision;
+    delete definition.expected_revision;
+    if (definition.type !== undefined && definition.type !== 'objective') {
+        throw new FoundationHttpError(400, 'invalid_input', 'Objective definition type must be objective');
+    }
+    return Object.freeze(definition);
+}
+function assertNoAuthorityFields(payload) {
+    const object = asRecord(payload);
+    if (!object)
+        return;
+    for (const key of Object.keys(object)) {
+        if (AUTHORITY_FIELDS.has(key)) {
+            throw new FoundationHttpError(400, 'authority_field_in_body', `Request body cannot set ${key}`);
+        }
+    }
+}
+function parseConstraintReferences(payload) {
+    const object = asRecord(payload);
+    const values = Array.isArray(payload) ? payload : object?.refs ?? object?.references;
+    if (!Array.isArray(values))
+        throw new FoundationHttpError(400, 'invalid_input', 'refs must be an array');
+    return values.map((value, index) => {
+        const ref = asRecord(value);
+        if (!ref || ref.type !== 'constraint' || typeof ref.id !== 'string' || !positiveRevision(ref.revision)) {
+            throw new FoundationHttpError(400, 'invalid_input', `refs[${index}] must be a Constraint revision reference`);
+        }
+        return { id: ref.id, type: 'constraint', revision: ref.revision };
+    });
+}
+function readinessPayload(readiness) {
+    return { state: 'ready', ready: readiness.ready, issues: readiness.issues };
+}
+function normalizeCollectionPayload(value, key) {
+    if (Array.isArray(value))
+        return { state: value.length ? 'ready' : 'empty', [key]: value, absence_confirmed: true };
+    const object = asRecord(value);
+    if (object && Object.prototype.hasOwnProperty.call(object, key) && Array.isArray(object[key])) {
+        return {
+            ...object,
+            [key]: object[key],
+            // A collection without an explicit absence claim is not a confirmed
+            // empty result. Preserve false/unknown instead of inventing true.
+            absence_confirmed: object.absence_confirmed === true,
+        };
+    }
+    throw new FoundationHttpError(500, 'readback_mismatch', `The ${key} adapter returned an invalid collection`);
+}
+function methodNotAllowed(allow) {
+    return jsonResponse(405, { error: { code: 'method_not_allowed', message: 'Method not allowed' } }, { Allow: allow.join(', ') });
+}
+function errorResponse(error) {
+    const normalized = normalizeHttpError(error);
+    const body = {
+        error: {
+            code: normalized.code,
+            message: normalized.message,
+            ...(normalized.currentRevision ? { currentRevision: normalized.currentRevision } : {}),
+        },
+    };
+    return jsonResponse(normalized.status, body);
+}
+function normalizeHttpError(error) {
+    if (error instanceof FoundationHttpError)
+        return error;
+    if (error instanceof FoundationStoreError) {
+        const status = error.code === 'authorization_denied' || error.code === 'scope_violation' ? 403
+            : error.code === 'not_found' ? 404
+                : error.code === 'revision_conflict' ? 409
+                    : error.code === 'unsupported_graph' ? 503
+                        : error.code === 'readback_mismatch' ? 500
+                            : 400;
+        return new FoundationHttpError(status, error.code, error.message, { currentRevision: error.currentRevision });
+    }
+    if (error instanceof Error && error.name === 'FoundationHttpError') {
+        return new FoundationHttpError(500, 'internal_error', error.message);
+    }
+    return new FoundationHttpError(500, 'internal_error', 'Foundation request failed');
+}
+function jsonResponse(status, body, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            'Content-Type': 'application/json; charset=utf-8',
+            ...headers,
+        },
+    });
+}
+async function readJsonBody(request, limitBytes) {
+    const contentLength = Number(request.headers.get('content-length'));
+    if (Number.isFinite(contentLength) && contentLength > limitBytes) {
+        throw new FoundationHttpError(413, 'body_too_large', 'Request body exceeds the configured limit');
+    }
+    const text = await request.text();
+    if (!text)
+        throw new FoundationHttpError(400, 'invalid_json', 'A JSON body is required');
+    if (new TextEncoder().encode(text).byteLength > limitBytes) {
+        throw new FoundationHttpError(413, 'body_too_large', 'Request body exceeds the configured limit');
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new FoundationHttpError(400, 'invalid_json', 'Request body is not valid JSON');
+    }
+}
+function requestUrl(request) {
+    return new URL(request.url, 'http://localhost');
+}
+function decodePathPart(value) {
+    try {
+        const decoded = decodeURIComponent(value);
+        if (!decoded)
+            throw new Error('empty');
+        return decoded;
+    }
+    catch {
+        throw new FoundationHttpError(400, 'invalid_input', 'Path identifier is not valid');
+    }
+}
+function positiveRevision(value) {
+    return typeof value === 'string' && /^[1-9]\d*$/.test(value) ? value : undefined;
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function firstString(value, ...keys) {
+    if (!value)
+        return undefined;
+    for (const key of keys)
+        if (typeof value[key] === 'string')
+            return value[key];
+    return undefined;
+}

package/dist/foundation-public-provider.d.ts

@@ -0,0 +1,140 @@
+import { type PhilosophyRevisionReader } from './philosophy-revision-reader.js';
+import type { FoundationRevisionStore, FoundationStoreContext } from './foundation-store.js';
+import { type JudgmentProblemReferenceProvider } from './judgment-problem-snapshot.js';
+import type { FoundationHttpRoute } from './foundation-http.js';
+export declare const FOUNDATION_PUBLIC_CONTRACT_VERSION: "foundation-public.v1";
+/** The host owns canonical storage and authentication. No body can supply either. */
+export declare function createFoundationPublicProvider(options: {
+    store: Pick<FoundationRevisionStore, 'read'>;
+    philosophyReader?: PhilosophyRevisionReader;
+    /** Canonical Observation/authority/etc. ports; cannot override Foundation or philosophy. */
+    resolveOther?: JudgmentProblemReferenceProvider['resolve'];
+}): {
+    describe(): {
+        contractVersion: "foundation-public.v1";
+        foundation: import("./ontology-foundation.js").JudgmentFoundationContract;
+        connection: string;
+        storage: string;
+        philosophy: {
+            kind: string;
+            canonicalSource: string;
+            connected: boolean;
+            immutableRevisionRequired: boolean;
+        };
+        historicalRead: string;
+        executionPermission: string;
+    };
+    read(raw: unknown, context: FoundationStoreContext): Promise<import("./types.js").FoundationCatalogRecord | import("./philosophy-revision-reader.js").PhilosophyRevisionRecord>;
+    validate(raw: unknown, context: FoundationStoreContext): Promise<import("./judgment-problem-snapshot.js").JudgmentProblemReferenceResolution>;
+    validateProblem(raw: unknown, context: FoundationStoreContext): Promise<{
+        status: "resolved";
+        executionPermission: "none";
+    }>;
+};
+export type FoundationPublicProvider = ReturnType<typeof createFoundationPublicProvider>;
+export interface FoundationPublicConnection {
+    provider: FoundationPublicProvider;
+    resolveContext(): FoundationStoreContext | null | Promise<FoundationStoreContext | null>;
+}
+export declare const foundationPublicToolDefinitions: readonly [{
+    readonly name: "foundation_describe";
+    readonly description: "Describe the connected versioned judgment foundation contract.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+}, {
+    readonly name: "foundation_read";
+    readonly description: "Read an exact canonical foundation revision under current access rights.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["type", "id", "revision"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly type: {
+                readonly type: "string";
+                readonly enum: readonly ["objective", "variable", "model", "constraint", "philosophy"];
+            };
+            readonly id: {
+                readonly type: "string";
+            };
+            readonly revision: {
+                readonly type: "string";
+            };
+            readonly digest: {
+                readonly type: "string";
+            };
+        };
+    };
+}, {
+    readonly name: "foundation_validate_reference";
+    readonly description: "Validate an exact foundation or philosophy reference for judgment, including its dependencies.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["reference"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly reference: {
+                readonly type: "object";
+                readonly required: readonly ["kind", "id", "revision", "digest", "scope", "valid_from"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["objective", "variable", "model", "constraint", "philosophy"];
+                    };
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly revision: {
+                        readonly type: "string";
+                    };
+                    readonly digest: {
+                        readonly type: "string";
+                    };
+                    readonly scope: {
+                        readonly type: "object";
+                        readonly required: readonly ["type", "id"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["personal", "project", "organization"];
+                            };
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly valid_from: {
+                        readonly type: "string";
+                    };
+                    readonly valid_to: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                };
+            };
+            readonly phase: {
+                readonly type: "string";
+                readonly enum: readonly ["read", "historical_read"];
+            };
+        };
+    };
+}, {
+    readonly name: "foundation_validate_problem";
+    readonly description: "Validate a complete judgment snapshot and canonical observation measurement conditions. Grants no execution permission.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["snapshot"];
+        readonly properties: {
+            readonly snapshot: {
+                readonly type: "object";
+            };
+        };
+        readonly additionalProperties: false;
+    };
+}];
+export declare function callFoundationPublicTool(name: string, args: unknown, connection?: FoundationPublicConnection): Promise<unknown>;
+/** Mounted with createFoundationHttpRouter, whose host resolves auth and CSRF. */
+export declare function createFoundationPublicRoute(provider: FoundationPublicProvider): FoundationHttpRoute;