@axtary/actionpass 0.0.1

package/README.md

@@ -0,0 +1,64 @@
+# @axtary/actionpass
+
+Scoped, signed ActionPass artifacts for runtime-governed AI agent actions.
+
+This is an early package reservation and v0 development build for Axtary. The API is not stable yet.
+
+## What It Does
+
+- Validates normalized agent actions at runtime.
+- Evaluates a first deterministic GitHub PR policy.
+- Produces canonical SHA-256 payload hashes.
+- Issues signed ActionPass JWT/JWS artifacts for allowed actions.
+- Verifies that a signed pass still matches the exact action payload.
+- Records ledger entries with hashable decision evidence.
+
+## Current Status
+
+Version `0.0.1` is a placeholder/pre-release package. Do not use it for production authorization.
+
+Before production use, Axtary still needs:
+
+- A built `dist/` output instead of raw TypeScript exports.
+- Stable schema versioning.
+- Revocation and key rotation.
+- Policy package extraction.
+- External security review.
+
+## Example Shape
+
+```ts
+import {
+  authorize,
+  demoAction,
+  verifyActionPass,
+} from "@axtary/actionpass";
+
+const result = await authorize({
+  action: demoAction,
+  issuer: "https://api.axtary.dev",
+  tenant: "org:company",
+  signingKey,
+});
+
+if (result.actionPass) {
+  const verified = await verifyActionPass({
+    token: result.actionPass.token,
+    action: demoAction,
+    verificationKey,
+    issuer: "https://api.axtary.dev",
+  });
+}
+```
+
+## 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 payload hash mismatches.
+- Verification binds agent, human owner, runtime, task, tool, resource, and payload hash.
+
+Signing currently defaults to `ES256`.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@axtary/actionpass",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Scoped, signed ActionPass artifacts for runtime-governed AI agent actions.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axtary/axtary.git",
+    "directory": "packages/actionpass"
+  },
+  "keywords": [
+    "ai-agents",
+    "authorization",
+    "runtime-security",
+    "jwt",
+    "mcp"
+  ],
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24"
+  },
+  "files": [
+    "README.md",
+    "src/index.ts"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "dependencies": {
+    "jose": "^6.2.3",
+    "zod": "^4.4.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,552 @@
+import { createHash, randomUUID } from "node:crypto";
+import { SignJWT, jwtVerify, type JWK, type KeyObject } from "jose";
+import { z } from "zod";
+
+export const ACTION_SCHEMA_VERSION = "axtary.action.v0";
+export const ACTIONPASS_VERSION = "axtary.actionpass.v0";
+export const LEDGER_SCHEMA_VERSION = "axtary.ledger.v0";
+export const DEFAULT_EXPIRES_IN_SECONDS = 600;
+export const DEFAULT_SIGNING_ALGORITHM = "ES256";
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+const JsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+  ])
+);
+
+export const AxtaryDecisionSchema = z.enum(["allow", "deny", "step_up"]);
+export type AxtaryDecision = z.infer<typeof AxtaryDecisionSchema>;
+
+export const NormalizedActionSchema = z.object({
+  schemaVersion: z.literal(ACTION_SCHEMA_VERSION).default(ACTION_SCHEMA_VERSION),
+  actor: z.object({
+    agentId: z.string().min(1),
+    humanOwner: z.string().min(1),
+    runtime: z.string().min(1),
+    tenant: z.string().min(1).optional(),
+  }),
+  intent: z.object({
+    taskId: z.string().min(1),
+    declaredGoal: z.string().min(1),
+    maxDelegationDepth: z.number().int().nonnegative().optional(),
+  }),
+  capability: z.object({
+    tool: z.string().min(1),
+    resource: z.string().min(1),
+    payload: z.record(z.string(), JsonValueSchema),
+    constraints: z.record(z.string(), JsonValueSchema).optional(),
+  }),
+  toolDefinition: z
+    .object({
+      serverIdentity: z.string().min(1),
+      schemaVersion: z.string().min(1),
+      definitionHash: z.string().min(1),
+    })
+    .optional(),
+  budget: z
+    .object({
+      reservationId: z.string().min(1).optional(),
+      limit: z.record(z.string(), JsonValueSchema).optional(),
+      commitStatus: z.enum(["pending", "committed", "rolled_back"]).optional(),
+    })
+    .optional(),
+});
+export type NormalizedAction = z.infer<typeof NormalizedActionSchema>;
+
+export const PolicyDecisionSchema = z.object({
+  decision: AxtaryDecisionSchema,
+  reasons: z.array(z.string().min(1)),
+  policy: z.object({
+    nativeRule: z.string().min(1),
+    version: z.string().min(1),
+    cedarCompatible: z.boolean(),
+    opaCompatible: z.boolean(),
+  }),
+  constraints: z.object({
+    expiresInSeconds: z.number().int().positive(),
+    maxFilesChanged: z.number().int().nonnegative(),
+    blockedPaths: z.array(z.string().min(1)),
+  }),
+});
+export type PolicyDecision = z.infer<typeof PolicyDecisionSchema>;
+export type ActionPassDecision = PolicyDecision;
+
+export const ApprovalSchema = z.object({
+  mode: z.enum(["none", "human", "policy_override"]),
+  approvedBy: z.string().min(1).optional(),
+  approvalArtifact: z.string().min(1).optional(),
+  approvedAt: z.string().datetime().optional(),
+});
+export type Approval = z.infer<typeof ApprovalSchema>;
+
+export const ActionPassClaimsSchema = z.object({
+  apv: z.literal(ACTIONPASS_VERSION),
+  iss: z.string().min(1),
+  sub: z.string().min(1),
+  aud: z.union([z.string().min(1), z.array(z.string().min(1))]),
+  exp: z.number().int().positive(),
+  nbf: z.number().int().positive(),
+  iat: z.number().int().positive(),
+  jti: z.string().min(1),
+  tenant: z.string().min(1),
+  humanOwner: z.string().min(1),
+  agentRuntime: z.string().min(1),
+  intent: NormalizedActionSchema.shape.intent,
+  capability: z.object({
+    tool: z.string().min(1),
+    resource: z.string().min(1),
+    constraints: z.record(z.string(), JsonValueSchema).optional(),
+  }),
+  decision: AxtaryDecisionSchema,
+  reasons: z.array(z.string().min(1)),
+  policy: PolicyDecisionSchema.shape.policy,
+  payloadHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  approval: ApprovalSchema.optional(),
+  audit: z.object({
+    traceId: z.string().min(1),
+    parentPassId: z.string().min(1).nullable(),
+    ledgerHash: z.string().min(1).nullable(),
+  }),
+});
+export type ActionPassClaims = z.infer<typeof ActionPassClaimsSchema>;
+
+export const LedgerRecordSchema = z.object({
+  schemaVersion: z.literal(LEDGER_SCHEMA_VERSION),
+  id: z.string().min(1),
+  occurredAt: z.string().datetime(),
+  actionHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  payloadHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  decision: AxtaryDecisionSchema,
+  reasons: z.array(z.string().min(1)),
+  policy: PolicyDecisionSchema.shape.policy,
+  actionPassId: z.string().min(1).nullable(),
+  previousLedgerHash: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(),
+  ledgerHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+});
+export type LedgerRecord = z.infer<typeof LedgerRecordSchema>;
+
+export type SigningKey = CryptoKey | KeyObject | JWK | Uint8Array;
+export type VerificationKey = CryptoKey | KeyObject | JWK | Uint8Array;
+export type SigningAlgorithm = "ES256" | "EdDSA";
+
+export type PolicyOptions = {
+  allowedTool?: string;
+  requiredBaseBranch?: string;
+  maxFilesChanged?: number;
+  blockedPathPrefixes?: string[];
+  policyVersion?: string;
+};
+
+export type IssueActionPassInput = {
+  action: unknown;
+  decision: PolicyDecision;
+  issuer: string;
+  tenant: string;
+  signingKey: SigningKey;
+  keyId?: string;
+  algorithm?: SigningAlgorithm;
+  now?: Date;
+  expiresInSeconds?: number;
+  approval?: Approval;
+  parentPassId?: string | null;
+  ledgerHash?: string | null;
+  traceId?: string;
+};
+
+export type IssueActionPassResult = {
+  token: string;
+  claims: ActionPassClaims;
+};
+
+export type AuthorizeInput = {
+  action: unknown;
+  issuer: string;
+  tenant: string;
+  signingKey: SigningKey;
+  keyId?: string;
+  algorithm?: SigningAlgorithm;
+  now?: Date;
+  policy?: PolicyOptions;
+  previousLedgerHash?: string | null;
+};
+
+export type AuthorizeResult = {
+  action: NormalizedAction;
+  decision: PolicyDecision;
+  payloadHash: string;
+  actionPass: IssueActionPassResult | null;
+  ledger: LedgerRecord;
+};
+
+export type VerifyActionPassInput = {
+  token: string;
+  action: unknown;
+  verificationKey: VerificationKey;
+  issuer?: string;
+  audience?: string | string[];
+  algorithms?: SigningAlgorithm[];
+  clockTolerance?: string | number;
+};
+
+export type VerifyActionPassResult =
+  | {
+      valid: true;
+      claims: ActionPassClaims;
+      payloadHash: string;
+    }
+  | {
+      valid: false;
+      reason: string;
+    };
+
+export const demoAction: NormalizedAction = NormalizedActionSchema.parse({
+  actor: {
+    agentId: "agent:codex-prod",
+    humanOwner: "user:asrar@company.com",
+    runtime: "codex-cli",
+    tenant: "org:company",
+  },
+  intent: {
+    taskId: "AXT-418",
+    declaredGoal: "Open a PR that fixes the auth redirect bug",
+  },
+  capability: {
+    tool: "github.pull_requests.create",
+    resource: "repo:company/web-app",
+    payload: {
+      baseBranch: "main",
+      filesChanged: ["src/app/login/page.tsx", "src/lib/auth/session.ts"],
+      touchesProduction: false,
+    },
+  },
+});
+
+export function parseNormalizedAction(action: unknown): NormalizedAction {
+  return NormalizedActionSchema.parse(action);
+}
+
+export function evaluateAction(
+  actionInput: unknown,
+  options: PolicyOptions = {}
+): PolicyDecision {
+  const action = parseNormalizedAction(actionInput);
+  const payload = action.capability.payload;
+  const filesChanged = getStringArray(payload.filesChanged);
+  const requiredBaseBranch = options.requiredBaseBranch ?? "main";
+  const maxFilesChanged = options.maxFilesChanged ?? 12;
+  const blockedPathPrefixes = options.blockedPathPrefixes ?? [
+    "infra/prod/",
+    "billing/",
+    ".env",
+  ];
+  const policy = {
+    nativeRule: "github_pr_coding_agent_v0",
+    version: options.policyVersion ?? "2026-05-30",
+    cedarCompatible: true,
+    opaCompatible: true,
+  };
+  const constraints = {
+    expiresInSeconds: DEFAULT_EXPIRES_IN_SECONDS,
+    maxFilesChanged,
+    blockedPaths: ["infra/prod/**", "billing/**", ".env*"],
+  };
+  const stepUpReasons: string[] = [];
+
+  if (action.capability.tool !== (options.allowedTool ?? "github.pull_requests.create")) {
+    return {
+      decision: "deny",
+      reasons: [
+        `unsupported_tool: ${action.capability.tool} is not enabled by this policy`,
+      ],
+      policy,
+      constraints,
+    };
+  }
+
+  if (payload.baseBranch !== requiredBaseBranch) {
+    stepUpReasons.push(`base_branch_mismatch: expected ${requiredBaseBranch}`);
+  }
+
+  if (filesChanged.length > maxFilesChanged) {
+    stepUpReasons.push("file_count_exceeds_policy_limit");
+  }
+
+  if (
+    filesChanged.some((path) =>
+      blockedPathPrefixes.some((prefix) => path.startsWith(prefix))
+    )
+  ) {
+    stepUpReasons.push("payload_touches_protected_path");
+  }
+
+  if (payload.touchesProduction === true) {
+    stepUpReasons.push("payload_declares_production_impact");
+  }
+
+  if (stepUpReasons.length > 0) {
+    return {
+      decision: "step_up",
+      reasons: stepUpReasons,
+      policy,
+      constraints,
+    };
+  }
+
+  return {
+    decision: "allow",
+    reasons: ["payload_is_inside_current_actionpass_constraints"],
+    policy,
+    constraints,
+  };
+}
+
+export async function authorize(input: AuthorizeInput): Promise<AuthorizeResult> {
+  const action = parseNormalizedAction(input.action);
+  const decision = evaluateAction(action, input.policy);
+  const payloadHash = hashPayload(action.capability.payload);
+  const actionPass =
+    decision.decision === "allow"
+      ? await issueActionPass({
+          action,
+          decision,
+          issuer: input.issuer,
+          tenant: input.tenant,
+          signingKey: input.signingKey,
+          keyId: input.keyId,
+          algorithm: input.algorithm,
+          now: input.now,
+        })
+      : null;
+  const ledger = recordDecision({
+    action,
+    decision,
+    actionPassId: actionPass?.claims.jti ?? null,
+    previousLedgerHash: input.previousLedgerHash ?? null,
+    occurredAt: input.now,
+  });
+
+  return {
+    action,
+    decision,
+    payloadHash,
+    actionPass,
+    ledger,
+  };
+}
+
+export async function issueActionPass(
+  input: IssueActionPassInput
+): Promise<IssueActionPassResult> {
+  const action = parseNormalizedAction(input.action);
+  const decision = PolicyDecisionSchema.parse(input.decision);
+
+  if (decision.decision !== "allow") {
+    throw new Error("ActionPass can only be issued for an allow decision.");
+  }
+
+  const now = input.now ?? new Date();
+  const issuedAt = toNumericDate(now);
+  const expiresInSeconds =
+    input.expiresInSeconds ?? decision.constraints.expiresInSeconds;
+  const expiresAt = issuedAt + expiresInSeconds;
+  const passId = `ap_${randomUUID()}`;
+  const claims: ActionPassClaims = ActionPassClaimsSchema.parse({
+    apv: ACTIONPASS_VERSION,
+    iss: input.issuer,
+    sub: action.actor.agentId,
+    aud: action.capability.resource,
+    exp: expiresAt,
+    nbf: issuedAt,
+    iat: issuedAt,
+    jti: passId,
+    tenant: input.tenant,
+    humanOwner: action.actor.humanOwner,
+    agentRuntime: action.actor.runtime,
+    intent: action.intent,
+    capability: {
+      tool: action.capability.tool,
+      resource: action.capability.resource,
+      constraints: action.capability.constraints,
+    },
+    decision: decision.decision,
+    reasons: decision.reasons,
+    policy: decision.policy,
+    payloadHash: hashPayload(action.capability.payload),
+    approval: input.approval,
+    audit: {
+      traceId: input.traceId ?? `trace_${randomUUID()}`,
+      parentPassId: input.parentPassId ?? null,
+      ledgerHash: input.ledgerHash ?? null,
+    },
+  });
+
+  const token = await new SignJWT(claims)
+    .setProtectedHeader({
+      alg: input.algorithm ?? DEFAULT_SIGNING_ALGORITHM,
+      typ: "axtary-actionpass+jwt",
+      kid: input.keyId,
+    })
+    .sign(input.signingKey);
+
+  return { token, claims };
+}
+
+export async function verifyActionPass(
+  input: VerifyActionPassInput
+): Promise<VerifyActionPassResult> {
+  try {
+    const action = parseNormalizedAction(input.action);
+    const { payload } = await jwtVerify(input.token, input.verificationKey, {
+      issuer: input.issuer,
+      audience: input.audience ?? action.capability.resource,
+      algorithms: input.algorithms ?? [DEFAULT_SIGNING_ALGORITHM],
+      clockTolerance: input.clockTolerance,
+    });
+    const claims = ActionPassClaimsSchema.parse(payload);
+    const payloadHash = hashPayload(action.capability.payload);
+    const bindingError = validatePassBinding(claims, action, payloadHash);
+
+    if (bindingError) {
+      return {
+        valid: false,
+        reason: bindingError,
+      };
+    }
+
+    return {
+      valid: true,
+      claims,
+      payloadHash,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      reason: error instanceof Error ? error.message : "verification_failed",
+    };
+  }
+}
+
+export function recordDecision(input: {
+  action: unknown;
+  decision: PolicyDecision;
+  actionPassId?: string | null;
+  previousLedgerHash?: string | null;
+  occurredAt?: Date;
+}): LedgerRecord {
+  const action = parseNormalizedAction(input.action);
+  const decision = PolicyDecisionSchema.parse(input.decision);
+  const payloadHash = hashPayload(action.capability.payload);
+  const actionHash = hashJson(action);
+  const recordWithoutHash = {
+    schemaVersion: LEDGER_SCHEMA_VERSION,
+    id: `ledger_${randomUUID()}`,
+    occurredAt: (input.occurredAt ?? new Date()).toISOString(),
+    actionHash,
+    payloadHash,
+    decision: decision.decision,
+    reasons: decision.reasons,
+    policy: decision.policy,
+    actionPassId: input.actionPassId ?? null,
+    previousLedgerHash: input.previousLedgerHash ?? null,
+  };
+
+  return LedgerRecordSchema.parse({
+    ...recordWithoutHash,
+    ledgerHash: hashJson(recordWithoutHash),
+  });
+}
+
+export function hashPayload(payload: unknown): string {
+  return hashJson(JsonValueSchema.parse(payload));
+}
+
+export function hashJson(value: unknown): string {
+  return `sha256:${createHash("sha256")
+    .update(stableStringify(value))
+    .digest("hex")}`;
+}
+
+export function stableStringify(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+function validatePassBinding(
+  claims: ActionPassClaims,
+  action: NormalizedAction,
+  payloadHash: string
+): string | null {
+  if (claims.sub !== action.actor.agentId) {
+    return "agent_id_mismatch";
+  }
+  if (claims.humanOwner !== action.actor.humanOwner) {
+    return "human_owner_mismatch";
+  }
+  if (claims.agentRuntime !== action.actor.runtime) {
+    return "agent_runtime_mismatch";
+  }
+  if (claims.intent.taskId !== action.intent.taskId) {
+    return "task_id_mismatch";
+  }
+  if (claims.capability.tool !== action.capability.tool) {
+    return "tool_mismatch";
+  }
+  if (claims.capability.resource !== action.capability.resource) {
+    return "resource_mismatch";
+  }
+  if (claims.payloadHash !== payloadHash) {
+    return "payload_hash_mismatch";
+  }
+
+  return null;
+}
+
+function getStringArray(value: JsonValue | undefined): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function toNumericDate(date: Date): number {
+  return Math.floor(date.getTime() / 1000);
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, canonicalize(entryValue)])
+    );
+  }
+
+  return value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}