ActionLock is an enforced MCP capability gateway for agents that consume untrusted Technocore messages. It keeps sender authenticity, content safety, human approval, and permission to act as separate decisions.
Community project. Not affiliated with or endorsed by FLOP Labs.
Live: Public console · Choose user or builder path · Documentation · Machine-readable overview
Technocore rooms are world-writable. A valid did:key signature proves that a key signed a message; it does not make the message safe or authorize that message to control tools.
ActionLock closes the gap between reading a message and performing a side effect:
actionlock_read_roomfetches a bounded room window from the pinned Technocore origin.- Each observed message receives a short-lived HMAC evidence receipt.
- A trusted local config maps an exact downstream MCP tool to its capability, operation, target, and argument limit.
actionlock_previewderives a versioned action hash from the complete evidence receipt, server, tool, executable policy, and canonical argument hash.- A human may issue one short-lived approval for that exact action hash.
actionlock_executeconsumes the approval atomically before forwarding the call to the configured MCP server.- The decision and execution outcome are appended to a locked hash chain with an HMAC-protected head checkpoint.
The model cannot declare its own capability class, invent evidence, substitute the evidence/server/tool/policy/arguments after approval, or replay an approval after restart.
- Technocore message URLs are data and are never followed automatically.
- GET-shaped Technocore write URLs embedded in content are always blocked.
- Shell, wallet, and social actions derived from remote content remain blocked even when an approval token is supplied.
- Every downstream call derived from remote content requires an exact approval.
- Capability, operation, target, command, and environment inheritance come only from trusted local config.
- Approval replay protection uses atomic exclusive file creation and survives process restarts.
- Audit appenders use an inter-process lock and refuse to extend an invalid chain.
- The hosted web console has no root secret, downstream config, private key, write tool, or approval issuer.
| Rule | Condition | Result |
|---|---|---|
ACTIONLOCK-001 |
Message embeds a Technocore GET-write URL | Block |
ACTIONLOCK-010 |
Bounded built-in inspection | Allow with provenance |
ACTIONLOCK-020 |
Remote content requests shell, wallet, or social access | Block |
ACTIONLOCK-030 |
Remote content reaches a configured downstream tool | Exact approval required |
ACTIONLOCK-031 |
Approval matches evidence, tool policy, target, and canonical arguments | Allow once |
ACTIONLOCK-040 |
Sensitive local action lacks approval | Approval required |
ACTIONLOCK-050 |
Local action is inside the configured policy boundary | Allow |
Requirements: Node.js 20 or newer.
npm install
npm run check
npm run check:mcp
npm run devOpen http://127.0.0.1:3000. The web console is a read-only inspection and policy-simulation surface. It cannot issue evidence receipts or execute tools.
Console users can scan the newest 25, 50, 100, or 200 retained room messages, enable a 30- or 60-second refresh, search and filter the current window, or run a user-triggered exact-sequence lookup. Current-window matches resolve locally; older sequences use the bounded room export. A found record enters the same signature, provenance, and risk pipeline as a live scan. Users can pin up to 100 evidence records in browser-local IndexedDB and export the selected evidence as JSON. These actions remain inspection operations; they do not post to Technocore or execute a downstream tool.
The console distinguishes an empty retained window, a record that has rotated out, an unexplained sequence gap, and a temporary Technocore outage. Exact lookup is capped at 12 MiB and never runs on refresh. Browser pins stay on that browser profile; the hosted application remains stateless and is not a historical archive.
Generate a local root secret:
node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))"Set that value as ACTIONLOCK_ROOT_SECRET. Copy actionlock.config.example.json to the ignored actionlock.config.json, then replace the example command with an absolute path to a trusted MCP server. Do not put secrets in the config; use inheritEnv to name only the environment variables that server needs.
npm run mcpThe MCP server exposes:
actionlock_read_roomactionlock_list_policiesactionlock_previewactionlock_executeactionlock_verify_audit
A missing config produces an empty policy list and disables all downstream execution.
Verify the real stdio handshake before connecting an agent:
npm run check:mcpThe smoke test starts ActionLock with an isolated temporary state directory, connects with the official MCP client SDK, verifies the five advertised tools, confirms that the policy list is empty without trusted config, and closes without retaining local state.
Run actionlock_preview first and review the evidence, downstream server, tool, arguments, policy, and action hash. Issue an approval outside the agent process:
npm run approve -- <64-character-action-hash>Pass the returned token to actionlock_execute without changing any argument. The token expires within 120 seconds and is consumed before the downstream call starts. A failed downstream call still consumes it.
The hosted application is stateless by design:
- no server-side database or scheduled polling; optional pins use browser-local IndexedDB only;
- no wallet, Technocore signing key, root secret, or gateway config;
- room scans run only on request;
- scan responses are bounded to the newest 200 retained messages and cached at the edge for 30 seconds;
- exact-sequence lookups are user-triggered, uncached, streamed from the room export, and fail closed above 12 MiB;
- Technocore exposes no backwards pagination. Export lookup can find a record only while it remains in the room ring, and reports
not_retainedafter rotation.
Create it as a separate Vercel project. Do not attach another project's environment variables, domains, or deployment settings.
npm run check
npm run check:mcp
npm run buildTests cover canonical Technocore signatures, big-integer evidence, signed receipt tampering and expiry, exact evidence/server/tool/policy/argument approval binding, bounded HTTP bodies, persistent replay protection, audit quotas, concurrent audit appends, blocked sensitive capabilities, and end-to-end gateway execution.
Protocol verification includes fixed RFC 8032-backed vectors from techbone/technocore-conformance, rather than relying only on values generated by ActionLock itself.
See SECURITY.md, docs/architecture.md, and docs/landscape.md.
For a complete agent setup, MCP client example, approval sequence, and bypass warning, see docs/integration.md or the hosted /docs page.
Coding agents should read AGENTS.md. Runtime agents and crawlers can use the hosted /llms.txt overview.
ActionLock protects only tools routed through its gateway. An agent with a separate unrestricted shell, wallet, social, or downstream MCP connection can bypass it; remove those bypass paths from the agent's capability set.
The local HMAC checkpoint detects edits to the current audit head. It cannot detect coordinated rollback of both the audit log and checkpoint unless the head hash is copied to an external append-only system.
MIT