enigma-memory 0.1.18 → 0.1.22

package/packages/mcp-server/src/oauth.js

@@ -0,0 +1,561 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { dirname, resolve } from 'node:path';
+
+const STORE_SCHEMA = 'enigma.oauth_store.v1';
+const DEFAULT_SCOPES = Object.freeze(['mcp:invoke']);
+const DEFAULT_NATIVE_REDIRECT_SCHEMES = Object.freeze(['enigma-ios']);
+export const ENIGMA_OAUTH_SUPPORTED_SCOPES = Object.freeze([
+  'mcp:invoke', 'models:invoke', 'images:generate', 'video:generate', 'code:execute', 'browser:control', 'usage:read', 'credits:create', 'offline_access',
+  'memory:read', 'memory:write', 'memory:delete', 'vault:admin',
+  'swarm:read', 'swarm:write', 'security:inspect', 'metering:write',
+  'settlement:read', 'settlement:write', 'settlement:operator', 'nullifier:prepare', 'payments:execute',
+]);
+const TOKEN_BYTES = 32;
+
+class OAuthHttpError extends Error {
+  constructor(status, error, description) {
+    super(description);
+    this.name = 'OAuthHttpError';
+    this.status = status;
+    this.error = error;
+  }
+}
+
+function nowIso(clock) {
+  return new Date(clock()).toISOString();
+}
+
+function token() {
+  return randomBytes(TOKEN_BYTES).toString('base64url');
+}
+
+function digest(value) {
+  return createHash('sha256').update(String(value), 'utf8').digest('base64url');
+}
+
+function secretMatches(value, expectedHash) {
+  const actual = Buffer.from(digest(value), 'base64url');
+  const expected = Buffer.from(expectedHash || '', 'base64url');
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+
+function boundedInteger(value, name, minimum, maximum, fallback) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isInteger(resolved) || resolved < minimum || resolved > maximum) {
+    throw new TypeError(`${name} must be an integer from ${minimum} through ${maximum}`);
+  }
+  return resolved;
+}
+
+function exactHttpsOrLoopbackUrl(value, name, { allowPath = true } = {}) {
+  const url = new URL(String(value));
+  const loopback = ['127.0.0.1', '::1', 'localhost'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    throw new TypeError(`${name} must use HTTPS outside localhost`);
+  }
+  if (url.username || url.password || url.hash) throw new TypeError(`${name} must not contain credentials or a fragment`);
+  if (!allowPath && (url.pathname !== '/' || url.search)) throw new TypeError(`${name} must contain only scheme, host, and port`);
+  return url;
+}
+
+function canonicalResource(value) {
+  const url = exactHttpsOrLoopbackUrl(value, 'resource');
+  if (url.search) throw new TypeError('resource must not contain a query');
+  if (url.pathname === '/') url.pathname = '';
+  return url.toString().replace(/\/$/, '');
+}
+function nativeRedirectSchemes(value) {
+  const entries = value === undefined ? DEFAULT_NATIVE_REDIRECT_SCHEMES : value;
+  if (!Array.isArray(entries)) throw new TypeError('nativeRedirectSchemes must be an array');
+  const schemes = entries.map((entry) => String(entry).trim().toLowerCase());
+  if (schemes.some((scheme) => !/^[a-z][a-z0-9+.-]*$/.test(scheme) || scheme === 'http' || scheme === 'https')) {
+    throw new TypeError('nativeRedirectSchemes contains an invalid private-use URI scheme');
+  }
+  return new Set(schemes);
+}
+
+
+function normalizeRedirectUri(value, allowedNativeSchemes = new Set()) {
+  try {
+    const url = new URL(String(value));
+    const scheme = url.protocol.slice(0, -1).toLowerCase();
+    if (allowedNativeSchemes.has(scheme)) {
+      if (!url.hostname || url.username || url.password || url.hash) throw new Error();
+      return url.toString();
+    }
+    return exactHttpsOrLoopbackUrl(value, 'redirect_uri').toString();
+  } catch {
+    throw new OAuthHttpError(400, 'invalid_redirect_uri', 'redirect_uri must be HTTPS, loopback HTTP, or an approved native-app URI');
+  }
+}
+
+function requestResource(value) {
+  try {
+    return canonicalResource(value);
+  } catch {
+    throw new OAuthHttpError(400, 'invalid_target', 'resource must be a canonical HTTPS or loopback HTTP URI');
+  }
+}
+
+function normalizeScopes(value, supportedScopes, fallback = DEFAULT_SCOPES) {
+  const entries = Array.isArray(value) ? value : String(value || '').split(/\s+/);
+  const scopes = [...new Set(entries.map((entry) => String(entry).trim()).filter(Boolean))];
+  const resolved = scopes.length ? scopes : [...fallback];
+  if (resolved.some((scope) => !supportedScopes.has(scope))) throw new OAuthHttpError(400, 'invalid_scope', 'one or more requested scopes are unsupported');
+  return resolved.sort();
+}
+
+function emptyStore() {
+  return { schema: STORE_SCHEMA, revision: 0, clients: {}, codes: {}, accessTokens: {}, refreshTokens: {} };
+}
+
+function cleanStore(state, clock) {
+  const cutoff = clock();
+  for (const [key, record] of Object.entries(state.codes)) {
+    if (Date.parse(record.expiresAt) <= cutoff || record.usedAt) delete state.codes[key];
+  }
+  for (const [key, record] of Object.entries(state.accessTokens)) {
+    if (Date.parse(record.expiresAt) <= cutoff || record.revokedAt) delete state.accessTokens[key];
+  }
+  for (const [key, record] of Object.entries(state.refreshTokens)) {
+    const terminal = record.revokedAt || (record.usedAt && Date.parse(record.usedAt) + 24 * 60 * 60_000 <= cutoff);
+    if (Date.parse(record.expiresAt) <= cutoff || terminal) delete state.refreshTokens[key];
+  }
+  return state;
+}
+
+function createStoreAdapter(load, save, clock) {
+  let queue = Promise.resolve();
+  const transaction = (operation) => {
+    const run = queue.then(async () => {
+      const state = cleanStore(await load(), clock);
+      const output = await operation(state);
+      state.revision += 1;
+      await save(state);
+      return output;
+    });
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const view = async (operation) => {
+    await queue;
+    return operation(cleanStore(await load(), clock));
+  };
+
+  return Object.freeze({
+    async putClient(record) {
+      return transaction((state) => {
+        state.clients[record.clientId] = structuredClone(record);
+        return structuredClone(record);
+      });
+    },
+    async getClient(clientId) {
+      return view((state) => state.clients[clientId] ? structuredClone(state.clients[clientId]) : null);
+    },
+    async putCode(codeValue, record) {
+      return transaction((state) => { state.codes[digest(codeValue)] = structuredClone(record); });
+    },
+    async takeCode(codeValue) {
+      return transaction((state) => {
+        const key = digest(codeValue);
+        const record = state.codes[key];
+        if (!record || record.usedAt) return null;
+        record.usedAt = nowIso(clock);
+        return structuredClone(record);
+      });
+    },
+    async putAccessToken(tokenValue, record) {
+      return transaction((state) => { state.accessTokens[digest(tokenValue)] = structuredClone(record); });
+    },
+    async getAccessToken(tokenValue) {
+      return view((state) => {
+        const record = state.accessTokens[digest(tokenValue)];
+        return record && !record.revokedAt ? structuredClone(record) : null;
+      });
+    },
+    async putRefreshToken(tokenValue, record) {
+      return transaction((state) => { state.refreshTokens[digest(tokenValue)] = structuredClone(record); });
+    },
+    async rotateRefreshToken(tokenValue) {
+      return transaction((state) => {
+        const record = state.refreshTokens[digest(tokenValue)];
+        if (!record) return { status: 'missing', record: null };
+        if (record.revokedAt) return { status: 'revoked', record: structuredClone(record) };
+        if (record.usedAt) return { status: 'reused', record: structuredClone(record) };
+        record.usedAt = nowIso(clock);
+        return { status: 'active', record: structuredClone(record) };
+      });
+    },
+    async revokeFamily(familyId) {
+      return transaction((state) => {
+        const revokedAt = nowIso(clock);
+        for (const record of Object.values(state.refreshTokens)) {
+          if (record.familyId === familyId) record.revokedAt = revokedAt;
+        }
+        for (const record of Object.values(state.accessTokens)) {
+          if (record.familyId === familyId) record.revokedAt = revokedAt;
+        }
+      });
+    },
+  });
+}
+
+export function createEphemeralOAuthStore(options = {}) {
+  const clock = options.clock || Date.now;
+  let state = emptyStore();
+  return createStoreAdapter(async () => structuredClone(state), async (next) => { state = structuredClone(next); }, clock);
+}
+
+export function createFileOAuthStore(options = {}) {
+  const clock = options.clock || Date.now;
+  const path = resolve(String(options.path || '.enigma/oauth-store.json'));
+  async function load() {
+    try {
+      const state = JSON.parse(await readFile(path, 'utf8'));
+      if (state?.schema !== STORE_SCHEMA) throw new Error('unsupported OAuth store schema');
+      return state;
+    } catch (error) {
+      if (error.code === 'ENOENT') return emptyStore();
+      throw error;
+    }
+  }
+  async function save(state) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(JSON.stringify(state));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  }
+  return createStoreAdapter(load, save, clock);
+}
+
+function parseBasicAuthorization(value) {
+  if (!value || !String(value).startsWith('Basic ')) return null;
+  try {
+    const decoded = Buffer.from(String(value).slice(6), 'base64').toString('utf8');
+    const separator = decoded.indexOf(':');
+    if (separator < 0) return null;
+    return { clientId: decodeURIComponent(decoded.slice(0, separator)), clientSecret: decodeURIComponent(decoded.slice(separator + 1)) };
+  } catch {
+    return null;
+  }
+}
+
+async function readBody(request, maximum, expectedContentType) {
+  const contentType = String(request.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase();
+  if (contentType !== expectedContentType) throw new OAuthHttpError(415, 'invalid_request', `Content-Type must be ${expectedContentType}`);
+  const chunks = [];
+  let size = 0;
+  let tooLarge = false;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > maximum) tooLarge = true;
+    else chunks.push(chunk);
+  }
+  if (tooLarge) throw new OAuthHttpError(413, 'invalid_request', 'request body is too large');
+  return Buffer.concat(chunks, size).toString('utf8');
+}
+
+function json(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.end(body);
+}
+
+function securityHeaders(response) {
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Pragma', 'no-cache');
+  response.setHeader('Referrer-Policy', 'no-referrer');
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.setHeader('X-Frame-Options', 'DENY');
+}
+
+function clientPublicView(client, includeSecret = null) {
+  return {
+    client_id: client.clientId,
+    client_id_issued_at: Math.floor(Date.parse(client.createdAt) / 1_000),
+    client_name: client.clientName,
+    redirect_uris: [...client.redirectUris],
+    grant_types: [...client.grantTypes],
+    response_types: ['code'],
+    token_endpoint_auth_method: client.tokenEndpointAuthMethod,
+    scope: client.scopes.join(' '),
+    ...(includeSecret ? { client_secret: includeSecret, client_secret_expires_at: 0 } : {}),
+  };
+}
+
+export function createOAuthAuthorizationServer(options = {}) {
+  const issuer = exactHttpsOrLoopbackUrl(options.issuer, 'issuer', { allowPath: false }).toString().replace(/\/$/, '');
+  const resource = canonicalResource(options.resource);
+  const store = options.store;
+  if (!store || typeof store.getClient !== 'function' || typeof store.getAccessToken !== 'function') throw new TypeError('OAuth store is required');
+  if (typeof options.approveAuthorization !== 'function') throw new TypeError('approveAuthorization is required; Enigma never silently grants user access');
+  const supportedScopes = new Set(options.scopes || ENIGMA_OAUTH_SUPPORTED_SCOPES);
+  const allowedNativeRedirectSchemes = nativeRedirectSchemes(options.nativeRedirectSchemes);
+  const clock = options.clock || Date.now;
+  const accessTokenTtlMs = boundedInteger(options.accessTokenTtlMs, 'accessTokenTtlMs', 60_000, 60 * 60_000, 10 * 60_000);
+  const refreshTokenTtlMs = boundedInteger(options.refreshTokenTtlMs, 'refreshTokenTtlMs', 60_000, 90 * 24 * 60 * 60_000, 30 * 24 * 60 * 60_000);
+  const codeTtlMs = boundedInteger(options.codeTtlMs, 'codeTtlMs', 30_000, 10 * 60_000, 2 * 60_000);
+  const maxBodyBytes = boundedInteger(options.maxBodyBytes, 'maxBodyBytes', 1_024, 1_048_576, 64 * 1_024);
+  const authorizationEndpoint = `${issuer}/authorize`;
+  const tokenEndpoint = `${issuer}/token`;
+  const registrationEndpoint = `${issuer}/register`;
+  const metadata = Object.freeze({
+    issuer,
+    authorization_endpoint: authorizationEndpoint,
+    token_endpoint: tokenEndpoint,
+    ...(typeof options.authorizeRegistration === 'function' ? { registration_endpoint: registrationEndpoint } : {}),
+    response_types_supported: ['code'],
+    response_modes_supported: ['query'],
+    grant_types_supported: ['authorization_code', 'refresh_token'],
+    token_endpoint_auth_methods_supported: ['none', 'client_secret_basic', 'client_secret_post'],
+    code_challenge_methods_supported: ['S256'],
+    scopes_supported: [...supportedScopes].sort(),
+    authorization_response_iss_parameter_supported: true,
+  });
+  const protectedResourceMetadata = Object.freeze({
+    resource,
+    authorization_servers: [issuer],
+    bearer_methods_supported: ['header'],
+    scopes_supported: [...supportedScopes].sort(),
+    resource_name: 'Enigma Platform',
+  });
+
+  async function registerClient(input, context = {}) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new OAuthHttpError(400, 'invalid_client_metadata', 'client metadata must be an object');
+    if (!Array.isArray(input.redirect_uris)) throw new OAuthHttpError(400, 'invalid_redirect_uri', 'redirect_uris must be an array');
+    const redirectUris = [...new Set(input.redirect_uris.map((value) => normalizeRedirectUri(value, allowedNativeRedirectSchemes)))];
+    if (!redirectUris.length || redirectUris.length > 16) throw new OAuthHttpError(400, 'invalid_redirect_uri', 'one through sixteen redirect_uris are required');
+    if (input.grant_types !== undefined && !Array.isArray(input.grant_types)) throw new OAuthHttpError(400, 'invalid_client_metadata', 'grant_types must be an array');
+    const grantTypes = [...new Set(input.grant_types || ['authorization_code', 'refresh_token'])];
+    if (grantTypes.some((grant) => !['authorization_code', 'refresh_token'].includes(grant)) || !grantTypes.includes('authorization_code')) {
+      throw new OAuthHttpError(400, 'invalid_client_metadata', 'only authorization_code and refresh_token grants are supported');
+    }
+    const authMethod = input.token_endpoint_auth_method || 'none';
+    if (!['none', 'client_secret_basic', 'client_secret_post'].includes(authMethod)) {
+      throw new OAuthHttpError(400, 'invalid_client_metadata', 'unsupported token_endpoint_auth_method');
+    }
+    const scopes = normalizeScopes(input.scope, supportedScopes);
+    const clientId = randomUUID();
+    const clientSecret = authMethod === 'none' ? null : token();
+    const record = {
+      clientId,
+      clientName: String(input.client_name || 'MCP client').slice(0, 200),
+      redirectUris,
+      grantTypes,
+      tokenEndpointAuthMethod: authMethod,
+      clientSecretHash: clientSecret ? digest(clientSecret) : null,
+      scopes,
+      createdAt: nowIso(clock),
+      registrationContext: context.registrationContext || null,
+    };
+    await store.putClient(record);
+    return clientPublicView(record, clientSecret);
+  }
+
+  async function authenticateClient(request, params) {
+    const basic = parseBasicAuthorization(request.headers.authorization);
+    const clientId = basic?.clientId || params.get('client_id');
+    if (!clientId) throw new OAuthHttpError(401, 'invalid_client', 'client authentication is required');
+    const client = await store.getClient(clientId);
+    if (!client) throw new OAuthHttpError(401, 'invalid_client', 'client authentication failed');
+    if (client.tokenEndpointAuthMethod === 'none') {
+      if (basic || params.has('client_secret')) throw new OAuthHttpError(401, 'invalid_client', 'public client must not send a client secret');
+    } else {
+      const methodMatches = client.tokenEndpointAuthMethod === 'client_secret_basic' ? Boolean(basic) : !basic;
+      const suppliedSecret = basic?.clientSecret || params.get('client_secret') || '';
+      if (!methodMatches || !secretMatches(suppliedSecret, client.clientSecretHash)) throw new OAuthHttpError(401, 'invalid_client', 'client authentication failed');
+    }
+    return client;
+  }
+
+  async function issueTokens({ client, subject, tenantId, scopes, familyId = randomUUID() }) {
+    const issuedAt = clock();
+    const accessToken = token();
+    const accessRecord = {
+      tokenId: randomUUID(), familyId, clientId: client.clientId, subject, tenantId, scopes, resource,
+      issuedAt: new Date(issuedAt).toISOString(), expiresAt: new Date(issuedAt + accessTokenTtlMs).toISOString(), revokedAt: null,
+    };
+    await store.putAccessToken(accessToken, accessRecord);
+    let refreshToken = null;
+    if (scopes.includes('offline_access') && client.grantTypes.includes('refresh_token')) {
+      refreshToken = token();
+      await store.putRefreshToken(refreshToken, {
+        tokenId: randomUUID(), familyId, clientId: client.clientId, subject, tenantId, scopes, resource,
+        issuedAt: new Date(issuedAt).toISOString(), expiresAt: new Date(issuedAt + refreshTokenTtlMs).toISOString(), usedAt: null, revokedAt: null,
+      });
+    }
+    return {
+      access_token: accessToken,
+      token_type: 'Bearer',
+      expires_in: Math.floor(accessTokenTtlMs / 1_000),
+      scope: scopes.join(' '),
+      ...(refreshToken ? { refresh_token: refreshToken } : {}),
+    };
+  }
+
+  async function handleAuthorize(request, response, url) {
+    const query = url.searchParams;
+    if (query.get('response_type') !== 'code') throw new OAuthHttpError(400, 'unsupported_response_type', 'response_type must be code');
+    const client = await store.getClient(query.get('client_id'));
+    if (!client) throw new OAuthHttpError(400, 'invalid_request', 'unknown client_id');
+    const redirectUri = normalizeRedirectUri(query.get('redirect_uri'), allowedNativeRedirectSchemes);
+    if (!client.redirectUris.includes(redirectUri)) throw new OAuthHttpError(400, 'invalid_request', 'redirect_uri does not exactly match a registered URI');
+    if (query.get('resource') !== resource) throw new OAuthHttpError(400, 'invalid_target', 'resource must identify this protected resource');
+    const challenge = query.get('code_challenge');
+    if (!challenge || query.get('code_challenge_method') !== 'S256' || !/^[A-Za-z0-9_-]{43}$/.test(challenge)) {
+      throw new OAuthHttpError(400, 'invalid_request', 'PKCE S256 code_challenge is required');
+    }
+    const scopes = normalizeScopes(query.get('scope'), supportedScopes);
+    if (scopes.some((scope) => !client.scopes.includes(scope))) throw new OAuthHttpError(400, 'invalid_scope', 'client is not registered for the requested scopes');
+    const decision = await options.approveAuthorization({
+      request,
+      client: clientPublicView(client),
+      requestedScopes: scopes,
+      resource,
+      state: query.get('state') || null,
+    });
+    const redirect = new URL(redirectUri);
+    if (!decision?.approved) {
+      redirect.searchParams.set('error', 'access_denied');
+      if (query.has('state')) redirect.searchParams.set('state', query.get('state'));
+      response.statusCode = 302;
+      response.setHeader('Location', redirect.toString());
+      response.end();
+      return;
+    }
+    const tenantId = String(decision.tenantId || decision.tenant_id || 'default').trim();
+    if (!tenantId || tenantId.length > 512) throw new OAuthHttpError(500, 'server_error', 'authorization decision did not provide a valid tenant');
+    const subject = String(decision.subject || '').trim();
+    if (!subject || subject.length > 512) throw new OAuthHttpError(500, 'server_error', 'authorization decision did not provide a valid subject');
+    const grantedScopes = normalizeScopes(decision.scopes || scopes, supportedScopes).filter((scope) => scopes.includes(scope));
+    if (!grantedScopes.length) throw new OAuthHttpError(400, 'invalid_scope', 'authorization granted no requested scopes');
+    const codeValue = token();
+    await store.putCode(codeValue, {
+      codeId: randomUUID(), clientId: client.clientId, redirectUri, challenge, resource, subject, tenantId, scopes: grantedScopes,
+      issuedAt: nowIso(clock), expiresAt: new Date(clock() + codeTtlMs).toISOString(), usedAt: null,
+    });
+    redirect.searchParams.set('code', codeValue);
+    redirect.searchParams.set('iss', issuer);
+    if (query.has('state')) redirect.searchParams.set('state', query.get('state'));
+    response.statusCode = 302;
+    response.setHeader('Location', redirect.toString());
+    response.end();
+  }
+
+  async function handleToken(request, response) {
+    const body = await readBody(request, maxBodyBytes, 'application/x-www-form-urlencoded');
+    const params = new URLSearchParams(body);
+    const client = await authenticateClient(request, params);
+    const requestedResource = requestResource(params.get('resource'));
+    if (requestedResource !== resource) throw new OAuthHttpError(400, 'invalid_target', 'resource must identify this protected resource');
+    const grantType = params.get('grant_type');
+    if (grantType === 'authorization_code') {
+      const codeValue = params.get('code') || '';
+      const code = await store.takeCode(codeValue);
+      if (!code || Date.parse(code.expiresAt) <= clock()) throw new OAuthHttpError(400, 'invalid_grant', 'authorization code is invalid, expired, or already used');
+      const redirectUri = normalizeRedirectUri(params.get('redirect_uri'), allowedNativeRedirectSchemes);
+      if (code.clientId !== client.clientId || code.redirectUri !== redirectUri || code.resource !== resource) {
+        throw new OAuthHttpError(400, 'invalid_grant', 'authorization code binding failed');
+      }
+      const verifier = params.get('code_verifier') || '';
+      if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)) throw new OAuthHttpError(400, 'invalid_grant', 'PKCE code_verifier is invalid');
+      const computedChallenge = createHash('sha256').update(verifier).digest('base64url');
+      const actual = Buffer.from(computedChallenge);
+      const expected = Buffer.from(code.challenge);
+      if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) throw new OAuthHttpError(400, 'invalid_grant', 'PKCE verification failed');
+      json(response, 200, await issueTokens({ client, subject: code.subject, tenantId: code.tenantId, scopes: code.scopes }));
+      return;
+    }
+    if (grantType === 'refresh_token') {
+      const rotated = await store.rotateRefreshToken(params.get('refresh_token') || '');
+      if (rotated.status === 'reused') {
+        await store.revokeFamily(rotated.record.familyId);
+        throw new OAuthHttpError(400, 'invalid_grant', 'refresh token reuse detected; token family revoked');
+      }
+      if (rotated.status !== 'active' || Date.parse(rotated.record.expiresAt) <= clock()) throw new OAuthHttpError(400, 'invalid_grant', 'refresh token is invalid or expired');
+      if (rotated.record.clientId !== client.clientId || rotated.record.resource !== resource) {
+        await store.revokeFamily(rotated.record.familyId);
+        throw new OAuthHttpError(400, 'invalid_grant', 'refresh token binding failed');
+      }
+      const requestedScopes = params.has('scope') ? normalizeScopes(params.get('scope'), supportedScopes) : rotated.record.scopes;
+      if (requestedScopes.some((scope) => !rotated.record.scopes.includes(scope))) throw new OAuthHttpError(400, 'invalid_scope', 'refresh cannot increase scope');
+      json(response, 200, await issueTokens({ client, subject: rotated.record.subject, tenantId: rotated.record.tenantId, scopes: requestedScopes, familyId: rotated.record.familyId }));
+      return;
+    }
+    throw new OAuthHttpError(400, 'unsupported_grant_type', 'grant_type must be authorization_code or refresh_token');
+  }
+
+  async function handler(request, response) {
+    securityHeaders(response);
+    try {
+      const url = new URL(request.url || '/', issuer);
+      if (request.method === 'GET' && url.pathname === '/.well-known/oauth-authorization-server') {
+        json(response, 200, metadata);
+      } else if (request.method === 'GET' && url.pathname === '/.well-known/oauth-protected-resource') {
+        json(response, 200, protectedResourceMetadata);
+      } else if (request.method === 'GET' && url.pathname === '/authorize') {
+        await handleAuthorize(request, response, url);
+      } else if (request.method === 'POST' && url.pathname === '/token') {
+        await handleToken(request, response);
+      } else if (request.method === 'POST' && url.pathname === '/register' && typeof options.authorizeRegistration === 'function') {
+        const body = await readBody(request, maxBodyBytes, 'application/json');
+        let input;
+        try { input = JSON.parse(body); } catch { throw new OAuthHttpError(400, 'invalid_client_metadata', 'registration body is not valid JSON'); }
+        const registrationContext = await options.authorizeRegistration({ request, input });
+        if (!registrationContext) throw new OAuthHttpError(403, 'registration_denied', 'dynamic client registration denied');
+        json(response, 201, await registerClient(input, { registrationContext }));
+      } else {
+        throw new OAuthHttpError(404, 'not_found', 'OAuth endpoint not found');
+      }
+    } catch (error) {
+      if (response.writableEnded) return;
+      const status = error instanceof OAuthHttpError ? error.status : 500;
+      json(response, status, {
+        error: error instanceof OAuthHttpError ? error.error : 'server_error',
+        error_description: error instanceof OAuthHttpError ? error.message : 'internal server error',
+      });
+    }
+  }
+
+  async function authorizeBearer({ authorization, requiredScopes = ['mcp:invoke'] } = {}) {
+    if (!authorization || !String(authorization).startsWith('Bearer ')) return null;
+    const tokenValue = String(authorization).slice(7);
+    if (!tokenValue || tokenValue.includes(' ')) return null;
+    const record = await store.getAccessToken(tokenValue);
+    if (!record || record.resource !== resource || Date.parse(record.expiresAt) <= clock()) return null;
+    if (requiredScopes.some((scope) => !record.scopes.includes(scope))) return null;
+    return Object.freeze({ subject: record.subject, tenantId: record.tenantId || 'default', clientId: record.clientId, scopes: [...record.scopes], resource: record.resource, tokenId: record.tokenId });
+  }
+
+  return Object.freeze({ handler, metadata, protectedResourceMetadata, registerClient, authorizeBearer, issuer, resource });
+}
+
+export async function startOAuthAuthorizationServer(options = {}) {
+  const host = String(options.host || '127.0.0.1');
+  const port = boundedInteger(options.port, 'port', 0, 65_535, 0);
+  if (!['127.0.0.1', '::1', 'localhost'].includes(host) && options.allowPublicListener !== true) {
+    throw new Error('public OAuth listeners require allowPublicListener=true and an external TLS terminator');
+  }
+  const oauth = createOAuthAuthorizationServer(options);
+  const server = createServer((request, response) => oauth.handler(request, response));
+  await new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolveListen);
+  });
+  return Object.freeze({
+    ...oauth,
+    server,
+    address: server.address(),
+    close: () => new Promise((resolveClose, reject) => server.close((error) => error ? reject(error) : resolveClose())),
+  });
+}

