@prmichaelsen/remember-mcp 3.18.1 → 3.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prmichaelsen/remember-mcp",
-  "version": "3.18.1",
+  "version": "3.19.0",
   "description": "Multi-tenant memory system MCP server with vector search and relationships",
   "main": "dist/server.js",
   "type": "module",

package/src/auth/config-resolver.spec.ts

@@ -0,0 +1,101 @@
+import { resolveAuthConfig } from './config-resolver.js';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+
+describe('resolveAuthConfig', () => {
+  const projectDir = join(process.cwd(), '.remember');
+  const savedEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    // Save env vars
+    savedEnv.REMEMBER_OAUTH_ENDPOINT = process.env.REMEMBER_OAUTH_ENDPOINT;
+    savedEnv.REMEMBER_API_TOKEN = process.env.REMEMBER_API_TOKEN;
+    // Clear env vars
+    delete process.env.REMEMBER_OAUTH_ENDPOINT;
+    delete process.env.REMEMBER_API_TOKEN;
+  });
+
+  afterEach(() => {
+    // Restore env vars
+    if (savedEnv.REMEMBER_OAUTH_ENDPOINT !== undefined) {
+      process.env.REMEMBER_OAUTH_ENDPOINT = savedEnv.REMEMBER_OAUTH_ENDPOINT;
+    } else {
+      delete process.env.REMEMBER_OAUTH_ENDPOINT;
+    }
+    if (savedEnv.REMEMBER_API_TOKEN !== undefined) {
+      process.env.REMEMBER_API_TOKEN = savedEnv.REMEMBER_API_TOKEN;
+    } else {
+      delete process.env.REMEMBER_API_TOKEN;
+    }
+    // Cleanup project config
+    if (existsSync(projectDir)) {
+      rmSync(projectDir, { recursive: true });
+    }
+  });
+
+  it('resolves from project config file', () => {
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'config'), 'oauth_endpoint: https://proj.example.com/oauth\napi_token: ab_live-sk_proj\n');
+
+    const config = resolveAuthConfig();
+    expect(config.oauthEndpoint).toBe('https://proj.example.com/oauth');
+    expect(config.apiToken).toBe('ab_live-sk_proj');
+  });
+
+  it('env vars override file values', () => {
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'config'), 'oauth_endpoint: https://file.com/oauth\napi_token: ab_live-sk_file\n');
+    process.env.REMEMBER_API_TOKEN = 'ab_live-sk_env';
+
+    const config = resolveAuthConfig();
+    expect(config.oauthEndpoint).toBe('https://file.com/oauth');
+    expect(config.apiToken).toBe('ab_live-sk_env');
+  });
+
+  it('works with env vars only (no config file)', () => {
+    process.env.REMEMBER_OAUTH_ENDPOINT = 'https://env.com/oauth';
+    process.env.REMEMBER_API_TOKEN = 'ab_live-sk_envonly';
+
+    const config = resolveAuthConfig();
+    expect(config.oauthEndpoint).toBe('https://env.com/oauth');
+    expect(config.apiToken).toBe('ab_live-sk_envonly');
+  });
+
+  it('throws when oauth_endpoint is missing', () => {
+    process.env.REMEMBER_API_TOKEN = 'ab_live-sk_tok';
+
+    expect(() => resolveAuthConfig()).toThrow('Could not resolve OAuth endpoint');
+  });
+
+  it('throws when api_token is missing', () => {
+    process.env.REMEMBER_OAUTH_ENDPOINT = 'https://x.com/oauth';
+
+    expect(() => resolveAuthConfig()).toThrow('Could not resolve API token');
+  });
+
+  it('handles comments and empty lines in config file', () => {
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'config'), [
+      '# This is a comment',
+      '',
+      'oauth_endpoint: https://comments.com/oauth',
+      '# Another comment',
+      'api_token: ab_live-sk_comments',
+      '',
+    ].join('\n'));
+
+    const config = resolveAuthConfig();
+    expect(config.oauthEndpoint).toBe('https://comments.com/oauth');
+    expect(config.apiToken).toBe('ab_live-sk_comments');
+  });
+
+  it('partial file + env var fills gaps', () => {
+    mkdirSync(projectDir, { recursive: true });
+    writeFileSync(join(projectDir, 'config'), 'api_token: ab_live-sk_fromfile\n');
+    process.env.REMEMBER_OAUTH_ENDPOINT = 'https://mixed.com/oauth';
+
+    const config = resolveAuthConfig();
+    expect(config.oauthEndpoint).toBe('https://mixed.com/oauth');
+    expect(config.apiToken).toBe('ab_live-sk_fromfile');
+  });
+});

