@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/resource-reservation-http.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ResourceReservationService } from './resource-reservations.js';
+type MaybePromise<T> = T | Promise<T>;
+/** Context resolved by the host after authentication and tenant selection. */
+export interface TrustedResourceReservationRequestContext {
+    tenantId: string;
+    principal: string;
+    scopeId: string;
+    /** A non-empty value means that the host already verified the mutation origin. */
+    verifiedMutationOrigin?: string;
+}
+/** The factory is the boundary where a host binds a service to its trusted context. */
+export type ResourceReservationServiceFactory = (context: TrustedResourceReservationRequestContext) => MaybePromise<ResourceReservationService>;
+export interface ResourceReservationMutationVerificationInput {
+    request: IncomingMessage;
+    context: TrustedResourceReservationRequestContext;
+}
+export interface ResourceReservationHttpOptions {
+    serviceFactory: ResourceReservationServiceFactory;
+    basePath?: string;
+    bodyLimitBytes?: number;
+    /** Required for hosts that do not attach verifiedMutationOrigin to context. */
+    verifyMutationRequest?: (input: ResourceReservationMutationVerificationInput) => MaybePromise<boolean>;
+}
+/**
+ * A composable route handler.  `false` means that the request is outside this
+ * route and may be passed to the host's next handler.
+ */
+export type ResourceReservationHttpHandler = (request: IncomingMessage, response: ServerResponse, context: TrustedResourceReservationRequestContext | null) => Promise<boolean>;
+export declare function createResourceReservationHttpHandler(options: ResourceReservationHttpOptions): ResourceReservationHttpHandler;
+export {};

package/dist/resource-reservation-http.js

