@absolutejs/policy 0.1.0 → 0.2.0

package/README.md

@@ -8,3 +8,11 @@ and simulation evaluates an unpersisted candidate without changing live policy.
 `createAuthzenAdapter()` speaks the OpenID AuthZEN evaluation API while custom
 adapters can target Cedar, OPA, cloud IAM, or an embedded rules engine. PostgreSQL
 enforces one active version per policy with a partial unique index.
+
+Version 0.2 adds direct support for the OpenID AuthZEN AARP and COAZ Working
+Group Drafts. AARP helpers extract requestable denials, preserve their binding,
+submit idempotent access requests, persist portable task handles, and only
+produce approval context for a fresh PDP evaluation. COAZ validates MCP
+`coaz` / `x-coaz-mapping` declarations and constructs single or aligned bulk
+SARC requests through an injected CEL evaluator. Any mapping, PDP, or decision
+failure denies tool execution.

package/dist/aarp.d.ts

@@ -0,0 +1,77 @@
+export type AuthzenEntity = Record<string, unknown>;
+export type AarpRequestableDenial = {
+    endpoint: string;
+    evaluationId?: string;
+    evaluatedAt?: string;
+    reason?: string;
+    expiresAt: string;
+    bindingToken?: string;
+    template?: string;
+    display?: Record<string, unknown>;
+    formUrl?: string;
+    requestSchemaUrl?: string;
+    requestCatalogsUrl?: string;
+};
+export type AarpAccessRequest = {
+    subject: AuthzenEntity;
+    resource?: AuthzenEntity;
+    action?: AuthzenEntity;
+    items?: Array<{
+        resource: AuthzenEntity;
+        action: AuthzenEntity;
+        requested_access?: AuthzenEntity;
+        denial?: AuthzenEntity;
+    }>;
+    context?: AuthzenEntity;
+    requested_access?: AuthzenEntity;
+    denial: {
+        evaluation_id?: string;
+        evaluated_at?: string;
+        expires_at: string;
+        reason?: string;
+        binding_token?: string;
+        template?: string;
+    };
+};
+export type AarpTaskResponse = {
+    task: {
+        id: string;
+        status: "pending" | "approved" | "denied" | "expired" | "cancelled";
+        status_endpoint: string;
+        expires_at?: string;
+        progress?: Record<string, unknown>;
+        display?: Record<string, unknown>;
+        links?: Record<string, string>;
+        items?: unknown[];
+    };
+    result?: {
+        mode: string;
+        approval?: {
+            id: string;
+            state?: string;
+            approved_until?: string;
+        };
+    };
+};
+/** Extracts a requestable denial from an AuthZEN decision. It never converts the denial into permission. */
+export declare const readAarpRequestableDenial: (decision: {
+    allowed: boolean;
+    metadata?: Record<string, unknown>;
+}, pdpMetadata: {
+    access_request_endpoint?: string;
+}, now?: number) => AarpRequestableDenial | undefined;
+export declare const createAarpAccessRequest: (denial: AarpRequestableDenial, request: Omit<AarpAccessRequest, "denial">) => AarpAccessRequest;
+export type AarpFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare const createAarpClient: ({ fetch: request, trustedOrigins, headers, maxResponseBytes, }: {
+    fetch?: AarpFetch;
+    trustedOrigins: string[];
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    maxResponseBytes?: number;
+}) => {
+    submit: (denial: AarpRequestableDenial, body: AarpAccessRequest, idempotencyKey: string) => Promise<AarpTaskResponse>;
+    status: (task: AarpTaskResponse["task"]) => Promise<AarpTaskResponse>;
+};
+/** Approval is only input to a mandatory fresh AuthZEN evaluation. */
+export declare const aarpReevaluationContext: (response: AarpTaskResponse) => {
+    approval: NonNullable<AarpTaskResponse["result"]>["approval"];
+} | undefined;

package/dist/coaz.d.ts

