nofax 0.2.0-oidc-test.0

package/src/mcp-tools.mjs

@@ -0,0 +1,240 @@
+import { loadConfig } from './config.mjs';
+import {
+  createRemoteRequest,
+  pollRemoteResponse,
+  sendNotification,
+  sendResponseConfirmation
+} from './ntfy.mjs';
+import {
+  listPendingRequests,
+  loadRequest,
+  resolveRequest,
+  savePendingRequest
+} from './requests.mjs';
+
+const MAX_WAIT_SECONDS = 240;
+const DEFAULT_WAIT_SECONDS = 240;
+
+export const WAIT_REQUIRED = (requestId) =>
+  `WAIT REQUIRED: human response for ${requestId} is still pending. Do not continue, infer approval, or complete the guarded action. Call nofax_wait_for_response with requestId "${requestId}" and repeat whenever it returns pending until a terminal response is returned.`;
+
+function pendingResult(requestId) {
+  return {
+    status: 'pending',
+    requestId,
+    mustWait: true,
+    instruction: WAIT_REQUIRED(requestId)
+  };
+}
+
+function terminalResult(request) {
+  if (request.decision === 'allow') {
+    return {
+      status: 'resolved',
+      requestId: request.requestId,
+      decision: 'allow',
+      instruction: 'Human approved this request. The caller may continue only within its existing authority.'
+    };
+  }
+  if (request.decision === 'deny') {
+    return {
+      status: 'resolved',
+      requestId: request.requestId,
+      decision: 'deny',
+      instruction: 'Human denied this request. Do not perform the guarded action.'
+    };
+  }
+  if (request.decision === 'refine') {
+    return {
+      status: 'resolved',
+      requestId: request.requestId,
+      decision: 'refine',
+      text: request.text,
+      instruction: 'Apply the human refinement. If the resulting action still requires approval, create a new approval request and wait for that new terminal response before acting.'
+    };
+  }
+  return {
+    status: 'resolved',
+    requestId: request.requestId,
+    decision: request.decision,
+    instruction: 'Human choice received. Apply only that explicit choice within the caller\'s existing authority.'
+  };
+}
+
+function publicRequest(request) {
+  const result = {
+    requestId: request.requestId,
+    kind: request.kind,
+    status: request.status,
+    createdAt: request.createdAt
+  };
+  if (request.status === 'resolved') {
+    result.resolvedAt = request.resolvedAt;
+    result.decision = request.decision;
+    if (request.text !== undefined) result.text = request.text;
+  }
+  return result;
+}
+
+function validateText(value, name, max = 2200) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`NOFAX_${name}_REQUIRED`);
+  return value.trim().slice(0, max);
+}
+
+function validateWaitSeconds(value) {
+  const seconds = value ?? DEFAULT_WAIT_SECONDS;
+  if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_WAIT_SECONDS) {
+    throw new Error('NOFAX_MCP_WAIT_SECONDS_INVALID');
+  }
+  return seconds;
+}
+
+function validateChoiceOptions(options) {
+  if (!Array.isArray(options) || options.length < 1 || options.length > 3) throw new Error('NOFAX_CHOICE_LIMIT');
+  return options.map((option) => {
+    if (typeof option === 'string') {
+      const value = option.trim();
+      if (!value) throw new Error('NOFAX_CHOICE_INVALID');
+      return { value: value.slice(0, 80), label: value.slice(0, 32) };
+    }
+    if (!option || typeof option.value !== 'string' || typeof option.label !== 'string') throw new Error('NOFAX_CHOICE_INVALID');
+    const value = option.value.trim();
+    const label = option.label.trim();
+    if (!value || !label) throw new Error('NOFAX_CHOICE_INVALID');
+    return { value: value.slice(0, 80), label: label.slice(0, 32) };
+  });
+}
+
+export function createMcpToolHandlers(overrides = {}) {
+  const deps = {
+    home: overrides.home,
+    env: overrides.env ?? process.env,
+    loadConfigImpl: overrides.loadConfigImpl ?? loadConfig,
+    sendNotificationImpl: overrides.sendNotificationImpl ?? sendNotification,
+    createRemoteRequestImpl: overrides.createRemoteRequestImpl ?? createRemoteRequest,
+    pollRemoteResponseImpl: overrides.pollRemoteResponseImpl ?? pollRemoteResponse,
+    sendResponseConfirmationImpl: overrides.sendResponseConfirmationImpl ?? sendResponseConfirmation,
+    savePendingRequestImpl: overrides.savePendingRequestImpl ?? savePendingRequest,
+    loadRequestImpl: overrides.loadRequestImpl ?? loadRequest,
+    resolveRequestImpl: overrides.resolveRequestImpl ?? resolveRequest,
+    listPendingRequestsImpl: overrides.listPendingRequestsImpl ?? listPendingRequests,
+    nowImpl: overrides.nowImpl ?? Date.now,
+    sleepImpl: overrides.sleepImpl ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  };
+
+  async function config() {
+    return deps.loadConfigImpl({ home: deps.home, env: deps.env });
+  }
+
+  async function persistRemote({ kind, remote }) {
+    const request = {
+      version: 1,
+      requestId: remote.requestId,
+      kind,
+      responseTopic: remote.responseTopic,
+      allowed: remote.allowed,
+      status: 'pending',
+      createdAt: new Date(deps.nowImpl()).toISOString()
+    };
+    await deps.savePendingRequestImpl({ home: deps.home, env: deps.env, request });
+    return pendingResult(remote.requestId);
+  }
+
+  return {
+    async notify({ title = 'Nofax', message }) {
+      const current = await config();
+      await deps.sendNotificationImpl({
+        config: current,
+        title: validateText(title, 'TITLE', 120),
+        message: validateText(message, 'MESSAGE')
+      });
+      return { status: 'sent' };
+    },
+
+    async requestApproval({ title = 'Nofax approval', message, allowRefine = false }) {
+      const current = await config();
+      const remote = await deps.createRemoteRequestImpl({
+        config: current,
+        title: validateText(title, 'TITLE', 120),
+        message: validateText(message, 'MESSAGE'),
+        options: [
+          { value: 'allow', label: 'Allow' },
+          { value: 'deny', label: 'Deny' }
+        ],
+        includeRefine: allowRefine === true
+      });
+      return persistRemote({ kind: 'approval', remote });
+    },
+
+    async requestChoice({ title = 'Nofax choice', message, options }) {
+      const current = await config();
+      const normalized = validateChoiceOptions(options);
+      const remote = await deps.createRemoteRequestImpl({
+        config: current,
+        title: validateText(title, 'TITLE', 120),
+        message: validateText(message, 'MESSAGE'),
+        options: normalized,
+        includeRefine: false
+      });
+      return persistRemote({ kind: 'choice', remote });
+    },
+
+    async requestRefinement({ title = 'Nofax refinement', message }) {
+      const current = await config();
+      const remote = await deps.createRemoteRequestImpl({
+        config: current,
+        title: validateText(title, 'TITLE', 120),
+        message: validateText(message, 'MESSAGE'),
+        options: [],
+        includeRefine: true
+      });
+      return persistRemote({ kind: 'refinement', remote });
+    },
+
+    async waitForResponse({ requestId, waitSeconds }) {
+      const seconds = validateWaitSeconds(waitSeconds);
+      let request = await deps.loadRequestImpl({ home: deps.home, env: deps.env, requestId });
+      if (request.status === 'resolved') return terminalResult(request);
+
+      const current = await config();
+      const deadline = deps.nowImpl() + seconds * 1000;
+      while (deps.nowImpl() < deadline) {
+        const response = await deps.pollRemoteResponseImpl({
+          config: current,
+          responseTopic: request.responseTopic,
+          requestId: request.requestId,
+          allowed: request.allowed
+        });
+        if (response !== null) {
+          request = await deps.resolveRequestImpl({
+            home: deps.home,
+            env: deps.env,
+            requestId: request.requestId,
+            response,
+            resolvedAt: new Date(deps.nowImpl()).toISOString()
+          });
+          await deps.sendResponseConfirmationImpl({
+            config: current,
+            response,
+            title: request.kind === 'approval' ? 'Approval' : request.kind === 'refinement' ? 'Refinement' : 'Choice'
+          });
+          return terminalResult(request);
+        }
+        const remaining = deadline - deps.nowImpl();
+        if (remaining <= 0) break;
+        await deps.sleepImpl(Math.min(1000, remaining));
+      }
+      return pendingResult(request.requestId);
+    },
+
+    async getRequest({ requestId }) {
+      const request = await deps.loadRequestImpl({ home: deps.home, env: deps.env, requestId });
+      return { status: 'ok', request: publicRequest(request) };
+    },
+
+    async listPending({ limit = 20 } = {}) {
+      const requests = await deps.listPendingRequestsImpl({ home: deps.home, env: deps.env, limit });
+      return { status: 'ok', requests: requests.map(publicRequest) };
+    }
+  };
+}

