@unson/brainbase-mcp 0.21.1 → 0.22.0

package/dist/meeting-minutes-storage-http.js

@@ -0,0 +1,312 @@
+import { createHash } from 'node:crypto';
+import { MeetingMinutesError, } from './meeting-minutes.js';
+import { MeetingMinutesStorageControllerError, } from './meeting-minutes-storage-controller.js';
+import { LocalWebHttpError, readJsonObjectBody, requestUrl, writeHttpError, writeJson, } from './local-web-security.js';
+/** HTTP boundary for host supplied native/external minutes placement. */
+export const MEETING_MINUTES_STORAGE_HTTP_VERSION = 'brainbase.meeting-minutes-storage-http.v1';
+export const MEETING_MINUTES_STORAGE_HTTP_PREFIX = '/api/meeting-minutes';
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 200;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeBasePath(path) {
+    const value = (path ?? MEETING_MINUTES_STORAGE_HTTP_PREFIX).trim().replace(/\/+$/u, '');
+    if (!value.startsWith('/') || value === '')
+        throw new TypeError('basePath must be an absolute path');
+    return value;
+}
+function decodePathSegment(value) {
+    try {
+        const decoded = decodeURIComponent(value);
+        return decoded === '' || decoded.includes('/') ? undefined : decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
+function routeFor(pathname, basePath) {
+    if (pathname === basePath)
+        return { kind: 'collection' };
+    if (!pathname.startsWith(`${basePath}/`))
+        return undefined;
+    const rawSegments = pathname.slice(basePath.length + 1).split('/');
+    if (rawSegments.some((segment) => segment === ''))
+        return { kind: 'meeting' };
+    const segments = rawSegments.map(decodePathSegment);
+    if (segments.some((segment) => segment === undefined))
+        return { kind: 'meeting' };
+    const [meetingId, noun, minutesId, action, versionId] = segments;
+    if (!meetingId)
+        return { kind: 'meeting' };
+    if (segments.length === 1)
+        return { kind: 'meeting', meetingId };
+    if (segments.length === 2 && noun === 'minutes')
+        return { kind: 'minutes', meetingId };
+    if (segments.length === 3 && noun === 'minutes' && minutesId)
+        return { kind: 'save', meetingId, minutesId };
+    if (segments.length === 4 && noun === 'minutes' && minutesId && action === 'confirm') {
+        return { kind: 'confirm', meetingId, minutesId };
+    }
+    if (segments.length === 5 && noun === 'minutes' && minutesId && action === 'versions' && versionId) {
+        return { kind: 'version', meetingId, minutesId, versionId };
+    }
+    return { kind: 'meeting' };
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`);
+    return `{${entries.join(',')}}`;
+}
+function headerValue(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    return typeof value === 'string' ? value : undefined;
+}
+function idempotencyKey(request) {
+    const value = headerValue(request, 'idempotency-key');
+    if (value === undefined)
+        return undefined;
+    const key = value.trim();
+    if (key === '' || key.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+        throw new LocalWebHttpError(422, 'invalid_idempotency_key', 'Idempotency-Key must be 1–200 characters');
+    }
+    return key;
+}
+function requestFingerprint(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex')}`;
+}
+function idempotencyFields(key, fingerprint) {
+    if (key === undefined || fingerprint === undefined)
+        return {};
+    return { idempotency_key: key, idempotency_fingerprint: fingerprint };
+}
+function hasOwn(body, key) {
+    return Object.prototype.hasOwnProperty.call(body, key);
+}
+function text(value, label) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new MeetingMinutesError('invalid_input', `${label} is required`);
+    return value.trim();
+}
+function optionalText(value, label) {
+    if (value === undefined)
+        return undefined;
+    return text(value, label);
+}
+function placement(value, fallbackBody, fallbackLabel) {
+    if (value === undefined) {
+        return { kind: 'native', body: fallbackBody === undefined ? '' : text(fallbackBody, fallbackLabel) };
+    }
+    if (!isRecord(value) || (value.kind !== 'native' && value.kind !== 'external')) {
+        throw new MeetingMinutesError('invalid_input', 'placement.kind must be native or external');
+    }
+    if (value.kind === 'native') {
+        // Keep an omitted native body distinguishable from an explicit empty body.
+        // Rebind uses the former to copy the current exact source under ACL; create
+        // and save operations still normalize it to an empty native body in the
+        // controller when no body was supplied.
+        return { kind: 'native', body: value.body === undefined ? undefined : text(value.body, 'placement.body') };
+    }
+    if (hasOwn(value, 'body'))
+        throw new MeetingMinutesError('invalid_input', 'External placement must not carry a native body');
+    return {
+        kind: 'external',
+        provider: text(value.provider, 'placement.provider'),
+        locator: text(value.locator, 'placement.locator'),
+    };
+}
+function rebindPlacement(body) {
+    if (hasOwn(body, 'placement'))
+        return placement(body.placement, body.body, 'body');
+    // An omitted body means “keep the current exact version” for native rebind.
+    // This lets the controller read an external current body under the current
+    // ACL instead of replacing it with an empty native version.
+    if (!hasOwn(body, 'body'))
+        return { kind: 'native' };
+    return { kind: 'native', body: text(body.body, 'body') };
+}
+function createInput(body, key, fingerprint) {
+    return {
+        title: text(body.title, 'title'),
+        scheduled_at: optionalText(body.scheduled_at, 'scheduled_at'),
+        ended_at: optionalText(body.ended_at, 'ended_at'),
+        participant_ids: Array.isArray(body.participant_ids) ? body.participant_ids : undefined,
+        metadata: isRecord(body.metadata) ? body.metadata : undefined,
+        minutes_title: optionalText(body.minutes_title, 'minutes_title'),
+        minutes_metadata: isRecord(body.minutes_metadata) ? body.minutes_metadata : undefined,
+        ...idempotencyFields(key, fingerprint),
+    };
+}
+function createMinutesInput(body, key, fingerprint) {
+    return {
+        title: optionalText(body.title, 'title'),
+        metadata: isRecord(body.metadata) ? body.metadata : undefined,
+        expected_revision: body.expected_revision,
+        ...idempotencyFields(key, fingerprint),
+    };
+}
+function saveInput(body, minutesId, meetingId, key, fingerprint) {
+    return {
+        meeting_id: meetingId,
+        minutes_id: minutesId,
+        metadata: isRecord(body.metadata) ? body.metadata : undefined,
+        expected_revision: body.expected_revision,
+        predecessor_version_id: optionalText(body.predecessor_version_id, 'predecessor_version_id'),
+        ...idempotencyFields(key, fingerprint),
+    };
+}
+function confirmInput(body, meetingId, minutesId, key, fingerprint) {
+    return {
+        meeting_id: meetingId,
+        minutes_id: minutesId,
+        version_id: text(body.version_id, 'version_id'),
+        expected_revision: body.expected_revision,
+        ...idempotencyFields(key, fingerprint),
+    };
+}
+function versionPayload(resolved) {
+    const body = resolved.body === undefined ? {} : { body: resolved.body };
+    return {
+        ...resolved.version,
+        ...body,
+        placement: resolved.placement,
+        source_status: resolved.source_status,
+        ...(resolved.capabilities ? { capabilities: resolved.capabilities } : {}),
+        ...(resolved.source_result ? { source_result: resolved.source_result } : {}),
+        ...(resolved.reason ? { reason: resolved.reason } : {}),
+    };
+}
+function statusForStorageError(error) {
+    switch (error.code) {
+        case 'source_denied': return 403;
+        case 'source_changed': return 409;
+        case 'source_unavailable': return 503;
+        case 'idempotency_conflict': return 409;
+        case 'invalid_configuration': return 422;
+        case 'storage_unavailable': return 500;
+    }
+}
+function operationError(error) {
+    if (error instanceof MeetingMinutesError) {
+        const statusCode = error.code === 'invalid_input' ? 422
+            : error.code === 'not_found' ? 404
+                : error.code === 'authorization_denied' ? 403
+                    : error.code === 'revision_conflict' || error.code === 'idempotency_conflict' ? 409 : 500;
+        return { statusCode, body: { error: { code: error.code, message: error.message } } };
+    }
+    if (error instanceof MeetingMinutesStorageControllerError) {
+        return { statusCode: statusForStorageError(error), body: { error: { code: error.code, message: error.message } } };
+    }
+    return { statusCode: 500, body: { error: { code: 'internal_error', message: 'Meeting minutes request failed' } } };
+}
+export function createMeetingMinutesStorageHttpHandler(options) {
+    if (!options || !options.store || !options.controller || typeof options.resolveContext !== 'function') {
+        throw new TypeError('store, controller and resolveContext are required');
+    }
+    const basePath = normalizeBasePath(options.basePath);
+    const bodyLimitBytes = options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes <= 0)
+        throw new TypeError('bodyLimitBytes must be a positive integer');
+    async function execute(route, body, context, key, fingerprint) {
+        try {
+            switch (route.kind) {
+                case 'collection': {
+                    if (body === undefined) {
+                        return { statusCode: 200, body: { state: 'ready', meetings: await options.store.list_meetings(context), absence_confirmed: true } };
+                    }
+                    const input = createInput(body, key, fingerprint);
+                    return {
+                        statusCode: 201,
+                        body: await options.controller.create_meeting(input, placement(body.placement, body.initial_body, 'initial_body'), context),
+                    };
+                }
+                case 'meeting':
+                    return { statusCode: 200, body: await options.store.get_meeting(route.meetingId ?? '', context) };
+                case 'minutes': {
+                    if (body === undefined)
+                        throw new MeetingMinutesError('invalid_input', 'Request body is required');
+                    return {
+                        statusCode: 201,
+                        body: await options.controller.create_minutes(route.meetingId ?? '', createMinutesInput(body, key, fingerprint), placement(body.placement, body.body, 'body'), context),
+                    };
+                }
+                case 'save': {
+                    if (body === undefined)
+                        throw new MeetingMinutesError('invalid_input', 'Request body is required');
+                    const before = await options.store.get_meeting(route.meetingId ?? '', context);
+                    if (!before.minutes.some((candidate) => candidate.minutes_id === route.minutesId)) {
+                        throw new MeetingMinutesError('not_found', `Minutes document ${route.minutesId} was not found`);
+                    }
+                    const after = await options.controller.rebind(saveInput(body, route.minutesId ?? '', route.meetingId ?? '', key, fingerprint), rebindPlacement(body), context);
+                    // The controller detail intentionally omits native audit timestamps.
+                    // Read the canonical store again for lifecycle hooks so they receive
+                    // the same exact version shape as the native HTTP handler while the
+                    // response keeps the controller's placement fields.
+                    const lineageAfter = options.afterSave
+                        ? await options.store.get_meeting(route.meetingId ?? '', context)
+                        : undefined;
+                    const lineage = options.afterSave && lineageAfter
+                        ? await options.afterSave({ before, after: lineageAfter, context })
+                        : undefined;
+                    return {
+                        statusCode: 201,
+                        body: lineage === undefined ? after : { ...after, lineage },
+                    };
+                }
+                case 'confirm': {
+                    if (body === undefined)
+                        throw new MeetingMinutesError('invalid_input', 'Request body is required');
+                    return {
+                        statusCode: 200,
+                        body: await options.controller.confirm_version(confirmInput(body, route.meetingId ?? '', route.minutesId ?? '', key, fingerprint), context),
+                    };
+                }
+                case 'version':
+                    return {
+                        statusCode: 200,
+                        body: versionPayload(await options.controller.get_version(route.meetingId ?? '', route.minutesId ?? '', route.versionId ?? '', context)),
+                    };
+            }
+        }
+        catch (error) {
+            return operationError(error);
+        }
+    }
+    return async (request, response) => {
+        const path = requestUrl(request).pathname;
+        const route = routeFor(path, basePath);
+        if (!route)
+            return false;
+        const method = (request.method ?? 'GET').toUpperCase();
+        const allowed = route.kind === 'collection' ? ['GET', 'POST']
+            : route.kind === 'meeting' || route.kind === 'version' ? ['GET'] : ['POST'];
+        if (!allowed.includes(method)) {
+            response.setHeader('Allow', allowed.join(', '));
+            writeJson(response, 405, { error: { code: 'method_not_allowed', message: `Use ${allowed.join(' or ')}` } });
+            return true;
+        }
+        try {
+            const context = await options.resolveContext(request);
+            if (!context || typeof context.principal_id !== 'string' || context.principal_id.trim() === '') {
+                throw new LocalWebHttpError(401, 'authorization_required', 'A trusted meeting-minutes principal is required');
+            }
+            const body = method === 'POST' ? await readJsonObjectBody(request, bodyLimitBytes) : undefined;
+            const key = method === 'POST' ? idempotencyKey(request) : undefined;
+            const fingerprint = key === undefined ? undefined : requestFingerprint({ method, path, body: body ?? null });
+            const result = await execute(route, body, context, key, fingerprint);
+            writeJson(response, result.statusCode, result.body);
+        }
+        catch (error) {
+            if (error instanceof LocalWebHttpError)
+                writeHttpError(response, error);
+            else
+                writeJson(response, 500, { error: { code: 'internal_error', message: 'Meeting minutes request failed' } });
+        }
+        return true;
+    };
+}

