@prmichaelsen/remember-mcp 3.0.0 → 3.13.0

package/src/services/access-control.ts

@@ -0,0 +1,291 @@
+/**
+ * Access control service — per-memory access checks with escalation prevention.
+ *
+ * In ghost mode (default), query-level filtering handles trust at the Weaviate layer.
+ * This service is needed for:
+ * 1. Trust escalation penalty tracking
+ * 2. Block management
+ * 3. Prompt/hybrid enforcement modes (per-memory access checks)
+ * 4. Future direct access tools
+ *
+ * See agent/design/access-control-result-pattern.md
+ * See agent/design/local.ghost-persona-system.md
+ */
+
+import type { Memory } from '../types/memory.js';
+import type { AccessResult } from '../types/access-result.js';
+import type { GhostConfig } from '../types/ghost-config.js';
+import { DEFAULT_GHOST_CONFIG } from '../types/ghost-config.js';
+import { isTrustSufficient } from './trust-enforcement.js';
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+/** Block record for a specific (accessor, memory) pair */
+export interface MemoryBlock {
+  blocked_at: string; // ISO 8601
+  reason: string;
+  attempt_count: number;
+}
+
+/** Attempt record for escalation tracking */
+export interface AttemptRecord {
+  count: number;
+  last_attempt_at: string; // ISO 8601
+}
+
+/**
+ * Provider interface for GhostConfig lookups.
+ * In-memory stub now, Firestore implementation in M16.
+ */
+export interface GhostConfigProvider {
+  getGhostConfig(ownerUserId: string): Promise<GhostConfig | null>;
+}
+
+/**
+ * Provider interface for block and attempt tracking.
+ * In-memory stub now, Firestore implementation in M16.
+ */
+export interface EscalationStore {
+  getBlock(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<MemoryBlock | null>;
+  setBlock(ownerUserId: string, accessorUserId: string, memoryId: string, block: MemoryBlock): Promise<void>;
+  removeBlock(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<void>;
+  getAttempts(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<AttemptRecord | null>;
+  incrementAttempts(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<AttemptRecord>;
+}
+
+// ─── In-Memory Implementations ────────────────────────────────────────────
+
+/** Stub GhostConfig provider — returns null (ghost not configured) */
+export class StubGhostConfigProvider implements GhostConfigProvider {
+  private configs: Map<string, GhostConfig> = new Map();
+
+  async getGhostConfig(ownerUserId: string): Promise<GhostConfig | null> {
+    return this.configs.get(ownerUserId) ?? null;
+  }
+
+  /** Test helper: set a GhostConfig for a user */
+  setGhostConfig(ownerUserId: string, config: GhostConfig): void {
+    this.configs.set(ownerUserId, config);
+  }
+}
+
+/** In-memory escalation store for development/testing */
+export class InMemoryEscalationStore implements EscalationStore {
+  private blocks: Map<string, MemoryBlock> = new Map();
+  private attempts: Map<string, AttemptRecord> = new Map();
+
+  private key(ownerUserId: string, accessorUserId: string, memoryId: string): string {
+    return `${ownerUserId}:${accessorUserId}:${memoryId}`;
+  }
+
+  async getBlock(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<MemoryBlock | null> {
+    return this.blocks.get(this.key(ownerUserId, accessorUserId, memoryId)) ?? null;
+  }
+
+  async setBlock(ownerUserId: string, accessorUserId: string, memoryId: string, block: MemoryBlock): Promise<void> {
+    this.blocks.set(this.key(ownerUserId, accessorUserId, memoryId), block);
+  }
+
+  async removeBlock(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<void> {
+    this.blocks.delete(this.key(ownerUserId, accessorUserId, memoryId));
+  }
+
+  async getAttempts(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<AttemptRecord | null> {
+    return this.attempts.get(this.key(ownerUserId, accessorUserId, memoryId)) ?? null;
+  }
+
+  async incrementAttempts(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<AttemptRecord> {
+    const k = this.key(ownerUserId, accessorUserId, memoryId);
+    const existing = this.attempts.get(k);
+    const record: AttemptRecord = {
+      count: (existing?.count ?? 0) + 1,
+      last_attempt_at: new Date().toISOString(),
+    };
+    this.attempts.set(k, record);
+    return record;
+  }
+}
+
+// ─── Constants ─────────────────────────────────────────────────────────────
+
+/** Trust penalty applied per failed access attempt */
+const TRUST_PENALTY = 0.1;
+
+/** Number of failed attempts before blocking */
+const MAX_ATTEMPTS_BEFORE_BLOCK = 3;
+
+// ─── Core Access Control ───────────────────────────────────────────────────
+
+/**
+ * Check if an accessor has permission to access a specific memory.
+ *
+ * Flow:
+ * 1. Self-access → always granted (owner)
+ * 2. Ghost not enabled → no_permission
+ * 3. Accessor blocked by owner → no_permission
+ * 4. Memory-specific block → blocked
+ * 5. Insufficient trust → insufficient_trust (+ penalty, possible block)
+ * 6. Sufficient trust → granted (trusted; trust 1.0 memories capped to existence-only by formatting layer)
+ */
+export async function checkMemoryAccess(
+  accessorUserId: string,
+  memory: Memory,
+  ghostConfigProvider: GhostConfigProvider,
+  escalationStore: EscalationStore,
+): Promise<AccessResult> {
+  const ownerUserId = memory.user_id;
+  const memoryId = memory.id;
+
+  // 1. Self-access always granted
+  if (accessorUserId === ownerUserId) {
+    return { status: 'granted', memory, access_level: 'owner' };
+  }
+
+  // 2. Check if ghost is enabled for owner
+  const ghostConfig = await ghostConfigProvider.getGhostConfig(ownerUserId);
+  if (!ghostConfig || !ghostConfig.enabled) {
+    return { status: 'no_permission', owner_user_id: ownerUserId, accessor_user_id: accessorUserId };
+  }
+
+  // 3. Check if accessor is user-wide blocked
+  if (ghostConfig.blocked_users.includes(accessorUserId)) {
+    return { status: 'no_permission', owner_user_id: ownerUserId, accessor_user_id: accessorUserId };
+  }
+
+  // 4. Check memory-specific block
+  const block = await escalationStore.getBlock(ownerUserId, accessorUserId, memoryId);
+  if (block) {
+    return {
+      status: 'blocked',
+      memory_id: memoryId,
+      reason: block.reason,
+      blocked_at: block.blocked_at,
+    };
+  }
+
+  // 5. Check trust level
+  const accessorTrust = resolveAccessorTrustLevel(ghostConfig, accessorUserId);
+  const memoryTrust = memory.trust;
+
+  if (!isTrustSufficient(memoryTrust, accessorTrust)) {
+    // Apply escalation
+    const result = await handleInsufficientTrust(
+      ownerUserId, accessorUserId, memoryId, memoryTrust, accessorTrust, escalationStore
+    );
+    return result;
+  }
+
+  // 6. All checks pass (trust 1.0 memories capped to existence-only by formatting layer)
+  return { status: 'granted', memory, access_level: 'trusted' };
+}
+
+// ─── Trust Escalation ──────────────────────────────────────────────────────
+
+/**
+ * Handle an insufficient trust access attempt.
+ * Applies -0.1 penalty, blocks after 3 attempts.
+ */
+export async function handleInsufficientTrust(
+  ownerUserId: string,
+  accessorUserId: string,
+  memoryId: string,
+  requiredTrust: number,
+  actualTrust: number,
+  escalationStore: EscalationStore,
+): Promise<AccessResult> {
+  const attempt = await escalationStore.incrementAttempts(ownerUserId, accessorUserId, memoryId);
+
+  // Block after MAX_ATTEMPTS_BEFORE_BLOCK
+  if (attempt.count >= MAX_ATTEMPTS_BEFORE_BLOCK) {
+    const block: MemoryBlock = {
+      blocked_at: new Date().toISOString(),
+      reason: `Access blocked after ${attempt.count} unauthorized attempts`,
+      attempt_count: attempt.count,
+    };
+    await escalationStore.setBlock(ownerUserId, accessorUserId, memoryId, block);
+    return {
+      status: 'blocked',
+      memory_id: memoryId,
+      reason: block.reason,
+      blocked_at: block.blocked_at,
+    };
+  }
+
+  return {
+    status: 'insufficient_trust',
+    memory_id: memoryId,
+    required_trust: requiredTrust,
+    actual_trust: Math.max(0, actualTrust - TRUST_PENALTY),
+    attempts_remaining: MAX_ATTEMPTS_BEFORE_BLOCK - attempt.count,
+  };
+}
+
+/**
+ * Check if access to a specific memory is blocked.
+ */
+export async function isMemoryBlocked(
+  ownerUserId: string,
+  accessorUserId: string,
+  memoryId: string,
+  escalationStore: EscalationStore,
+): Promise<boolean> {
+  const block = await escalationStore.getBlock(ownerUserId, accessorUserId, memoryId);
+  return block !== null;
+}
+
+/**
+ * Reset a memory-specific block (e.g., via grant_access).
+ */
+export async function resetBlock(
+  ownerUserId: string,
+  accessorUserId: string,
+  memoryId: string,
+  escalationStore: EscalationStore,
+): Promise<void> {
+  await escalationStore.removeBlock(ownerUserId, accessorUserId, memoryId);
+}
+
+// ─── Trust Resolution ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the trust level for an accessor from GhostConfig.
+ *
+ * Priority: per_user_trust → default_friend_trust → default_public_trust → 0
+ *
+ * Note: "friend" vs "public" distinction will be determined by the calling
+ * context in M16 (friend list, social graph). For now, non-per_user accessors
+ * fall through to default_public_trust.
+ */
+export function resolveAccessorTrustLevel(ghostConfig: GhostConfig, accessorUserId: string): number {
+  // 1. Per-user override
+  if (accessorUserId in ghostConfig.per_user_trust) {
+    return ghostConfig.per_user_trust[accessorUserId];
+  }
+
+  // 2. Fall through to public trust (friend detection deferred to M16)
+  return ghostConfig.default_public_trust ?? 0;
+}
+
+// ─── Message Formatting ───────────────────────────────────────────────────
+
+/**
+ * Format an AccessResult into a human-readable message.
+ */
+export function formatAccessResultMessage(result: AccessResult): string {
+  switch (result.status) {
+    case 'granted':
+      return result.access_level === 'owner'
+        ? 'Access granted (owner).'
+        : 'Access granted (trusted).';
+    case 'insufficient_trust':
+      return `Insufficient trust level. Required: ${result.required_trust.toFixed(2)}, actual: ${result.actual_trust.toFixed(2)}. ${result.attempts_remaining} attempt(s) remaining before access is blocked.`;
+    case 'blocked':
+      return `Access blocked: ${result.reason}`;
+    case 'no_permission':
+      return 'No permission to access this user\'s memories.';
+    case 'not_found':
+      return `Memory ${result.memory_id} not found.`;
+    case 'deleted':
+      return `Memory ${result.memory_id} was deleted on ${result.deleted_at}.`;
+  }
+}

package/src/services/credentials-provider.spec.ts

@@ -0,0 +1,22 @@
+import { StubCredentialsProvider, createCredentialsProvider } from './credentials-provider.js';
+
+describe('StubCredentialsProvider', () => {
+  it('returns the correct userId', async () => {
+    const provider = new StubCredentialsProvider();
+    const creds = await provider.getCredentials('token-123', 'user-abc');
+    expect(creds.user_id).toBe('user-abc');
+  });
+
+  it('returns empty group_memberships', async () => {
+    const provider = new StubCredentialsProvider();
+    const creds = await provider.getCredentials('token-123', 'user-abc');
+    expect(creds.group_memberships).toEqual([]);
+  });
+});
+
+describe('createCredentialsProvider', () => {
+  it('returns a StubCredentialsProvider instance', () => {
+    const provider = createCredentialsProvider();
+    expect(provider).toBeInstanceOf(StubCredentialsProvider);
+  });
+});

package/src/services/credentials-provider.ts

@@ -0,0 +1,34 @@
+/**
+ * Credentials Provider
+ *
+ * Resolves user credentials (group memberships, permissions) from an access token.
+ * Currently uses a stub implementation; future: HTTP provider hitting /api/credentials/agentbase.
+ */
+
+import type { CredentialsProvider, UserCredentials } from '../types/auth.js';
+
+/**
+ * Stub credentials provider — returns empty group memberships.
+ * Used until an HTTP-based provider is wired up.
+ */
+export class StubCredentialsProvider implements CredentialsProvider {
+  async getCredentials(_accessToken: string, userId: string): Promise<UserCredentials> {
+    return {
+      user_id: userId,
+      group_memberships: [],
+    };
+  }
+}
+
+/**
+ * Factory to create the appropriate credentials provider.
+ * Future: reads config to pick stub vs HTTP implementation.
+ */
+export function createCredentialsProvider(): CredentialsProvider {
+  return new StubCredentialsProvider();
+}
+
+/**
+ * Singleton credentials provider instance
+ */
+export const credentialsProvider = createCredentialsProvider();

package/src/services/escalation.service.spec.ts

@@ -0,0 +1,183 @@
+import { FirestoreEscalationStore } from './escalation.service.js';
+import * as firestoreInit from '../firestore/init';
+
+jest.mock('../firestore/init', () => ({
+  getDocument: jest.fn(),
+  setDocument: jest.fn(),
+  deleteDocument: jest.fn(),
+}));
+
+jest.mock('../firestore/paths', () => ({
+  BASE: 'test-remember-mcp',
+}));
+
+const mockGetDocument = firestoreInit.getDocument as jest.MockedFunction<typeof firestoreInit.getDocument>;
+const mockSetDocument = firestoreInit.setDocument as jest.MockedFunction<typeof firestoreInit.setDocument>;
+const mockDeleteDocument = (firestoreInit as any).deleteDocument as jest.MockedFunction<any>;
+
+describe('FirestoreEscalationStore', () => {
+  let store: FirestoreEscalationStore;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    store = new FirestoreEscalationStore();
+  });
+
+  describe('getBlock', () => {
+    it('returns null when no document exists', async () => {
+      mockGetDocument.mockResolvedValue(null);
+
+      const result = await store.getBlock('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toBeNull();
+      expect(mockGetDocument).toHaveBeenCalledWith(
+        'test-remember-mcp.users/owner-1/ghost_escalation',
+        'accessor-1:mem-1'
+      );
+    });
+
+    it('returns null when document exists but not blocked', async () => {
+      mockGetDocument.mockResolvedValue({ attempt_count: 2, blocked: false });
+
+      const result = await store.getBlock('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toBeNull();
+    });
+
+    it('returns block when document has blocked flag', async () => {
+      mockGetDocument.mockResolvedValue({
+        blocked: true,
+        blocked_at: '2026-02-27T00:00:00.000Z',
+        reason: 'Too many attempts',
+        attempt_count: 3,
+      });
+
+      const result = await store.getBlock('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toEqual({
+        blocked_at: '2026-02-27T00:00:00.000Z',
+        reason: 'Too many attempts',
+        attempt_count: 3,
+      });
+    });
+
+    it('returns null on Firestore error', async () => {
+      mockGetDocument.mockRejectedValue(new Error('Firestore unavailable'));
+
+      const result = await store.getBlock('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('setBlock', () => {
+    it('writes block to Firestore', async () => {
+      mockSetDocument.mockResolvedValue(undefined);
+
+      await store.setBlock('owner-1', 'accessor-1', 'mem-1', {
+        blocked_at: '2026-02-27T00:00:00.000Z',
+        reason: 'Escalation limit',
+        attempt_count: 3,
+      });
+
+      expect(mockSetDocument).toHaveBeenCalledWith(
+        'test-remember-mcp.users/owner-1/ghost_escalation',
+        'accessor-1:mem-1',
+        {
+          blocked: true,
+          blocked_at: '2026-02-27T00:00:00.000Z',
+          reason: 'Escalation limit',
+          attempt_count: 3,
+          accessor_user_id: 'accessor-1',
+          memory_id: 'mem-1',
+        },
+        { merge: true }
+      );
+    });
+  });
+
+  describe('removeBlock', () => {
+    it('deletes the escalation document', async () => {
+      mockDeleteDocument.mockResolvedValue(undefined);
+
+      await store.removeBlock('owner-1', 'accessor-1', 'mem-1');
+
+      expect(mockDeleteDocument).toHaveBeenCalledWith(
+        'test-remember-mcp.users/owner-1/ghost_escalation',
+        'accessor-1:mem-1'
+      );
+    });
+  });
+
+  describe('getAttempts', () => {
+    it('returns null when no document exists', async () => {
+      mockGetDocument.mockResolvedValue(null);
+
+      const result = await store.getAttempts('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toBeNull();
+    });
+
+    it('returns attempt record when document exists', async () => {
+      mockGetDocument.mockResolvedValue({
+        attempt_count: 2,
+        last_attempt_at: '2026-02-27T01:00:00.000Z',
+      });
+
+      const result = await store.getAttempts('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toEqual({
+        count: 2,
+        last_attempt_at: '2026-02-27T01:00:00.000Z',
+      });
+    });
+
+    it('returns null on Firestore error', async () => {
+      mockGetDocument.mockRejectedValue(new Error('Firestore unavailable'));
+
+      const result = await store.getAttempts('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('incrementAttempts', () => {
+    it('creates new attempt record when none exists', async () => {
+      mockGetDocument.mockResolvedValue(null);
+      mockSetDocument.mockResolvedValue(undefined);
+
+      const result = await store.incrementAttempts('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result.count).toBe(1);
+      expect(result.last_attempt_at).toBeDefined();
+      expect(mockSetDocument).toHaveBeenCalledWith(
+        'test-remember-mcp.users/owner-1/ghost_escalation',
+        'accessor-1:mem-1',
+        expect.objectContaining({
+          attempt_count: 1,
+          accessor_user_id: 'accessor-1',
+          memory_id: 'mem-1',
+        }),
+        { merge: true }
+      );
+    });
+
+    it('increments existing attempt count', async () => {
+      mockGetDocument.mockResolvedValue({
+        attempt_count: 2,
+        last_attempt_at: '2026-02-27T00:00:00.000Z',
+      });
+      mockSetDocument.mockResolvedValue(undefined);
+
+      const result = await store.incrementAttempts('owner-1', 'accessor-1', 'mem-1');
+
+      expect(result.count).toBe(3);
+      expect(mockSetDocument).toHaveBeenCalledWith(
+        'test-remember-mcp.users/owner-1/ghost_escalation',
+        'accessor-1:mem-1',
+        expect.objectContaining({ attempt_count: 3 }),
+        { merge: true }
+      );
+    });
+  });
+});

package/src/services/escalation.service.ts

@@ -0,0 +1,150 @@
+/**
+ * Firestore-backed Escalation Store
+ *
+ * Persists trust escalation tracking (attempt counts, blocks) to Firestore.
+ * Replaces InMemoryEscalationStore for production use.
+ *
+ * Firestore path: {BASE}.users/{ownerUserId}/ghost_escalation/{accessorUserId}:{memoryId}
+ *
+ * See agent/design/local.ghost-persona-system.md
+ */
+
+import { getDocument, setDocument, deleteDocument } from '../firestore/init.js';
+import { BASE } from '../firestore/paths.js';
+import { logger } from '../utils/logger.js';
+import type { EscalationStore, MemoryBlock, AttemptRecord } from './access-control.js';
+
+const SERVICE = 'EscalationService';
+
+/**
+ * Get Firestore collection path for escalation data.
+ */
+function getEscalationPath(ownerUserId: string): string {
+  return `${BASE}.users/${ownerUserId}/ghost_escalation`;
+}
+
+/**
+ * Build a document ID from accessor and memory.
+ * Uses colon separator (safe in Firestore doc IDs).
+ */
+function docId(accessorUserId: string, memoryId: string): string {
+  return `${accessorUserId}:${memoryId}`;
+}
+
+/**
+ * Firestore-backed escalation store for production use.
+ */
+export class FirestoreEscalationStore implements EscalationStore {
+  async getBlock(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<MemoryBlock | null> {
+    try {
+      const doc = await getDocument(
+        getEscalationPath(ownerUserId),
+        docId(accessorUserId, memoryId)
+      );
+
+      if (!doc || !doc.blocked) {
+        return null;
+      }
+
+      return {
+        blocked_at: doc.blocked_at,
+        reason: doc.reason || 'Trust escalation limit reached',
+        attempt_count: doc.attempt_count || 0,
+      };
+    } catch (error) {
+      logger.error('Failed to get block', {
+        service: SERVICE,
+        ownerUserId,
+        accessorUserId,
+        memoryId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  async setBlock(ownerUserId: string, accessorUserId: string, memoryId: string, block: MemoryBlock): Promise<void> {
+    await setDocument(
+      getEscalationPath(ownerUserId),
+      docId(accessorUserId, memoryId),
+      {
+        blocked: true,
+        blocked_at: block.blocked_at,
+        reason: block.reason,
+        attempt_count: block.attempt_count,
+        accessor_user_id: accessorUserId,
+        memory_id: memoryId,
+      },
+      { merge: true }
+    );
+
+    logger.info('User blocked from memory', {
+      service: SERVICE,
+      ownerUserId,
+      accessorUserId,
+      memoryId,
+      reason: block.reason,
+    });
+  }
+
+  async removeBlock(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<void> {
+    await deleteDocument(
+      getEscalationPath(ownerUserId),
+      docId(accessorUserId, memoryId)
+    );
+
+    logger.info('Block removed', {
+      service: SERVICE,
+      ownerUserId,
+      accessorUserId,
+      memoryId,
+    });
+  }
+
+  async getAttempts(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<AttemptRecord | null> {
+    try {
+      const doc = await getDocument(
+        getEscalationPath(ownerUserId),
+        docId(accessorUserId, memoryId)
+      );
+
+      if (!doc || doc.attempt_count === undefined) {
+        return null;
+      }
+
+      return {
+        count: doc.attempt_count,
+        last_attempt_at: doc.last_attempt_at,
+      };
+    } catch (error) {
+      logger.error('Failed to get attempts', {
+        service: SERVICE,
+        ownerUserId,
+        accessorUserId,
+        memoryId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  async incrementAttempts(ownerUserId: string, accessorUserId: string, memoryId: string): Promise<AttemptRecord> {
+    const existing = await this.getAttempts(ownerUserId, accessorUserId, memoryId);
+    const newCount = (existing?.count ?? 0) + 1;
+    const now = new Date().toISOString();
+
+    await setDocument(
+      getEscalationPath(ownerUserId),
+      docId(accessorUserId, memoryId),
+      {
+        attempt_count: newCount,
+        last_attempt_at: now,
+        accessor_user_id: accessorUserId,
+        memory_id: memoryId,
+      },
+      { merge: true }
+    );
+
+    return { count: newCount, last_attempt_at: now };
+  }
+}