@axtary/actionpass

Scoped, signed ActionPass artifacts for runtime-governed AI 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.

npm install @axtary/actionpass

What It Does

• Validates normalized agent actions at runtime.
• Produces canonical SHA-256 payload hashes.
• Produces payload-bound approval artifacts for exact human or policy override approvals.
• Issues signed ActionPass JWT/JWS artifacts for allowed actions.
• Produces revocation records and rejects revoked passes during verification.
• Verifies passes against a keyring by kid so rotated keys can coexist.
• Persists local public verification keys and revocations in a JSON trust store.
• Verifies that a signed pass and any embedded approval evidence still match the exact action payload.
• Records ledger entries with hashable decision evidence.

Current Status

0.x versions are early releases. Do not use them for production authorization yet.

Before production use, Axtary still needs:

• Stable schema versioning.
• External signing-key management.
• Hosted approval queue integration.
• External security review.

The package builds to dist/ and publishes JavaScript plus TypeScript declarations.

Quickstart

This example runs as-is with Node 20+:

import { generateKeyPair } from "jose";
import {
  authorize,
  createApprovalArtifact,
  demoAction,
  verifyActionPass,
} from "@axtary/actionpass";

const { publicKey, privateKey } = await generateKeyPair("ES256");

// Bind a human approval to the exact payload hash.
const { artifact } = createApprovalArtifact({
  action: demoAction,
  mode: "human",
  approvedBy: "user:[email protected]",
  reason: "Reviewed the exact PR payload",
});

// Evaluate policy, issue a signed ActionPass, produce a ledger record.
const result = await authorize({
  action: demoAction,
  issuer: "https://axtary.local",
  tenant: "org:example",
  signingKey: privateKey,
  approvalArtifact: artifact,
});

console.log(result.decision.decision, result.payloadHash);

// Verification fails closed on expiry, revocation, or payload mismatch.
const verified = await verifyActionPass({
  token: result.actionPass.token,
  action: demoAction,
  verificationKey: publicKey,
  issuer: "https://axtary.local",
});

console.log(verified.valid);

Security Notes

ActionPass is designed to fail closed:

• Malformed actions fail schema validation.
• Denied and step-up actions do not receive passes.
• Verification rejects expired tokens.
• Verification rejects revoked pass IDs.
• Verification rejects payload hash mismatches.
• Pass issuance rejects approval artifacts that were created for a different action or payload.
• Keyring verification fails closed when the JWT kid is unknown.
• The local trust store persists public verification JWKs only; signing keys should remain in KMS, env-managed dev secrets, or another controlled key custodian.
• Verification binds agent, human owner, runtime, task, tool, resource, and payload hash.

Signing currently defaults to ES256.