@debian777/kairos-mcp 3.0.1-beta.14

package/dist/utils/space-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-filter.d.ts","sourceRoot":"","sources":["../../src/utils/space-filter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,EAAE,EACzB,cAAc,CAAC,EAAE,gBAAgB,GAChC;IAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,CAS1C"}

package/dist/utils/space-filter.js

@@ -0,0 +1,18 @@
+/**
+ * Build Qdrant filter for space isolation. Merges space_id constraint with optional existing filter.
+ */
+/**
+ * Build a filter that restricts results to points whose space_id is in allowedSpaceIds.
+ * Merges with existingFilter.must so callers can add domain, chain.id, etc.
+ */
+export function buildSpaceFilter(allowedSpaceIds, existingFilter) {
+    const spaceCondition = {
+        key: 'space_id',
+        match: { any: allowedSpaceIds }
+    };
+    const existingMust = existingFilter?.must ?? [];
+    return {
+        must: [spaceCondition, ...existingMust]
+    };
+}
+//# sourceMappingURL=space-filter.js.map

package/dist/utils/space-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-filter.js","sourceRoot":"","sources":["../../src/utils/space-filter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,eAAyB,EACzB,cAAiC;IAEjC,MAAM,cAAc,GAAG;QACrB,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE;KAChC,CAAC;IACF,MAAM,YAAY,GAAG,cAAc,EAAE,IAAI,IAAI,EAAE,CAAC;IAChD,OAAO;QACL,IAAI,EAAE,CAAC,cAAc,EAAE,GAAG,YAAY,CAAC;KACxC,CAAC;AACJ,CAAC"}

package/dist/utils/structured-logger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Structured HTTP Access Logging for KAIROS MCP
+ *
+ * Uses shared Pino backend (log-core) for consistent JSON shape.
+ * See docs/logging.md for levels, standard fields, and usage.
+ *
+ * Features:
+ * - request_id, client_ip, duration_ms, error_code
+ * - child(component, module) for context
+ * - Proxy-safe client IP when TRUSTED_PROXY_CIDRS is set
+ */
+import pino from 'pino';
+import type { Request, Response } from 'express';
+declare function getClientIp(req: Request): string;
+declare const httpLogger: (req: Request, res: Response, next: Function) => void;
+export type ToolOperation = 'search' | 'store' | 'update' | 'delete' | 'retrieve' | 'upsert' | 'rate';
+export interface ErrorLogOptions {
+    error_code?: string;
+    request_id?: string;
+    [key: string]: unknown;
+}
+export interface StructuredLoggerApi {
+    debug(message: string): void;
+    info(message: string): void;
+    info(bindings: Record<string, unknown>, message: string): void;
+    warn(message: string): void;
+    error(message: string, error?: Error | unknown): void;
+    error(message: string, error: Error | unknown, options: ErrorLogOptions): void;
+    tool(toolName: string, operation: ToolOperation, details: string): void;
+    success(operation: string, details: string): void;
+    requestTimeout(operation: string, timeoutMs: number): void;
+    getTransportType(): 'stdio' | 'http';
+    getLogFormat(): 'text' | 'json';
+    getPinoLogger(): pino.Logger;
+    child(bindings: Record<string, unknown>): StructuredLoggerApi;
+}
+declare const structuredLogger: StructuredLoggerApi;
+export { structuredLogger, httpLogger, getClientIp };
+export type { Request, Response };
+export type { Logger } from 'pino';
+//# sourceMappingURL=structured-logger.d.ts.map

package/dist/utils/structured-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.d.ts","sourceRoot":"","sources":["../../src/utils/structured-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AASjD,iBAAS,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAazC;AAKD,QAAA,MAAM,UAAU,GAAI,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,KAAG,IA+BjE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtG,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IACtD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/E,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D,gBAAgB,IAAI,OAAO,GAAG,MAAM,CAAC;IACrC,YAAY,IAAI,MAAM,GAAG,MAAM,CAAC;IAChC,aAAa,IAAI,IAAI,CAAC,MAAM,CAAC;IAC7B,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAAC;CAC/D;AAmFD,QAAA,MAAM,gBAAgB,qBAAuB,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AACrD,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAClC,YAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC"}

package/dist/utils/structured-logger.js

