Evidence before authority.

A valid signature proves that a key signed a message. It does not make the text safe or authorize an agent tool. ActionLock binds the message to evidence, derives capabilities only from trusted local policy, and requires a one-time approval for eligible downstream effects.

Use Node.js 20 or newer. The MCP check starts an isolated local server, connects with a real client, verifies all five tools, and confirms fail-closed startup.

Copy actionlock.config.example.json to the ignored local file actionlock.config.json. Every exposed tool needs a fixed capability, operation, target, and argument-size limit.

{
  "version": 1,
  "servers": [{
    "id": "reports",
    "command": "node",
    "args": ["/absolute/path/to/trusted-mcp-server.js"],
    "inheritEnv": [],
    "tools": {
      "write_report": {
        "capability": "file_write",
        "operation": "write reviewed report",
        "target": "local report workspace",
        "maxArgumentBytes": 16000
      }
    }
  }]
}

Generate the secret on the builder’s machine. Keep it out of Git, screenshots, chat, and the hosted console.

Add one local stdio server to the agent’s MCP configuration. Replace paths and the secret locally. Do not expose the same downstream server directly to the agent.

{
  "mcpServers": {
    "actionlock": {
      "command": "npm",
      "args": ["--prefix", "/absolute/path/technocore-actionlock", "run", "mcp"],
      "env": {
        "ACTIONLOCK_ROOT_SECRET": "<local-secret-at-least-32-bytes>",
        "ACTIONLOCK_CONFIG": "/absolute/path/actionlock.config.json"
      }
    }
  }
}

Restart the client. It should discover five ActionLock tools and no direct downstream tools. If it cannot find npm, use the absolute executable path.

1. Read evidenceCall actionlock_read_room and retain the short-lived evidence token.
2. Inspect policyCall actionlock_list_policies. An empty list means downstream execution is disabled.
3. Preview exact argumentsCall actionlock_preview. Review the evidence, tool, target, arguments, and action hash without executing.
4. Approve outside the agentRun npm run approve -- <action-hash>. The one-time token expires after 120 seconds.
5. Execute onceCall actionlock_execute without changing evidence, server, tool, arguments, or approval token.
6. Keep public receiptsSuccessful, recorded calls return the signed pair at publicReceipts.approval and publicReceipts.execution. When completion or recording is uncertain, retain approvalReceipt and the outcome response instead.
7. Verify the auditCall actionlock_verify_audit. Replayed or modified approvals are rejected.

The local gateway creates an Ed25519 key in its private state directory. Approval receipts contain the complete inputs needed to recompute the action hash and are signed before the downstream call. Result receipts are signed separately and link to the approval receipt hash.

Save the complete publicReceipts object to verify the linked approval and execution pair. V1 pairs require the correct receipt kinds and the same signing key; malformed signed fields and non-canonical signature encodings are rejected. The key command prints only the public identity that an operator can publish independently.

Implementing a verifier? Compare your encoding against the fixed JSON, UTF-8 and SHA-256 vectors and read the canonicalization specification. The custom profile is not RFC 8785 / JCS; matching these examples alone is not full receipt verification.

Changing receipt keys? The planned key-transition guide covers a local handover signed by both keys. Preparation does not activate a key or change verifier trust. It is not revocation, compromise recovery, or an independently timestamped history.

1. No policies listedThe config is missing, unreadable, or intentionally empty. No downstream execution is available.
2. Approval requiredThe action is eligible but no exact, valid one-time approval matches its current hash.
3. BlockedThe requested boundary is prohibited. Remote shell, wallet, and social capabilities cannot be approved.
4. Unknown execution outcomeA downstream error may occur after an effect. Inspect executionStatus and recordingErrors. Never retry automatically or request a fresh approval before checking the downstream records. An audit or signing failure does not reverse a completed action.
5. Partial scanMalformed records are excluded and counted in rejectedCount. They receive no evidence receipts. Valid records remain inspectable, but the result is not complete coverage or proof that the room is safe. Invalid envelopes and mismatched rooms fail the read; exact-sequence export remains fail-closed.
6. Technocore unavailableThe hosted console remains online but cannot fetch the upstream retained window. Retry after the upstream service returns. Upstream error bodies are discarded instead of relayed to agents.
7. Not retainedThe requested sequence is older than the first record in the current export. ActionLock reports the boundary and does not fabricate missing evidence.