@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/graph-revision-reader.js

@@ -0,0 +1,246 @@
+import { createHash } from 'node:crypto';
+import { canonicalEdgeId, isActiveAt } from './canonical-graph.js';
+import { canonicalPortableJson } from './portable-graph.js';
+/** Immutable Graph entity/edge reads are versioned independently of Graph file releases. */
+export const GRAPH_REVISION_READ_CONTRACT_VERSION = 'graph-revision-read.v1';
+const GRAPH_KINDS = ['entity', 'edge'];
+const REVISION_PATTERN = /^[1-9]\d*$/u;
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const SCOPE_TYPES = ['personal', 'project', 'organization'];
+const ACL_VISIBILITIES = ['private', 'project', 'organization', 'public'];
+const CORE_RELATIONS = [
+    'member_of',
+    'participates_in',
+    'accountable_for',
+    'owned_by',
+    'governs',
+    'supersedes'
+];
+const ENTITY_TYPES = new Set(['person', 'org', 'project', 'decision']);
+/**
+ * Computes the stable digest used by a GraphRevisionReference.  Current ACL
+ * is intentionally excluded so an ACL change does not create a false content
+ * revision; the adapter still checks the current ACL before every read.
+ */
+export function graphRevisionDigest(input) {
+    assertGraphRevisionIdentity(input);
+    assertGraphRevisionPayload(input.kind, input.id, input.payload);
+    const content = {
+        kind: input.kind,
+        id: input.id,
+        revision: input.revision,
+        payload: input.payload
+    };
+    return `sha256:${createHash('sha256').update(canonicalPortableJson(content), 'utf8').digest('hex')}`;
+}
+/** Structural check for callers that need to validate a reference before I/O. */
+export function isGraphRevisionReference(value) {
+    if (!isPlainRecord(value) || !GRAPH_KINDS.includes(value.kind))
+        return false;
+    if (!isNonEmptyString(value.id) || !isPositiveRevision(value.revision) || !isDigest(value.digest))
+        return false;
+    return isGraphRevisionScope(value.scope);
+}
+/**
+ * Adapt Graph entity/edge reads to `JudgmentProblemReferenceProvider.resolveOther`.
+ * Unknown reference kinds remain unresolved so another provider can be composed
+ * explicitly by the caller; this resolver never treats an unhandled kind as
+ * resolved.
+ */
+export function createJudgmentProblemGraphReferenceResolver(options) {
+    if (!options || !options.reader || typeof options.reader.read !== 'function') {
+        throw new TypeError('A GraphRevisionReader is required');
+    }
+    return async (input) => {
+        const kind = input.reference.kind;
+        if (!GRAPH_KINDS.includes(kind)) {
+            return { status: 'unresolved', message: `Graph revision resolver does not handle ${input.reference.kind}` };
+        }
+        if (!isNonEmptyString(input.context.principal)) {
+            return { status: 'unauthorized', message: 'A trusted principal is required for Graph revision reads' };
+        }
+        const reference = {
+            kind,
+            id: input.reference.id,
+            revision: input.reference.revision,
+            digest: input.reference.digest,
+            scope: cloneScope(input.reference.scope)
+        };
+        if (!isGraphRevisionReference(reference)) {
+            return { status: 'unresolved', message: 'Graph revision reference is invalid' };
+        }
+        let result;
+        try {
+            result = await options.reader.read({
+                reference,
+                phase: input.phase,
+                // The scope is a requested boundary.  The host reader must bind it to
+                // its trusted tenant/project context before returning a record.
+                context: { principal: input.context.principal, scope: cloneScope(reference.scope) }
+            });
+        }
+        catch {
+            return { status: 'unresolved', message: 'Graph revision reader failed closed' };
+        }
+        if (!isPlainRecord(result) || typeof result.status !== 'string') {
+            return { status: 'unresolved', message: 'Graph revision reader returned an invalid result' };
+        }
+        if (result.status === 'missing') {
+            return { status: 'missing', message: result.message ?? 'Graph revision was not found' };
+        }
+        if (result.status === 'unauthorized') {
+            return { status: 'unauthorized', message: result.message ?? 'Graph revision is not readable' };
+        }
+        if (result.status === 'corrupt') {
+            return { status: 'unresolved', message: result.message ?? 'Graph revision failed integrity validation' };
+        }
+        if (result.status !== 'resolved' || !isPlainRecord(result.record)) {
+            return { status: 'unresolved', message: 'Graph revision reader returned an invalid resolved record' };
+        }
+        const record = result.record;
+        const integrity = validateResolvedRecord(record, reference, input.context.principal);
+        if (integrity.status !== 'resolved')
+            return integrity;
+        return { status: 'resolved', digest: reference.digest };
+    };
+}
+function validateResolvedRecord(record, reference, principal) {
+    if (!GRAPH_KINDS.includes(record.kind) || record.kind !== reference.kind ||
+        record.id !== reference.id || record.revision !== reference.revision) {
+        return { status: 'unresolved', message: 'Graph revision identity does not match the requested reference' };
+    }
+    if (!isDigest(record.digest) || record.digest !== reference.digest) {
+        return { status: 'unresolved', message: 'Graph revision digest does not match the requested reference' };
+    }
+    try {
+        assertGraphRevisionPayload(record.kind, record.id, record.payload);
+        if (graphRevisionDigest(record) !== record.digest) {
+            return { status: 'unresolved', message: 'Graph revision payload digest is corrupt' };
+        }
+    }
+    catch {
+        return { status: 'unresolved', message: 'Graph revision payload is corrupt' };
+    }
+    if (!isGraphRevisionAcl(record.currentAcl) || !isGraphRevisionScope(record.currentScope)) {
+        return { status: 'unresolved', message: 'Graph revision authorization metadata is corrupt' };
+    }
+    if (!sameScope(record.currentScope, reference.scope)) {
+        return { status: 'unauthorized', message: 'Graph revision is outside the requested tenant/project scope' };
+    }
+    if (!canReadGraphRevision(record.currentAcl, principal)) {
+        return { status: 'unauthorized', message: 'Graph revision is not readable by the current principal' };
+    }
+    return { status: 'resolved', digest: reference.digest };
+}
+function assertGraphRevisionIdentity(value) {
+    if (!GRAPH_KINDS.includes(value.kind) || !isNonEmptyString(value.id) || !isPositiveRevision(value.revision)) {
+        throw new TypeError('Graph revision identity requires kind, id, and a positive revision');
+    }
+}
+function assertGraphRevisionPayload(kind, id, payload) {
+    if (!isPlainRecord(payload) || payload.id !== id)
+        throw new TypeError('Graph revision payload id does not match its reference');
+    if (kind === 'entity') {
+        if (!ENTITY_TYPES.has(payload.type) || !isNonEmptyString(payload.name)) {
+            throw new TypeError('Graph entity revision payload is invalid');
+        }
+        assertOptionalStringArray(payload.aliases);
+        assertOptionalString(payload.summary);
+        assertOptionalStringArray(payload.tags);
+        assertOptionalRecord(payload.metadata);
+        assertOptionalValidity(payload.validFrom, payload.validTo);
+        return;
+    }
+    if (!isNonEmptyString(payload.fromId) || !isNonEmptyString(payload.toId) ||
+        !CORE_RELATIONS.includes(payload.relation) ||
+        canonicalEdgeId({
+            fromId: payload.fromId,
+            relation: payload.relation,
+            toId: payload.toId
+        }) !== id) {
+        throw new TypeError('Graph edge revision payload is invalid');
+    }
+    assertOptionalString(payload.role);
+    assertOptionalString(payload.context);
+    assertOptionalValidity(payload.validFrom, payload.validTo);
+    if (payload.provenance !== undefined) {
+        if (!isPlainRecord(payload.provenance) ||
+            !['user_approved', 'migration', 'import', 'onboarding'].includes(String(payload.provenance.sourceKind))) {
+            throw new TypeError('Graph edge provenance is invalid');
+        }
+        assertOptionalString(payload.provenance.sourceId);
+        assertOptionalString(payload.provenance.evidenceHash);
+    }
+}
+function isGraphRevisionAcl(value) {
+    if (!isPlainRecord(value) || !isNonEmptyString(value.ownerId) ||
+        !ACL_VISIBILITIES.includes(value.visibility) ||
+        !isStringArray(value.readerIds) || !isStringArray(value.writerIds))
+        return false;
+    return new Set(value.readerIds).size === value.readerIds.length && new Set(value.writerIds).size === value.writerIds.length;
+}
+function canReadGraphRevision(acl, principal) {
+    return acl.visibility === 'public' || acl.ownerId === principal ||
+        acl.readerIds.includes(principal) || acl.writerIds.includes(principal);
+}
+function isGraphRevisionScope(value) {
+    return isPlainRecord(value) && SCOPE_TYPES.includes(value.type) && isNonEmptyString(value.id);
+}
+function sameScope(left, right) {
+    return left.type === right.type && left.id === right.id;
+}
+function cloneScope(scope) {
+    return { type: scope.type, id: scope.id };
+}
+function isDigest(value) {
+    return typeof value === 'string' && DIGEST_PATTERN.test(value);
+}
+function isPositiveRevision(value) {
+    return typeof value === 'string' && REVISION_PATTERN.test(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 && !value.includes('\0');
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => isNonEmptyString(item));
+}
+function assertOptionalString(value) {
+    if (value !== undefined && typeof value !== 'string')
+        throw new TypeError('Optional Graph revision text must be a string');
+}
+function assertOptionalStringArray(value) {
+    if (value !== undefined && !isStringArray(value))
+        throw new TypeError('Optional Graph revision string array is invalid');
+}
+function assertOptionalRecord(value) {
+    if (value !== undefined && !isPlainRecord(value))
+        throw new TypeError('Optional Graph revision metadata must be a record');
+}
+function assertOptionalValidity(from, to) {
+    if (from !== undefined && !isRfc3339(from))
+        throw new TypeError('Graph revision validFrom is invalid');
+    if (to !== undefined && !isRfc3339(to))
+        throw new TypeError('Graph revision validTo is invalid');
+    if (typeof from === 'string' && typeof to === 'string' && Date.parse(from) > Date.parse(to)) {
+        throw new TypeError('Graph revision validity interval is invalid');
+    }
+}
+function isRfc3339(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        // Reuse the canonical Graph calendar validation so historical revision
+        // payloads and current Graph reads reject the same malformed timestamps.
+        isActiveAt({ validFrom: value }, value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const GRAPH_WEB_HTTP_VERSION: "graph-web-http.v1";
+export interface GraphWebHttpOptions {
+    /** Personal OS data directory chosen by the host. Never taken from the request. */
+    readonly dataDir: string;
+    readonly basePath?: string;
+    /**
+     * Called before a write request body is read. The host checks its per-launch
+     * token and same origin here and throws to refuse the write. Without it every
+     * write is refused.
+     */
+    readonly assertWriteAllowed?: (request: IncomingMessage) => void | Promise<void>;
+    readonly now?: () => Date;
+}
+export type GraphWebHttpHandler = (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+/**
+ * Node-style handler for the local Graph read and correction API:
+ *
+ * - `GET {base}/status`, `GET {base}/projects`, `GET {base}/projects/:id`
+ * - `GET {base}/search?q=&type=&as_of=&limit=`, `GET {base}/entities/:id`, `GET {base}/ontology`
+ * - `POST {base}/corrections`
+ *
+ * It returns `false` for any other path so the host can compose other handlers
+ * under the same base path. It never starts a server.
+ */
+export declare function createGraphWebHttpHandler(options: GraphWebHttpOptions): GraphWebHttpHandler;

package/dist/graph-web-http.js

@@ -0,0 +1,215 @@
+import { applyGraphCorrection, GraphCorrectionError } from './graph-corrections.js';
+import { GraphWebError, listGraphProjects, readGraphEntity, readGraphOntology, readGraphProject, readGraphWebStatus, searchGraphEntities } from './graph-web.js';
+export const GRAPH_WEB_HTTP_VERSION = 'graph-web-http.v1';
+const DEFAULT_BASE_PATH = '/api/graph';
+const MAX_BODY_BYTES = 16 * 1024;
+class HttpError extends Error {
+    statusCode;
+    code;
+    extra;
+    headers;
+    constructor(statusCode, code, message, extra = {}, headers = {}) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.extra = extra;
+        this.headers = headers;
+    }
+}
+/**
+ * Node-style handler for the local Graph read and correction API:
+ *
+ * - `GET {base}/status`, `GET {base}/projects`, `GET {base}/projects/:id`
+ * - `GET {base}/search?q=&type=&as_of=&limit=`, `GET {base}/entities/:id`, `GET {base}/ontology`
+ * - `POST {base}/corrections`
+ *
+ * It returns `false` for any other path so the host can compose other handlers
+ * under the same base path. It never starts a server.
+ */
+export function createGraphWebHttpHandler(options) {
+    if (typeof options.dataDir !== 'string' || options.dataDir.trim() === '') {
+        throw new TypeError('dataDir is required');
+    }
+    const basePath = (options.basePath ?? DEFAULT_BASE_PATH).replace(/\/+$/u, '');
+    const now = options.now ?? (() => new Date());
+    const dataDir = options.dataDir;
+    return async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://localhost');
+        let route;
+        try {
+            route = matchRoute(url.pathname, basePath);
+        }
+        catch (error) {
+            if (error instanceof HttpError) {
+                writeError(response, error);
+                return true;
+            }
+            throw error;
+        }
+        if (!route)
+            return false;
+        try {
+            if (route.name === 'corrections') {
+                if (request.method !== 'POST')
+                    throw methodNotAllowed('POST');
+                await assertWriteAllowed(options.assertWriteAllowed, request);
+                const body = await readJsonBody(request);
+                const result = await applyGraphCorrection(dataDir, body, { now: now() });
+                writeJson(response, 201, result);
+                return true;
+            }
+            if (request.method !== 'GET')
+                throw methodNotAllowed('GET');
+            const asOf = queryValue(url, 'as_of');
+            const readOptions = { ...(asOf !== undefined ? { asOf } : {}), now: now() };
+            switch (route.name) {
+                case 'status':
+                    writeJson(response, 200, await readGraphWebStatus(dataDir, readOptions));
+                    break;
+                case 'projects':
+                    writeJson(response, 200, await listGraphProjects(dataDir, readOptions));
+                    break;
+                case 'project':
+                    writeJson(response, 200, await readGraphProject(dataDir, route.id, readOptions));
+                    break;
+                case 'search':
+                    writeJson(response, 200, await searchGraphEntities(dataDir, {
+                        q: queryValue(url, 'q'),
+                        type: queryValue(url, 'type'),
+                        asOf,
+                        limit: parseLimit(queryValue(url, 'limit')),
+                        now: readOptions.now
+                    }));
+                    break;
+                case 'entity':
+                    writeJson(response, 200, await readGraphEntity(dataDir, route.id, readOptions));
+                    break;
+                case 'ontology':
+                    writeJson(response, 200, await readGraphOntology(dataDir, readOptions));
+                    break;
+            }
+        }
+        catch (error) {
+            writeError(response, toHttpError(error));
+        }
+        return true;
+    };
+}
+function matchRoute(pathname, basePath) {
+    if (pathname !== basePath && !pathname.startsWith(`${basePath}/`))
+        return undefined;
+    const rest = pathname.slice(basePath.length);
+    if (rest === '/status')
+        return { name: 'status' };
+    if (rest === '/projects')
+        return { name: 'projects' };
+    if (rest === '/search')
+        return { name: 'search' };
+    if (rest === '/ontology')
+        return { name: 'ontology' };
+    if (rest === '/corrections')
+        return { name: 'corrections' };
+    const match = /^\/(projects|entities)\/([^/]+)$/u.exec(rest);
+    if (!match)
+        return undefined;
+    let id;
+    try {
+        id = decodeURIComponent(match[2]);
+    }
+    catch {
+        throw new HttpError(400, 'invalid_id', 'The id in the path is not valid percent-encoding');
+    }
+    if (id.trim() === '' || id.length > 500)
+        throw new HttpError(400, 'invalid_id', 'The id in the path is not valid');
+    return { name: match[1] === 'projects' ? 'project' : 'entity', id };
+}
+async function assertWriteAllowed(guard, request) {
+    if (!guard) {
+        throw new HttpError(403, 'write_protection_missing', 'Writes are disabled because the host did not provide write protection');
+    }
+    try {
+        await guard(request);
+    }
+    catch (error) {
+        const candidate = error;
+        const statusCode = typeof candidate.statusCode === 'number' && candidate.statusCode >= 400 && candidate.statusCode < 500
+            ? candidate.statusCode
+            : 403;
+        const code = typeof candidate.code === 'string' && candidate.code ? candidate.code : 'write_not_allowed';
+        const message = typeof candidate.message === 'string' && candidate.message ? candidate.message : 'Write is not allowed';
+        throw new HttpError(statusCode, code, message);
+    }
+}
+async function readJsonBody(request) {
+    const contentType = String(request.headers['content-type'] ?? '');
+    if (!contentType.toLowerCase().startsWith('application/json')) {
+        throw new HttpError(415, 'unsupported_media_type', 'Content-Type must be application/json');
+    }
+    const declared = Number(request.headers['content-length']);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        throw new HttpError(413, 'payload_too_large', 'Request body is too large');
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_BODY_BYTES)
+            throw new HttpError(413, 'payload_too_large', 'Request body is too large');
+        chunks.push(buffer);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new HttpError(400, 'invalid_json', 'Request body must be JSON');
+    }
+}
+function toHttpError(error) {
+    if (error instanceof HttpError)
+        return error;
+    if (error instanceof GraphCorrectionError) {
+        if (error.kind === 'conflict') {
+            return new HttpError(409, error.code, error.message, error.current ? { current: error.current } : {});
+        }
+        const status = error.kind === 'invalid' ? 400
+            : error.kind === 'not_found' ? 404
+                : error.kind === 'migration_required' ? 409
+                    : 500;
+        return new HttpError(status, error.code, error.message);
+    }
+    if (error instanceof GraphWebError) {
+        const status = error.kind === 'invalid' ? 400 : error.kind === 'not_found' ? 404 : 503;
+        return new HttpError(status, error.code, error.message);
+    }
+    // Canonical files that cannot be read or written are reported, never hidden.
+    return new HttpError(500, 'graph_operation_failed', error instanceof Error ? error.message : 'Unexpected error');
+}
+function methodNotAllowed(allow) {
+    return new HttpError(405, 'method_not_allowed', `Use ${allow}`, {}, { Allow: allow });
+}
+function queryValue(url, key) {
+    const value = url.searchParams.get(key);
+    return value === null ? undefined : value;
+}
+function parseLimit(value) {
+    if (value === undefined || value === '')
+        return undefined;
+    if (!/^\d+$/u.test(value))
+        throw new HttpError(400, 'invalid_query', 'limit must be a positive integer');
+    return Number(value);
+}
+function writeJson(response, statusCode, body, headers = {}) {
+    if (response.headersSent)
+        return;
+    response.statusCode = statusCode;
+    response.setHeader('Content-Type', 'application/json; charset=utf-8');
+    response.setHeader('Cache-Control', 'no-store');
+    response.setHeader('X-Content-Type-Options', 'nosniff');
+    for (const [name, value] of Object.entries(headers))
+        response.setHeader(name, value);
+    response.end(JSON.stringify(body));
+}
+function writeError(response, error) {
+    writeJson(response, error.statusCode, { error: { code: error.code, message: error.message, ...error.extra } }, error.headers);
+}