@unson/brainbase-mcp 0.7.0 → 0.9.0

package/dist/local-web-security.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Protections shared by every local single-owner Web host (the value-proof
+ * review host and the general local Web host).  They have no login, so the
+ * loopback Host check, the per-launch token and the same-origin check are the
+ * whole boundary against another site in the owner's browser.
+ */
+export declare const LOCAL_WEB_CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+export declare class LocalWebHttpError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(statusCode: number, code: string, message: string);
+}
+export declare function requestUrl(request: IncomingMessage): URL;
+export declare function writeJson(response: ServerResponse, statusCode: number, body: unknown): void;
+export declare function writeHttpError(response: ServerResponse, error: LocalWebHttpError): void;
+export declare function tokenMatches(expected: string, received: string | string[] | undefined): boolean;
+/** A browser always sends Origin on a cross-site write; it must name this Host. */
+export declare function assertSameOrigin(request: IncomingMessage): void;
+/** Reads the whole body but stops as soon as it exceeds the limit. */
+export declare function readBoundedBody(request: IncomingMessage, limitBytes: number): Promise<Buffer>;
+export declare function readJsonObjectBody(request: IncomingMessage, limitBytes: number): Promise<Record<string, unknown>>;
+export declare const LOOPBACK_HOSTNAMES: readonly ["127.0.0.1", "localhost", "[::1]"];
+/** Rejects rebound DNS names: the Host must be a loopback name for the port this connection arrived on. */
+export declare function isLoopbackHost(request: IncomingMessage): boolean;

package/dist/local-web-security.js

