@atbash/eliza-plugin

Atbash safety plugin for ElizaOS agents.

Use this when your agent already runs inside ElizaOS and you want Atbash checks around sensitive actions, current policy context in runtime, and best-effort audit logging after action completion.

What It Adds

• atbashPlugin Registers the Atbash service, policy provider, audit evaluator, and explicit judge action.
• AtbashService Loads the Atbash agent identity from Eliza runtime settings.
• ATBASH_JUDGE Explicit Eliza action that asks Atbash for a safety verdict.
• withAtbashGuard(handler) Wraps sensitive action handlers so Atbash decides before the real handler runs.
• policyProvider Exposes current policy and jail status to the runtime.
• auditEvaluator Logs completed action text to Atbash on a best-effort basis.

Runtime Inputs

• ATBASH_AGENT_PRIVKEY Required. Used to derive the Atbash agent identity and sign requests.
• ATBASH_ENDPOINT Optional. Overrides the default Atbash API endpoint.

Runtime Model

At startup:

1. Eliza loads atbashPlugin.
2. AtbashService reads ATBASH_AGENT_PRIVKEY.
3. The service derives the public key and creates one reusable Atbash client.
4. The service checks whether the agent is registered and warns if it is not.

During runtime:

1. policyProvider can expose current safety status.
2. ATBASH_JUDGE can request an explicit verdict.
3. withAtbashGuard() checks Atbash before sensitive action handlers run.
4. auditEvaluator logs completed activity without crashing the agent if logging fails.

Guarded Actions

Wrap the action closest to the side effect:

import { withAtbashGuard } from "@atbash/eliza-plugin";

export const sendFundsAction = {
  name: "SEND_FUNDS",
  description: "Send funds to an external destination",
  validate: async () => true,
  handler: withAtbashGuard(async (_runtime, message) => {
    await submitTransfer(message);
    return { success: true, text: "Transfer submitted" };
  }),
};

Verdict behavior:

• ALLOW Original action handler runs.
• HOLD Original action handler does not run. The action returns a held result with the Atbash toolCallId.
• BLOCK Original action handler does not run. The action returns a blocked result with the policy reason.
• ERROR Original action handler does not run. The action returns an error result.

Explicit Judge Action

ATBASH_JUDGE asks Atbash for a verdict and returns the decision in data.

Use it when the agent or app needs to inspect safety before choosing a next step. It does not execute your business action.

Example

The runtime example uses a real Eliza AgentRuntime, an in-memory adapter, and a simulated guarded transfer action.

npm run build
ATBASH_AGENT_PRIVKEY=your_key_here npm run example

Optional endpoint:

ATBASH_AGENT_PRIVKEY=your_key_here ATBASH_ENDPOINT=https://atbash.ai npm run example