@jungjaehoon/mama-core 2.1.2 → 2.2.1

package/db/migrations/064-create-principals.sql

@@ -0,0 +1,27 @@
+CREATE TABLE IF NOT EXISTS principals (
+  principal_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('owner', 'member')),
+  display_name TEXT,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'suspended', 'offboarded')),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_principals_at_most_one_owner
+  ON principals(kind)
+  WHERE kind = 'owner' AND status = 'active';
+
+CREATE TABLE IF NOT EXISTS external_identities (
+  connector TEXT NOT NULL,
+  namespace TEXT NOT NULL,
+  external_id TEXT NOT NULL,
+  principal_id TEXT NOT NULL REFERENCES principals(principal_id),
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (connector, namespace, external_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_external_identities_principal
+  ON external_identities(principal_id);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (64, 'Create principals and external_identities for member registry');

package/db/migrations/065-create-principal-scope-grants.sql

@@ -0,0 +1,24 @@
+CREATE TABLE IF NOT EXISTS principal_scope_grants (
+  principal_id TEXT NOT NULL REFERENCES principals(principal_id),
+  grant_kind TEXT NOT NULL CHECK (grant_kind IN ('source', 'memory')),
+  scope_kind TEXT NOT NULL CHECK (
+    length(trim(scope_kind)) > 0
+    AND scope_kind <> '*'
+    AND (grant_kind = 'source' OR scope_kind IN ('project', 'channel', 'global'))
+  ),
+  scope_id TEXT NOT NULL CHECK (length(trim(scope_id)) > 0 AND scope_id <> '*'),
+  granted_by_principal_id TEXT NOT NULL REFERENCES principals(principal_id),
+  created_at INTEGER NOT NULL,
+  revoked_at INTEGER CHECK (revoked_at IS NULL OR revoked_at >= created_at)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_principal_scope_grants_one_active
+  ON principal_scope_grants(principal_id, grant_kind, scope_kind, scope_id)
+  WHERE revoked_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_principal_scope_grants_active_listing
+  ON principal_scope_grants(principal_id, created_at, grant_kind, scope_kind, scope_id)
+  WHERE revoked_at IS NULL;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (65, 'Create principal scope grants for human-team access');

package/dist/embedding-server/index.js

@@ -32,9 +32,9 @@ exports.SHUTDOWN_TOKEN = process.env.MAMA_SHUTDOWN_TOKEN || crypto_1.default.ran
 const embeddings_js_1 = require("../embeddings.js");
 const config_loader_js_1 = require("../config-loader.js");
 const db_manager_js_1 = require("../db-manager.js");
-// Import Session API handler (Mobile Chat)
+// Import Session API handler (chat session API)
 const session_api_js_1 = require("./mobile/session-api.js");
-// Import WebSocket handler (Mobile Chat - V2 with MessageRouter)
+// Import WebSocket handler (chat WebSocket API - V2 with MessageRouter)
 const websocket_handler_js_1 = require("./mobile/websocket-handler.js");
 // Import Session Manager
 const session_manager_js_1 = require("./mobile/session-manager.js");
@@ -95,7 +95,7 @@ async function handleRequest(req, res) {
     // Security Note: CORS '*' is safe here because:
     // 1. Server binds to localhost only (127.0.0.1)
     // 2. No sensitive data exposed (user's own decisions)
-    // 3. Required for browser-based Graph Viewer
+    // 3. Required for the browser-based Viewer
     res.setHeader('Content-Type', 'application/json');
     res.setHeader('Access-Control-Allow-Origin', '*');
     // Health check
@@ -212,7 +212,7 @@ async function handleRequest(req, res) {
         }
         return;
     }
-    // Session API routes (Mobile Chat)
+    // Session API routes (chat session API)
     try {
         const sessionHandled = await sessionHandler(req, res);
         if (sessionHandled) {
@@ -257,7 +257,7 @@ async function handleRequest(req, res) {
 <body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee;">
   <div style="text-align: center; padding: 2rem;">
     <h1>🧠 MAMA Viewer</h1>
-    <p>Viewer and Chat features are only available in <strong>Standalone</strong> mode.</p>
+    <p>The Viewer is only available in <strong>Standalone</strong> mode.</p>
     <p style="color: #888; margin-top: 1rem;">Start Standalone: <code style="background: #333; padding: 0.25rem 0.5rem; border-radius: 4px;">mama start</code></p>
     <p style="color: #666; font-size: 0.9rem; margin-top: 2rem;">Current: MCP Server (embedding only)</p>
   </div>
@@ -313,7 +313,7 @@ async function startEmbeddingServer(port = exports.DEFAULT_PORT, options = {}) {
     // Check if HTTP server is disabled
     if (process.env.MAMA_DISABLE_HTTP_SERVER === 'true') {
         console.error('[EmbeddingHTTP] HTTP server disabled via MAMA_DISABLE_HTTP_SERVER');
-        console.error('[EmbeddingHTTP] Graph Viewer and Mobile Chat will not be available');
+        console.error('[EmbeddingHTTP] The Viewer and the chat WebSocket API will not be available');
         return null;
     }
     // Initialize database for graph API

package/dist/identity/principal-repository.d.ts

@@ -0,0 +1,68 @@
+import type { DatabaseAdapter as DBManagerAdapter } from '../db-manager.js';
+export interface PrincipalRow {
+    principalId: string;
+    kind: 'owner' | 'member';
+    status: 'active' | 'suspended' | 'offboarded';
+}
+export declare const SHARED_MEMORY_SCOPE_KINDS: readonly ["project", "channel", "global"];
+export type SharedMemoryScopeKind = (typeof SHARED_MEMORY_SCOPE_KINDS)[number];
+export type PrincipalScopeGrantRef = {
+    kind: 'source';
+    connector: string;
+    channelId: string;
+} | {
+    kind: 'memory';
+    scopeKind: SharedMemoryScopeKind;
+    scopeId: string;
+};
+export interface PrincipalScopeGrantRecord {
+    targetPrincipalId: string;
+    scope: PrincipalScopeGrantRef;
+    grantedByPrincipalId: string;
+    createdAt: number;
+}
+export interface PrincipalScopeGrantMutationInput {
+    targetPrincipalId: string;
+    ownerPrincipalId: string;
+    scope: PrincipalScopeGrantRef;
+    now: number;
+}
+export interface PrincipalRepository {
+    resolveByExternal(connector: string, namespace: string, externalId: string): PrincipalRow | null;
+    registerMember(input: {
+        displayName?: string;
+        connector: string;
+        namespace: string;
+        externalId: string;
+        now: number;
+    }): string;
+    bindIdentity(principalId: string, connector: string, namespace: string, externalId: string, now: number): void;
+    suspend(principalId: string, now: number): void;
+    offboard(principalId: string, now: number): void;
+    ensureOwner(input: {
+        connector: string;
+        namespace: string;
+        externalId: string;
+        now: number;
+    }): 'created' | 'exists' | 'conflict';
+    listMembers(): Array<{
+        principalId: string;
+        displayName?: string;
+        status: string;
+    }>;
+    grantScope(input: PrincipalScopeGrantMutationInput): 'created' | 'exists';
+    revokeScope(input: PrincipalScopeGrantMutationInput): 'revoked' | 'absent';
+    listActiveGrants(principalId: string): PrincipalScopeGrantRecord[];
+}
+export type PrincipalRegistrationErrorCode = 'identity_bound_to_owner' | 'member_not_active';
+export declare class PrincipalRegistrationError extends Error {
+    readonly code: PrincipalRegistrationErrorCode;
+    constructor(code: PrincipalRegistrationErrorCode, message: string);
+}
+export type PrincipalScopeGrantErrorCode = 'target_not_active_member' | 'grantor_not_active_owner' | 'invalid_scope';
+export declare class PrincipalScopeGrantError extends Error {
+    readonly code: PrincipalScopeGrantErrorCode;
+    constructor(code: PrincipalScopeGrantErrorCode, message: string);
+}
+export declare function createPrincipalRepository(adapter: Pick<DBManagerAdapter, 'prepare' | 'transaction'>): PrincipalRepository;
+//# sourceMappingURL=principal-repository.d.ts.map

package/dist/identity/principal-repository.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalScopeGrantError = exports.PrincipalRegistrationError = exports.SHARED_MEMORY_SCOPE_KINDS = void 0;
+exports.createPrincipalRepository = createPrincipalRepository;
+const node_crypto_1 = require("node:crypto");
+exports.SHARED_MEMORY_SCOPE_KINDS = ['project', 'channel', 'global'];
+class PrincipalRegistrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PrincipalRegistrationError';
+        this.code = code;
+    }
+}
+exports.PrincipalRegistrationError = PrincipalRegistrationError;
+class PrincipalScopeGrantError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PrincipalScopeGrantError';
+        this.code = code;
+    }
+}
+exports.PrincipalScopeGrantError = PrincipalScopeGrantError;
+const MAX_SCOPE_COMPONENT_LENGTH = 512;
+function containsControlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint < 32 || codePoint === 127;
+    });
+}
+function canonicalizeScopeComponent(value, label, lowercase = false) {
+    if (typeof value !== 'string') {
+        throw new PrincipalScopeGrantError('invalid_scope', `${label} must be a string`);
+    }
+    const trimmed = value.trim();
+    const canonical = lowercase ? trimmed.toLowerCase() : trimmed;
+    if (canonical.length === 0 ||
+        canonical.length > MAX_SCOPE_COMPONENT_LENGTH ||
+        canonical === '*' ||
+        containsControlCharacter(canonical)) {
+        throw new PrincipalScopeGrantError('invalid_scope', `${label} is not a canonical scope value`);
+    }
+    return canonical;
+}
+function canonicalizeGrantScope(scope) {
+    if (typeof scope !== 'object' || scope === null) {
+        throw new PrincipalScopeGrantError('invalid_scope', 'Grant scope must be an object');
+    }
+    const candidate = scope;
+    if (candidate.kind === 'source') {
+        return {
+            kind: 'source',
+            connector: canonicalizeScopeComponent(candidate.connector, 'Source connector', true),
+            channelId: canonicalizeScopeComponent(candidate.channelId, 'Source channel ID'),
+        };
+    }
+    if (candidate.kind === 'memory') {
+        if (typeof candidate.scopeKind !== 'string' ||
+            !exports.SHARED_MEMORY_SCOPE_KINDS.includes(candidate.scopeKind)) {
+            throw new PrincipalScopeGrantError('invalid_scope', 'Memory grant kind must be project, channel, or global');
+        }
+        return {
+            kind: 'memory',
+            scopeKind: candidate.scopeKind,
+            scopeId: canonicalizeScopeComponent(candidate.scopeId, 'Memory scope ID'),
+        };
+    }
+    throw new PrincipalScopeGrantError('invalid_scope', 'Grant kind must be source or memory');
+}
+function scopeColumns(scope) {
+    if (scope.kind === 'source') {
+        return {
+            grantKind: 'source',
+            scopeKind: scope.connector,
+            scopeId: scope.channelId,
+        };
+    }
+    return {
+        grantKind: 'memory',
+        scopeKind: scope.scopeKind,
+        scopeId: scope.scopeId,
+    };
+}
+function mapPrincipalScopeGrant(row) {
+    const scope = row.grant_kind === 'source'
+        ? { kind: 'source', connector: row.scope_kind, channelId: row.scope_id }
+        : {
+            kind: 'memory',
+            scopeKind: row.scope_kind,
+            scopeId: row.scope_id,
+        };
+    return {
+        targetPrincipalId: row.principal_id,
+        scope,
+        grantedByPrincipalId: row.granted_by_principal_id,
+        createdAt: row.created_at,
+    };
+}
+function mintPrincipalId(kind, connector, namespace, externalId) {
+    const identityKey = JSON.stringify([kind, connector, namespace, externalId]);
+    const digest = (0, node_crypto_1.createHash)('sha256').update(identityKey, 'utf8').digest('hex');
+    return `principal_${digest}`;
+}
+function mapPrincipal(row) {
+    return {
+        principalId: row.principal_id,
+        kind: row.kind,
+        status: row.status,
+    };
+}
+function createPrincipalRepository(adapter) {
+    const resolveByExternalStatement = adapter.prepare(`SELECT p.principal_id, p.kind, p.status
+     FROM external_identities AS e
+     JOIN principals AS p ON p.principal_id = e.principal_id
+     WHERE e.connector = ? AND e.namespace = ? AND e.external_id = ?`);
+    const insertPrincipalStatement = adapter.prepare(`INSERT INTO principals (
+       principal_id, kind, display_name, status, created_at, updated_at
+     ) VALUES (?, ?, ?, 'active', ?, ?)`);
+    const insertIdentityStatement = adapter.prepare(`INSERT INTO external_identities (
+       connector, namespace, external_id, principal_id, created_at
+     ) VALUES (?, ?, ?, ?, ?)`);
+    const selectPrincipalKindStatement = adapter.prepare('SELECT kind FROM principals WHERE principal_id = ?');
+    const updatePrincipalStatusStatement = adapter.prepare('UPDATE principals SET status = ?, updated_at = ? WHERE principal_id = ?');
+    const selectActiveOwnerStatement = adapter.prepare("SELECT principal_id FROM principals WHERE kind = 'owner' AND status = 'active' LIMIT 1");
+    const listMembersStatement = adapter.prepare(`SELECT principal_id, display_name, status
+     FROM principals
+     WHERE kind = 'member'
+     ORDER BY created_at ASC, principal_id ASC`);
+    const selectActiveMemberStatement = adapter.prepare(`SELECT 1
+     FROM principals
+     WHERE principal_id = ? AND kind = 'member' AND status = 'active'`);
+    const selectActiveGrantorStatement = adapter.prepare(`SELECT 1
+     FROM principals
+     WHERE principal_id = ? AND kind = 'owner' AND status = 'active'`);
+    const insertGrantStatement = adapter.prepare(`INSERT INTO principal_scope_grants (
+       principal_id, grant_kind, scope_kind, scope_id,
+       granted_by_principal_id, created_at, revoked_at
+     )
+     SELECT ?, ?, ?, ?, ?, ?, NULL
+     WHERE EXISTS (
+       SELECT 1 FROM principals
+       WHERE principal_id = ? AND kind = 'member' AND status = 'active'
+     )
+       AND EXISTS (
+         SELECT 1 FROM principals
+         WHERE principal_id = ? AND kind = 'owner' AND status = 'active'
+       )
+     ON CONFLICT (principal_id, grant_kind, scope_kind, scope_id)
+       WHERE revoked_at IS NULL
+     DO NOTHING`);
+    const revokeGrantStatement = adapter.prepare(`UPDATE principal_scope_grants
+     SET revoked_at = ?
+     WHERE principal_id = ? AND grant_kind = ? AND scope_kind = ? AND scope_id = ?
+       AND revoked_at IS NULL
+       AND EXISTS (
+         SELECT 1 FROM principals
+         WHERE principal_id = ? AND kind = 'member' AND status = 'active'
+       )
+       AND EXISTS (
+         SELECT 1 FROM principals
+         WHERE principal_id = ? AND kind = 'owner' AND status = 'active'
+       )`);
+    const listActiveGrantsStatement = adapter.prepare(`SELECT
+       grants.principal_id,
+       grants.grant_kind,
+       grants.scope_kind,
+       grants.scope_id,
+       grants.granted_by_principal_id,
+       grants.created_at
+     FROM principal_scope_grants AS grants
+     JOIN principals AS target ON target.principal_id = grants.principal_id
+     WHERE grants.principal_id = ?
+       AND grants.revoked_at IS NULL
+       AND target.kind = 'member'
+       AND target.status = 'active'
+     ORDER BY grants.created_at ASC, grants.grant_kind ASC,
+       grants.scope_kind ASC, grants.scope_id ASC`);
+    function assertGrantMutationPrincipals(targetPrincipalId, ownerPrincipalId) {
+        if (!selectActiveMemberStatement.get(targetPrincipalId)) {
+            throw new PrincipalScopeGrantError('target_not_active_member', 'Grant target must be an active member principal');
+        }
+        if (!selectActiveGrantorStatement.get(ownerPrincipalId)) {
+            throw new PrincipalScopeGrantError('grantor_not_active_owner', 'Grant mutation requires an active owner principal');
+        }
+    }
+    function resolveByExternal(connector, namespace, externalId) {
+        const row = resolveByExternalStatement.get(connector, namespace, externalId);
+        return row ? mapPrincipal(row) : null;
+    }
+    function bindIdentity(principalId, connector, namespace, externalId, now) {
+        insertIdentityStatement.run(connector, namespace, externalId, principalId, now);
+    }
+    function registerMember(input) {
+        const existing = resolveByExternal(input.connector, input.namespace, input.externalId);
+        if (existing) {
+            if (existing.kind === 'member' && existing.status === 'active') {
+                return existing.principalId;
+            }
+            if (existing.kind === 'owner') {
+                throw new PrincipalRegistrationError('identity_bound_to_owner', 'External identity is already bound to an owner principal');
+            }
+            throw new PrincipalRegistrationError('member_not_active', 'External identity is already bound to a non-active member principal');
+        }
+        const principalId = mintPrincipalId('member', input.connector, input.namespace, input.externalId);
+        adapter.transaction(() => {
+            insertPrincipalStatement.run(principalId, 'member', input.displayName ?? null, input.now, input.now);
+            bindIdentity(principalId, input.connector, input.namespace, input.externalId, input.now);
+        });
+        return principalId;
+    }
+    function transitionMember(principalId, status, now) {
+        const principal = selectPrincipalKindStatement.get(principalId);
+        if (!principal) {
+            throw new Error(`Principal not found: ${principalId}`);
+        }
+        if (principal.kind === 'owner') {
+            throw new Error(`Owner principals cannot be ${status}`);
+        }
+        updatePrincipalStatusStatement.run(status, now, principalId);
+    }
+    function ensureOwner(input) {
+        return adapter.transaction(() => {
+            const existing = resolveByExternal(input.connector, input.namespace, input.externalId);
+            if (existing) {
+                return existing.kind === 'owner' ? 'exists' : 'conflict';
+            }
+            if (selectActiveOwnerStatement.get()) {
+                return 'conflict';
+            }
+            const principalId = mintPrincipalId('owner', input.connector, input.namespace, input.externalId);
+            insertPrincipalStatement.run(principalId, 'owner', null, input.now, input.now);
+            bindIdentity(principalId, input.connector, input.namespace, input.externalId, input.now);
+            return 'created';
+        });
+    }
+    function listMembers() {
+        return listMembersStatement.all().map((row) => {
+            const member = {
+                principalId: row.principal_id,
+                status: row.status,
+            };
+            return row.display_name === null ? member : { ...member, displayName: row.display_name };
+        });
+    }
+    function grantScope(input) {
+        const canonicalScope = canonicalizeGrantScope(input.scope);
+        const { grantKind, scopeKind, scopeId } = scopeColumns(canonicalScope);
+        return adapter.transaction(() => {
+            const result = insertGrantStatement.run(input.targetPrincipalId, grantKind, scopeKind, scopeId, input.ownerPrincipalId, input.now, input.targetPrincipalId, input.ownerPrincipalId);
+            if (result.changes === 1) {
+                return 'created';
+            }
+            assertGrantMutationPrincipals(input.targetPrincipalId, input.ownerPrincipalId);
+            return 'exists';
+        });
+    }
+    function revokeScope(input) {
+        const canonicalScope = canonicalizeGrantScope(input.scope);
+        const { grantKind, scopeKind, scopeId } = scopeColumns(canonicalScope);
+        return adapter.transaction(() => {
+            const result = revokeGrantStatement.run(input.now, input.targetPrincipalId, grantKind, scopeKind, scopeId, input.targetPrincipalId, input.ownerPrincipalId);
+            if (result.changes === 1) {
+                return 'revoked';
+            }
+            assertGrantMutationPrincipals(input.targetPrincipalId, input.ownerPrincipalId);
+            return 'absent';
+        });
+    }
+    function listActiveGrants(principalId) {
+        return listActiveGrantsStatement.all(principalId).map(mapPrincipalScopeGrant);
+    }
+    return {
+        resolveByExternal,
+        registerMember,
+        bindIdentity,
+        suspend(principalId, now) {
+            transitionMember(principalId, 'suspended', now);
+        },
+        offboard(principalId, now) {
+            transitionMember(principalId, 'offboarded', now);
+        },
+        ensureOwner,
+        listMembers,
+        grantScope,
+        revokeScope,
+        listActiveGrants,
+    };
+}
+//# sourceMappingURL=principal-repository.js.map

package/dist/index.d.ts

@@ -72,6 +72,7 @@ export * from './cases/wiki-page-index.js';
 export * from './connectors/event-index.js';
 export * from './connectors/raw-query.js';
 export * from './connectors/types.js';
+export * from './identity/principal-repository.js';
 export * from './search/question-type.js';
 export * from './search/feedback-store.js';
 export * from './search/ranker-features.js';

package/dist/index.js

@@ -264,6 +264,7 @@ __exportStar(require("./cases/wiki-page-index.js"), exports);
 __exportStar(require("./connectors/event-index.js"), exports);
 __exportStar(require("./connectors/raw-query.js"), exports);
 __exportStar(require("./connectors/types.js"), exports);
+__exportStar(require("./identity/principal-repository.js"), exports);
 __exportStar(require("./search/question-type.js"), exports);
 __exportStar(require("./search/feedback-store.js"), exports);
 __exportStar(require("./search/ranker-features.js"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungjaehoon/mama-core",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "MAMA Core - Shared modules for Memory-Augmented MCP Assistant",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",