@@ -0,0 +1,371 @@
+import { z } from 'zod';
+import { ResourceReservationError, } from './resource-reservations.js';
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_BASE_PATH = '/resource-reservations';
+const snapshotIdPattern = /^sha256:[0-9a-f]{64}$/u;
+const boundedText = z.string().min(1).max(512).refine((value) => !/[\u0000-\u001f\u007f]/u.test(value), 'must be a bounded text value');
+const periodSchema = z.object({
+    startsAt: boundedText,
+    endsAt: boundedText,
+}).strict();
+const problemSchema = z.object({
+    problem_snapshot_id: z.string().min(1).max(512).regex(snapshotIdPattern),
+    problem_id: boundedText,
+    revision: boundedText,
+}).strict();
+const reservationRequestSchema = z.object({
+    operationId: boundedText,
+    tenantId: boundedText,
+    principal: boundedText,
+    scopeId: boundedText,
+    resourceId: boundedText,
+    period: periodSchema,
+    amount: z.number().finite().positive(),
+    unit: boundedText,
+    runId: boundedText,
+    problem: problemSchema,
+}).strict();
+const reserveRequestSchema = reservationRequestSchema.extend({
+    approvalId: boundedText.optional(),
+}).strict();
+const mutationSchema = z.object({
+    operationId: boundedText,
+    tenantId: boundedText,
+    principal: boundedText,
+    scopeId: boundedText,
+    reservationId: boundedText,
+}).strict();
+class HttpInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HttpInputError';
+    }
+}
+class BodyLimitError extends Error {
+    constructor() {
+        super('Request body exceeds the configured limit');
+        this.name = 'BodyLimitError';
+    }
+}
+class BodyReadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BodyReadError';
+    }
+}
+function requestPath(request) {
+    try {
+        return new URL(request.url ?? '/', 'http://localhost').pathname;
+    }
+    catch {
+        return '/';
+    }
+}
+function headerValue(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    return Array.isArray(value) ? value[0] : value;
+}
+function writeJson(response, statusCode, body, headers = {}) {
+    if (response.headersSent)
+        return;
+    response.statusCode = statusCode;
+    response.setHeader('Content-Type', 'application/json');
+    for (const [name, value] of Object.entries(headers))
+        response.setHeader(name, value);
+    response.end(JSON.stringify(body));
+}
+async function readJsonBody(request, limitBytes) {
+    const contentLengthHeader = headerValue(request, 'content-length');
+    if (contentLengthHeader !== undefined) {
+        const contentLength = Number(contentLengthHeader);
+        if (Number.isFinite(contentLength) && contentLength > limitBytes) {
+            request.resume();
+            throw new BodyLimitError();
+        }
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            request.removeListener('data', onData);
+            request.removeListener('end', onEnd);
+            request.removeListener('error', onError);
+            request.removeListener('aborted', onAborted);
+        };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const onData = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buffer.byteLength;
+            if (totalBytes > limitBytes) {
+                request.resume();
+                finish(new BodyLimitError());
+                return;
+            }
+            chunks.push(buffer);
+        };
+        const onEnd = () => finish();
+        const onError = () => finish(new BodyReadError('Request body could not be read'));
+        const onAborted = () => finish(new BodyReadError('Request was aborted'));
+        request.on('data', onData);
+        request.once('end', onEnd);
+        request.once('error', onError);
+        request.once('aborted', onAborted);
+    });
+    if (chunks.length === 0)
+        throw new HttpInputError('Request body must be a JSON object');
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new HttpInputError('Request body must contain valid JSON');
+    }
+}
+function normalizeBasePath(basePath) {
+    const value = basePath ?? DEFAULT_BASE_PATH;
+    if (typeof value !== 'string' || !value.startsWith('/') || value === '/' || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new TypeError('basePath must be an absolute URL path');
+    }
+    const normalized = value.replace(/\/+$/u, '');
+    if (normalized.length === 0)
+        throw new TypeError('basePath must not be root');
+    return normalized;
+}
+function normalizePath(path) {
+    if (path.length > 1)
+        return path.replace(/\/+$/u, '');
+    return path;
+}
+function matchRoute(path, basePath) {
+    const normalized = normalizePath(path);
+    if (normalized === basePath)
+        return { operation: 'read' };
+    const prefix = `${basePath}/`;
+    if (!normalized.startsWith(prefix))
+        return null;
+    const operation = normalized.slice(prefix.length);
+    const operations = ['estimate', 'approve', 'reserve', 'release', 'cancel', 'consume'];
+    return { operation: operations.includes(operation) ? operation : null };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function assertContext(context) {
+    if (!context
+        || typeof context.tenantId !== 'string' || context.tenantId.length === 0
+        || typeof context.principal !== 'string' || context.principal.length === 0
+        || typeof context.scopeId !== 'string' || context.scopeId.length === 0) {
+        throw new HttpInputError('Authenticated reservation context is required');
+    }
+}
+function bindTrustedIdentity(body, context) {
+    if (!isRecord(body))
+        throw new HttpInputError('Request body must be a JSON object');
+    const input = { ...body };
+    if (hasOwn(input, 'authority') || hasOwn(input, 'authorities')) {
+        throw new HttpInputError('authority is not accepted in the request body');
+    }
+    const identityFields = [
+        ['tenantId', ['tenantId', 'tenant_id', 'tenant'], context.tenantId],
+        ['principal', ['principal', 'actorId', 'actor_id', 'actor'], context.principal],
+        ['scopeId', ['scopeId', 'scope_id'], context.scopeId],
+    ];
+    for (const [canonical, aliases, expected] of identityFields) {
+        for (const alias of aliases) {
+            if (!hasOwn(input, alias))
+                continue;
+            if (typeof input[alias] !== 'string' || input[alias] !== expected) {
+                throw new HttpInputError(`${canonical} does not match the trusted request context`);
+            }
+            delete input[alias];
+        }
+        input[canonical] = expected;
+    }
+    return input;
+}
+function parseOperationBody(operation, body, context) {
+    const bound = bindTrustedIdentity(body, context);
+    const parsed = operation === 'reserve'
+        ? reserveRequestSchema.safeParse(bound)
+        : operation === 'estimate' || operation === 'approve'
+            ? reservationRequestSchema.safeParse(bound)
+            : mutationSchema.safeParse(bound);
+    if (!parsed.success) {
+        throw new HttpInputError(parsed.error.issues[0]?.message ?? 'Request body is invalid');
+    }
+    return parsed.data;
+}
+function serviceError(error) {
+    if (!(error instanceof ResourceReservationError)) {
+        return { status: 500, code: 'internal_error', message: 'Resource reservation operation failed' };
+    }
+    const status = (() => {
+        switch (error.code) {
+            case 'authorization_denied':
+            case 'scope_mismatch':
+                return 403;
+            case 'reservation_not_found':
+                return 404;
+            case 'capacity_unknown':
+                return 503;
+            case 'operation_conflict':
+            case 'approval_expired':
+            case 'approval_revoked':
+            case 'approval_required':
+            case 'approval_mismatch':
+            case 'capacity_exceeded':
+            case 'reservation_state_conflict':
+            case 'external_action_reconciliation_required':
+                return 409;
+            case 'ledger_invalid':
+                return 500;
+            case 'validation_error':
+            case 'problem_snapshot_invalid':
+                return 400;
+            default:
+                return 500;
+        }
+    })();
+    return { status, code: error.code, message: error.message };
+}
+function writeError(response, status, code, message, headers = {}) {
+    writeJson(response, status, { error: { code, message } }, headers);
+}
+function methodAllowed(operation, method) {
+    return operation === 'read' ? method === 'GET' : method === 'POST';
+}
+async function verifyMutationRequest(options, request, context) {
+    if (typeof context.verifiedMutationOrigin === 'string' && context.verifiedMutationOrigin.trim().length > 0)
+        return true;
+    if (!options.verifyMutationRequest)
+        return false;
+    try {
+        return Boolean(await options.verifyMutationRequest({ request, context }));
+    }
+    catch {
+        return false;
+    }
+}
+export function createResourceReservationHttpHandler(options) {
+    if (!options || typeof options !== 'object' || typeof options.serviceFactory !== 'function') {
+        throw new TypeError('serviceFactory is 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');
+    }
+    return async (request, response, context) => {
+        const route = matchRoute(requestPath(request), basePath);
+        if (!route)
+            return false;
+        if (!context) {
+            writeError(response, 401, 'unauthorized', 'Authenticated reservation context is required');
+            return true;
+        }
+        try {
+            assertContext(context);
+        }
+        catch (error) {
+            writeError(response, 401, 'unauthorized', error instanceof Error ? error.message : 'Authenticated reservation context is required');
+            return true;
+        }
+        if (!route.operation) {
+            writeError(response, 404, 'not_found', 'Resource reservation route was not found');
+            return true;
+        }
+        const method = (request.method ?? 'GET').toUpperCase();
+        if (!methodAllowed(route.operation, method)) {
+            writeError(response, 405, 'method_not_allowed', 'Method is not allowed for this reservation route', { Allow: route.operation === 'read' ? 'GET' : 'POST' });
+            return true;
+        }
+        if (route.operation === 'read') {
+            try {
+                const service = await options.serviceFactory(context);
+                const result = await service.readLedger({
+                    tenantId: context.tenantId,
+                    principal: context.principal,
+                    scopeId: context.scopeId,
+                });
+                writeJson(response, 200, { action: 'read', result });
+            }
+            catch (error) {
+                const failure = serviceError(error);
+                writeError(response, failure.status, failure.code, failure.message);
+            }
+            return true;
+        }
+        let body;
+        try {
+            body = await readJsonBody(request, bodyLimitBytes);
+        }
+        catch (error) {
+            if (error instanceof BodyLimitError) {
+                writeError(response, 413, 'body_too_large', error.message);
+            }
+            else {
+                writeError(response, 400, 'invalid_request', error instanceof Error ? error.message : 'Request body is invalid');
+            }
+            return true;
+        }
+        let parsed;
+        try {
+            parsed = parseOperationBody(route.operation, body, context);
+        }
+        catch (error) {
+            writeError(response, 400, 'invalid_request', error instanceof Error ? error.message : 'Request body is invalid');
+            return true;
+        }
+        if (!await verifyMutationRequest(options, request, context)) {
+            writeError(response, 403, 'mutation_origin_unverified', 'Mutation origin could not be verified');
+            return true;
+        }
+        try {
+            const service = await options.serviceFactory(context);
+            let result;
+            switch (route.operation) {
+                case 'estimate':
+                    result = await service.estimate(parsed);
+                    break;
+                case 'approve':
+                    result = await service.approve(parsed);
+                    break;
+                case 'reserve':
+                    result = await service.reserve(parsed);
+                    break;
+                case 'release':
+                    result = await service.release(parsed);
+                    break;
+                case 'cancel':
+                    result = await service.cancel(parsed);
+                    break;
+                case 'consume':
+                    result = await service.consume(parsed);
+                    break;
+            }
+            const operationId = 'operationId' in parsed ? parsed.operationId : undefined;
+            writeJson(response, 200, {
+                action: route.operation,
+                ...(operationId === undefined ? {} : { operationId }),
+                result,
+            });
+        }
+        catch (error) {
+            const failure = serviceError(error);
+            writeError(response, failure.status, failure.code, failure.message);
+        }
+        return true;
+    };
+}

package/dist/resource-reservations.d.ts

@@ -0,0 +1,221 @@
+declare const ledgerVersion: 1;
+export type ResourceReservationAction = 'estimate' | 'approve' | 'reserve' | 'release' | 'cancel' | 'consume' | 'start_external' | 'read';
+export type ResourceReservationState = 'approved' | 'reserved' | 'released' | 'cancelled' | 'consumed';
+export type ExternalActionStatus = 'not_started' | 'started' | 'completed' | 'unknown';
+export interface ResourceReservationPeriod {
+    startsAt: string;
+    endsAt: string;
+}
+/** A fixed reference to Story05's immutable Problem snapshot. */
+export interface ResourceReservationProblemReference {
+    problem_snapshot_id: string;
+    problem_id: string;
+    revision: string;
+}
+export interface ResourceReservationRequest {
+    operationId: string;
+    tenantId: string;
+    principal: string;
+    scopeId: string;
+    resourceId: string;
+    period: ResourceReservationPeriod;
+    amount: number;
+    unit: string;
+    runId: string;
+    problem: ResourceReservationProblemReference;
+}
+export interface EstimateResourceReservationInput extends ResourceReservationRequest {
+}
+export interface ApproveResourceReservationInput extends ResourceReservationRequest {
+}
+export interface ReserveResourceReservationInput extends ResourceReservationRequest {
+    approvalId?: string;
+}
+export interface ResourceReservationMutationInput {
+    operationId: string;
+    tenantId: string;
+    principal: string;
+    scopeId: string;
+    reservationId: string;
+}
+export interface ResourceReservationAuthorizationRequest {
+    action: ResourceReservationAction;
+    operationId: string;
+    tenantId: string;
+    principal: string;
+    scopeId: string;
+    resourceId?: string;
+    runId?: string;
+    problem?: ResourceReservationProblemReference;
+    approvalId?: string;
+    reservationId?: string;
+    reservation?: ResourceReservationRecord;
+}
+export interface ResourceReservationAuthorizationDecision {
+    status: 'approved' | 'denied' | 'expired' | 'revoked';
+    approvalId?: string;
+    expiresAt?: string | null;
+    evidence?: Record<string, string>;
+}
+/** Organization roles, budgets, and approval workflow stay behind this port. */
+export interface ResourceReservationAuthorizationPort {
+    authorize(request: ResourceReservationAuthorizationRequest): ResourceReservationAuthorizationDecision | Promise<ResourceReservationAuthorizationDecision>;
+}
+export interface ResourceReservationProblemSnapshotPort {
+    verify(input: {
+        tenantId: string;
+        principal: string;
+        scopeId: string;
+        reference: ResourceReservationProblemReference;
+    }): void | boolean | Promise<void | boolean>;
+}
+/**
+ * The small part of Story05's immutable snapshot returned by its store.
+ *
+ * The reservation package keeps this structural so it can consume the
+ * snapshot package without copying its model or making the two packages
+ * depend on one another's source files.
+ */
+export interface ResourceReservationProblemSnapshotRecord {
+    snapshot_version: 'judgment-problem-snapshot.v1';
+    problem_id: string;
+    revision: string;
+    owner_scope: {
+        type: 'personal' | 'project' | 'organization';
+        id: string;
+    };
+    execution_permission: 'none';
+}
+/** Request shape passed to Story05's loadJudgmentProblemSnapshot function. */
+export interface ResourceReservationProblemSnapshotLoadRequest {
+    root: string;
+    snapshot_id: string;
+    access: {
+        principal: string;
+    };
+    /** New approvals/reservations must revalidate canonical references. */
+    reference_resolution: 'current';
+}
+export type ResourceReservationProblemSnapshotLoader = (request: ResourceReservationProblemSnapshotLoadRequest) => Promise<ResourceReservationProblemSnapshotRecord>;
+/**
+ * Adapt the real immutable ProblemSnapshot store to the reservation port.
+ *
+ * Story05 owns loading, integrity checks, and current read ACL checks.  This
+ * adapter only binds the caller's principal, loads the current snapshot, and
+ * verifies the fixed problem/revision and scope reference.  The loader must
+ * connect Story05's canonical reference provider.  The tenant boundary and
+ * execution authorization remain the reservation/auth ports.
+ */
+export declare function createResourceReservationProblemSnapshotPort(options: {
+    root: string;
+    load: ResourceReservationProblemSnapshotLoader;
+}): ResourceReservationProblemSnapshotPort;
+export interface ResourceReservationCapacityPort {
+    read(input: {
+        tenantId: string;
+        principal: string;
+        scopeId: string;
+        resourceId: string;
+        period: ResourceReservationPeriod;
+        unit: string;
+    }): number | null | Promise<number | null>;
+}
+export interface ResourceReservationApproval {
+    approvalId: string;
+    approvedAt: string;
+    expiresAt?: string;
+    evidence: Record<string, string>;
+}
+export interface ResourceReservationExternalAction {
+    status: ExternalActionStatus;
+    startedAt?: string;
+}
+export interface ResourceReservationHistoryEntry {
+    action: Exclude<ResourceReservationAction, 'estimate' | 'read'>;
+    operationId: string;
+    principal: string;
+    occurredAt: string;
+    fromState?: ResourceReservationState;
+    toState: ResourceReservationState;
+    amount: number;
+    externalActionStatus: ExternalActionStatus;
+}
+export interface ResourceReservationRecord {
+    reservationId: string;
+    state: ResourceReservationState;
+    tenantId: string;
+    principal: string;
+    scopeId: string;
+    resourceId: string;
+    period: ResourceReservationPeriod;
+    amount: number;
+    unit: string;
+    runId: string;
+    problem: ResourceReservationProblemReference;
+    approval: ResourceReservationApproval;
+    externalAction: ResourceReservationExternalAction;
+    createdAt: string;
+    updatedAt: string;
+    history: ResourceReservationHistoryEntry[];
+}
+export interface ResourceReservationEstimate {
+    tenantId: string;
+    scopeId: string;
+    resourceId: string;
+    period: ResourceReservationPeriod;
+    unit: string;
+    requestedAmount: number;
+    capacity: number;
+    committedAmount: number;
+    availableAmount: number;
+}
+export interface ResourceReservationLedgerSnapshot {
+    version: typeof ledgerVersion;
+    reservations: ResourceReservationRecord[];
+}
+export interface ResourceReservationServiceOptions {
+    dataDir: string;
+    authorization: ResourceReservationAuthorizationPort;
+    problemSnapshot: ResourceReservationProblemSnapshotPort;
+    capacity: ResourceReservationCapacityPort;
+    clock?: () => Date;
+    sidecarPath?: string;
+}
+export type ResourceReservationErrorCode = 'validation_error' | 'authorization_denied' | 'approval_expired' | 'approval_revoked' | 'approval_required' | 'approval_mismatch' | 'capacity_unknown' | 'capacity_exceeded' | 'operation_conflict' | 'scope_mismatch' | 'reservation_not_found' | 'reservation_state_conflict' | 'external_action_reconciliation_required' | 'problem_snapshot_invalid' | 'ledger_invalid';
+export declare class ResourceReservationError extends Error {
+    readonly code: ResourceReservationErrorCode;
+    constructor(code: ResourceReservationErrorCode, message: string);
+}
+export interface ResourceReservationMutationResult {
+    reservation: ResourceReservationRecord;
+}
+export declare class ResourceReservationService {
+    private readonly dataDir;
+    private readonly authorization;
+    private readonly problemSnapshot;
+    private readonly capacity;
+    private readonly clock;
+    private readonly sidecarPath;
+    constructor(options: ResourceReservationServiceOptions);
+    initialize(): Promise<void>;
+    estimate(input: EstimateResourceReservationInput): Promise<ResourceReservationEstimate>;
+    approve(input: ApproveResourceReservationInput): Promise<ResourceReservationMutationResult>;
+    reserve(input: ReserveResourceReservationInput): Promise<ResourceReservationMutationResult>;
+    release(input: ResourceReservationMutationInput): Promise<ResourceReservationMutationResult>;
+    cancel(input: ResourceReservationMutationInput): Promise<ResourceReservationMutationResult>;
+    consume(input: ResourceReservationMutationInput): Promise<ResourceReservationMutationResult>;
+    startExternalAction(input: ResourceReservationMutationInput): Promise<ResourceReservationMutationResult>;
+    readLedger(input: {
+        tenantId: string;
+        principal: string;
+        scopeId: string;
+    }): Promise<ResourceReservationLedgerSnapshot>;
+    private transition;
+    private mutate;
+    private reauthorizeReplay;
+    private authorize;
+    private verifyProblem;
+    private readCapacity;
+    private now;
+}
+export {};