@@ -0,0 +1,95 @@
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Protections shared by every local single-owner Web host (the value-proof
+ * review host and the general local Web host).  They have no login, so the
+ * loopback Host check, the per-launch token and the same-origin check are the
+ * whole boundary against another site in the owner's browser.
+ */
+export const LOCAL_WEB_CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+export class LocalWebHttpError extends Error {
+    statusCode;
+    code;
+    constructor(statusCode, code, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = 'LocalWebHttpError';
+    }
+}
+export function requestUrl(request) {
+    return new URL(request.url ?? '/', 'http://localhost');
+}
+export function writeJson(response, statusCode, body) {
+    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');
+    response.end(JSON.stringify(body));
+}
+export function writeHttpError(response, error) {
+    writeJson(response, error.statusCode, { error: { code: error.code, message: error.message } });
+}
+export function tokenMatches(expected, received) {
+    if (typeof received !== 'string')
+        return false;
+    const left = Buffer.from(expected);
+    const right = Buffer.from(received);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** A browser always sends Origin on a cross-site write; it must name this Host. */
+export function assertSameOrigin(request) {
+    const origin = request.headers.origin;
+    if (origin === undefined)
+        return;
+    let host;
+    try {
+        host = new URL(origin).host;
+    }
+    catch {
+        throw new LocalWebHttpError(403, 'cross_origin_rejected', 'Origin is not allowed');
+    }
+    if (host !== request.headers.host)
+        throw new LocalWebHttpError(403, 'cross_origin_rejected', 'Origin is not allowed');
+}
+/** Reads the whole body but stops as soon as it exceeds the limit. */
+export async function readBoundedBody(request, limitBytes) {
+    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 > limitBytes)
+            throw new LocalWebHttpError(413, 'payload_too_large', 'Request body is too large');
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+export async function readJsonObjectBody(request, limitBytes) {
+    const contentType = String(request.headers['content-type'] ?? '');
+    if (!contentType.toLowerCase().startsWith('application/json')) {
+        throw new LocalWebHttpError(415, 'unsupported_media_type', 'Content-Type must be application/json');
+    }
+    const body = await readBoundedBody(request, limitBytes);
+    let value;
+    try {
+        value = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        throw new LocalWebHttpError(400, 'invalid_json', 'Request body must be JSON');
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new LocalWebHttpError(400, 'invalid_json', 'Request body must be a JSON object');
+    }
+    return value;
+}
+export const LOOPBACK_HOSTNAMES = ['127.0.0.1', 'localhost', '[::1]'];
+/** Rejects rebound DNS names: the Host must be a loopback name for the port this connection arrived on. */
+export function isLoopbackHost(request) {
+    const host = request.headers.host?.toLowerCase();
+    const port = request.socket.localPort;
+    if (host === undefined || port === undefined)
+        return false;
+    return LOOPBACK_HOSTNAMES.some((name) => host === `${name}:${port}` || (port === 80 && host === name));
+}

package/dist/organization-graph.d.ts

@@ -41,6 +41,18 @@ export interface PortableGraphReadback {
     readonly bundle: unknown;
     readonly digest: string;
 }
+/** One snapshot the organization stored for the token's owner. */
+export interface PortableGraphListEntry {
+    readonly graphId: string;
+    readonly projectCode: string;
+    readonly digest: string;
+    readonly createdAt: string;
+}
+export interface PortableGraphList {
+    readonly bundles: readonly PortableGraphListEntry[];
+    /** The organization returned only its newest page. */
+    readonly truncated: boolean;
+}
 export interface PortableGraphImportResult {
     readonly status: 'imported' | 'unchanged';
     readonly digest: string;
@@ -65,6 +77,7 @@ export interface OrganizationGraphClient {
     search(input: GraphRetrievalInput): Promise<GraphRetrievalResponse>;
     importPortableGraph(bundle: unknown): Promise<PortableGraphImportResult>;
     readPortableGraph(): Promise<PortableGraphReadback>;
+    listPortableGraphs(): Promise<PortableGraphList>;
 }
 /** Forward the existing Graph retrieval input unchanged inside the request envelope. */
 export declare function searchOrganizationGraph(config: OrganizationGraphConfig, input: GraphRetrievalInput): Promise<GraphRetrievalResponse>;
@@ -72,5 +85,7 @@ export declare function searchOrganizationGraph(config: OrganizationGraphConfig,
 export declare function importPortableGraph(config: OrganizationGraphConfig, bundle: unknown): Promise<PortableGraphImportResult>;
 /** Read and verify the complete organization-side bundle and its digest. */
 export declare function readPortableGraph(config: OrganizationGraphConfig): Promise<PortableGraphReadback>;
+/** List the token owner's snapshots. The organization decides the owner; no project or Graph ID is sent. */
+export declare function listPortableGraphs(config: OrganizationGraphConfig): Promise<PortableGraphList>;
 /** Validate the privacy boundary before any upload leaves the local process. */
 export declare function assertPortableGraphBundle(bundle: unknown): asserts bundle is PortableGraphBundle;

package/dist/organization-graph.js

@@ -64,7 +64,8 @@ export function createOrganizationGraphClient(config) {
     return {
         search: (input) => searchOrganizationGraph(normalized, input),
         importPortableGraph: (bundle) => importPortableGraph(normalized, bundle),
-        readPortableGraph: () => readPortableGraph(normalized)
+        readPortableGraph: () => readPortableGraph(normalized),
+        listPortableGraphs: () => listPortableGraphs(normalized)
     };
 }
 /** Forward the existing Graph retrieval input unchanged inside the request envelope. */
@@ -100,6 +101,21 @@ export async function readPortableGraph(config) {
     }
     return readback;
 }
+/** List the token owner's snapshots. The organization decides the owner; no project or Graph ID is sent. */
+export async function listPortableGraphs(config) {
+    const value = await requestJson(config, 'GET', route(config, 'list'));
+    const fields = ['graph_id', 'project_code', 'digest', 'created_at'];
+    if (!isRecord(value) || typeof value.truncated !== 'boolean' || !Array.isArray(value.bundles)
+        || value.bundles.some((entry) => !isRecord(entry) || fields.some((field) => typeof entry[field] !== 'string' || entry[field].trim() === ''))) {
+        throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned an invalid bundle list');
+    }
+    return {
+        truncated: value.truncated,
+        bundles: value.bundles.map((entry) => ({
+            graphId: entry.graph_id, projectCode: entry.project_code, digest: entry.digest, createdAt: entry.created_at
+        }))
+    };
+}
 /** Validate the privacy boundary before any upload leaves the local process. */
 export function assertPortableGraphBundle(bundle) {
     validatePortableGraph(bundle);
@@ -110,7 +126,7 @@ function parseGraphRetrievalResponse(value) {
         || (value.schemaVersion !== 1 && value.schemaVersion !== 2)
         || (value.status !== 'ok' && value.status !== 'migration_required')
         || typeof value.migrationRequired !== 'boolean'
-        || value.authority !== 'organization_graph'
+        || (value.authority !== 'owner_private' && value.authority !== 'organization_graph')
         || typeof value.query !== 'string'
         || typeof value.asOf !== 'string'
         || !['semantic', 'lexical', 'seed'].includes(String(value.method))
@@ -135,7 +151,10 @@ function parseGraphRetrievalResponse(value) {
         || value.absenceConfirmed !== false) {
         throw new OrganizationGraphError('organization_graph_response_invalid', 'organization service returned a response outside the OSS GraphRetrievalResponse contract');
     }
-    return value;
+    // This route searches only the token owner's own snapshot (the owner-private
+    // area), never the organization's shared Graph. A service from before the
+    // owner_private label answered organization_graph for the same area.
+    return { ...value, authority: 'owner_private' };
 }
 function parseImportResult(value) {
     if (!isRecord(value)
@@ -271,7 +290,8 @@ async function withTimeout(operation, controller, timeoutMs) {
 function route(config, suffix, query) {
     const base = new URL(config.url);
     const prefix = base.pathname.replace(/\/+$/u, '');
-    const routePath = `${prefix}/api/info/graph/portable/${encodeURIComponent(config.graphId)}${suffix ? `/${suffix}` : ''}`;
+    const graphPath = suffix === 'list' ? '' : `/${encodeURIComponent(config.graphId)}${suffix ? `/${suffix}` : ''}`;
+    const routePath = `${prefix}/api/info/graph/portable${graphPath}`;
     const endpoint = new URL(routePath || '/', base.origin);
     for (const [key, value] of Object.entries(query ?? {}))
         endpoint.searchParams.set(key, value);

package/dist/personal-knowledge.d.ts

@@ -83,6 +83,18 @@ export interface PersonalKnowledgeStoreOptions {
 }
 export declare function createLocalPersonalKnowledgeStore(options?: PersonalKnowledgeStoreOptions): PersonalKnowledgeStore;
 export declare const createPersonalKnowledgeStore: typeof createLocalPersonalKnowledgeStore;
+export interface LocalPersonalKnowledgeSnapshot extends PersonalKnowledgeContextEnvelope {
+    events: PersonalKnowledgeEvent[];
+}
+/**
+ * Read the local v1 store without creating it. Returns undefined when the
+ * store has never been created; a half-created store is an error.
+ */
+export declare function readLocalPersonalKnowledgeEvents(options?: {
+    dataDir?: string;
+}): Promise<LocalPersonalKnowledgeSnapshot | undefined>;
+/** True when the value is a timestamp the v1 event contract accepts. */
+export declare function isPersonalKnowledgeTimestamp(value: unknown): value is string;
 export interface PersonalKnowledgeClientOptions {
     mode: PersonalKnowledgeStorageMode;
     apiUrl: string;

package/dist/personal-knowledge.js

@@ -412,6 +412,35 @@ export function createLocalPersonalKnowledgeStore(options = {}) {
     return new LocalPersonalKnowledgeStore(options);
 }
 export const createPersonalKnowledgeStore = createLocalPersonalKnowledgeStore;
+/**
+ * Read the local v1 store without creating it. Returns undefined when the
+ * store has never been created; a half-created store is an error.
+ */
+export async function readLocalPersonalKnowledgeEvents(options = {}) {
+    const directory = join(resolveDataDir(options.dataDir), PERSONAL_KNOWLEDGE_LOCAL_DIRECTORY);
+    const contextPath = join(directory, LOCAL_CONTEXT_FILE);
+    const eventsPath = join(directory, LOCAL_EVENTS_FILE);
+    const [contextExists, eventsExists] = await Promise.all([exists(contextPath), exists(eventsPath)]);
+    if (!contextExists && !eventsExists)
+        return undefined;
+    if (contextExists !== eventsExists)
+        throw new Error(`Partial Personal Knowledge v1 store in ${directory}.`);
+    const context = validatePersonalKnowledgeContext(JSON.parse(await readFile(contextPath, 'utf8')));
+    if (context.scope !== 'personal_owned') {
+        throw new Error('OSS local Personal Knowledge storage requires a personal_owned context.');
+    }
+    return { context, events: await readEventsFile(eventsPath) };
+}
+/** True when the value is a timestamp the v1 event contract accepts. */
+export function isPersonalKnowledgeTimestamp(value) {
+    try {
+        validateTimestamp(value, 'timestamp');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function readEventsFile(path) {
     const serialized = await readFile(path, 'utf8');
     const events = [];

package/dist/personal-memory-handover.d.ts

@@ -0,0 +1,108 @@
+import { type PersonalKnowledgeContext } from './personal-knowledge.js';
+/**
+ * Handover of personal memories from OSS Personal to an organization.
+ *
+ * The owner lists the memories kept on this machine and re-registers only the
+ * ones they choose into the organization's personal KG (organization_private,
+ * readable by the owner only). Nothing moves automatically: listing and the
+ * default preview never touch the network, and only selected memories are sent.
+ */
+/** Local record of what the organization confirmed, relative to the data directory. */
+export declare const MEMORY_REGISTRATION_RECEIPTS_FILE: string;
+export type LocalMemoryStore = 'personal-knowledge-v1' | 'personal-kg';
+export type MemoryRegistrationStatus = 'unregistered' | 'registered' | 'changed';
+/**
+ * The event content sent for one memory. The organization event ID is added
+ * only when the destination is known (see organizationMemoryEventId).
+ * Local provenance such as file paths, local metadata, and local episode IDs
+ * is deliberately not part of it.
+ */
+export interface MemoryRegistrationContent {
+    body: string;
+    body_hash: string;
+    source: {
+        system: 'brainbase-oss';
+        store: LocalMemoryStore;
+    };
+    source_pointer: {
+        memory_id: string;
+    };
+    occurred_at?: string;
+    captured_at?: string;
+    kind?: string;
+    type?: string;
+    tags?: string[];
+    sensitivity?: string;
+}
+export interface MemoryRegistrationReceipt {
+    schema_version: 1;
+    memory_id: string;
+    memory_digest: string;
+    event_id: string;
+    body_hash: string;
+    organization_id: string;
+    owner_person_id: string;
+    registered_at: string;
+}
+export interface LocalMemory {
+    /** Stable selection ID: `v1:<event_id>` or `legacy:<id>`. */
+    id: string;
+    store: LocalMemoryStore;
+    type: string | null;
+    preview: string;
+    /** Digest of exactly the content that would be sent; it changes when the memory changes. */
+    memoryDigest: string;
+    content: MemoryRegistrationContent;
+    status: MemoryRegistrationStatus;
+    /** Latest receipt for this memory: the matching one when registered, otherwise the newest. */
+    lastRegistration?: MemoryRegistrationReceipt;
+}
+export interface RegisteredMemory {
+    id: string;
+    eventId: string;
+    memoryDigest: string;
+    bodyHash: string;
+}
+export interface MemoryRegistrationResult {
+    organizationId: string;
+    ownerPersonId: string;
+    registered: RegisteredMemory[];
+}
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface RegisterSelectedMemoriesOptions {
+    dataDir?: string;
+    ids: readonly string[];
+    /** Organization base URL and the member's signed Bearer token. */
+    organization: {
+        url: string;
+        token: string;
+    };
+    fetch?: FetchLike;
+    now?: () => Date;
+    timeoutMs?: number;
+}
+export declare class PersonalMemoryRegistrationError extends Error {
+    readonly memoryId: string;
+    readonly registered: RegisteredMemory[];
+    constructor(memoryId: string, reason: string, registered: RegisteredMemory[]);
+}
+/** Read both local memory stores and each memory's registration state. Never uses the network. */
+export declare function listLocalMemories(dataDirInput?: string): Promise<LocalMemory[]>;
+/** Pick exactly the requested memories, in request order, or fail before anything is sent. */
+export declare function selectLocalMemories(memories: readonly LocalMemory[], ids: readonly string[]): LocalMemory[];
+/**
+ * The organization event ID for a memory. It is derived from the memory's
+ * content and origin (memoryDigest) and from the authenticated destination,
+ * so re-sending the same memory to the same owner produces the same event,
+ * and another owner or organization never collides with it.
+ */
+export declare function organizationMemoryEventId(context: PersonalKnowledgeContext, memoryDigest: string): string;
+/** Send only the selected memories and record a receipt for each one the organization confirmed. */
+export declare function registerSelectedMemories(options: RegisterSelectedMemoriesOptions): Promise<MemoryRegistrationResult>;
+export declare function readMemoryRegistrationReceipts(dataDirInput?: string): Promise<MemoryRegistrationReceipt[]>;
+export declare function renderMemoryList(memories: readonly LocalMemory[]): string;
+export declare function memoryListJson(memories: readonly LocalMemory[]): unknown;
+export declare function registrationPreviewJson(memories: readonly LocalMemory[]): unknown;
+export declare function renderRegistrationPreview(memories: readonly LocalMemory[]): string;
+export declare function renderRegistrationResult(result: MemoryRegistrationResult): string;
+export {};