Skip to content

Security: fahomid/Efficient-Token

Security

SECURITY.md

Security Policy

Reporting a vulnerability

Do not open a public issue for a security vulnerability.

Use GitHub's private Report a vulnerability form, or email fahomid2012@gmail.com with the subject efficient-token security.

Include the affected version, platform, reproduction steps, and impact. You should receive an acknowledgement within a few days. A fix or mitigation timeline follows after triage.

Supported versions

Security fixes are made on the latest released minor version. Pin the version you use and watch releases for updates.

Version Supported
1.1.x Yes
Earlier versions No

Trust boundary

efficient-token runs on the developer's machine over MCP stdio. Workspace tools operate inside the configured root. Package scripts are an explicit execution boundary, and heartbeat state is a narrow external write.

The server assumes that the user trusts the selected workspace and its package.json scripts. Processes that can change the workspace under the same account are also inside the local trust boundary.

Each server admits at most 16 concurrent MCP tool handlers. Excess requests fail without entering an unbounded queue, and requests cancelled before execution do not enter plugin code.

Workspace file access

Every project or source path passes through PathSandbox and SafeFs.

  • Lexical checks reject null bytes, traversal outside the root, and absolute paths outside the root. On Windows, a colon in any relative path segment is rejected to block drive syntax and NTFS alternate data streams.
  • Reads open regular files only. They verify the opened file against its canonical in-root path before returning data.
  • UTF-8 text reads and writes are capped by EFFICIENT_TOKEN_MAX_FILE_BYTES, which defaults to 2 MB. Invalid UTF-8 reads and unpaired UTF-16 surrogate writes are rejected.
  • Binary tools use their own bounded byte or header reads.
  • Writes create an exclusive temporary file in the destination directory, verify it, sync it, and atomically rename it into place.
  • Process-wide path locks serialize mutations made through SafeFs instances in the same server process.

Coordinated edits use expected source content. All expected values are checked before the first change and again before each replacement. If a later change fails, completed changes are rolled back in reverse order. Rollback refuses to overwrite a path changed by another actor and reports any file it cannot safely restore.

Portable Node.js does not expose directory-handle-relative rename and unlink operations. A process that can swap a parent directory at the final filesystem call can still race the portable checks. Multi-file changes also do not provide durability across a machine crash.

Package script execution

code_check, check_locate, and test_run can run a script already defined in the root package.json. They do not accept a free-form shell command.

The launcher validates script names and forwarded filters, resolves npm and its script shell through trusted absolute paths outside the workspace, and removes environment values that can redirect Node.js or the shell. Output is byte-capped. Timeouts, MCP cancellation, and server shutdown request process-tree termination. The server keeps tracking the child and inherited pipes until they close, and a cancelled run is never reported as successful.

An allowed package script remains arbitrary project code. It runs with the user's normal operating-system permissions and may access files outside the workspace, change the workspace, start processes, or use the network. Review project scripts before allowing a runner tool to execute them.

Git isolation

Read-only Git helpers resolve Git outside the workspace and launch it from the executable's directory. They remove inherited GIT_* control variables and disable optional locks, fsmonitor, lazy object fetching, external diff, text conversion, and signature display where relevant.

When the workspace is a subdirectory of a parent repository, Git pathspecs and output are scoped and rebased to the configured root. Working-tree inspection fails closed when an applicable external clean or process filter would need to run.

Optional media probing

media_info may invoke ffprobe. It resolves the executable outside the workspace, starts it from a trusted directory with a sanitized environment, and passes the media path as a separate argument. Protocol and demuxer restrictions are selected from the declared file type. Probe output, runtime, and input count are bounded.

Network behavior

The built-in free tools make no direct outbound network requests. Package scripts may use the network, so runner annotations advertise open-world behavior. Optional premium discovery runs only after the entitlement provider permits premium access. The free provider never imports or registers an optional premium module.

Protocol and status state

stdout carries MCP JSON-RPC only. Diagnostics go to stderr.

Each live server may write one small status file outside the workspace. The default location is a per-user runtime or temporary directory with a bucket derived from the canonical workspace root. Readers reject symlinks and require the current owner on supported POSIX systems. The default base, workspace bucket, and status files use private modes. An existing custom base may have a broader mode, but its bucket and files remain private. Status files are bounded and decoded as strict UTF-8. Set EFFICIENT_TOKEN_STATE_DIR to select the base or EFFICIENT_TOKEN_HEARTBEAT=0 to disable status writes.

Read-only compatibility checks for old .claude/.efficient-token heartbeat paths remain available. The server does not create new heartbeat files there.

Operator guidance

  • Set EFFICIENT_TOKEN_ROOT explicitly when the server working directory or host project directory is not the intended workspace.
  • Treat MCP annotations as host-facing hints, not an access-control boundary.
  • Configure the host to confirm mutating and runner tools when human approval is required.
  • Keep Node.js, npm, Git, optional media tools, and project dependencies patched.

For Codex, this project-scoped configuration asks the host to approve tools that are not marked read-only:

[mcp_servers.efficient-token]
command = "npx"
args = ["-y", "efficient-token"]
cwd = "/abs/path/to/project"
default_tools_approval_mode = "writes"

[mcp_servers.efficient-token.env]
EFFICIENT_TOKEN_ROOT = "/abs/path/to/project"

There aren't any published security advisories