nofax 0.2.0 → 0.2.2

package/SECURITY.md

@@ -1,144 +1,144 @@
-# Security Policy
-
-## Supported versions
-
-Nofax is pre-1.0 software. Security fixes are applied to the latest release on the default branch.
-
-## Reporting a vulnerability
-
-Do not publish credentials, exploit details, private ntfy topics, one-time response URLs, remote MCP capability URLs, or sensitive hook/MCP payloads in a public issue.
-
-If GitHub private vulnerability reporting is enabled for this repository, use it. Otherwise, open a minimal public issue asking for a private maintainer contact channel without including sensitive details.
-
-## Local Nofax security
-
-### Public ntfy is not end-to-end encryption
-
-With the default `https://ntfy.sh` configuration, notification content transits and may be cached by the ntfy service. A random topic name reduces unauthorized discovery but does not encrypt content from the service operator.
-
-Use a trusted authenticated/self-hosted ntfy server for sensitive source code, production operations, credentials, regulated data, or confidential prompts.
-
-### Topics and one-time response URLs are capabilities
-
-On anonymous ntfy servers, knowledge of a topic can be sufficient to subscribe or publish. Treat the local ntfy topic as a bearer secret.
-
-Local Nofax generates fresh one-time response topics for interactive requests. Do not log, share, bookmark, or persist those callback URLs outside the state Nofax itself requires.
-
-### Durable local request state
-
-Local MCP human-response requests are stored under `~/.nofax/requests/` so an MCP/client restart does not erase an unresolved human decision gate.
-
-Nofax writes these files with user-only permissions where supported. MCP-facing request projections deliberately omit the secret response topic. Protect the Nofax home directory like other local application state.
-
-### Pending never means approved
-
-A local interactive request remains pending until a matching terminal response is accepted. Passage of time, timeout, tool failure, network failure, or client disconnect never means approval.
-
-`nofax_wait_for_response` uses bounded long-polls. If it returns pending, the caller must wait again rather than continue the guarded action.
-
-### First terminal response wins
-
-Local durable requests are single-use. Once a valid terminal response is accepted, later responses cannot intentionally replace it.
-
-### Native hook failures never become approval
-
-The Claude Code and Codex adapters fail closed. If the local transport times out, returns malformed data, or encounters a network/polling error, Nofax does not synthesize an Allow decision.
-
-### Redaction is best-effort
-
-Nofax redacts values under common secret-bearing object keys and bounds serialized payloads. It cannot reliably detect a credential embedded in arbitrary free-form command text. Treat all notification content accordingly.
-
-## Remote Worker security
-
-The optional Cloudflare Worker in v0.3 is a **one-way notification plus inspection remote MCP endpoint**.
-
-### Remote side effects are structurally bounded
-
-MCP tool annotations are descriptive metadata, not the security boundary.
-
-The remote Worker bounds side effects in code:
-
-- only `nofax_notify`, `nofax_get_request`, and `nofax_list_pending` are registered as MCP tools;
-- the remote handler object exposes one-way notification plus two read operations;
-- there is no remote approval, choice, refinement, wait, callback, or webhook handler;
-- public Worker routing is limited to health and authenticated MCP paths;
-- `/telegram/webhook` and `/r/*` are not routes and return 404;
-- pending-list reads filter expired rows without deleting them or performing hidden cleanup writes.
-
-The two inspection tools are annotated with `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, and `openWorldHint: false`. `nofax_notify` is accurately marked side-effecting/non-idempotent/open-world and non-destructive.
-
-### Remote response minimization
-
-Remote MCP responses deliberately omit capability-bearing or unnecessary fields. Public request projections do not expose:
-
-- callback hashes;
-- callback tokens/URLs;
-- original request title;
-- original request message/prompt material;
-- internal allowed-decision lists.
-
-Terminal state may include the stored terminal decision and historical refinement text when present in existing durable state.
-
-### Remote MCP key is a bearer secret
-
-The Worker is a private single-user deployment protected by `NOFAX_REMOTE_KEY`.
-
-Preferred clients send:
-
-```text
-Authorization: Bearer <NOFAX_REMOTE_KEY>
-```
-
-Clients that cannot attach a static header may use:
-
-```text
-/mcp/<NOFAX_REMOTE_KEY>
-```
-
-The complete capability URL is equivalent to a password and may leak through browser history, screenshots, copied configuration, proxies, or third-party logging. Prefer the Authorization header whenever the MCP host supports it.
-
-Nofax uses equal-length constant-time credential comparison. After capability-path authentication, the Worker normalizes the request internally to `/mcp` before MCP protocol handling.
-
-Rotate `NOFAX_REMOTE_KEY` immediately if it is exposed.
-
-A single deployment-wide key is not sufficient for a shared/public multi-user service. Use a delegated authentication and authorization design before operating a multi-user deployment.
-
-### Durable Object compatibility
-
-The v0.3 Worker preserves the existing SQLite request schema so upgrading from experimental pre-read-only Worker builds does not require destructive storage migration.
-
-Only request-inspection methods are reachable for Durable Object state. Existing legacy rows may therefore be inspected after upgrade, but the Worker cannot create, resolve, or delete them through MCP or HTTP routes. The separate `nofax_notify` method can publish an explicitly requested one-way notification and does not mutate request state.
-
-### Cloudflare is the remote trust boundary
-
-Remote mode adds Cloudflare as an infrastructure boundary. For notification calls, ntfy is an additional provider boundary and receives the bounded notification title/message plus the configured topic identifier.
-
-The Worker does not automatically forward durable request records to ntfy. Only explicit `nofax_notify` content is published; Telegram, WhatsApp, SMS, and human-response callbacks remain absent remotely.
-
-Do not expose the deployment key in source, Wrangler vars, `.env`, `.dev.vars`, CI logs, PR text, screenshots, or issue reports. Use Wrangler secrets for production values and keep local secret files untracked.
-
-### Hosted ntfy quotas are an external availability boundary
-
-The public `ntfy.sh` service applies its own publisher limits independently of Cloudflare Workers quotas. Serverless egress may be shared between unrelated workloads, so a Cloudflare Worker can receive an ntfy `42908` daily-quota response even when that individual Worker has published little traffic.
-
-Treat public ntfy availability and quota policy as an external dependency. Reliability-sensitive deployments should use a transport with account-scoped quota/identity or a trusted self-hosted service rather than assuming anonymous public-topic capacity.
-
-## Nofax is not a policy engine
-
-Local Nofax answers approval requests that an upstream agent or workflow explicitly delegates to it. It does not decide which operations should require approval and must not be used to bypass an agent's deny rules, sandbox, or existing authorization boundaries.
-
-An `allow` result permits the caller to continue only within authority it already possessed.
-
-The remote Worker does not grant authority. Its only mutation is sending an informational notification; request-state operations remain inspection-only.
-
-## MCP transport notes
-
-### Local stdio
-
-`nofax mcp` is a local stdio server. Stdout is reserved for MCP protocol traffic. Do not wrap it with tooling that injects banners or diagnostics into stdout.
-
-### Remote Streamable HTTP
-
-The optional Worker uses authenticated Streamable HTTP for MCP. The only unauthenticated functional route is the secret-free `/healthz` health check.
-
-See [`docs/remote-mcp.md`](docs/remote-mcp.md) for the remote architecture and qualification checklist.
+# Security Policy
+
+## Supported versions
+
+Nofax is pre-1.0 software. Security fixes are applied to the latest release on the default branch.
+
+## Reporting a vulnerability
+
+Do not publish credentials, exploit details, private ntfy topics, one-time response URLs, remote MCP capability URLs, or sensitive hook/MCP payloads in a public issue.
+
+If GitHub private vulnerability reporting is enabled for this repository, use it. Otherwise, open a minimal public issue asking for a private maintainer contact channel without including sensitive details.
+
+## Local Nofax security
+
+### Public ntfy is not end-to-end encryption
+
+With the default `https://ntfy.sh` configuration, notification content transits and may be cached by the ntfy service. A random topic name reduces unauthorized discovery but does not encrypt content from the service operator.
+
+Use a trusted authenticated/self-hosted ntfy server for sensitive source code, production operations, credentials, regulated data, or confidential prompts.
+
+### Topics and one-time response URLs are capabilities
+
+On anonymous ntfy servers, knowledge of a topic can be sufficient to subscribe or publish. Treat the local ntfy topic as a bearer secret.
+
+Local Nofax generates fresh one-time response topics for interactive requests. Do not log, share, bookmark, or persist those callback URLs outside the state Nofax itself requires.
+
+### Durable local request state
+
+Local MCP human-response requests are stored under `~/.nofax/requests/` so an MCP/client restart does not erase an unresolved human decision gate.
+
+Nofax writes these files with user-only permissions where supported. MCP-facing request projections deliberately omit the secret response topic. Protect the Nofax home directory like other local application state.
+
+### Pending never means approved
+
+A local interactive request remains pending until a matching terminal response is accepted. Passage of time, timeout, tool failure, network failure, or client disconnect never means approval.
+
+`nofax_wait_for_response` uses bounded long-polls. If it returns pending, the caller must wait again rather than continue the guarded action.
+
+### First terminal response wins
+
+Local durable requests are single-use. Once a valid terminal response is accepted, later responses cannot intentionally replace it.
+
+### Native hook failures never become approval
+
+The Claude Code and Codex adapters fail closed. If the local transport times out, returns malformed data, or encounters a network/polling error, Nofax does not synthesize an Allow decision.
+
+### Redaction is best-effort
+
+Nofax redacts values under common secret-bearing object keys and bounds serialized payloads. It cannot reliably detect a credential embedded in arbitrary free-form command text. Treat all notification content accordingly.
+
+## Remote Worker security
+
+The optional Cloudflare Worker in v0.3 is a **one-way notification plus inspection remote MCP endpoint**.
+
+### Remote side effects are structurally bounded
+
+MCP tool annotations are descriptive metadata, not the security boundary.
+
+The remote Worker bounds side effects in code:
+
+- only `nofax_notify`, `nofax_get_request`, and `nofax_list_pending` are registered as MCP tools;
+- the remote handler object exposes one-way notification plus two read operations;
+- there is no remote approval, choice, refinement, wait, callback, or webhook handler;
+- public Worker routing is limited to health and authenticated MCP paths;
+- `/telegram/webhook` and `/r/*` are not routes and return 404;
+- pending-list reads filter expired rows without deleting them or performing hidden cleanup writes.
+
+The two inspection tools are annotated with `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, and `openWorldHint: false`. `nofax_notify` is accurately marked side-effecting/non-idempotent/open-world and non-destructive.
+
+### Remote response minimization
+
+Remote MCP responses deliberately omit capability-bearing or unnecessary fields. Public request projections do not expose:
+
+- callback hashes;
+- callback tokens/URLs;
+- original request title;
+- original request message/prompt material;
+- internal allowed-decision lists.
+
+Terminal state may include the stored terminal decision and historical refinement text when present in existing durable state.
+
+### Remote MCP key is a bearer secret
+
+The Worker is a private single-user deployment protected by `NOFAX_REMOTE_KEY`.
+
+Preferred clients send:
+
+```text
+Authorization: Bearer <NOFAX_REMOTE_KEY>
+```
+
+Clients that cannot attach a static header may use:
+
+```text
+/mcp/<NOFAX_REMOTE_KEY>
+```
+
+The complete capability URL is equivalent to a password and may leak through browser history, screenshots, copied configuration, proxies, or third-party logging. Prefer the Authorization header whenever the MCP host supports it.
+
+Nofax uses equal-length constant-time credential comparison. After capability-path authentication, the Worker normalizes the request internally to `/mcp` before MCP protocol handling.
+
+Rotate `NOFAX_REMOTE_KEY` immediately if it is exposed.
+
+A single deployment-wide key is not sufficient for a shared/public multi-user service. Use a delegated authentication and authorization design before operating a multi-user deployment.
+
+### Durable Object compatibility
+
+The v0.3 Worker preserves the existing SQLite request schema so upgrading from experimental pre-read-only Worker builds does not require destructive storage migration.
+
+Only request-inspection methods are reachable for Durable Object state. Existing legacy rows may therefore be inspected after upgrade, but the Worker cannot create, resolve, or delete them through MCP or HTTP routes. The separate `nofax_notify` method can publish an explicitly requested one-way notification and does not mutate request state.
+
+### Cloudflare is the remote trust boundary
+
+Remote mode adds Cloudflare as an infrastructure boundary. For notification calls, ntfy is an additional provider boundary and receives the bounded notification title/message plus the configured topic identifier.
+
+The Worker does not automatically forward durable request records to ntfy. Only explicit `nofax_notify` content is published; Telegram, WhatsApp, SMS, and human-response callbacks remain absent remotely.
+
+Do not expose the deployment key in source, Wrangler vars, `.env`, `.dev.vars`, CI logs, PR text, screenshots, or issue reports. Use Wrangler secrets for production values and keep local secret files untracked.
+
+### Hosted ntfy quotas are an external availability boundary
+
+The public `ntfy.sh` service applies its own publisher limits independently of Cloudflare Workers quotas. Serverless egress may be shared between unrelated workloads, so a Cloudflare Worker can receive an ntfy `42908` daily-quota response even when that individual Worker has published little traffic.
+
+Treat public ntfy availability and quota policy as an external dependency. Reliability-sensitive deployments should use a transport with account-scoped quota/identity or a trusted self-hosted service rather than assuming anonymous public-topic capacity.
+
+## Nofax is not a policy engine
+
+Local Nofax answers approval requests that an upstream agent or workflow explicitly delegates to it. It does not decide which operations should require approval and must not be used to bypass an agent's deny rules, sandbox, or existing authorization boundaries.
+
+An `allow` result permits the caller to continue only within authority it already possessed.
+
+The remote Worker does not grant authority. Its only mutation is sending an informational notification; request-state operations remain inspection-only.
+
+## MCP transport notes
+
+### Local stdio
+
+`nofax mcp` is a local stdio server. Stdout is reserved for MCP protocol traffic. Do not wrap it with tooling that injects banners or diagnostics into stdout.
+
+### Remote Streamable HTTP
+
+The optional Worker uses authenticated Streamable HTTP for MCP. The only unauthenticated functional route is the secret-free `/healthz` health check.
+
+See [`docs/remote-mcp.md`](docs/remote-mcp.md) for the remote architecture and qualification checklist.

package/bin/nofax.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
-import { runCli } from '../src/cli.mjs';
-
-process.exitCode = await runCli(process.argv.slice(2));
+#!/usr/bin/env node
+import { runCli } from '../src/cli.mjs';
+
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "nofax",
-  "version": "0.2.0",
-  "mcpName": "io.github.AKzar1el/nofax",
-  "description": "Human-in-the-loop approvals and notifications for AI coding agents via CLI, MCP, and agent hooks.",
-  "type": "module",
-  "bin": {
-    "nofax": "./bin/nofax.mjs"
-  },
-  "exports": {
-    ".": "./src/index.mjs",
-    "./mcp": "./src/mcp-server.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "README.md",
-    "LICENSE",
-    "SECURITY.md"
-  ],
-  "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "check": "node --check bin/nofax.mjs && node --check src/cli.mjs && node --check src/config.mjs && node --check src/protocol.mjs && node --check src/ntfy.mjs && node --check src/requests.mjs && node --check src/mcp-tools.mjs && node --check src/mcp-server.mjs && node --check src/adapters/claude.mjs && node --check src/adapters/codex.mjs && node --check src/adapters/gemini.mjs"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.4.3"
-  },
-  "keywords": [
-    "ai-agent",
-    "approval",
-    "claude-code",
-    "codex",
-    "gemini-cli",
-    "human-in-the-loop",
-    "mcp",
-    "model-context-protocol",
-    "ntfy",
-    "notifications",
-    "remote",
-    "developer-tools"
-  ],
-  "license": "MIT",
-  "author": "Tomi Šeregi",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AKzar1el/nofax.git"
-  },
-  "homepage": "https://github.com/AKzar1el/nofax#readme",
-  "bugs": {
-    "url": "https://github.com/AKzar1el/nofax/issues"
-  }
-}
+{
+  "name": "nofax",
+  "version": "0.2.2",
+  "mcpName": "io.github.AKzar1el/nofax",
+  "description": "Human-in-the-loop approvals and notifications for AI coding agents via CLI, MCP, and agent hooks.",
+  "type": "module",
+  "bin": {
+    "nofax": "./bin/nofax.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./mcp": "./src/mcp-server.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check bin/nofax.mjs && node --check src/cli.mjs && node --check src/config.mjs && node --check src/protocol.mjs && node --check src/ntfy.mjs && node --check src/requests.mjs && node --check src/mcp-tools.mjs && node --check src/mcp-server.mjs && node --check src/adapters/claude.mjs && node --check src/adapters/codex.mjs && node --check src/adapters/gemini.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.4.3"
+  },
+  "keywords": [
+    "ai-agent",
+    "approval",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "human-in-the-loop",
+    "mcp",
+    "model-context-protocol",
+    "ntfy",
+    "notifications",
+    "remote",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "author": "Tomi Šeregi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AKzar1el/nofax.git"
+  },
+  "homepage": "https://github.com/AKzar1el/nofax#readme",
+  "bugs": {
+    "url": "https://github.com/AKzar1el/nofax/issues"
+  }
+}

package/src/adapters/claude.mjs

@@ -1,47 +1,47 @@
-import { buildAgentSummary } from '../protocol.mjs';
-import { requestApproval } from '../ntfy.mjs';
-
-function assertClaudePermissionRequest(input) {
-  if (!input || input.hook_event_name !== 'PermissionRequest') throw new Error('NOFAX_CLAUDE_EVENT');
-  if (typeof input.tool_name !== 'string' || !input.tool_name) throw new Error('NOFAX_CLAUDE_TOOL');
-}
-
-export async function handleClaudePermissionRequest(input, {
-  config,
-  requestApprovalImpl = requestApproval,
-  onError = () => {}
-} = {}) {
-  assertClaudePermissionRequest(input);
-  try {
-    const result = await requestApprovalImpl({
-      config,
-      title: `Claude Code needs approval: ${input.tool_name}`,
-      message: buildAgentSummary({
-        source: 'Claude Code',
-        toolName: input.tool_name,
-        cwd: input.cwd,
-        toolInput: input.tool_input
-      })
-    });
-    if (result.decision === 'allow') {
-      return {
-        hookSpecificOutput: {
-          hookEventName: 'PermissionRequest',
-          decision: { behavior: 'allow' }
-        }
-      };
-    }
-    if (result.decision === 'deny') {
-      return {
-        hookSpecificOutput: {
-          hookEventName: 'PermissionRequest',
-          decision: { behavior: 'deny', message: 'Denied remotely via Nofax.' }
-        }
-      };
-    }
-    return null;
-  } catch (error) {
-    onError(error);
-    return null;
-  }
-}
+import { buildAgentSummary } from '../protocol.mjs';
+import { requestApproval } from '../ntfy.mjs';
+
+function assertClaudePermissionRequest(input) {
+  if (!input || input.hook_event_name !== 'PermissionRequest') throw new Error('NOFAX_CLAUDE_EVENT');
+  if (typeof input.tool_name !== 'string' || !input.tool_name) throw new Error('NOFAX_CLAUDE_TOOL');
+}
+
+export async function handleClaudePermissionRequest(input, {
+  config,
+  requestApprovalImpl = requestApproval,
+  onError = () => {}
+} = {}) {
+  assertClaudePermissionRequest(input);
+  try {
+    const result = await requestApprovalImpl({
+      config,
+      title: `Claude Code needs approval: ${input.tool_name}`,
+      message: buildAgentSummary({
+        source: 'Claude Code',
+        toolName: input.tool_name,
+        cwd: input.cwd,
+        toolInput: input.tool_input
+      })
+    });
+    if (result.decision === 'allow') {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PermissionRequest',
+          decision: { behavior: 'allow' }
+        }
+      };
+    }
+    if (result.decision === 'deny') {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PermissionRequest',
+          decision: { behavior: 'deny', message: 'Denied remotely via Nofax.' }
+        }
+      };
+    }
+    return null;
+  } catch (error) {
+    onError(error);
+    return null;
+  }
+}

package/src/adapters/codex.mjs

@@ -1,47 +1,47 @@
-import { buildAgentSummary } from '../protocol.mjs';
-import { requestApproval } from '../ntfy.mjs';
-
-function assertCodexPermissionRequest(input) {
-  if (!input || input.hook_event_name !== 'PermissionRequest') throw new Error('NOFAX_CODEX_EVENT');
-  if (typeof input.tool_name !== 'string' || !input.tool_name) throw new Error('NOFAX_CODEX_TOOL');
-}
-
-export async function handleCodexPermissionRequest(input, {
-  config,
-  requestApprovalImpl = requestApproval,
-  onError = () => {}
-} = {}) {
-  assertCodexPermissionRequest(input);
-  try {
-    const result = await requestApprovalImpl({
-      config,
-      title: `Codex needs approval: ${input.tool_name}`,
-      message: buildAgentSummary({
-        source: 'Codex',
-        toolName: input.tool_name,
-        cwd: input.cwd,
-        toolInput: input.tool_input
-      })
-    });
-    if (result.decision === 'allow') {
-      return {
-        hookSpecificOutput: {
-          hookEventName: 'PermissionRequest',
-          decision: { behavior: 'allow' }
-        }
-      };
-    }
-    if (result.decision === 'deny') {
-      return {
-        hookSpecificOutput: {
-          hookEventName: 'PermissionRequest',
-          decision: { behavior: 'deny', message: 'Denied remotely via Nofax.' }
-        }
-      };
-    }
-    return null;
-  } catch (error) {
-    onError(error);
-    return null;
-  }
-}
+import { buildAgentSummary } from '../protocol.mjs';
+import { requestApproval } from '../ntfy.mjs';
+
+function assertCodexPermissionRequest(input) {
+  if (!input || input.hook_event_name !== 'PermissionRequest') throw new Error('NOFAX_CODEX_EVENT');
+  if (typeof input.tool_name !== 'string' || !input.tool_name) throw new Error('NOFAX_CODEX_TOOL');
+}
+
+export async function handleCodexPermissionRequest(input, {
+  config,
+  requestApprovalImpl = requestApproval,
+  onError = () => {}
+} = {}) {
+  assertCodexPermissionRequest(input);
+  try {
+    const result = await requestApprovalImpl({
+      config,
+      title: `Codex needs approval: ${input.tool_name}`,
+      message: buildAgentSummary({
+        source: 'Codex',
+        toolName: input.tool_name,
+        cwd: input.cwd,
+        toolInput: input.tool_input
+      })
+    });
+    if (result.decision === 'allow') {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PermissionRequest',
+          decision: { behavior: 'allow' }
+        }
+      };
+    }
+    if (result.decision === 'deny') {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PermissionRequest',
+          decision: { behavior: 'deny', message: 'Denied remotely via Nofax.' }
+        }
+      };
+    }
+    return null;
+  } catch (error) {
+    onError(error);
+    return null;
+  }
+}