package/dist/meeting-minutes-storage.d.ts

@@ -0,0 +1,169 @@
+/** The first real provider adapter. Its root is supplied by the customer. */
+export declare const FILESYSTEM_MEETING_MINUTES_ADAPTER: "filesystem";
+export interface MeetingMinutesStorageCapabilities {
+    readonly save: false;
+    readonly read: true;
+    readonly read_only: true;
+    readonly history: false;
+    /** ACL is supplied by the organization boundary for every operation. */
+    readonly current_acl: 'injected';
+    readonly retention_delete: false;
+}
+export type MeetingMinutesStorageAuthorizationOperation = 'register' | 'read' | 'read_history' | 'retention_delete';
+/** Context resolved by the host before calling the adapter. */
+export interface MeetingMinutesStorageRequestContext {
+    readonly principal_id: string;
+}
+export type MeetingMinutesAuthorizationTarget = {
+    readonly locator: string;
+    readonly reference?: never;
+} | {
+    readonly reference: MeetingMinutesExternalReference;
+    readonly locator?: never;
+};
+/** Result produced by the host-injected authorization callback. */
+export interface MeetingMinutesAuthorizationDecision {
+    readonly allowed: boolean;
+    readonly reason?: string;
+    readonly checked_at?: string;
+}
+export type MeetingMinutesAuthorize = (context: MeetingMinutesStorageRequestContext, operation: MeetingMinutesStorageAuthorizationOperation, target: MeetingMinutesAuthorizationTarget) => MeetingMinutesAuthorizationDecision | boolean | Promise<MeetingMinutesAuthorizationDecision | boolean>;
+export interface MeetingMinutesExternalProvenance {
+    readonly source: 'external';
+    readonly adapter: typeof FILESYSTEM_MEETING_MINUTES_ADAPTER;
+    readonly observed_at: string;
+}
+/** A locator and exact source version; it never contains the external body. */
+export interface MeetingMinutesExternalReference {
+    readonly provider: string;
+    /** Root-relative POSIX path for the filesystem adapter. */
+    readonly locator: string;
+    /** Content-addressed revision because a plain filesystem has no history API. */
+    readonly revision: string;
+    readonly digest: string;
+    readonly provenance: MeetingMinutesExternalProvenance;
+}
+export interface FilesystemMeetingMinutesAdapterOptions {
+    /** Absolute customer-configured root. No default is inferred. */
+    readonly root: string;
+    readonly provider?: string;
+    /** Host-owned ACL check; called before every register/read/history/delete operation. */
+    readonly authorize: MeetingMinutesAuthorize;
+    /** Maximum external source size accepted by the read-only adapter. */
+    readonly max_bytes?: number;
+}
+export interface MeetingMinutesRegisterRequest {
+    readonly locator: string;
+    readonly request_context: MeetingMinutesStorageRequestContext;
+}
+export interface MeetingMinutesReadRequest {
+    readonly reference: MeetingMinutesExternalReference;
+    readonly request_context: MeetingMinutesStorageRequestContext;
+}
+/**
+ * Read a source reference persisted by the provider-independent minutes core.
+ *
+ * The core deliberately keeps only provider/locator/revision/digest.  The
+ * adapter recreates its local provenance for this read; the observed source
+ * body still has to pass the exact revision and digest checks below.
+ */
+export interface MeetingMinutesReadSourceRequest {
+    readonly source_ref: {
+        readonly provider: string;
+        readonly locator: string;
+        readonly revision: string;
+        readonly digest: string;
+        readonly provenance?: Readonly<Record<string, unknown>>;
+    };
+    readonly request_context: MeetingMinutesStorageRequestContext;
+}
+export interface MeetingMinutesSaveRequest {
+    readonly reference?: MeetingMinutesExternalReference;
+    readonly body?: string;
+}
+export interface MeetingMinutesDeleteRequest {
+    readonly reference: MeetingMinutesExternalReference;
+    readonly request_context: MeetingMinutesStorageRequestContext;
+}
+export type MeetingMinutesUnavailableStatus = 'not_found' | 'symlink_rejected' | 'unavailable' | 'too_large' | 'invalid_encoding';
+export interface MeetingMinutesRegisterResultBase {
+    readonly capabilities: MeetingMinutesStorageCapabilities;
+}
+export type MeetingMinutesRegisterResult = MeetingMinutesRegisterResultBase & ({
+    readonly status: 'registered';
+    readonly reference: MeetingMinutesExternalReference;
+} | {
+    readonly status: 'denied' | 'invalid_locator' | MeetingMinutesUnavailableStatus;
+    readonly reason: string;
+});
+export type MeetingMinutesReadResult = MeetingMinutesRegisterResultBase & ({
+    readonly status: 'available';
+    readonly reference: MeetingMinutesExternalReference;
+    readonly body: string;
+} | {
+    readonly status: 'denied' | 'invalid_reference' | MeetingMinutesUnavailableStatus;
+    readonly reason: string;
+} | {
+    readonly status: 'integrity_mismatch';
+    readonly reason: string;
+    /** Metadata only; the changed body is deliberately not returned. */
+    readonly observed_reference: MeetingMinutesExternalReference;
+});
+export type MeetingMinutesUnsupportedOperation = MeetingMinutesRegisterResultBase & {
+    readonly status: 'unsupported';
+    readonly operation: 'save' | 'read_history' | 'retention_delete';
+    readonly capability: 'save' | 'history' | 'retention_delete';
+    readonly reason: string;
+};
+export type MeetingMinutesHistoryResult = MeetingMinutesUnsupportedOperation | (MeetingMinutesRegisterResultBase & {
+    readonly status: 'denied';
+    readonly reason: string;
+});
+export type MeetingMinutesDeleteResult = MeetingMinutesUnsupportedOperation | (MeetingMinutesRegisterResultBase & {
+    readonly status: 'denied';
+    readonly reason: string;
+});
+export interface MeetingMinutesStorageAdapter {
+    readonly capabilities: MeetingMinutesStorageCapabilities;
+    register(input: MeetingMinutesRegisterRequest): Promise<MeetingMinutesRegisterResult>;
+    read(input: MeetingMinutesReadRequest): Promise<MeetingMinutesReadResult>;
+    /** Resolve a core source_ref without asking callers to fabricate provenance. */
+    read_source?(input: MeetingMinutesReadSourceRequest): Promise<MeetingMinutesReadResult>;
+    read_history(input: MeetingMinutesReadRequest): Promise<MeetingMinutesHistoryResult>;
+    save(input: MeetingMinutesSaveRequest): Promise<MeetingMinutesUnsupportedOperation>;
+    delete(input: MeetingMinutesDeleteRequest): Promise<MeetingMinutesDeleteResult>;
+}
+/**
+ * Read-only adapter for a customer-selected filesystem root.
+ *
+ * The adapter keeps no native copy and performs no external write. A plain
+ * filesystem has no historical version contract, so old references fail with
+ * an integrity mismatch when the current file changes.
+ */
+export declare class FilesystemMeetingMinutesAdapter implements MeetingMinutesStorageAdapter {
+    readonly capabilities: MeetingMinutesStorageCapabilities;
+    private readonly root;
+    private readonly provider;
+    private readonly authorize;
+    private readonly maxBytes;
+    constructor(options: FilesystemMeetingMinutesAdapterOptions);
+    register(input: MeetingMinutesRegisterRequest): Promise<MeetingMinutesRegisterResult>;
+    read(input: MeetingMinutesReadRequest): Promise<MeetingMinutesReadResult>;
+    read_source(input: MeetingMinutesReadSourceRequest): Promise<MeetingMinutesReadResult>;
+    read_history(input: MeetingMinutesReadRequest): Promise<MeetingMinutesHistoryResult>;
+    save(_input: MeetingMinutesSaveRequest): Promise<MeetingMinutesUnsupportedOperation>;
+    delete(input: MeetingMinutesDeleteRequest): Promise<MeetingMinutesDeleteResult>;
+    private authorizationFailure;
+    private readStableFile;
+    private registerFailure;
+    private readFailure;
+    private unsupported;
+    private reference;
+    private referenceFailure;
+    private resolveFile;
+}
+export declare class MeetingMinutesStorageError extends Error {
+    readonly code: 'invalid_configuration';
+    constructor(code: 'invalid_configuration', message: string);
+}
+export declare function createFilesystemMeetingMinutesAdapter(options: FilesystemMeetingMinutesAdapterOptions): FilesystemMeetingMinutesAdapter;