@@ -0,0 +1,53 @@
+export type CoazMappingEntity = Record<string, string>;
+export type CoazMapping = {
+    subject: CoazMappingEntity[];
+    resource: CoazMappingEntity[];
+    action?: CoazMappingEntity[];
+    context: CoazMappingEntity[];
+};
+export type CoazTool = {
+    name: string;
+    coaz?: boolean;
+    inputSchema: Record<string, unknown> & {
+        "x-coaz-mapping"?: CoazMapping;
+    };
+};
+export type CoazCelEvaluator = (expression: string, variables: {
+    params: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    token: Record<string, unknown>;
+}) => unknown | Promise<unknown>;
+export type AuthzenEvaluation = {
+    subject: Record<string, unknown>;
+    action: Record<string, unknown>;
+    resource: Record<string, unknown>;
+    context: Record<string, unknown>;
+};
+export type CoazRequest = {
+    endpoint: "evaluation";
+    body: AuthzenEvaluation;
+} | {
+    endpoint: "evaluations";
+    body: Partial<AuthzenEvaluation> & {
+        evaluations: Array<Partial<AuthzenEvaluation>>;
+    };
+};
+export declare const validateCoazTool: (tool: CoazTool) => CoazMapping;
+export declare const createCoazRequest: ({ tool, arguments: args, token, verifyToken, evaluate, }: {
+    tool: CoazTool;
+    arguments: Record<string, unknown>;
+    token: Record<string, unknown>;
+    /** Must verify signature, issuer, audience, and expiration before claims are mapped. */
+    verifyToken: (token: Record<string, unknown>) => boolean | Promise<boolean>;
+    evaluate: CoazCelEvaluator;
+}) => Promise<CoazRequest>;
+export declare const COAZ_ERROR_CODES: {
+    readonly mapping: -32602;
+    readonly denied: -32401;
+    readonly pdpUnavailable: -32603;
+};
+export declare const enforceCoazDecisions: (decisions: readonly {
+    decision: boolean;
+}[]) => void;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export type PolicyStatus = "draft" | "active" | "retired";
+export * from "./aarp";
+export * from "./coaz";
 export type PolicyDocument = {
     createdAt: number;
     createdBy: string;

package/dist/index.js

@@ -1,4 +1,194 @@
 // @bun
+// src/aarp.ts
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+var https = (value) => {
+  if (typeof value !== "string")
+    return;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" ? url.href : undefined;
+  } catch {
+    return;
+  }
+};
+var readAarpRequestableDenial = (decision, pdpMetadata, now = Date.now()) => {
+  if (decision.allowed)
+    return;
+  const context = object(decision.metadata);
+  const hint = object(context?.access_request);
+  if (!hint || typeof hint.expires_at !== "string" || Date.parse(hint.expires_at) <= now)
+    return;
+  const endpoint = https(hint.endpoint) ?? https(pdpMetadata.access_request_endpoint);
+  const evaluationId = typeof context?.evaluation_id === "string" ? context.evaluation_id : undefined;
+  const bindingToken = typeof hint.binding_token === "string" ? hint.binding_token : undefined;
+  if (!endpoint || !evaluationId && !bindingToken)
+    return;
+  return {
+    endpoint,
+    expiresAt: hint.expires_at,
+    ...evaluationId ? { evaluationId } : {},
+    ...bindingToken ? { bindingToken } : {},
+    ...typeof context?.evaluated_at === "string" ? { evaluatedAt: context.evaluated_at } : {},
+    ...typeof context?.reason === "string" ? { reason: context.reason } : {},
+    ...typeof hint.template === "string" ? { template: hint.template } : {},
+    ...object(hint.display) ? { display: object(hint.display) } : {},
+    ...typeof hint.form_url === "string" ? { formUrl: hint.form_url } : {},
+    ...typeof hint.request_schema_url === "string" ? { requestSchemaUrl: hint.request_schema_url } : {},
+    ...typeof hint.request_catalogs_url === "string" ? { requestCatalogsUrl: hint.request_catalogs_url } : {}
+  };
+};
+var createAarpAccessRequest = (denial, request) => ({
+  ...structuredClone(request),
+  denial: {
+    expires_at: denial.expiresAt,
+    ...denial.evaluationId ? { evaluation_id: denial.evaluationId } : {},
+    ...denial.evaluatedAt ? { evaluated_at: denial.evaluatedAt } : {},
+    ...denial.reason ? { reason: denial.reason } : {},
+    ...denial.bindingToken ? { binding_token: denial.bindingToken } : {},
+    ...denial.template ? { template: denial.template } : {}
+  }
+});
+var createAarpClient = ({
+  fetch: request = fetch,
+  trustedOrigins,
+  headers,
+  maxResponseBytes = 65536
+}) => {
+  const call = async (urlValue, init) => {
+    const url = new URL(urlValue);
+    if (url.protocol !== "https:" || !trustedOrigins.includes(url.origin))
+      throw new Error("Untrusted AARP endpoint");
+    const supplied = typeof headers === "function" ? await headers() : headers;
+    const response = await request(url, {
+      ...init,
+      redirect: "manual",
+      headers: {
+        accept: "application/json",
+        ...Object.fromEntries(new Headers(supplied)),
+        ...Object.fromEntries(new Headers(init.headers))
+      }
+    });
+    if (response.status >= 300 && response.status < 400)
+      throw new Error("AARP redirects are denied");
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > maxResponseBytes)
+      throw new Error("AARP response is too large");
+    if (!response.ok)
+      throw new Error(`AARP service failed: ${response.status}`);
+    const body = JSON.parse(new TextDecoder().decode(bytes));
+    if (!body.task || typeof body.task.id !== "string" || !https(body.task.status_endpoint))
+      throw new Error("Invalid AARP task response");
+    return body;
+  };
+  return {
+    submit: (denial, body, idempotencyKey) => call(denial.endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey
+      },
+      body: JSON.stringify(body)
+    }),
+    status: (task) => call(task.status_endpoint, { method: "GET" })
+  };
+};
+var aarpReevaluationContext = (response) => response.task.status === "approved" && response.result?.mode === "reevaluate" && response.result.approval ? { approval: structuredClone(response.result.approval) } : undefined;
+// src/coaz.ts
+var validateCoazTool = (tool) => {
+  if (tool.coaz !== true)
+    throw new Error("Tool is not declared COAZ compatible");
+  const mapping = tool.inputSchema["x-coaz-mapping"];
+  if (!mapping || !Array.isArray(mapping.subject) || !Array.isArray(mapping.resource) || !Array.isArray(mapping.context) || mapping.subject.length === 0 || mapping.resource.length === 0 || mapping.context.length === 0)
+    throw new Error("Malformed x-coaz-mapping");
+  const lengths = [
+    mapping.subject.length,
+    mapping.resource.length,
+    mapping.action?.length ?? 1,
+    mapping.context.length
+  ];
+  const maximum = Math.max(...lengths);
+  if (lengths.some((length) => length !== 1 && length !== maximum))
+    throw new Error("COAZ mapping arrays have mismatched element counts");
+  for (const entities of [
+    mapping.subject,
+    mapping.resource,
+    mapping.action ?? [],
+    mapping.context
+  ])
+    for (const entity of entities)
+      for (const expression of Object.values(entity))
+        if (typeof expression !== "string" || expression.length === 0)
+          throw new Error("COAZ mapping expressions must be non-empty strings");
+  return mapping;
+};
+var createCoazRequest = async ({
+  tool,
+  arguments: args,
+  token,
+  verifyToken,
+  evaluate
+}) => {
+  if (!await verifyToken(token))
+    throw new Error("COAZ token verification failed");
+  const mapping = validateCoazTool(tool);
+  const variables = { params: { name: tool.name, arguments: args }, token };
+  const resolveEntity = async (entity) => Object.fromEntries(await Promise.all(Object.entries(entity).map(async ([key, expression]) => [
+    key,
+    await evaluate(expression, variables)
+  ])));
+  const resolved = {
+    subject: await Promise.all(mapping.subject.map(resolveEntity)),
+    resource: await Promise.all(mapping.resource.map(resolveEntity)),
+    action: await Promise.all((mapping.action ?? [{ name: `'${tool.name.replaceAll("'", "\\'")}'` }]).map(resolveEntity)),
+    context: await Promise.all(mapping.context.map(resolveEntity))
+  };
+  const maximum = Math.max(resolved.subject.length, resolved.resource.length, resolved.action.length, resolved.context.length);
+  const at = (values, index) => structuredClone(values.length === 1 ? values[0] : values[index]);
+  if (maximum === 1)
+    return {
+      endpoint: "evaluation",
+      body: {
+        subject: at(resolved.subject, 0),
+        resource: at(resolved.resource, 0),
+        action: at(resolved.action, 0),
+        context: at(resolved.context, 0)
+      }
+    };
+  const defaults = {};
+  if (resolved.subject.length === 1)
+    defaults.subject = at(resolved.subject, 0);
+  if (resolved.resource.length === 1)
+    defaults.resource = at(resolved.resource, 0);
+  if (resolved.action.length === 1)
+    defaults.action = at(resolved.action, 0);
+  if (resolved.context.length === 1)
+    defaults.context = at(resolved.context, 0);
+  return {
+    endpoint: "evaluations",
+    body: {
+      ...defaults,
+      evaluations: Array.from({ length: maximum }, (_, index) => ({
+        ...resolved.subject.length > 1 ? { subject: at(resolved.subject, index) } : {},
+        ...resolved.resource.length > 1 ? { resource: at(resolved.resource, index) } : {},
+        ...resolved.action.length > 1 ? { action: at(resolved.action, index) } : {},
+        ...resolved.context.length > 1 ? { context: at(resolved.context, index) } : {}
+      }))
+    }
+  };
+};
+var COAZ_ERROR_CODES = {
+  mapping: -32602,
+  denied: -32401,
+  pdpUnavailable: -32603
+};
+var enforceCoazDecisions = (decisions) => {
+  if (decisions.length === 0 || decisions.some((decision) => decision.decision !== true)) {
+    const error = new Error("AuthZEN denied the MCP tool invocation");
+    error.code = COAZ_ERROR_CODES.denied;
+    throw error;
+  }
+};
+
 // src/index.ts
 var canonical = (value) => {
   if (value === null || typeof value !== "object")
@@ -171,9 +361,17 @@ var createPostgresPolicyStore = ({
   };
 };
 export {
+  validateCoazTool,
+  readAarpRequestableDenial,
   policyPostgresSchemaSql,
+  enforceCoazDecisions,
   createPostgresPolicyStore,
   createPolicyEngine,
   createMemoryPolicyStore,
-  createAuthzenAdapter
+  createCoazRequest,
+  createAuthzenAdapter,
+  createAarpClient,
+  createAarpAccessRequest,
+  aarpReevaluationContext,
+  COAZ_ERROR_CODES
 };