package/src/auth/config-resolver.ts

@@ -0,0 +1,127 @@
+/**
+ * Local Config Resolution
+ *
+ * Resolves API token and OAuth endpoint from .remember/config files.
+ *
+ * Resolution order (first wins per field):
+ *   1. ./.remember/config  (project-level)
+ *   2. ~/.remember/config  (global)
+ *   3. REMEMBER_API_TOKEN / REMEMBER_OAUTH_ENDPOINT env vars
+ *
+ * Env vars override file values when both are present.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { logger } from '../utils/logger.js';
+
+export interface ResolvedAuthConfig {
+  oauthEndpoint: string;
+  apiToken: string;
+}
+
+interface ConfigFileValues {
+  oauth_endpoint?: string;
+  api_token?: string;
+}
+
+/**
+ * Parse a .remember/config file.
+ * Format: simple key: value pairs, one per line. Lines starting with # are comments.
+ */
+function parseConfigFile(filePath: string): ConfigFileValues {
+  const content = readFileSync(filePath, 'utf-8');
+  const result: ConfigFileValues = {};
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    const value = trimmed.slice(colonIndex + 1).trim();
+
+    if (key === 'oauth_endpoint' && value) {
+      result.oauth_endpoint = value;
+    } else if (key === 'api_token' && value) {
+      result.api_token = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Try to read a config file, returning null if it doesn't exist.
+ */
+function tryReadConfigFile(filePath: string): ConfigFileValues | null {
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const values = parseConfigFile(filePath);
+    logger.debug('Read config file', { filePath, keys: Object.keys(values) });
+    return values;
+  } catch (error) {
+    logger.warn('Failed to parse config file', {
+      filePath,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/**
+ * Resolve auth config from .remember/config files and env vars.
+ *
+ * Merge strategy:
+ *   - Project config fills in values
+ *   - Global config fills in remaining gaps
+ *   - Env vars override any file values
+ *
+ * @throws Error if required values are missing after resolution
+ */
+export function resolveAuthConfig(): ResolvedAuthConfig {
+  const projectConfigPath = join(process.cwd(), '.remember', 'config');
+  const globalConfigPath = join(homedir(), '.remember', 'config');
+
+  // Read config files (project takes precedence)
+  const projectConfig = tryReadConfigFile(projectConfigPath);
+  const globalConfig = tryReadConfigFile(globalConfigPath);
+
+  // Start with file values (project > global)
+  let oauthEndpoint = projectConfig?.oauth_endpoint ?? globalConfig?.oauth_endpoint ?? '';
+  let apiToken = projectConfig?.api_token ?? globalConfig?.api_token ?? '';
+
+  // Env vars override file values
+  if (process.env.REMEMBER_OAUTH_ENDPOINT) {
+    oauthEndpoint = process.env.REMEMBER_OAUTH_ENDPOINT;
+  }
+  if (process.env.REMEMBER_API_TOKEN) {
+    apiToken = process.env.REMEMBER_API_TOKEN;
+  }
+
+  // Validate
+  const searched = [projectConfigPath, globalConfigPath, 'env vars'].join(', ');
+
+  if (!oauthEndpoint) {
+    throw new Error(
+      `Could not resolve OAuth endpoint. Set REMEMBER_OAUTH_ENDPOINT env var or add oauth_endpoint to .remember/config. Searched: ${searched}`
+    );
+  }
+
+  if (!apiToken) {
+    throw new Error(
+      `Could not resolve API token. Set REMEMBER_API_TOKEN env var or add api_token to .remember/config. Searched: ${searched}`
+    );
+  }
+
+  logger.info('Auth config resolved', {
+    oauthEndpoint,
+    tokenSource: process.env.REMEMBER_API_TOKEN ? 'env' : projectConfig?.api_token ? 'project' : 'global',
+  });
+
+  return { oauthEndpoint, apiToken };
+}

package/src/auth/oauth-bootstrap.spec.ts

@@ -0,0 +1,72 @@
+import { bootstrapOAuth } from './oauth-bootstrap.js';
+import * as configResolver from './config-resolver.js';
+import * as oauthExchange from './oauth-exchange.js';
+
+jest.mock('./config-resolver.js');
+jest.mock('./oauth-exchange.js');
+
+const mockResolveAuthConfig = configResolver.resolveAuthConfig as jest.MockedFunction<typeof configResolver.resolveAuthConfig>;
+const mockExchangeApiToken = oauthExchange.exchangeApiToken as jest.MockedFunction<typeof oauthExchange.exchangeApiToken>;
+const mockExtractUserId = oauthExchange.extractUserId as jest.MockedFunction<typeof oauthExchange.extractUserId>;
+
+describe('bootstrapOAuth', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('completes full flow: resolve → exchange → extract', async () => {
+    mockResolveAuthConfig.mockReturnValue({
+      oauthEndpoint: 'https://example.com/oauth',
+      apiToken: 'ab_live-sk_test',
+    });
+    mockExchangeApiToken.mockResolvedValue({
+      access_token: 'jwt.payload.sig',
+      token_type: 'Bearer',
+      expires_in: 3600,
+    });
+    mockExtractUserId.mockReturnValue('user456');
+
+    const result = await bootstrapOAuth();
+
+    expect(result.accessToken).toBe('jwt.payload.sig');
+    expect(result.userId).toBe('user456');
+    expect(mockResolveAuthConfig).toHaveBeenCalledTimes(1);
+    expect(mockExchangeApiToken).toHaveBeenCalledWith('https://example.com/oauth', 'ab_live-sk_test');
+    expect(mockExtractUserId).toHaveBeenCalledWith('jwt.payload.sig');
+  });
+
+  it('propagates config resolution errors', async () => {
+    mockResolveAuthConfig.mockImplementation(() => {
+      throw new Error('Could not resolve API token');
+    });
+
+    await expect(bootstrapOAuth()).rejects.toThrow('Could not resolve API token');
+  });
+
+  it('propagates exchange errors', async () => {
+    mockResolveAuthConfig.mockReturnValue({
+      oauthEndpoint: 'https://x.com/oauth',
+      apiToken: 'ab_live-sk_bad',
+    });
+    mockExchangeApiToken.mockRejectedValue(new Error('invalid or expired API token'));
+
+    await expect(bootstrapOAuth()).rejects.toThrow('invalid or expired API token');
+  });
+
+  it('propagates userId extraction errors', async () => {
+    mockResolveAuthConfig.mockReturnValue({
+      oauthEndpoint: 'https://x.com/oauth',
+      apiToken: 'ab_live-sk_ok',
+    });
+    mockExchangeApiToken.mockResolvedValue({
+      access_token: 'bad.jwt',
+      token_type: 'Bearer',
+      expires_in: 3600,
+    });
+    mockExtractUserId.mockImplementation(() => {
+      throw new Error('Invalid JWT: expected 3 parts');
+    });
+
+    await expect(bootstrapOAuth()).rejects.toThrow('expected 3 parts');
+  });
+});

package/src/auth/oauth-bootstrap.ts

@@ -0,0 +1,45 @@
+/**
+ * OAuth Bootstrap
+ *
+ * Single entry point for the OAuth authentication flow.
+ * Resolves config → exchanges API token → extracts userId.
+ */
+
+import { logger } from '../utils/logger.js';
+import { resolveAuthConfig } from './config-resolver.js';
+import { exchangeApiToken, extractUserId } from './oauth-exchange.js';
+
+export interface OAuthBootstrapResult {
+  accessToken: string;  // JWT
+  userId: string;
+}
+
+/**
+ * Bootstrap OAuth authentication.
+ *
+ * 1. Resolves config from .remember/config files and env vars
+ * 2. Exchanges API token for JWT via OAuth endpoint
+ * 3. Extracts userId from JWT claims
+ *
+ * @returns The JWT access token and userId
+ * @throws Error with descriptive message at any step
+ */
+export async function bootstrapOAuth(): Promise<OAuthBootstrapResult> {
+  logger.info('Bootstrapping OAuth authentication...');
+
+  // Step 1: Resolve config
+  const { oauthEndpoint, apiToken } = resolveAuthConfig();
+
+  // Step 2: Exchange API token for JWT
+  const tokenResponse = await exchangeApiToken(oauthEndpoint, apiToken);
+
+  // Step 3: Extract userId from JWT
+  const userId = extractUserId(tokenResponse.access_token);
+
+  logger.info('OAuth bootstrap complete', { userId, oauthEndpoint });
+
+  return {
+    accessToken: tokenResponse.access_token,
+    userId,
+  };
+}

package/src/auth/oauth-exchange.spec.ts

@@ -0,0 +1,126 @@
+import { exchangeApiToken, extractUserId } from './oauth-exchange.js';
+
+// Helper to create a JWT with given payload
+function makeJwt(payload: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${header}.${body}.fakesig`;
+}
+
+describe('extractUserId', () => {
+  it('extracts sub from valid JWT', () => {
+    const jwt = makeJwt({ sub: 'user123', iss: 'agentbase.me' });
+    expect(extractUserId(jwt)).toBe('user123');
+  });
+
+  it('throws on missing sub claim', () => {
+    const jwt = makeJwt({ iss: 'agentbase.me' });
+    expect(() => extractUserId(jwt)).toThrow('missing or empty "sub" claim');
+  });
+
+  it('throws on empty sub claim', () => {
+    const jwt = makeJwt({ sub: '' });
+    expect(() => extractUserId(jwt)).toThrow('missing or empty "sub" claim');
+  });
+
+  it('throws on malformed JWT (wrong part count)', () => {
+    expect(() => extractUserId('onlyone')).toThrow('expected 3 parts');
+  });
+
+  it('throws on malformed JWT (bad base64)', () => {
+    expect(() => extractUserId('a.!!!invalid!!!.c')).toThrow('unable to decode payload');
+  });
+});
+
+describe('exchangeApiToken', () => {
+  const originalFetch = global.fetch;
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('returns token response on success', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        access_token: 'jwt123',
+        token_type: 'Bearer',
+        expires_in: 3600,
+      }),
+    });
+
+    const result = await exchangeApiToken('https://example.com/oauth', 'ab_live-sk_test');
+    expect(result.access_token).toBe('jwt123');
+    expect(result.token_type).toBe('Bearer');
+    expect(result.expires_in).toBe(3600);
+
+    expect(global.fetch).toHaveBeenCalledWith('https://example.com/oauth', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ grant_type: 'api_token', api_token: 'ab_live-sk_test' }),
+    });
+  });
+
+  it('throws descriptive error on 401', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: () => Promise.resolve('unauthorized'),
+    });
+
+    await expect(exchangeApiToken('https://x.com/oauth', 'bad'))
+      .rejects.toThrow('invalid or expired API token');
+  });
+
+  it('throws descriptive error on 403', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      text: () => Promise.resolve('disabled'),
+    });
+
+    await expect(exchangeApiToken('https://x.com/oauth', 'disabled'))
+      .rejects.toThrow('API token has been disabled');
+  });
+
+  it('throws descriptive error on network failure', async () => {
+    global.fetch = jest.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+
+    await expect(exchangeApiToken('https://x.com/oauth', 'tok'))
+      .rejects.toThrow('network error');
+  });
+
+  it('throws on invalid JSON response', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.reject(new Error('invalid json')),
+    });
+
+    await expect(exchangeApiToken('https://x.com/oauth', 'tok'))
+      .rejects.toThrow('invalid JSON response');
+  });
+
+  it('throws on missing access_token in response', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({ token_type: 'Bearer' }),
+    });
+
+    await expect(exchangeApiToken('https://x.com/oauth', 'tok'))
+      .rejects.toThrow('response missing access_token');
+  });
+
+  it('throws descriptive error on other HTTP errors', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+      text: () => Promise.resolve('internal server error'),
+    });
+
+    await expect(exchangeApiToken('https://x.com/oauth', 'tok'))
+      .rejects.toThrow('HTTP 500');
+  });
+});

package/src/auth/oauth-exchange.ts

@@ -0,0 +1,128 @@
+/**
+ * OAuth Token Exchange Client
+ *
+ * Exchanges an API token for a JWT by calling the configured OAuth endpoint.
+ * Uses native fetch (Node 18+) — no new dependencies.
+ */
+
+import { logger } from '../utils/logger.js';
+
+export interface OAuthTokenResponse {
+  access_token: string;
+  token_type: 'Bearer';
+  expires_in: number;
+}
+
+/**
+ * Exchange an API token for a JWT via the OAuth endpoint.
+ *
+ * @param oauthEndpoint - The OAuth token exchange URL
+ * @param apiToken - The opaque API token to exchange
+ * @returns The OAuth token response containing the JWT
+ * @throws Error with descriptive message on failure
+ */
+export async function exchangeApiToken(
+  oauthEndpoint: string,
+  apiToken: string
+): Promise<OAuthTokenResponse> {
+  logger.info('Exchanging API token for JWT', { oauthEndpoint });
+
+  let response: Response;
+  try {
+    response = await fetch(oauthEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        grant_type: 'api_token',
+        api_token: apiToken,
+      }),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `OAuth token exchange failed: network error connecting to ${oauthEndpoint} — ${message}`
+    );
+  }
+
+  if (response.status === 401) {
+    throw new Error(
+      'OAuth token exchange failed: invalid or expired API token'
+    );
+  }
+
+  if (response.status === 403) {
+    throw new Error(
+      'OAuth token exchange failed: API token has been disabled'
+    );
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new Error(
+      `OAuth token exchange failed: HTTP ${response.status} from ${oauthEndpoint}${body ? ` — ${body}` : ''}`
+    );
+  }
+
+  let data: unknown;
+  try {
+    data = await response.json();
+  } catch {
+    throw new Error(
+      'OAuth token exchange failed: invalid JSON response from endpoint'
+    );
+  }
+
+  if (
+    typeof data !== 'object' ||
+    data === null ||
+    !('access_token' in data) ||
+    typeof (data as any).access_token !== 'string'
+  ) {
+    throw new Error(
+      'OAuth token exchange failed: response missing access_token field'
+    );
+  }
+
+  const result: OAuthTokenResponse = {
+    access_token: (data as any).access_token,
+    token_type: (data as any).token_type ?? 'Bearer',
+    expires_in: (data as any).expires_in ?? 3600,
+  };
+
+  logger.info('API token exchanged successfully', {
+    expiresIn: result.expires_in,
+  });
+
+  return result;
+}
+
+/**
+ * Extract userId from a JWT access token.
+ *
+ * Decodes the JWT payload without verification — the OAuth endpoint
+ * already validated the token, so we just need the claims.
+ *
+ * @param jwt - The JWT access token
+ * @returns The userId from the `sub` claim
+ * @throws Error if JWT is malformed or missing `sub`
+ */
+export function extractUserId(jwt: string): string {
+  const parts = jwt.split('.');
+  if (parts.length !== 3) {
+    throw new Error('Invalid JWT: expected 3 parts (header.payload.signature)');
+  }
+
+  let payload: Record<string, unknown>;
+  try {
+    const decoded = Buffer.from(parts[1], 'base64url').toString('utf-8');
+    payload = JSON.parse(decoded);
+  } catch {
+    throw new Error('Invalid JWT: unable to decode payload');
+  }
+
+  if (typeof payload.sub !== 'string' || !payload.sub) {
+    throw new Error('Invalid JWT: missing or empty "sub" claim');
+  }
+
+  return payload.sub;
+}

package/src/config.ts

@@ -67,6 +67,52 @@ export const config = {
   },
 } as const;
 
+/**
+ * Auth scheme configuration — discriminated union.
+ *
+ * - 'service': Current behavior, JWT via mcp-auth (deployed behind remember-mcp-server)
+ * - 'oauth': Local mode, exchanges API token for JWT via OAuth endpoint
+ */
+type ServiceAuthConfig = { scheme: 'service' };
+type OAuthAuthConfig = {
+  scheme: 'oauth';
+  oauthEndpoint: string;
+  apiToken: string;
+};
+export type AuthSchemeConfig = ServiceAuthConfig | OAuthAuthConfig;
+
+/**
+ * Load auth scheme config from environment variables.
+ * Validates at startup — fails fast with descriptive errors.
+ *
+ * Note: apiToken may be empty here when scheme=oauth.
+ * The config-resolver (T517) fills it from .remember/config if not set via env var.
+ */
+export function loadAuthSchemeConfig(): AuthSchemeConfig {
+  const scheme = process.env.REMEMBER_AUTH_SCHEME ?? 'service';
+
+  if (scheme === 'service') {
+    return { scheme };
+  }
+
+  if (scheme !== 'oauth') {
+    throw new Error(
+      `Invalid REMEMBER_AUTH_SCHEME: "${scheme}". Valid values: "service", "oauth"`
+    );
+  }
+
+  const oauthEndpoint = process.env.REMEMBER_OAUTH_ENDPOINT;
+  if (!oauthEndpoint) {
+    throw new Error(
+      'REMEMBER_OAUTH_ENDPOINT is required when REMEMBER_AUTH_SCHEME=oauth'
+    );
+  }
+
+  const apiToken = process.env.REMEMBER_API_TOKEN ?? '';
+
+  return { scheme, oauthEndpoint, apiToken };
+}
+
 /**
  * Validate required configuration
  */