@@ -0,0 +1,133 @@
+/**
+ * Structured HTTP Access Logging for KAIROS MCP
+ *
+ * Uses shared Pino backend (log-core) for consistent JSON shape.
+ * See docs/logging.md for levels, standard fields, and usage.
+ *
+ * Features:
+ * - request_id, client_ip, duration_ms, error_code
+ * - child(component, module) for context
+ * - Proxy-safe client IP when TRUSTED_PROXY_CIDRS is set
+ */
+import { getBaseLogger } from './log-core.js';
+import { LOG_LEVEL, LOG_FORMAT, TRANSPORT_TYPE } from '../config.js';
+const TRUSTED_PROXY_CIDRS = (process.env['TRUSTED_PROXY_CIDRS'] || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+function getClientIp(req) {
+    const reqWithSocket = req;
+    const remote = reqWithSocket?.socket?.remoteAddress ?? reqWithSocket?.ip ?? 'unknown';
+    const xff = (req.headers && req.headers['x-forwarded-for'] ? String(req.headers['x-forwarded-for']) : '');
+    if (!xff)
+        return remote;
+    if (TRUSTED_PROXY_CIDRS.length > 0) {
+        const first = xff.split(',')[0];
+        return (first && first.trim()) || remote;
+    }
+    return remote;
+}
+const baseLogger = getBaseLogger();
+// HTTP logging middleware
+const httpLogger = (req, res, next) => {
+    const start = Date.now();
+    const startTime = new Date().toISOString();
+    const requestId = req.headers['x-request-id'] || `req-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    req.requestId = requestId;
+    baseLogger.info({
+        time: startTime,
+        http: { method: req.method, path: req.url, protocol: `HTTP/${req.httpVersion}` },
+        client: { ip: getClientIp(req) },
+        user_agent: req.headers['user-agent'],
+        request_id: requestId
+    }, `${req.method} ${req.url}`);
+    res.on('finish', () => {
+        const duration = Date.now() - start;
+        const statusCode = res.statusCode ?? 500;
+        const methodName = statusCode >= 500 ? 'error' : statusCode >= 400 ? 'warn' : 'info';
+        const rid = req.requestId ?? req.headers['x-request-id'];
+        baseLogger[methodName]({
+            time: new Date().toISOString(),
+            http: { method: req.method, path: req.url, protocol: `HTTP/${req.httpVersion}` },
+            status: statusCode,
+            response_time_ms: duration,
+            client: { ip: getClientIp(req) },
+            user_agent: req.headers['user-agent'],
+            request_id: rid
+        }, `${req.method} ${req.url} -> ${statusCode}`);
+    });
+    next();
+};
+function wrapPino(pinoInstance) {
+    const includeStack = LOG_LEVEL === 'debug' || process.env['NODE_ENV'] === 'development';
+    return {
+        debug(message) {
+            pinoInstance.debug(message);
+        },
+        info(msgOrBindings, message) {
+            if (typeof msgOrBindings === 'string') {
+                pinoInstance.info({ category: 'info' }, msgOrBindings);
+            }
+            else {
+                pinoInstance.info({ ...msgOrBindings, category: 'info' }, (message ?? ''));
+            }
+        },
+        warn(message) {
+            pinoInstance.warn({ category: 'warning' }, message);
+        },
+        error(message, error, options) {
+            const bindings = { category: 'error' };
+            if (options && options['error_code'])
+                bindings['error_code'] = options['error_code'];
+            if (options && options['request_id'])
+                bindings['request_id'] = options['request_id'];
+            if (options) {
+                Object.keys(options).forEach(k => {
+                    if (k !== 'error_code' && k !== 'request_id')
+                        bindings[k] = options[k];
+                });
+            }
+            if (error) {
+                bindings['error'] = error instanceof Error
+                    ? { message: error.message, stack: includeStack ? error.stack : undefined }
+                    : error;
+            }
+            pinoInstance.error(bindings, message);
+        },
+        tool(toolName, operation, details) {
+            const msg = `[${toolName}] ${operation.toUpperCase()} ${details}`;
+            pinoInstance.info({
+                tool: toolName,
+                operation: operation.toUpperCase(),
+                details,
+                category: 'tool_operation'
+            }, msg);
+        },
+        success(operation, details) {
+            pinoInstance.info({ operation, details, category: 'success' }, `[${operation}] ${details}`);
+        },
+        requestTimeout(operation, timeoutMs) {
+            pinoInstance.error({
+                operation,
+                timeoutMs,
+                category: 'timeout',
+                note: 'Client did not receive response'
+            }, 'Request timeout');
+        },
+        getTransportType() {
+            return TRANSPORT_TYPE;
+        },
+        getLogFormat() {
+            return LOG_FORMAT === 'json' ? 'json' : 'text';
+        },
+        getPinoLogger() {
+            return pinoInstance;
+        },
+        child(bindings) {
+            return wrapPino(pinoInstance.child(bindings));
+        }
+    };
+}
+const structuredLogger = wrapPino(baseLogger);
+export { structuredLogger, httpLogger, getClientIp };
+//# sourceMappingURL=structured-logger.js.map

package/dist/utils/structured-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.js","sourceRoot":"","sources":["../../src/utils/structured-logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/tenant-context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Space and tenant context for multitenancy.
+ * SpaceContext is derived from Keycloak (sub + groups); getTenantId() remains for metrics.
+ * AsyncLocalStorage allows Redis and other services to get current space without request reference.
+ * When AUTH_ENABLED, default space is disabled for strict isolation; unauthenticated/no-context
+ * uses a sentinel space so no tenant data is shared.
+ */
+/** Sentinel space when AUTH is on but no auth context (strict isolation; not shared with tenants). */
+export declare const NO_AUTH_SPACE_ID = "space:no-auth";
+export interface SpaceContext {
+    userId: string;
+    groupIds: string[];
+    allowedSpaceIds: string[];
+    defaultWriteSpaceId: string;
+}
+/**
+ * Run a function with the given space context stored in AsyncLocalStorage.
+ * Used by HTTP auth middleware so Redis and Qdrant helpers can read space without request.
+ * For sync callbacks the context is preserved. For async callbacks use runWithSpaceContextAsync
+ * so the context persists across await boundaries (run() loses context after the callback returns a Promise).
+ */
+export declare function runWithSpaceContext<T>(ctx: SpaceContext, fn: () => T): T;
+/**
+ * Run an async function with the given space context. Uses enterWith so the context
+ * persists for the entire async execution (including all await continuations).
+ * Use this when the callback does async work (e.g. storeChain) and getSpaceContext()
+ * must see the context inside that work.
+ */
+export declare function runWithSpaceContextAsync<T>(ctx: SpaceContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Get space context from AsyncLocalStorage (set by auth middleware via runWithSpaceContext).
+ * When not in a request: if AUTH_ENABLED, returns no-default context (strict isolation);
+ * otherwise returns default single-tenant context.
+ */
+export declare function getSpaceContextFromStorage(): SpaceContext;
+/** Current space id for Redis key prefix and similar; uses storage or KAIROS_APP_SPACE_ID when auth off. */
+export declare function getSpaceIdFromStorage(): string;
+/**
+ * Space IDs to use for search only: allowedSpaceIds plus Kairos app space (deduped).
+ * Writes (mint, update, delete) continue to use allowedSpaceIds only.
+ */
+export declare function getSearchSpaceIds(): string[];
+/**
+ * Async variant: run fn in narrowed space context so context persists across await.
+ * Use when the callback does async work (e.g. kairos_search) and getSpaceContext() must see the context.
+ */
+export declare function runWithOptionalSpaceAsync<T>(spaceParam: string | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * Get space context from request. Uses req.auth (set by auth middleware) when AUTH_ENABLED.
+ * When AUTH_ENABLED and no auth, returns no-default context (strict isolation).
+ * When AUTH_ENABLED=false, returns default single-tenant context.
+ * If no request is passed, falls back to AsyncLocalStorage (e.g. from runWithSpaceContext).
+ */
+export declare function getSpaceContext(request?: {
+    auth?: {
+        sub: string;
+        groups: string[];
+        realm?: string;
+        group_ids?: string[];
+    };
+    spaceContext?: SpaceContext;
+}): SpaceContext;
+/**
+ * Get tenant ID for metrics. Returns default write space id or first allowed space.
+ */
+export declare function getTenantId(request?: any): string;
+//# sourceMappingURL=tenant-context.d.ts.map

package/dist/utils/tenant-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.d.ts","sourceRoot":"","sources":["../../src/utils/tenant-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,sGAAsG;AACtG,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAgCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAExE;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQrG;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,YAAY,CAIzD;AAED,4GAA4G;AAC5G,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAK5C;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAYnH;AAsBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE;IACxC,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC/E,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,GAAG,YAAY,CAoBf;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,MAAM,CAGjD"}

package/dist/utils/tenant-context.js

@@ -0,0 +1,154 @@
+/**
+ * Space and tenant context for multitenancy.
+ * SpaceContext is derived from Keycloak (sub + groups); getTenantId() remains for metrics.
+ * AsyncLocalStorage allows Redis and other services to get current space without request reference.
+ * When AUTH_ENABLED, default space is disabled for strict isolation; unauthenticated/no-context
+ * uses a sentinel space so no tenant data is shared.
+ */
+import { AsyncLocalStorage } from 'async_hooks';
+import { AUTH_ENABLED, KAIROS_APP_SPACE_ID } from '../config.js';
+/** Sentinel space when AUTH is on but no auth context (strict isolation; not shared with tenants). */
+export const NO_AUTH_SPACE_ID = 'space:no-auth';
+/** Sentinel for "no context" when restoring after runWithSpaceContextAsync (enterWith does not accept undefined). */
+const NO_CONTEXT_SENTINEL = {
+    userId: '',
+    groupIds: [],
+    allowedSpaceIds: [],
+    defaultWriteSpaceId: ''
+};
+const spaceStorage = new AsyncLocalStorage();
+function defaultSpaceContext() {
+    const spaceId = KAIROS_APP_SPACE_ID;
+    return {
+        userId: '',
+        groupIds: [],
+        allowedSpaceIds: [spaceId],
+        defaultWriteSpaceId: spaceId
+    };
+}
+/** Context when AUTH_ENABLED and no auth/storage — no access to shared default space. */
+function noDefaultSpaceContext() {
+    return {
+        userId: '',
+        groupIds: [],
+        allowedSpaceIds: [],
+        defaultWriteSpaceId: NO_AUTH_SPACE_ID
+    };
+}
+/**
+ * Run a function with the given space context stored in AsyncLocalStorage.
+ * Used by HTTP auth middleware so Redis and Qdrant helpers can read space without request.
+ * For sync callbacks the context is preserved. For async callbacks use runWithSpaceContextAsync
+ * so the context persists across await boundaries (run() loses context after the callback returns a Promise).
+ */
+export function runWithSpaceContext(ctx, fn) {
+    return spaceStorage.run(ctx, fn);
+}
+/**
+ * Run an async function with the given space context. Uses enterWith so the context
+ * persists for the entire async execution (including all await continuations).
+ * Use this when the callback does async work (e.g. storeChain) and getSpaceContext()
+ * must see the context inside that work.
+ */
+export async function runWithSpaceContextAsync(ctx, fn) {
+    const prev = spaceStorage.getStore();
+    spaceStorage.enterWith(ctx);
+    try {
+        return await fn();
+    }
+    finally {
+        spaceStorage.enterWith(prev ?? NO_CONTEXT_SENTINEL);
+    }
+}
+/**
+ * Get space context from AsyncLocalStorage (set by auth middleware via runWithSpaceContext).
+ * When not in a request: if AUTH_ENABLED, returns no-default context (strict isolation);
+ * otherwise returns default single-tenant context.
+ */
+export function getSpaceContextFromStorage() {
+    const stored = spaceStorage.getStore();
+    if (stored && stored !== NO_CONTEXT_SENTINEL)
+        return stored;
+    return AUTH_ENABLED ? noDefaultSpaceContext() : defaultSpaceContext();
+}
+/** Current space id for Redis key prefix and similar; uses storage or KAIROS_APP_SPACE_ID when auth off. */
+export function getSpaceIdFromStorage() {
+    return getSpaceContextFromStorage().defaultWriteSpaceId;
+}
+/**
+ * Space IDs to use for search only: allowedSpaceIds plus Kairos app space (deduped).
+ * Writes (mint, update, delete) continue to use allowedSpaceIds only.
+ */
+export function getSearchSpaceIds() {
+    const ctx = getSpaceContextFromStorage();
+    const allowed = ctx.allowedSpaceIds;
+    if (allowed.includes(KAIROS_APP_SPACE_ID))
+        return [...allowed];
+    return [...allowed, KAIROS_APP_SPACE_ID];
+}
+/**
+ * Async variant: run fn in narrowed space context so context persists across await.
+ * Use when the callback does async work (e.g. kairos_search) and getSpaceContext() must see the context.
+ */
+export async function runWithOptionalSpaceAsync(spaceParam, fn) {
+    if (!spaceParam || typeof spaceParam !== 'string')
+        return fn();
+    const ctx = getSpaceContextFromStorage();
+    if (!ctx.allowedSpaceIds.includes(spaceParam)) {
+        throw new Error('Requested space is not in your allowed spaces');
+    }
+    const narrowed = {
+        ...ctx,
+        allowedSpaceIds: [spaceParam],
+        defaultWriteSpaceId: spaceParam
+    };
+    return runWithSpaceContextAsync(narrowed, fn);
+}
+/**
+ * Build allowed space ids and default write space from auth payload (sub + groups + realm + optional group_ids).
+ * Space IDs include realm for isolation across Keycloak realms; group ID is used when present so renames are stable.
+ */
+function fromAuthPayload(sub, groupNames, realm, groupIds) {
+    const personal = `user:${realm}:${sub}`;
+    const groupSpaces = groupNames.map((name, i) => {
+        const ref = groupIds?.[i] ?? name;
+        return `group:${realm}:${ref}`;
+    });
+    const allowedSpaceIds = [personal, ...groupSpaces];
+    const defaultWriteSpaceId = personal;
+    return { allowedSpaceIds, defaultWriteSpaceId };
+}
+/**
+ * Get space context from request. Uses req.auth (set by auth middleware) when AUTH_ENABLED.
+ * When AUTH_ENABLED and no auth, returns no-default context (strict isolation).
+ * When AUTH_ENABLED=false, returns default single-tenant context.
+ * If no request is passed, falls back to AsyncLocalStorage (e.g. from runWithSpaceContext).
+ */
+export function getSpaceContext(request) {
+    if (request?.spaceContext)
+        return request.spaceContext;
+    const stored = spaceStorage.getStore();
+    if (stored)
+        return stored;
+    if (!AUTH_ENABLED)
+        return defaultSpaceContext();
+    const auth = request?.auth;
+    if (!auth?.sub)
+        return noDefaultSpaceContext();
+    const realm = auth.realm ?? 'default';
+    const { allowedSpaceIds, defaultWriteSpaceId } = fromAuthPayload(auth.sub, auth.groups ?? [], realm, auth.group_ids);
+    return {
+        userId: auth.sub,
+        groupIds: auth.groups ?? [],
+        allowedSpaceIds,
+        defaultWriteSpaceId
+    };
+}
+/**
+ * Get tenant ID for metrics. Returns default write space id or first allowed space.
+ */
+export function getTenantId(request) {
+    const ctx = getSpaceContext(request);
+    return ctx.defaultWriteSpaceId || ctx.allowedSpaceIds[0] || 'default';
+}
+//# sourceMappingURL=tenant-context.js.map

package/dist/utils/tenant-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-context.js","sourceRoot":"","sources":["../../src/utils/tenant-context.ts"],"names":[],"mappings":"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"}

package/dist/utils/uri-builder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * URI Builder for KAIROS Resources
+ *
+ * Generates canonical kairos:// URIs for:
+ * - Domain/type/task resources: kairos://{domain}/{type}/{task}
+ * - Protocol steps: kairos://{domain}/{type}/{task}/step/{n}
+ * - Unified UUID resources: kairos://{uuid}
+ * - Templates: kairos://templates/{template_type}/{param}
+ */
+/**
+ * Build kairos://{domain}/{type}/{task} URI for domain/type/task format
+ *
+ * @param domain - Knowledge domain (e.g., 'typescript', 'docker')
+ * @param type - Knowledge type (e.g., 'rule', 'pattern', 'context')
+ * @param task - Task identifier (e.g., 'error-handling', 'networking')
+ * @returns kairos:// domain/type/task URI
+ *
+ * @example
+ * buildDomainTypeTaskURI('docker', 'pattern', 'networking')
+ * // Returns: 'kairos://docker/pattern/networking'
+ */
+export declare function buildDomainTypeTaskURI(domain: string, type: string, task: string): string;
+/**
+ * Build kairos://{domain}/{type}/{task}/step/{step} URI for protocol steps
+ *
+ * @param domain - Knowledge domain
+ * @param type - Knowledge type
+ * @param task - Task identifier
+ * @param step - Step number (1-based)
+ * @returns kairos:// protocol step URI
+ *
+ * @example
+ * buildProtocolStepURI('ai', 'rule', 'coding-rules', 3)
+ * // Returns: 'kairos://ai/rule/coding-rules/step/3'
+ */
+export declare function buildProtocolStepURI(domain: string, type: string, task: string, step: number): string;
+//# sourceMappingURL=uri-builder.d.ts.map

package/dist/utils/uri-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-builder.d.ts","sourceRoot":"","sources":["../../src/utils/uri-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAYzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAgBrG"}

package/dist/utils/uri-builder.js

@@ -0,0 +1,60 @@
+/**
+ * URI Builder for KAIROS Resources
+ *
+ * Generates canonical kairos:// URIs for:
+ * - Domain/type/task resources: kairos://{domain}/{type}/{task}
+ * - Protocol steps: kairos://{domain}/{type}/{task}/step/{n}
+ * - Unified UUID resources: kairos://{uuid}
+ * - Templates: kairos://templates/{template_type}/{param}
+ */
+/**
+ * Build kairos://{domain}/{type}/{task} URI for domain/type/task format
+ *
+ * @param domain - Knowledge domain (e.g., 'typescript', 'docker')
+ * @param type - Knowledge type (e.g., 'rule', 'pattern', 'context')
+ * @param task - Task identifier (e.g., 'error-handling', 'networking')
+ * @returns kairos:// domain/type/task URI
+ *
+ * @example
+ * buildDomainTypeTaskURI('docker', 'pattern', 'networking')
+ * // Returns: 'kairos://docker/pattern/networking'
+ */
+export function buildDomainTypeTaskURI(domain, type, task) {
+    if (!domain || !type || !task) {
+        throw new Error('buildDomainTypeTaskURI requires domain, type, and task parameters');
+    }
+    // Validate domain/type/task format (lowercase, alphanumeric, hyphens)
+    const validFormat = /^[a-z0-9-]+$/;
+    if (!validFormat.test(domain) || !validFormat.test(type) || !validFormat.test(task)) {
+        throw new Error('Domain, type, and task must be lowercase alphanumeric with hyphens only');
+    }
+    return `kairos://${domain}/${type}/${task}`;
+}
+/**
+ * Build kairos://{domain}/{type}/{task}/step/{step} URI for protocol steps
+ *
+ * @param domain - Knowledge domain
+ * @param type - Knowledge type
+ * @param task - Task identifier
+ * @param step - Step number (1-based)
+ * @returns kairos:// protocol step URI
+ *
+ * @example
+ * buildProtocolStepURI('ai', 'rule', 'coding-rules', 3)
+ * // Returns: 'kairos://ai/rule/coding-rules/step/3'
+ */
+export function buildProtocolStepURI(domain, type, task, step) {
+    if (!domain || !type || !task || step === undefined || step === null) {
+        throw new Error('buildProtocolStepURI requires domain, type, task, and step parameters');
+    }
+    if (!Number.isInteger(step) || step < 1) {
+        throw new Error('Step must be a positive integer');
+    }
+    // Validate domain/type/task format
+    const validFormat = /^[a-z0-9-]+$/;
+    if (!validFormat.test(domain) || !validFormat.test(type) || !validFormat.test(task)) {
+        throw new Error('Domain, type, and task must be lowercase alphanumeric with hyphens only');
+    }
+    return `kairos://${domain}/${type}/${task}/step/${step}`;
+}
+//# sourceMappingURL=uri-builder.js.map

package/dist/utils/uri-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-builder.js","sourceRoot":"","sources":["../../src/utils/uri-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,IAAY,EAAE,IAAY;IAC7E,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACzF,CAAC;IAED,sEAAsE;IACtE,MAAM,WAAW,GAAG,cAAc,CAAC;IACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO,YAAY,MAAM,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY;IACzF,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IAED,mCAAmC;IACnC,MAAM,WAAW,GAAG,cAAc,CAAC;IACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO,YAAY,MAAM,IAAI,IAAI,IAAI,IAAI,SAAS,IAAI,EAAE,CAAC;AAC7D,CAAC"}