@axtary/proxy

Local fail-closed runtime proxy for Axtary policy, ActionPass issuance, and ledger recording.

Early 0.x release: the runtime path is real and tested, but the API is not stable yet and may change between minor versions.

npm install @axtary/proxy

What It Does

• Parses a normalized Axtary action.
• Evaluates it through @axtary/policy.
• Requires ActionPass signing before execution by default.
• Appends every executable or blocked decision to @axtary/ledger.
• Executes only registered handlers for allowed tools.
• Can resolve exact approval evidence for step_up decisions before issuing a pass.
• Returns structured blocked, executed, failed, and malformed results.
• Returns per-stage timings for parse, policy, ActionPass issuance, ledger append, handler execution, and total latency.
• Accepts either a static policy object or an async policy getter for hot-reloaded local configs.

Quickstart

This example runs as-is with Node 20+:

import { createProxyRuntime } from "@axtary/proxy";
import { createFakeHandlers } from "@axtary/adapters";
import { LocalJsonlLedger } from "@axtary/ledger";
import { demoAction } from "@axtary/actionpass";

const proxy = createProxyRuntime({
  issuer: "https://axtary.local",
  tenant: "org:example",
  ledger: new LocalJsonlLedger(".axtary/ledger.jsonl"),
  handlers: createFakeHandlers(),
  allowUnsignedExecution: true, // local demo only; real runs sign every pass
});

// A PR inside policy with passing tests: decision, ledger write, then handler.
const safeAction = structuredClone(demoAction);
safeAction.capability.payload.testsPassed = true;
console.log((await proxy.handle(safeAction)).status); // executed

// The same PR without test evidence requires step-up; with no approval
// resolver attached, the proxy blocks before the handler is ever called.
console.log((await proxy.handle(demoAction)).status); // blocked

Design Notes

The proxy is the first runtime enforcement surface. It is intentionally local and deterministic. Real adapters register handlers and let the proxy own the decision, pass issuance, and ledger write before any production tool is touched.

Unsigned execution is possible only with allowUnsignedExecution: true, which is meant for dry-run tests and local demos.

Handlers are bounded by handlerTimeoutMs from config. Timeout failures are recorded as failed executions after the allow decision is ledgered, which keeps the authorization trace intact without letting slow providers stall the runtime.

When a dynamic policy getter fails, the proxy fails closed, records a deny decision in the ledger, and does not call the downstream handler. That preserves the audit trail while avoiding stale or partially parsed policy.

approvalResolver is the local bridge to hosted or local approval queues. It receives the normalized action and step_up policy decision, and may return a payload-bound approval artifact. If resolution fails, returns nothing, or the artifact does not bind to the exact action, the proxy blocks before handler execution.