package/packages/mcp-server/src/private-handoff.js

@@ -0,0 +1,84 @@
+export const ENIGMA_PRIVATE_PROTOCOL = 'enigma:';
+export const ENIGMA_PRIVATE_HOST = 'private';
+export const PRIVATE_SESSION_RESOURCE_URI = 'ui://enigma/private-session.html';
+export const DEFAULT_DESKTOP_ORIGIN = 'http://127.0.0.1:8765';
+
+const SENSITIVE_HANDOFF_PATTERN = /[\r\n]|[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}|0x[a-f0-9]{40}|\b(?:\d{1,3}\.){3}\d{1,3}\b/i;
+
+export function validatePrivateHandoffIntent(value) {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string') throw new TypeError('Private handoff intent must be a string.');
+  const intent = value.trim();
+  if (!intent || intent.length > 160 || SENSITIVE_HANDOFF_PATTERN.test(intent)) {
+    throw new TypeError('Private handoff intent must be a short non-sensitive label; type the actual private prompt inside Enigma.');
+  }
+  return intent;
+}
+
+export function validatePrivateHandoffModel(value) {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string') throw new TypeError('Private handoff model must be a string.');
+  const model = value.trim();
+  if (!model || model.length > 160 || /[\r\n]/.test(model)) {
+    throw new TypeError('Private handoff model must be a non-empty route label no longer than 160 characters.');
+  }
+  return model;
+}
+
+export function validateLoopbackDesktopOrigin(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch {
+    throw new TypeError('Desktop origin must be a valid loopback HTTP URL.');
+  }
+  const loopback = parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost';
+  if (parsed.protocol !== 'http:' || !loopback || parsed.username || parsed.password) {
+    throw new TypeError('Desktop origin must use unauthenticated loopback HTTP.');
+  }
+  return parsed.origin;
+}
+
+function appendHandoffParameters(target, input = {}) {
+  const intent = validatePrivateHandoffIntent(input.intent);
+  const model = validatePrivateHandoffModel(input.model);
+  if (intent) target.searchParams.set('intent', intent);
+  if (model) target.searchParams.set('model', model);
+  return target;
+}
+
+export function createPrivateSessionProtocolUrl(input = {}) {
+  const target = new URL(`${ENIGMA_PRIVATE_PROTOCOL}//${ENIGMA_PRIVATE_HOST}`);
+  appendHandoffParameters(target, input);
+  return target.toString();
+}
+
+export function createPrivateSessionHttpUrl(input = {}, desktopOrigin = DEFAULT_DESKTOP_ORIGIN) {
+  const target = new URL(validateLoopbackDesktopOrigin(desktopOrigin));
+  target.searchParams.set('source', 'mcp');
+  target.searchParams.set('mode', 'private');
+  appendHandoffParameters(target, input);
+  target.hash = 'workspace';
+  return target.toString();
+}
+
+export function createWorkspaceUrlFromProtocol(protocolUrl, desktopOrigin) {
+  let handoff;
+  try {
+    handoff = new URL(String(protocolUrl));
+  } catch {
+    throw new TypeError('Private handoff URL is invalid.');
+  }
+  if (handoff.protocol !== ENIGMA_PRIVATE_PROTOCOL || handoff.hostname !== ENIGMA_PRIVATE_HOST) {
+    throw new TypeError('Private handoff URL must use enigma://private.');
+  }
+  return createPrivateSessionHttpUrl({
+    intent: handoff.searchParams.get('intent') || undefined,
+    model: handoff.searchParams.get('model') || undefined,
+  }, desktopOrigin);
+}
+
+export function findPrivateSessionProtocolUrl(argv = []) {
+  if (!Array.isArray(argv)) return null;
+  return argv.find((value) => typeof value === 'string' && value.toLowerCase().startsWith('enigma://private')) || null;
+}