@agentpolicyspecification/core 0.1.0

package/src/engine/aps-engine.ts

@@ -0,0 +1,206 @@
+import { readFile } from "node:fs/promises";
+import type { InputPolicy, OutputPolicy, ToolCallPolicy } from "../core/policy.js";
+import type { InputContext } from "../generated/input-context.js";
+import type { OutputContext } from "../generated/output-context.js";
+import type { ToolCallContext } from "../generated/tool-call-context.js";
+import type { PolicyDecision } from "../generated/policy-decision.js";
+import type { PolicySet as JsonPolicySet, PolicyEntry } from "../generated/policy-set.js";
+import { AuditRecord, InterceptionPoint, PolicyDenialError, PolicyEvaluationError } from "../core/errors.js";
+import type { PolicySet } from "./policy-set.js";
+
+export type AuditHandler = (record: AuditRecord) => void | Promise<void>;
+
+export interface ApsEngineOptions {
+  policySet: PolicySet;
+  onAudit?: AuditHandler;
+}
+
+export class ApsEngine {
+  private readonly policySet: PolicySet;
+  private readonly onAudit: AuditHandler | undefined;
+
+  constructor({ policySet, onAudit }: ApsEngineOptions) {
+    this.policySet = policySet;
+    this.onAudit = onAudit;
+  }
+
+  static async fromJson(absolutePath: string, options?: Pick<ApsEngineOptions, "onAudit">): Promise<ApsEngine> {
+    const raw = await readFile(absolutePath, "utf-8");
+    const jsonPolicySet = JSON.parse(raw) as JsonPolicySet;
+
+    const input: InputPolicy[] = [];
+    const tool_call: ToolCallPolicy[] = [];
+    const output: OutputPolicy[] = [];
+
+    for (const [index, entry] of jsonPolicySet.policies.entries()) {
+      const id = `policy-${index}`;
+      const appliesTo = entry.applies_to as string[] | undefined;
+      const appliesToAll = !appliesTo || appliesTo.length === 0;
+
+      if (appliesToAll || appliesTo.includes("input")) {
+        input.push({ id, evaluate: (ctx) => evaluateEntry(entry, ctx) });
+      }
+
+      if (appliesToAll || appliesTo.includes("tool_call")) {
+        tool_call.push({
+          id,
+          evaluate: (ctx) => {
+            const tools = entry.tools as string[] | undefined;
+            if (tools && tools.length > 0 && !tools.includes(ctx.tool_name)) {
+              return Promise.resolve<PolicyDecision>({ decision: "allow" });
+            }
+            return evaluateEntry(entry, ctx);
+          },
+        });
+      }
+
+      if (appliesToAll || appliesTo.includes("output")) {
+        output.push({ id, evaluate: (ctx) => evaluateEntry(entry, ctx) });
+      }
+    }
+
+    return new ApsEngine({ policySet: { input, tool_call, output }, ...options });
+  }
+
+  async evaluateInput(context: InputContext): Promise<void> {
+    await this.runPolicies(this.policySet.input ?? [], context, "input");
+  }
+
+  async evaluateToolCall(context: ToolCallContext): Promise<void> {
+    await this.runPolicies(this.policySet.tool_call ?? [], context, "tool_call");
+  }
+
+  async evaluateOutput(context: OutputContext): Promise<void> {
+    await this.runPolicies(this.policySet.output ?? [], context, "output");
+  }
+
+  private async runPolicies(policies: InputPolicy[], context: InputContext, interceptionPoint: "input"): Promise<void>;
+  private async runPolicies(policies: ToolCallPolicy[], context: ToolCallContext, interceptionPoint: "tool_call"): Promise<void>;
+  private async runPolicies(policies: OutputPolicy[], context: OutputContext, interceptionPoint: "output"): Promise<void>;
+  private async runPolicies(
+    policies: (InputPolicy | ToolCallPolicy | OutputPolicy)[],
+    context: InputContext | ToolCallContext | OutputContext,
+    interceptionPoint: InterceptionPoint
+  ): Promise<void> {
+    for (const policy of policies) {
+      let decision: PolicyDecision;
+
+      try {
+        decision = await (policy as { evaluate(ctx: typeof context): Promise<PolicyDecision> | PolicyDecision }).evaluate(context);
+      } catch (err) {
+        console.error('err: ', err);
+        if (err instanceof PolicyEvaluationError) {
+          await this.audit({
+            policy_id: policy.id,
+            decision: "evaluation_error",
+            interception_point: interceptionPoint,
+            reason: String(err.cause),
+            context,
+            timestamp: new Date().toISOString(),
+          });
+        }
+
+        if ((this.policySet.on_error ?? "deny") === "deny") {
+          throw err instanceof PolicyEvaluationError
+            ? err
+            : new PolicyEvaluationError({ policy_id: policy.id, interception_point: interceptionPoint, cause: err });
+        }
+
+        continue;
+      }
+
+      if (decision.decision === "audit") {
+        await this.audit({
+          policy_id: policy.id,
+          decision: "audit",
+          interception_point: interceptionPoint,
+          reason: decision.reason,
+          context,
+          timestamp: new Date().toISOString(),
+        });
+        continue;
+      }
+
+      if (decision.decision === "deny") {
+        await this.audit({
+          policy_id: policy.id,
+          decision: "deny",
+          interception_point: interceptionPoint,
+          reason: decision.reason,
+          context,
+          timestamp: new Date().toISOString(),
+        });
+
+        throw new PolicyDenialError({
+          policy_id: decision.policy_id ?? policy.id,
+          interception_point: interceptionPoint,
+          reason: decision.reason ?? "Policy denied without reason",
+        });
+      }
+
+      // allow, redact, transform — log and continue
+      // (redact/transform mutation is left to the runtime adapter layer)
+      if (decision.decision !== "allow") {
+        await this.audit({
+          policy_id: policy.id,
+          decision: decision.decision,
+          interception_point: interceptionPoint,
+          reason: undefined,
+          context,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    }
+  }
+
+  private async audit(record: AuditRecord): Promise<void> {
+    if (this.onAudit) {
+      await this.onAudit(record);
+    }
+  }
+}
+
+// ── fromJson helpers ──────────────────────────────────────────────────────────
+
+function evaluateEntry(entry: PolicyEntry, ctx: unknown): Promise<PolicyDecision> {
+  if (!evaluateCondition(entry.condition, ctx)) {
+    return Promise.resolve<PolicyDecision>({ decision: "allow" });
+  }
+  return Promise.resolve(buildDecision(entry, ctx));
+}
+
+function evaluateCondition(condition: PolicyEntry["condition"], ctx: unknown): boolean {
+  const cond = condition as unknown as Record<string, unknown>;
+  if ("always" in cond) return true;
+  const field = cond.field as string;
+  const value = resolveField(ctx, field);
+  if ("equals" in cond) return value === cond.equals;
+  if ("contains" in cond) return (cond.contains as string[]).some(v => String(value).toLowerCase().includes(v.toLowerCase()));
+  if ("not_in" in cond) return !(cond.not_in as unknown[]).includes(value);
+  if ("greater_than" in cond) return Number(value) > (cond.greater_than as number);
+  return false;
+}
+
+function resolveField(obj: unknown, fieldPath: string): unknown {
+  return fieldPath.split(".").reduce<unknown>((acc, key) => (acc as Record<string, unknown>)?.[key], obj);
+}
+
+function buildDecision(entry: PolicyEntry, ctx: unknown): PolicyDecision {
+  if (entry.action === "allow") return { decision: "allow" };
+  if (entry.action === "deny") {
+    return {
+      decision: "deny",
+      ...(entry.reason ? { reason: entry.reason } : {}),
+    };
+  }
+  return {
+    decision: "transform",
+    transformation: {
+      operations: Object.entries(entry.transformation ?? {}).map(([field, template]) => ({
+        field,
+        op: "set" as const,
+        value: template.replace(/\{\{(.+?)\}\}/g, (_: string, expr: string) => String(resolveField(ctx, expr.trim()) ?? "")) as unknown as { [k: string]: unknown },
+      })),
+    },
+  };
+}

package/src/engine/policy-set.ts

@@ -0,0 +1,10 @@
+import type { InputPolicy, OutputPolicy, ToolCallPolicy } from "../core/policy.js";
+
+export type OnErrorBehavior = "deny" | "allow";
+
+export interface PolicySet {
+  on_error?: OnErrorBehavior;
+  input?: InputPolicy[];
+  tool_call?: ToolCallPolicy[];
+  output?: OutputPolicy[];
+}

package/src/generated/base.ts

@@ -0,0 +1,9 @@
+/* eslint-disable */
+// This file is auto-generated from base.schema.json. Do not edit manually.
+
+/**
+ * Base schema for the Agent Policy Specification v0.1.0. All other APS schemas extend this schema. Defines shared types used across the specification.
+ */
+export interface ApsBase {
+  [k: string]: unknown;
+}

package/src/generated/dsl-policy.ts

@@ -0,0 +1,133 @@
+/* eslint-disable */
+// This file is auto-generated from dsl-policy.schema.json. Do not edit manually.
+
+/**
+ * A condition that is evaluated against the context
+ */
+export type Condition = EqualsCondition | ContainsCondition | NotInCondition | GreaterThanCondition | AlwaysCondition;
+
+/**
+ * A single Agent Policy Specification DSL policy rule
+ */
+export interface DSLPolicy {
+  condition: Condition;
+  /**
+   * The action to take when the condition matches
+   */
+  action: "allow" | "deny" | "redact" | "transform" | "audit";
+  /**
+   * Optional human-readable reason for the action, typically used with deny
+   */
+  reason?: string;
+  /**
+   * Redaction instructions to apply when action is 'redact'.
+   *
+   * @minItems 1
+   */
+  redactions?: [
+    {
+      /**
+       * Dot-notation path to the field being redacted (e.g. 'response.content').
+       */
+      field: string;
+      /**
+       * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+       */
+      strategy: "mask" | "remove" | "replace";
+      /**
+       * Replacement string. Required when strategy is 'mask' or 'replace'.
+       */
+      replacement?: string;
+      /**
+       * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+       */
+      pattern?: string;
+    },
+    ...{
+      /**
+       * Dot-notation path to the field being redacted (e.g. 'response.content').
+       */
+      field: string;
+      /**
+       * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+       */
+      strategy: "mask" | "remove" | "replace";
+      /**
+       * Replacement string. Required when strategy is 'mask' or 'replace'.
+       */
+      replacement?: string;
+      /**
+       * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+       */
+      pattern?: string;
+    }[]
+  ];
+  /**
+   * Field transformations to apply when action is 'transform'. Keys are dot-notation field paths, values are template strings supporting {{field.path}} interpolation.
+   */
+  transformation?: {
+    [k: string]: string;
+  };
+}
+/**
+ * Matches when the resolved field value strictly equals the operand
+ */
+export interface EqualsCondition {
+  /**
+   * Dot-notation path to the field in the context (e.g. 'tool_name', 'messages.0.content')
+   */
+  field: string;
+  /**
+   * The value to compare against using strict equality
+   */
+  equals: {
+    [k: string]: unknown;
+  };
+}
+/**
+ * Matches when the resolved field value contains any of the given substrings (case-insensitive)
+ */
+export interface ContainsCondition {
+  /**
+   * Dot-notation path to the field in the context
+   */
+  field: string;
+  /**
+   * List of substrings to search for
+   *
+   * @minItems 1
+   */
+  contains: [string, ...string[]];
+}
+/**
+ * Matches when the resolved field value is not present in the given list
+ */
+export interface NotInCondition {
+  /**
+   * Dot-notation path to the field in the context
+   */
+  field: string;
+  /**
+   * List of values the field must not be equal to
+   */
+  not_in: unknown[];
+}
+/**
+ * Matches when the resolved field value is numerically greater than the operand
+ */
+export interface GreaterThanCondition {
+  /**
+   * Dot-notation path to the field in the context
+   */
+  field: string;
+  /**
+   * The numeric threshold
+   */
+  greater_than: number;
+}
+/**
+ * Always matches, regardless of context
+ */
+export interface AlwaysCondition {
+  always: true;
+}

package/src/generated/input-context.ts

@@ -0,0 +1,51 @@
+/* eslint-disable */
+// This file is auto-generated from input-context.schema.json. Do not edit manually.
+
+/**
+ * The evaluation input provided to policies at the Input Interception point.
+ */
+export type InputContext = ApsBase & {
+  /**
+   * The ordered message history to be forwarded to the LLM runtime.
+   */
+  messages: Message[];
+  metadata: Metadata;
+};
+
+/**
+ * Base schema for the Agent Policy Specification v0.1.0. All other APS schemas extend this schema. Defines shared types used across the specification.
+ */
+export interface ApsBase {
+  [k: string]: unknown;
+}
+/**
+ * A single message in a conversation.
+ */
+export interface Message {
+  /**
+   * The role of the message author.
+   */
+  role: "system" | "user" | "assistant";
+  /**
+   * The text content of the message.
+   */
+  content: string;
+}
+/**
+ * Common metadata attached to every APS context object.
+ */
+export interface Metadata {
+  /**
+   * Unique identifier for the agent that owns this session.
+   */
+  agent_id: string;
+  /**
+   * Unique identifier for the current session.
+   */
+  session_id: string;
+  /**
+   * ISO 8601 timestamp of when the interception occurred.
+   */
+  timestamp: string;
+  [k: string]: unknown;
+}

package/src/generated/output-context.ts

@@ -0,0 +1,45 @@
+/* eslint-disable */
+// This file is auto-generated from output-context.schema.json. Do not edit manually.
+
+/**
+ * The evaluation input provided to policies at the Output Interception point.
+ */
+export type OutputContext = ApsBase & {
+  response: AssistantMessage;
+  metadata: Metadata;
+};
+
+/**
+ * Base schema for the Agent Policy Specification v0.1.0. All other APS schemas extend this schema. Defines shared types used across the specification.
+ */
+export interface ApsBase {
+  [k: string]: unknown;
+}
+/**
+ * A message produced by the LLM (role must be 'assistant').
+ */
+export interface AssistantMessage {
+  role: "assistant";
+  /**
+   * The text content of the assistant message.
+   */
+  content: string;
+}
+/**
+ * Common metadata attached to every APS context object.
+ */
+export interface Metadata {
+  /**
+   * Unique identifier for the agent that owns this session.
+   */
+  agent_id: string;
+  /**
+   * Unique identifier for the current session.
+   */
+  session_id: string;
+  /**
+   * ISO 8601 timestamp of when the interception occurred.
+   */
+  timestamp: string;
+  [k: string]: unknown;
+}

package/src/generated/policy-decision.ts

@@ -0,0 +1,98 @@
+/* eslint-disable */
+// This file is auto-generated from policy-decision.schema.json. Do not edit manually.
+
+/**
+ * The result produced by a policy evaluation at any interception point.
+ */
+export type PolicyDecision = AllowDecision | DenyDecision | RedactDecision | TransformDecision | AuditDecision;
+
+export interface AllowDecision {
+  decision: "allow";
+  /**
+   * When true, an audit record is also produced for this interaction.
+   */
+  audit?: boolean;
+}
+export interface DenyDecision {
+  decision: "deny";
+  /**
+   * Human-readable explanation for the denial. MAY be omitted for security-sensitive denials.
+   */
+  reason?: string;
+  /**
+   * Identifier of the policy that produced this denial.
+   */
+  policy_id?: string;
+  /**
+   * When true, an audit record is also produced for this interaction.
+   */
+  audit?: boolean;
+}
+export interface RedactDecision {
+  decision: "redact";
+  /**
+   * @minItems 1
+   */
+  redactions: [Redaction, ...Redaction[]];
+  /**
+   * When true, an audit record is also produced for this interaction.
+   */
+  audit?: boolean;
+}
+export interface Redaction {
+  /**
+   * Dot-notation path to the field being redacted (e.g. 'response.content').
+   */
+  field: string;
+  /**
+   * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+   */
+  strategy: "mask" | "remove" | "replace";
+  /**
+   * Replacement string. Required when strategy is 'mask' or 'replace'.
+   */
+  replacement?: string;
+  /**
+   * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+   */
+  pattern?: string;
+}
+export interface TransformDecision {
+  decision: "transform";
+  transformation: Transformation;
+  /**
+   * When true, an audit record is also produced for this interaction.
+   */
+  audit?: boolean;
+}
+export interface Transformation {
+  /**
+   * Ordered list of transformation operations to apply.
+   */
+  operations: {
+    /**
+     * 'set' replaces the field value, 'prepend'/'append' adds content to a string field.
+     */
+    op: "set" | "prepend" | "append";
+    /**
+     * Dot-notation path to the field to transform.
+     */
+    field: string;
+    /**
+     * The value to apply. Type must match the target field.
+     */
+    value: {
+      [k: string]: unknown;
+    };
+  }[];
+}
+/**
+ * Produces only an audit record; the interaction proceeds unchanged.
+ */
+export interface AuditDecision {
+  decision: "audit";
+  /**
+   * Optional note to include in the audit record.
+   */
+  reason?: string;
+}

package/src/generated/policy-set.ts

@@ -0,0 +1,142 @@
+/* eslint-disable */
+// This file is auto-generated from policy-set.schema.json. Do not edit manually.
+
+/**
+ * A condition evaluated against the context
+ */
+export type Condition = EqualsCondition | ContainsCondition | NotInCondition | GreaterThanCondition | AlwaysCondition;
+
+/**
+ * A collection of DSL policies with interception point and tool scope bindings
+ */
+export interface PolicySet {
+  /**
+   * The APS specification version this policy set targets (e.g. '0.1.0').
+   */
+  aps_version: string;
+  /**
+   * The list of policies in this set
+   */
+  policies: PolicyEntry[];
+}
+/**
+ * A DSL policy rule with optional scope restrictions
+ */
+export interface PolicyEntry {
+  condition: Condition;
+  /**
+   * The action to take when the condition matches
+   */
+  action: "allow" | "deny" | "redact" | "transform" | "audit";
+  /**
+   * Optional human-readable reason, typically used with deny
+   */
+  reason?: string;
+  /**
+   * Redaction instructions to apply when action is 'redact'.
+   *
+   * @minItems 1
+   */
+  redactions?: [
+    {
+      /**
+       * Dot-notation path to the field being redacted (e.g. 'response.content').
+       */
+      field: string;
+      /**
+       * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+       */
+      strategy: "mask" | "remove" | "replace";
+      /**
+       * Replacement string. Required when strategy is 'mask' or 'replace'.
+       */
+      replacement?: string;
+      /**
+       * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+       */
+      pattern?: string;
+    },
+    ...{
+      /**
+       * Dot-notation path to the field being redacted (e.g. 'response.content').
+       */
+      field: string;
+      /**
+       * 'mask' replaces with a fixed string, 'remove' deletes the field, 'replace' substitutes matched patterns.
+       */
+      strategy: "mask" | "remove" | "replace";
+      /**
+       * Replacement string. Required when strategy is 'mask' or 'replace'.
+       */
+      replacement?: string;
+      /**
+       * Regex pattern identifying the content to redact. Required when strategy is 'replace'.
+       */
+      pattern?: string;
+    }[]
+  ];
+  /**
+   * Field transformations when action is 'transform'. Keys are dot-notation field paths, values are template strings supporting {{field.path}} interpolation.
+   */
+  transformation?: {
+    [k: string]: string;
+  };
+  /**
+   * Interception points this policy applies to. Omit to apply to all points.
+   *
+   * @minItems 1
+   */
+  applies_to?: ["input" | "output" | "tool_call", ...("input" | "output" | "tool_call")[]];
+  /**
+   * Tool names this policy applies to. Only evaluated when applies_to includes 'tool_call'. Omit to apply to all tools.
+   */
+  tools?: string[];
+}
+/**
+ * Matches when the resolved field value strictly equals the operand
+ */
+export interface EqualsCondition {
+  /**
+   * Dot-notation path to the field in the context (e.g. 'tool_name', 'messages.0.content')
+   */
+  field: string;
+  /**
+   * The value to compare against using strict equality
+   */
+  equals: {
+    [k: string]: unknown;
+  };
+}
+/**
+ * Matches when the resolved field value contains any of the given substrings (case-insensitive)
+ */
+export interface ContainsCondition {
+  field: string;
+  /**
+   * @minItems 1
+   */
+  contains: [string, ...string[]];
+}
+/**
+ * Matches when the resolved field value is not present in the given list
+ */
+export interface NotInCondition {
+  field: string;
+  /**
+   * List of values the field must not be equal to
+   */
+  not_in: unknown[];
+}
+/**
+ * Matches when the resolved field value is numerically greater than the operand
+ */
+export interface GreaterThanCondition {
+  field: string;
+  greater_than: number;
+}
+/**
+ * Always matches, regardless of context
+ */
+export interface AlwaysCondition {
+  always: true;
+}