@axtary/policy

Deterministic policy evaluation and Cedar/OPA mappings for Axtary agent actions.

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

The source repository is currently private. Public product documentation and runnable guides are at axtary.com/docs.

npm install @axtary/policy

What It Does

• Evaluates normalized Axtary actions against a local policy config.
• Returns allow, deny, or step_up decisions.
• Supports named multi-rule policies with wildcard tool/resource/actor matchers, deny-overrides precedence, and default-deny.
• Attaches enforceable obligations: narrowed TTL, approver roles, blocked paths, UTC time windows, and per-process rate windows.
• Ships guardrails for GitHub PRs/reviews/checks and content reads/writes, Slack posts (channel allowlists + external-recipient step-up), Linear/Jira issue actions, Postgres scoped SELECT analysis (write statements denied before execution), Google Drive file reads, and MCP tool calls pinned by definition hash (same-name definition drift denies).
• Maps the same normalized action into Cedar-style principal/action/resource/context.
• Exposes OPA/Rego-compatible input JSON, with an executable --parity harness that fails on any cross-engine disagreement.
• Exposes a thin Agent Control-style pre_tool_call / post_tool_call shim that maps tool-call snapshots into normalized Axtary actions and fails closed on malformed envelopes.
• Emits an offline AgentCore Cedar-shaped Gateway authorization request mapping for parity fixtures. This is an export shape, not a live AWS deployment.

Quickstart

This example runs as-is with Node 20+:

import { evaluatePolicy, explainPolicyDecision } from "@axtary/policy";
import { demoAction } from "@axtary/actionpass";

// Deterministic decision for a normalized action: allow | deny | step_up.
const decision = evaluatePolicy(demoAction);
console.log(decision.decision, decision.reasons);

// Human-readable explanation for agents and reviewers.
console.log(explainPolicyDecision(decision).summary);

Multi-rule policies

axtary.yml may define a top-level policies: block. When rules is empty, the existing provider guardrail preset remains active for compatibility. When one or more rules are present, only the explicit rules apply and unmatched actions deny.

policies:
  defaultDecision: deny
  rules:
    - id: review-repo-writes
      match:
        tools: github.contents.write
        resources: repo:company/*
        actors:
          runtimes: [codex-*, claude-*]
      effect: step_up
      reason: repository_write_requires_review
      obligations:
        expiresInSeconds: 60
        requiredApproverRoles: [security-reviewer]
        blockedPathPrefixes: [.env, secrets/]

All matching rules are evaluated. deny outranks step_up, which outranks allow; obligations are merged toward the narrower result. Use simulatePolicy for the complete match/mismatch trace.

Design Notes

The normalized action schema from @axtary/actionpass remains the source of truth. Policy evaluation is deterministic and fail-closed for unknown protected tools.

Deterministic provenance guard

Set policy.provenance.enabled: true to require authority-stamped lineage for covered outbound/content fields. Missing or unknown lineage denies with provenance_unknown_egress. Untrusted document/tool-output lineage steps up with provenance_untrusted_egress by default, or can be configured to deny. The guard runs after the underlying native, Cedar, or Rego decision and can only preserve or restrict it—never turn a deny into an allow.

Coverage is intentionally explicit (PROVENANCE_COVERAGE) rather than generic DLP or semantic prompt-injection detection.

This package stays format-agnostic. @axtary/config loads YAML and passes the parsed policy object into this evaluator so the same deterministic decision path can be used by tests, the local proxy, and future MCP wrappers.

Standards adapters

The ACS shim lives at @axtary/policy/acs:

import {
  createAxtaryAcsManifest,
  evaluateAcsIntervention,
} from "@axtary/policy/acs";

const manifest = createAxtaryAcsManifest();
const result = evaluateAcsIntervention({
  manifest,
  interventionPoint: "pre_tool_call",
  snapshot,
});

allow maps to allow, step_up maps to escalate, and deny maps to deny. Invalid manifests or malformed snapshots return deny-style runtime_error:* reasons.

AgentCore/Cedar export helpers live at @axtary/policy/parity and are also included in axtary test-policy --parity --json. They emit Cedar-shaped Gateway requests with Axtary action and payload hashes, but do not claim live AWS AgentCore enforcement.