@axtary/actionpass 0.0.1 → 0.1.0

package/src/index.ts

@@ -1,552 +0,0 @@
-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
-  );
-}