package/src/ntfy.mjs

@@ -0,0 +1,259 @@
+import { createRequestId, createResponseTopic, parseResponseMessage } from './protocol.mjs';
+
+const MAX_TITLE = 120;
+const MAX_MESSAGE = 2200;
+const DEFAULT_REFINE_SHORTCUT = 'Nofax Refine';
+
+function boundText(value, max, name) {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`NOFAX_${name}_REQUIRED`);
+  const text = value.trim();
+  return text.length <= max ? text : `${text.slice(0, max - 14)}…[truncated]`;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function httpAction({ label, server, responseTopic, requestId, decision }) {
+  return {
+    action: 'http',
+    label,
+    url: `${server}/${responseTopic}`,
+    method: 'POST',
+    body: JSON.stringify({ v: 1, requestId, decision }),
+    clear: true
+  };
+}
+
+export function buildRefineShortcutUrl({ shortcutName = DEFAULT_REFINE_SHORTCUT, server, responseTopic, requestId }) {
+  const payload = JSON.stringify({
+    v: 1,
+    requestId,
+    callbackUrl: `${server}/${responseTopic}`
+  });
+  const url = new URL('shortcuts://run-shortcut');
+  url.searchParams.set('name', shortcutName);
+  url.searchParams.set('input', 'text');
+  url.searchParams.set('text', payload);
+  return url.toString();
+}
+
+function refineAction({ shortcutName, server, responseTopic, requestId }) {
+  return {
+    action: 'view',
+    label: 'Refine',
+    url: buildRefineShortcutUrl({ shortcutName, server, responseTopic, requestId }),
+    clear: true
+  };
+}
+
+async function ensureOk(response, code) {
+  if (!response?.ok) throw new Error(`${code}_${response?.status ?? 'NETWORK'}`);
+  return response;
+}
+
+export async function sendNotification({ config, title, message, actions, priority = 4, tags = ['bell'], fetchImpl = fetch }) {
+  const payload = {
+    topic: config.topic,
+    title: boundText(title, MAX_TITLE, 'TITLE'),
+    message: boundText(message, MAX_MESSAGE, 'MESSAGE'),
+    priority,
+    tags
+  };
+  if (actions?.length) payload.actions = actions;
+
+  let response;
+  try {
+    response = await fetchImpl(`${config.server}/`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload)
+    });
+  } catch (error) {
+    throw new Error(`NOFAX_NTFY_PUBLISH_NETWORK: ${error?.message ?? String(error)}`);
+  }
+  await ensureOk(response, 'NOFAX_NTFY_PUBLISH');
+}
+
+function normalizeOptions(options) {
+  if (!Array.isArray(options) || options.length > 3) throw new Error('NOFAX_CHOICE_LIMIT');
+  const normalized = options.map((option) => {
+    if (typeof option === 'string') return { value: option, label: option };
+    if (!option || typeof option.value !== 'string' || typeof option.label !== 'string') throw new Error('NOFAX_CHOICE_INVALID');
+    const value = option.value.trim();
+    const label = option.label.trim();
+    if (!value || !label || value.length > 80) throw new Error('NOFAX_CHOICE_INVALID');
+    return { value, label: label.slice(0, 32) };
+  });
+  if (new Set(normalized.map((option) => option.value)).size !== normalized.length) throw new Error('NOFAX_CHOICE_DUPLICATE');
+  return normalized;
+}
+
+export async function createRemoteRequest({
+  config,
+  title,
+  message,
+  options = [],
+  includeRefine = false,
+  shortcutName = config.refineShortcutName ?? DEFAULT_REFINE_SHORTCUT,
+  fetchImpl = fetch
+}) {
+  const normalized = normalizeOptions(options);
+  const totalActions = normalized.length + (includeRefine ? 1 : 0);
+  if (totalActions < 1 || totalActions > 3) throw new Error('NOFAX_CHOICE_LIMIT');
+
+  const requestId = createRequestId();
+  const responseTopic = createResponseTopic();
+  const actions = [];
+  const allowed = [];
+
+  if (includeRefine && normalized.length === 2) {
+    const [first, second] = normalized;
+    actions.push(httpAction({ label: first.label, server: config.server, responseTopic, requestId, decision: first.value }));
+    allowed.push(first.value);
+    actions.push(refineAction({ shortcutName, server: config.server, responseTopic, requestId }));
+    allowed.push('refine');
+    actions.push(httpAction({ label: second.label, server: config.server, responseTopic, requestId, decision: second.value }));
+    allowed.push(second.value);
+  } else {
+    for (const option of normalized) {
+      actions.push(httpAction({ label: option.label, server: config.server, responseTopic, requestId, decision: option.value }));
+      allowed.push(option.value);
+    }
+    if (includeRefine) {
+      actions.push(refineAction({ shortcutName, server: config.server, responseTopic, requestId }));
+      allowed.push('refine');
+    }
+  }
+
+  await sendNotification({ config, title, message, actions, fetchImpl });
+  return { requestId, responseTopic, allowed };
+}
+
+function parseNtfyPoll(text, requestId, allowed) {
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event?.event !== 'message') continue;
+    const response = parseResponseMessage(event.message, { requestId, allowed });
+    if (response !== null) return response;
+  }
+  return null;
+}
+
+export async function pollRemoteResponse({ config, responseTopic, requestId, allowed, fetchImpl = fetch }) {
+  let response;
+  try {
+    response = await fetchImpl(`${config.server}/${responseTopic}/json?poll=1&since=10m`, {
+      method: 'GET',
+      headers: { accept: 'application/x-ndjson' }
+    });
+  } catch (error) {
+    throw new Error(`NOFAX_NTFY_POLL_NETWORK: ${error?.message ?? String(error)}`);
+  }
+  await ensureOk(response, 'NOFAX_NTFY_POLL');
+  return parseNtfyPoll(await response.text(), requestId, allowed);
+}
+
+export async function sendResponseConfirmation({ config, response, title = 'Nofax', fetchImpl = fetch }) {
+  let confirmationTitle = 'Response received';
+  let tag = 'white_check_mark';
+  if (response.decision === 'allow') confirmationTitle = 'Approved';
+  else if (response.decision === 'deny') {
+    confirmationTitle = 'Denied';
+    tag = 'no_entry';
+  } else if (response.decision === 'refine') confirmationTitle = 'Refinement received';
+  else confirmationTitle = 'Choice received';
+
+  try {
+    await sendNotification({
+      config,
+      title: `${confirmationTitle} - ${title}`,
+      message: response.decision === 'refine'
+        ? 'Your refinement was sent back to the agent.'
+        : `Nofax recorded: ${response.decision}`,
+      priority: 2,
+      tags: [tag],
+      fetchImpl
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function waitRemoteResponse({
+  config,
+  responseTopic,
+  requestId,
+  allowed,
+  timeoutMs,
+  pollIntervalMs = 1000,
+  fetchImpl = fetch,
+  nowImpl = Date.now,
+  sleepImpl = sleep
+}) {
+  const deadline = nowImpl() + timeoutMs;
+  while (nowImpl() < deadline) {
+    const response = await pollRemoteResponse({ config, responseTopic, requestId, allowed, fetchImpl });
+    if (response !== null) return response;
+    const remaining = deadline - nowImpl();
+    if (remaining <= 0) break;
+    await sleepImpl(Math.min(pollIntervalMs, remaining));
+  }
+  return null;
+}
+
+async function requestDecision({
+  config,
+  title,
+  message,
+  options,
+  includeRefine = false,
+  fetchImpl = fetch,
+  timeoutMs = config.timeoutSeconds * 1000,
+  pollIntervalMs = 1000,
+  nowImpl = Date.now,
+  sleepImpl = sleep
+}) {
+  const remote = await createRemoteRequest({ config, title, message, options, includeRefine, fetchImpl });
+  const response = await waitRemoteResponse({
+    config,
+    ...remote,
+    timeoutMs,
+    pollIntervalMs,
+    fetchImpl,
+    nowImpl,
+    sleepImpl
+  });
+  if (response === null) {
+    return { decision: 'timeout', requestId: remote.requestId, responseTopic: remote.responseTopic };
+  }
+  await sendResponseConfirmation({ config, response, title, fetchImpl });
+  return { ...response, requestId: remote.requestId, responseTopic: remote.responseTopic };
+}
+
+export async function requestApproval(options) {
+  return requestDecision({
+    ...options,
+    options: [
+      { value: 'allow', label: 'Allow' },
+      { value: 'deny', label: 'Deny' }
+    ]
+  });
+}
+
+export async function requestRefinement(options) {
+  return requestDecision({ ...options, options: [], includeRefine: true });
+}
+
+export async function requestChoice({ options, ...rest }) {
+  const normalized = normalizeOptions(options);
+  if (normalized.length < 1 || normalized.length > 3) throw new Error('NOFAX_CHOICE_LIMIT');
+  return requestDecision({ ...rest, options: normalized });
+}

package/src/protocol.mjs

@@ -0,0 +1,108 @@
+import { randomBytes } from 'node:crypto';
+
+const SECRET_KEY = /(?:^|[_-])(token|password|passwd|secret|api[_-]?key|authorization|cookie|credential|private[_-]?key)(?:$|[_-])/i;
+const MAX_STRING = 500;
+const MAX_DEPTH = 5;
+const MAX_ARRAY = 20;
+const MAX_OBJECT_KEYS = 30;
+const MAX_SUMMARY = 2200;
+const MAX_RESPONSE_TEXT = 2000;
+
+function randomBase64Url(bytes) {
+  return randomBytes(bytes).toString('base64url');
+}
+
+export function createRequestId() {
+  return `nfx_${randomBase64Url(18)}`;
+}
+
+export function createResponseTopic() {
+  return `nofax_r_${randomBase64Url(24)}`;
+}
+
+export function createPhoneTopic() {
+  return `nofax_${randomBase64Url(24)}`;
+}
+
+function boundString(value) {
+  if (value.length <= MAX_STRING) return value;
+  return `${value.slice(0, MAX_STRING)}…[truncated]`;
+}
+
+export function redactAndBound(value, options = {}) {
+  const seen = options.seen ?? new WeakSet();
+  const depth = options.depth ?? 0;
+
+  if (value === null || value === undefined) return value;
+  if (typeof value === 'string') return boundString(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'bigint') return value.toString();
+  if (typeof value === 'function' || typeof value === 'symbol') return `[${typeof value}]`;
+  if (depth >= MAX_DEPTH) return '[MAX_DEPTH]';
+  if (typeof value !== 'object') return boundString(String(value));
+
+  if (seen.has(value)) return '[CIRCULAR]';
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    return value.slice(0, MAX_ARRAY).map((item) => redactAndBound(item, { seen, depth: depth + 1 }));
+  }
+
+  const out = {};
+  for (const [key, child] of Object.entries(value).slice(0, MAX_OBJECT_KEYS)) {
+    out[key] = SECRET_KEY.test(key)
+      ? '[REDACTED]'
+      : redactAndBound(child, { seen, depth: depth + 1 });
+  }
+  return out;
+}
+
+function serializeBounded(value) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(redactAndBound(value), null, 2);
+  } catch {
+    serialized = '[unserializable]';
+  }
+  if (serialized.length <= 1400) return serialized;
+  return `${serialized.slice(0, 1400)}\n…[truncated]`;
+}
+
+export function buildAgentSummary({ source, toolName, cwd, toolInput, message }) {
+  const lines = [];
+  if (source) lines.push(`Source: ${boundString(String(source))}`);
+  if (toolName) lines.push(`Tool: ${boundString(String(toolName))}`);
+  if (cwd) lines.push(`Working directory: ${boundString(String(cwd))}`);
+  if (message) lines.push('', boundString(String(message)));
+  if (toolInput !== undefined) lines.push('', 'Request:', serializeBounded(toolInput));
+  const result = lines.join('\n').trim();
+  if (result.length <= MAX_SUMMARY) return result;
+  return `${result.slice(0, MAX_SUMMARY - 14)}\n…[truncated]`;
+}
+
+export function parseResponseMessage(message, { requestId, allowed }) {
+  if (typeof message !== 'string') return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(message);
+  } catch {
+    return null;
+  }
+  if (!parsed || parsed.v !== 1 || parsed.requestId !== requestId || typeof parsed.decision !== 'string') {
+    return null;
+  }
+  if (!allowed.includes(parsed.decision)) return null;
+
+  if (parsed.decision === 'refine') {
+    if (typeof parsed.text !== 'string') return null;
+    const text = parsed.text.trim();
+    if (!text) return null;
+    return { decision: 'refine', text: boundString(text).slice(0, MAX_RESPONSE_TEXT) };
+  }
+
+  return { decision: parsed.decision };
+}
+
+export function parseDecisionMessage(message, { requestId, allowed }) {
+  return parseResponseMessage(message, { requestId, allowed })?.decision ?? null;
+}