kavachos 0.3.0 → 0.4.1

package/dist/index.js

@@ -2,7 +2,7 @@ import { eq, like, sql, and, lt, gte, lte, desc, asc, gt, inArray, or, notInArra
 export { and, eq, like } from 'drizzle-orm';
 import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';
 import * as jose2 from 'jose';
-import { jwtVerify, generateKeyPair, exportJWK, importJWK, SignJWT, decodeJwt, createRemoteJWKSet, errors, compactVerify } from 'jose';
+import { jwtVerify, generateKeyPair, exportJWK, importJWK, SignJWT, decodeJwt, createRemoteJWKSet, CompactSign, errors, compactVerify } from 'jose';
 import { z } from 'zod';
 import { deflateRaw } from 'zlib';
 
@@ -319,6 +319,8 @@ var permissions = sqliteTable("kavach_permissions", {
   actions: text("actions", { mode: "json" }).notNull().$type(),
   // ["read", "write", "execute"]
   constraints: text("constraints", { mode: "json" }).$type(),
+  // When set, the policy engine consults the ReBAC graph for this permission.
+  relation: text("relation"),
   createdAt: integer("created_at", { mode: "timestamp" }).notNull()
 });
 var delegationChains = sqliteTable("kavach_delegation_chains", {
@@ -348,6 +350,8 @@ var auditLogs = sqliteTable("kavach_audit_logs", {
   tokensCost: integer("tokens_cost"),
   ip: text("ip"),
   userAgent: text("user_agent"),
+  // True when this audit row corresponds to a policy-engine cache-hit evaluation.
+  cacheHit: integer("cache_hit", { mode: "boolean" }).notNull().default(false),
   timestamp: integer("timestamp", { mode: "timestamp" }).notNull()
 });
 var rateLimits = sqliteTable("kavach_rate_limits", {
@@ -4844,6 +4848,77 @@ var HibpApiError = class extends Error {
     this.name = "HibpApiError";
   }
 };
+
+// src/standards/claims.ts
+var AGENTIC_JWT_CLAIMS = {
+  /**
+   * Stable identifier of the agent making the call.
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.1
+   */
+  AGENT_ID: "agent_id",
+  /**
+   * Operational mode of the agent: `autonomous`, `delegated`, or `supervised`.
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.2
+   */
+  AGENT_TYPE: "agent_type",
+  /**
+   * Subject principal the agent is acting on behalf of (human user or upstream agent).
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.3
+   */
+  ON_BEHALF_OF: "on_behalf_of",
+  /**
+   * Actor claim per RFC 8693. Identifies the current actor in an
+   * impersonation or delegation chain.
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.4
+   * @see RFC 8693
+   */
+  ACT: "act",
+  /**
+   * Authorized future actors for delegation chains (RFC 8693 `may_act`).
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.5
+   * @see RFC 8693
+   */
+  MAY_ACT: "may_act",
+  /**
+   * Trust score band at token issuance (e.g. `standard`, `elevated`).
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.6
+   */
+  TRUST_TIER: "trust_tier",
+  /**
+   * Correlation id for tracing this token back to an entry in the audit log.
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.7
+   */
+  AUDIT_REF: "audit_ref",
+  /**
+   * Per-tool budget or rate constraints encoded as a structured object.
+   *
+   * @see draft-goswami-agentic-jwt-00 §3.8
+   */
+  TOOL_CONSTRAINTS: "tool_constraints",
+  /**
+   * Workload Identity Token (WIT). Present only when three-layer cryptographic
+   * binding is active (draft-liu §4.2). Absent in standard issuance paths.
+   *
+   * @see draft-liu-agent-operation-authorization-01 §4.2
+   * TODO(v3): populate from WIT issuance when three-layer binding is implemented.
+   */
+  WORKLOAD_BINDING: "wit",
+  /**
+   * The scoped operation this token authorizes (e.g. `read:documents`).
+   *
+   * @see draft-liu-agent-operation-authorization-01 §4.3
+   */
+  OPERATION: "operation"
+};
+
+// src/auth/jwt-session.ts
 var configSchema = z.object({
   secret: z.union([z.string().min(1), z.instanceof(Object)]),
   algorithm: z.string().optional(),
@@ -4924,6 +4999,18 @@ function createJwtSessionModule(config, db) {
         });
         Object.assign(claimsFromUser, extra);
       }
+      if (config.emitAgenticJwtClaims === true && user.agenticContext !== void 0) {
+        const ac = user.agenticContext;
+        if (ac.agentId !== void 0) {
+          claimsFromUser[AGENTIC_JWT_CLAIMS.AGENT_ID] = ac.agentId;
+        }
+        if (ac.agentType !== void 0) {
+          claimsFromUser[AGENTIC_JWT_CLAIMS.AGENT_TYPE] = ac.agentType;
+        }
+        if (ac.trustTier !== void 0) {
+          claimsFromUser[AGENTIC_JWT_CLAIMS.TRUST_TIER] = ac.trustTier;
+        }
+      }
       let builder = new SignJWT({
         sub: user.id,
         ...user.email !== void 0 ? { email: user.email } : {},
@@ -5954,7 +6041,8 @@ var AUTHORIZATION_URL2 = "https://discord.com/api/oauth2/authorize";
 var TOKEN_URL2 = "https://discord.com/api/oauth2/token";
 var USER_INFO_URL = "https://discord.com/api/users/@me";
 var CDN_BASE = "https://cdn.discordapp.com";
-var DEFAULT_SCOPES2 = ["identify", "email"];
+var DEFAULT_DISCORD_SCOPES = ["identify", "email"];
+var DEFAULT_SCOPES2 = DEFAULT_DISCORD_SCOPES;
 function createDiscordProvider(config) {
   const scopes = mergeScopes2(DEFAULT_SCOPES2, config.scopes);
   async function getAuthorizationUrl(state, codeVerifier, redirectUri) {
@@ -6555,7 +6643,8 @@ function mergeScopes7(defaults, extras) {
 var AUTHORIZATION_URL8 = "https://slack.com/oauth/v2/authorize";
 var TOKEN_URL8 = "https://slack.com/api/oauth.v2.access";
 var USER_INFO_URL6 = "https://slack.com/api/openid.connect.userInfo";
-var DEFAULT_SCOPES8 = ["openid", "profile", "email"];
+var DEFAULT_SLACK_SCOPES = ["openid", "profile", "email"];
+var DEFAULT_SCOPES8 = DEFAULT_SLACK_SCOPES;
 function createSlackProvider(config) {
   const scopes = mergeScopes8(DEFAULT_SCOPES8, config.scopes);
   async function getAuthorizationUrl(state, codeVerifier, redirectUri) {
@@ -15584,6 +15673,7 @@ function buildStatements(provider) {
   resource    TEXT  NOT NULL,
   actions     ${json2} NOT NULL,
   constraints ${json2},
+  relation    TEXT,
   created_at  ${ts} NOT NULL
 )`
     },
@@ -15622,6 +15712,7 @@ function buildStatements(provider) {
   tokens_cost  INTEGER,
   ip           TEXT,
   user_agent   TEXT,
+  cache_hit    ${bool} NOT NULL DEFAULT ${isPostgres ? "FALSE" : "0"},
   timestamp    ${ts}   NOT NULL
 )`
     },
@@ -17480,6 +17571,9 @@ function validateArgPatterns(patterns, args) {
   return { valid: true };
 }
 async function checkRateLimit(db, agentId, resource, maxCallsPerHour) {
+  if (!agentId) {
+    return { allowed: true };
+  }
   const oneHourAgo = new Date(Date.now() - 60 * 60 * 1e3);
   const rows = await db.select().from(rateLimits).where(
     and(
@@ -17510,66 +17604,20 @@ async function checkRateLimit(db, agentId, resource, maxCallsPerHour) {
   }
   return { allowed: true };
 }
-function createPermissionEngine(config) {
-  const { db, auditAll } = config;
-  async function authorize(agent, request) {
-    const startTime = performance.now();
-    const auditId = generateId();
-    const matchingPermission = agent.permissions.find(
-      (p2) => matchResource(p2.resource, request.resource) && matchAction(p2.actions, request.action)
-    );
-    if (!matchingPermission) {
-      const result2 = {
-        allowed: false,
-        reason: `No permission grants agent "${agent.name}" access to "${request.action}" on "${request.resource}"`,
-        auditId
-      };
-      if (auditAll) {
-        await writeAuditLog(db, agent, request, result2, startTime, auditId);
-      }
-      return result2;
-    }
-    if (matchingPermission.constraints) {
-      const constraintResult = await evaluateConstraints(
-        db,
-        agent,
-        request,
-        matchingPermission.constraints
-      );
-      if (!constraintResult.allowed) {
-        const result2 = {
-          allowed: false,
-          reason: constraintResult.reason,
-          auditId
-        };
-        if (auditAll) {
-          await writeAuditLog(db, agent, request, result2, startTime, auditId);
-        }
-        return result2;
-      }
-    }
-    const result = { allowed: true, auditId };
-    if (auditAll) {
-      await writeAuditLog(db, agent, request, result, startTime, auditId);
-    }
-    return result;
-  }
-  return { authorize };
-}
-async function evaluateConstraints(db, agent, request, constraints) {
+async function evaluateConstraints(db, input, constraints) {
   if (constraints.maxCallsPerHour) {
     const rateResult = await checkRateLimit(
       db,
-      agent.id,
-      request.resource,
+      input.subjectId,
+      input.resource,
       constraints.maxCallsPerHour
     );
     if (!rateResult.allowed) {
       return rateResult;
     }
   }
-  if (constraints.allowedArgPatterns && request.arguments) {
-    const patternResult = validateArgPatterns(constraints.allowedArgPatterns, request.arguments);
+  if (constraints.allowedArgPatterns && input.arguments) {
+    const patternResult = validateArgPatterns(constraints.allowedArgPatterns, input.arguments);
     if (!patternResult.valid) {
       return { allowed: false, reason: patternResult.reason };
     }
@@ -17593,21 +17641,77 @@ async function evaluateConstraints(db, agent, request, constraints) {
     }
   }
   if (constraints.ipAllowlist && constraints.ipAllowlist.length > 0) {
-    if (!request.ip) {
+    if (!input.ip) {
       return {
         allowed: false,
         reason: "IP_NOT_ALLOWED: No IP address provided; resource requires an IP allowlist match"
       };
     }
-    if (!isIPAllowed(constraints.ipAllowlist, request.ip)) {
+    if (!isIPAllowed(constraints.ipAllowlist, input.ip)) {
       return {
         allowed: false,
-        reason: `IP_NOT_ALLOWED: IP "${request.ip}" is not in the allowlist for this resource`
+        reason: `IP_NOT_ALLOWED: IP "${input.ip}" is not in the allowlist for this resource`
       };
     }
   }
   return { allowed: true };
 }
+function isCacheUnsafe(constraints) {
+  if (!constraints) return false;
+  return Boolean(constraints.maxCallsPerHour) || Boolean(constraints.timeWindow) || Array.isArray(constraints.allowedArgPatterns) && constraints.allowedArgPatterns.length > 0;
+}
+
+// src/permission/engine.ts
+function createPermissionEngine(config) {
+  const { db, auditAll } = config;
+  async function authorize(agent, request) {
+    const startTime = performance.now();
+    const auditId = generateId();
+    const matchingPermission = agent.permissions.find(
+      (p2) => matchResource(p2.resource, request.resource) && matchAction(p2.actions, request.action)
+    );
+    if (!matchingPermission) {
+      const result2 = {
+        allowed: false,
+        reason: `No permission grants agent "${agent.name}" access to "${request.action}" on "${request.resource}"`,
+        auditId
+      };
+      if (auditAll) {
+        await writeAuditLog(db, agent, request, result2, startTime, auditId);
+      }
+      return result2;
+    }
+    if (matchingPermission.constraints) {
+      const constraintResult = await evaluateConstraints(
+        db,
+        {
+          subjectId: agent.id,
+          resource: request.resource,
+          arguments: request.arguments,
+          ip: request.ip
+        },
+        matchingPermission.constraints
+      );
+      if (!constraintResult.allowed) {
+        const result2 = {
+          allowed: false,
+          reason: constraintResult.reason,
+          auditId
+        };
+        if (auditAll) {
+          await writeAuditLog(db, agent, request, result2, startTime, auditId);
+        }
+        return result2;
+      }
+    }
+    const result = { allowed: true, auditId };
+    if (auditAll) {
+      await writeAuditLog(db, agent, request, result, startTime, auditId);
+    }
+    return result;
+  }
+  return { authorize };
+}
 async function writeAuditLog(db, agent, request, result, startTime, auditId) {
   const durationMs = Math.round(performance.now() - startTime);
   await db.insert(auditLogs).values({
@@ -17990,6 +18094,509 @@ function createPolicyModule(db) {
   return { create, get, list, update, remove, checkBudget, recordUsage, resetDaily, resetMonthly };
 }
 
+// src/policy/cache.ts
+function readEnvNumber(name) {
+  if (typeof process === "undefined") return void 0;
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return void 0;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : void 0;
+}
+function readEnvBool(name) {
+  if (typeof process === "undefined") return void 0;
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return void 0;
+  return raw.toLowerCase() !== "false" && raw !== "0";
+}
+var DEFAULT_MAX_ENTRIES = 1e4;
+var DEFAULT_TTL_MS = 6e4;
+function createPolicyCache(config) {
+  const rawMax = config.maxEntries ?? readEnvNumber("KAVACH_POLICY_CACHE_MAX") ?? DEFAULT_MAX_ENTRIES;
+  const maxEntries = rawMax > 0 ? rawMax : DEFAULT_MAX_ENTRIES;
+  const ttlMs = config.ttlMs ?? readEnvNumber("KAVACH_POLICY_CACHE_TTL_MS") ?? DEFAULT_TTL_MS;
+  const enabled = config.enabled ?? readEnvBool("KAVACH_POLICY_CACHE") ?? true;
+  const store = /* @__PURE__ */ new Map();
+  let hits = 0;
+  let misses = 0;
+  let evictions = 0;
+  function evictOldest() {
+    const firstKey = store.keys().next().value;
+    if (firstKey !== void 0) {
+      store.delete(firstKey);
+      evictions++;
+    }
+  }
+  function isExpired(entry) {
+    return Date.now() >= entry.expiresAt;
+  }
+  function get(key) {
+    if (!enabled) {
+      misses++;
+      return void 0;
+    }
+    const entry = store.get(key);
+    if (entry === void 0) {
+      misses++;
+      return void 0;
+    }
+    if (isExpired(entry)) {
+      store.delete(key);
+      evictions++;
+      misses++;
+      return void 0;
+    }
+    store.delete(key);
+    store.set(key, entry);
+    hits++;
+    return entry.value;
+  }
+  function set(key, value, options) {
+    if (!enabled || options?.skipCache === true) return;
+    const existing = store.get(key);
+    if (existing !== void 0) {
+      store.delete(key);
+    }
+    while (store.size >= maxEntries) {
+      evictOldest();
+    }
+    store.set(key, { value, expiresAt: Date.now() + ttlMs });
+  }
+  function del(key) {
+    return store.delete(key);
+  }
+  function clear() {
+    store.clear();
+  }
+  function invalidatePrefix(prefix) {
+    let count = 0;
+    for (const key of store.keys()) {
+      if (key.startsWith(prefix)) {
+        store.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+  function stats() {
+    return {
+      hits,
+      misses,
+      size: store.size,
+      evictions
+    };
+  }
+  return { get, set, delete: del, clear, invalidatePrefix, stats };
+}
+
+// src/policy/types.ts
+var POLICY_ERROR_CODES = {
+  INVALID_INPUT: "POLICY_INVALID_INPUT",
+  SUBJECT_NOT_FOUND: "POLICY_SUBJECT_NOT_FOUND",
+  GRAPH_QUERY_FAILED: "POLICY_GRAPH_QUERY_FAILED",
+  NO_MATCHING_PERMISSION: "POLICY_NO_MATCHING_PERMISSION",
+  CONSTRAINT_FAILED: "POLICY_CONSTRAINT_FAILED"
+};
+
+// src/policy/combiner.ts
+function combine(partials, strategy = "deny-overrides") {
+  if (partials.length === 0) {
+    return {
+      allowed: false,
+      effect: "indeterminate",
+      reason: POLICY_ERROR_CODES.NO_MATCHING_PERMISSION
+    };
+  }
+  if (strategy === "deny-overrides") {
+    const firstDeny = partials.find((p2) => p2.effect === "deny");
+    if (firstDeny !== void 0) {
+      return {
+        allowed: false,
+        effect: "deny",
+        reason: firstDeny.reason,
+        matchedPermissionId: firstDeny.matchedPermissionId,
+        matchedRelation: firstDeny.matchedRelation
+      };
+    }
+    const firstPermit = partials.find((p2) => p2.effect === "permit");
+    if (firstPermit !== void 0) {
+      return {
+        allowed: true,
+        effect: "permit",
+        reason: firstPermit.reason,
+        matchedPermissionId: firstPermit.matchedPermissionId,
+        matchedRelation: firstPermit.matchedRelation
+      };
+    }
+  }
+  if (strategy === "permit-overrides") {
+    const firstPermit = partials.find((p2) => p2.effect === "permit");
+    if (firstPermit !== void 0) {
+      return {
+        allowed: true,
+        effect: "permit",
+        reason: firstPermit.reason,
+        matchedPermissionId: firstPermit.matchedPermissionId,
+        matchedRelation: firstPermit.matchedRelation
+      };
+    }
+    const firstDeny = partials.find((p2) => p2.effect === "deny");
+    if (firstDeny !== void 0) {
+      return {
+        allowed: false,
+        effect: "deny",
+        reason: firstDeny.reason,
+        matchedPermissionId: firstDeny.matchedPermissionId,
+        matchedRelation: firstDeny.matchedRelation
+      };
+    }
+  }
+  return {
+    allowed: false,
+    effect: "indeterminate",
+    reason: POLICY_ERROR_CODES.NO_MATCHING_PERMISSION
+  };
+}
+function parsePermissionString(raw) {
+  const idx = raw.lastIndexOf(":");
+  if (idx === -1) return null;
+  const resource = raw.slice(0, idx);
+  const action = raw.slice(idx + 1);
+  if (!resource || !action) return null;
+  return { resource, action };
+}
+function toPermissions(rawStrings) {
+  const map = /* @__PURE__ */ new Map();
+  for (const raw of rawStrings) {
+    const parsed = parsePermissionString(raw);
+    if (!parsed) continue;
+    const existing = map.get(parsed.resource);
+    if (existing) {
+      existing.add(parsed.action);
+    } else {
+      map.set(parsed.resource, /* @__PURE__ */ new Set([parsed.action]));
+    }
+  }
+  return Array.from(map.entries()).map(([resource, actionsSet]) => ({
+    resource,
+    actions: Array.from(actionsSet).sort()
+  }));
+}
+function deduplicate(permissions2) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const perm of permissions2) {
+    const key = `${perm.resource}|${[...perm.actions].sort().join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(perm);
+    }
+  }
+  return result;
+}
+function createRbacResolver(deps) {
+  const { db } = deps;
+  async function resolveRolePermissions(input) {
+    const { userId, orgId } = input;
+    const baseWhere = orgId ? and(eq(orgMembers.userId, userId), eq(orgMembers.orgId, orgId)) : eq(orgMembers.userId, userId);
+    const roleRows = await db.select({ permissions: orgRoles.permissions }).from(orgMembers).innerJoin(
+      orgRoles,
+      and(eq(orgRoles.orgId, orgMembers.orgId), eq(orgRoles.name, orgMembers.role))
+    ).where(baseWhere);
+    if (roleRows.length === 0) return [];
+    const allRawPermissions = roleRows.flatMap((r) => r.permissions);
+    if (allRawPermissions.length === 0) return [];
+    return deduplicate(toPermissions(allRawPermissions));
+  }
+  return { resolveRolePermissions };
+}
+
+// src/policy/rebac-bridge.ts
+var WILDCARD_REASON = "rebac:wildcard-resource-not-supported";
+var INVALID_SUBJECT_REASON = "rebac:invalid-subject";
+var GRAPH_FAILED_REASON = "rebac:graph-query-failed";
+var MATCHED_REASON = "rebac:matched";
+var NO_TUPLE_REASON = "rebac:no-tuple";
+function parseResource(resource) {
+  if (resource.includes("*")) return null;
+  const colonIdx = resource.indexOf(":");
+  if (colonIdx === -1) return null;
+  const objectType = resource.slice(0, colonIdx);
+  const objectId = resource.slice(colonIdx + 1);
+  if (!objectType || !objectId) return null;
+  return { objectType, objectId };
+}
+function parseSubject(subject) {
+  if (subject.agentId !== void 0 && subject.userId !== void 0) {
+    return null;
+  }
+  if (subject.agentId !== void 0) {
+    return { subjectType: "agent", subjectId: subject.agentId };
+  }
+  if (subject.userId !== void 0) {
+    return { subjectType: "user", subjectId: subject.userId };
+  }
+  if (subject.orgId !== void 0) {
+    return { subjectType: "org", subjectId: subject.orgId };
+  }
+  return null;
+}
+function createRebacBridge(deps) {
+  const rebac = createReBACModule({}, deps.db);
+  async function checkRelation(input) {
+    const parsed = parseResource(input.resource);
+    if (!parsed) {
+      return { matched: false, reason: WILDCARD_REASON };
+    }
+    const subject = parseSubject(input.subject);
+    if (!subject) {
+      return { matched: false, reason: INVALID_SUBJECT_REASON };
+    }
+    const { objectType, objectId } = parsed;
+    const { subjectType, subjectId } = subject;
+    let result;
+    try {
+      result = await rebac.check({
+        subjectType,
+        subjectId,
+        permission: input.relation,
+        objectType,
+        objectId
+      });
+    } catch {
+      return { matched: false, reason: GRAPH_FAILED_REASON };
+    }
+    if (!result.success) {
+      return { matched: false, reason: GRAPH_FAILED_REASON };
+    }
+    return result.data.allowed ? { matched: true, reason: MATCHED_REASON } : { matched: false, reason: NO_TUPLE_REASON };
+  }
+  return { checkRelation };
+}
+
+// src/policy/engine.ts
+function createPolicyEngine(deps) {
+  const { db, config = {} } = deps;
+  const cache = createPolicyCache(config.cache ?? {});
+  const rbac = createRbacResolver({ db });
+  const rebac = createRebacBridge({ db });
+  const strategy = config.combineStrategy ?? "deny-overrides";
+  const auditEnabled = config.audit !== false;
+  const sampleRate = clampSampleRate(config.auditSampleRate);
+  async function evaluate(input) {
+    const start = performance.now();
+    const validation = validateInput(input);
+    if (!validation.ok) {
+      return finalize(
+        {
+          allowed: false,
+          effect: "indeterminate",
+          reason: validation.reason,
+          cacheHit: false,
+          durationMs: 0
+        },
+        start
+      );
+    }
+    const cacheKey = buildCacheKey(input);
+    const cached = cache.get(cacheKey);
+    if (cached) {
+      const auditIdForHit = willEmitAudit(input) ? generateId() : void 0;
+      const decision2 = {
+        ...cached,
+        auditId: auditIdForHit,
+        cacheHit: true,
+        durationMs: Math.round(performance.now() - start)
+      };
+      emitAudit(decision2, input, auditIdForHit).catch(noop);
+      return decision2;
+    }
+    let effective;
+    try {
+      effective = await resolveEffectivePermissions(db, rbac, input);
+    } catch {
+      return finalize(
+        {
+          allowed: false,
+          effect: "indeterminate",
+          reason: POLICY_ERROR_CODES.SUBJECT_NOT_FOUND,
+          cacheHit: false,
+          durationMs: 0
+        },
+        start
+      );
+    }
+    const partials = [];
+    let cacheUnsafeSeen = false;
+    for (const perm of effective) {
+      if (!matchResource(perm.resource, input.resource)) continue;
+      if (!matchAction(perm.actions, input.action)) continue;
+      if (perm.relation) {
+        const result = await rebac.checkRelation({
+          subject: input.subject,
+          relation: perm.relation,
+          resource: input.resource
+        });
+        if (result.reason === "rebac:graph-query-failed") {
+          return finalize(
+            {
+              allowed: false,
+              effect: "indeterminate",
+              reason: POLICY_ERROR_CODES.GRAPH_QUERY_FAILED,
+              cacheHit: false,
+              durationMs: 0
+            },
+            start
+          );
+        }
+        if (!result.matched) continue;
+      }
+      if (perm.constraints) {
+        if (isCacheUnsafe(perm.constraints)) cacheUnsafeSeen = true;
+        const constraintResult = await evaluateConstraints(
+          db,
+          {
+            subjectId: input.subject.agentId ?? "",
+            resource: input.resource,
+            arguments: input.context?.arguments,
+            ip: input.context?.ip
+          },
+          perm.constraints
+        );
+        if (!constraintResult.allowed) {
+          partials.push({
+            effect: "deny",
+            reason: constraintResult.reason ?? POLICY_ERROR_CODES.CONSTRAINT_FAILED,
+            matchedRelation: perm.relation
+          });
+          continue;
+        }
+      }
+      partials.push({
+        effect: "permit",
+        reason: "matched",
+        matchedRelation: perm.relation
+      });
+    }
+    const combined = combine(partials, strategy);
+    const auditIdForMiss = willEmitAudit(input) ? generateId() : void 0;
+    const decision = {
+      ...combined,
+      auditId: auditIdForMiss,
+      cacheHit: false,
+      durationMs: Math.round(performance.now() - start)
+    };
+    if (!cacheUnsafeSeen) {
+      cache.set(cacheKey, decision);
+    }
+    emitAudit(decision, input, auditIdForMiss).catch(noop);
+    return decision;
+  }
+  function willEmitAudit(input) {
+    if (!auditEnabled) return false;
+    if (!input.subject.agentId) return false;
+    return sampleRate >= 1 || Math.random() < sampleRate;
+  }
+  function invalidate(scope) {
+    if (scope.agentId) cache.invalidatePrefix(`${scope.agentId}|`);
+    if (scope.userId) cache.invalidatePrefix(`${scope.userId}|`);
+    if (scope.resource) cache.clear();
+  }
+  function stats() {
+    return cache.stats();
+  }
+  async function emitAudit(decision, input, auditId) {
+    if (!auditId || !input.subject.agentId) return;
+    let userId = input.subject.userId;
+    if (!userId) {
+      const ownerRows = await db.select({ ownerId: agents.ownerId }).from(agents).where(eq(agents.id, input.subject.agentId)).limit(1);
+      userId = ownerRows[0]?.ownerId;
+      if (!userId) return;
+    }
+    try {
+      await db.insert(auditLogs).values({
+        id: auditId,
+        agentId: input.subject.agentId,
+        userId,
+        action: input.action,
+        resource: input.resource,
+        parameters: input.context?.arguments ?? {},
+        result: decision.allowed ? "allowed" : "denied",
+        reason: decision.reason ?? null,
+        durationMs: decision.durationMs,
+        timestamp: /* @__PURE__ */ new Date(),
+        ip: input.context?.ip ?? null,
+        userAgent: typeof input.context?.userAgent === "string" ? input.context.userAgent : null,
+        cacheHit: decision.cacheHit
+      });
+    } catch {
+    }
+  }
+  return { evaluate, invalidate, stats };
+}
+function buildCacheKey(input) {
+  const subjectKey = input.subject.agentId ?? input.subject.userId ?? "";
+  const orgKey = input.subject.orgId ?? "__noorg__";
+  const ipKey = input.context?.ip ?? "";
+  return `${subjectKey}|${orgKey}|${input.action}|${input.resource}|${ipKey}`;
+}
+function validateInput(input) {
+  if (!input || !input.subject || !input.action || !input.resource) {
+    return { ok: false, reason: POLICY_ERROR_CODES.INVALID_INPUT };
+  }
+  if (!input.subject.agentId && !input.subject.userId) {
+    return { ok: false, reason: POLICY_ERROR_CODES.INVALID_INPUT };
+  }
+  return { ok: true };
+}
+function clampSampleRate(rate) {
+  if (typeof rate !== "number" || Number.isNaN(rate)) return 1;
+  if (rate < 0) return 0;
+  if (rate > 1) return 1;
+  return rate;
+}
+function finalize(decision, start) {
+  return {
+    ...decision,
+    durationMs: Math.round(performance.now() - start)
+  };
+}
+async function resolveEffectivePermissions(db, rbac, input) {
+  const direct = input.subject.agentId ? await fetchDirectPermissions(db, input.subject.agentId) : [];
+  const delegated = input.subject.agentId ? await fetchDelegatedPermissions(db, input.subject.agentId) : [];
+  const roles = input.subject.userId ? await rbac.resolveRolePermissions({
+    userId: input.subject.userId,
+    orgId: input.subject.orgId
+  }) : [];
+  return [...direct, ...delegated, ...roles];
+}
+async function fetchDirectPermissions(db, agentId) {
+  const rows = await db.select().from(permissions).where(eq(permissions.agentId, agentId));
+  return rows.map((r) => ({
+    resource: r.resource,
+    actions: r.actions,
+    constraints: r.constraints ?? void 0,
+    relation: r.relation ?? void 0
+  }));
+}
+async function fetchDelegatedPermissions(db, agentId) {
+  const now = /* @__PURE__ */ new Date();
+  const chains = await db.select().from(delegationChains).where(
+    and(
+      eq(delegationChains.toAgentId, agentId),
+      eq(delegationChains.status, "active"),
+      gt(delegationChains.expiresAt, now)
+    )
+  );
+  return chains.flatMap(
+    (chain) => chain.permissions.map((perm) => ({
+      resource: perm.resource,
+      actions: perm.actions
+    }))
+  );
+}
+function noop() {
+}
+
 // src/redirect/chain.ts
 var DEFAULT_COOKIE_NAME = "kavach_redirect";
 var DEFAULT_MAX_AGE = 600;
@@ -18554,6 +19161,7 @@ async function createKavach(config) {
   if (!config.database.skipMigrations) {
     await createTables(db, config.database.provider, config);
   }
+  const policyEngine = createPolicyEngine({ db, config: config.policy });
   const agentConfig = {
     db,
     maxPerUser: config.agents?.maxPerUser ?? 10,
@@ -19203,6 +19811,34 @@ async function createKavach(config) {
      * ```
      */
     redirects: redirectChain,
+    /**
+     * Unified policy engine.
+     *
+     * Single decision point that combines RBAC role expansion, ABAC constraint
+     * evaluation, and ReBAC graph queries. Backed by a process-local LRU cache
+     * with deterministic invalidation.
+     *
+     * @example
+     * ```typescript
+     * const decision = await kavach.policy.evaluate({
+     *   subject: { agentId: 'agent-abc' },
+     *   action: 'read',
+     *   resource: 'tool:github:list_issues',
+     * });
+     * if (!decision.allowed) throw new Error(decision.reason);
+     *
+     * // Flush cached decisions after a permission change
+     * kavach.policy.invalidate({ agentId: 'agent-abc' });
+     *
+     * // Inspect cache health
+     * const { hits, misses, size, evictions } = kavach.policy.stats();
+     * ```
+     */
+    policy: {
+      evaluate: policyEngine.evaluate,
+      invalidate: policyEngine.invalidate,
+      stats: policyEngine.stats
+    },
     /**
      * Plugin system.
      *
@@ -20341,7 +20977,7 @@ var CredentialSubjectSchema = z.object({
   ).optional(),
   name: z.string().optional(),
   type: z.string().optional()
-});
+}).passthrough();
 var VerifiableCredentialSchema = z.object({
   "@context": z.array(z.string()).min(1),
   id: z.string().optional(),
@@ -20362,8 +20998,156 @@ var VerifiablePresentationSchema = z.object({
   proof: ProofSchema.optional()
 });
 
-// src/vc/issuer.ts
+// src/vc/audit-export.ts
+var KAVACHOS_AUDIT_CREDENTIAL = "KavachosAuditCredential";
+var KAVACHOS_AUDIT_CONTEXT = "https://kavachos.com/contexts/audit/v1.jsonld";
+var KAVACHOS_VERSION = "0.3.0";
 var DEFAULT_TTL_SECONDS2 = 86400;
+function toDecision(result) {
+  if (result === "allowed") return "allow";
+  return "deny";
+}
+function buildAuditCredential(record, issuerDid) {
+  const subject = {
+    id: record.id,
+    agentId: record.agentId,
+    ...record.userId ? { principalId: record.userId } : {},
+    operation: record.action,
+    target: record.resource,
+    decision: toDecision(record.result),
+    ...record.reason ? { policyName: record.reason } : {},
+    timestamp: record.timestamp.toISOString(),
+    kavachosVersion: KAVACHOS_VERSION
+  };
+  return {
+    "@context": [VC_CONTEXT_V2, KAVACHOS_AUDIT_CONTEXT],
+    id: `urn:uuid:${generateId()}`,
+    type: [VC_TYPE_CREDENTIAL, KAVACHOS_AUDIT_CREDENTIAL],
+    issuer: issuerDid,
+    issuanceDate: (/* @__PURE__ */ new Date()).toISOString(),
+    expirationDate: new Date(Date.now() + DEFAULT_TTL_SECONDS2 * 1e3).toISOString(),
+    // Cast: AuditCredentialSubject is intentionally wider than CredentialSubject
+    // because the VC schema uses an open-ended subject. The additional fields
+    // (operation, target, decision, etc.) are preserved via spread at runtime.
+    credentialSubject: subject
+  };
+}
+async function signAsJsonLd(credential, config) {
+  const { issuerDid, privateKeyJwk } = config;
+  const kid = `${issuerDid}#${issuerDid.split(":").pop() ?? "key-1"}`;
+  const key = await importJWK(privateKeyJwk, "EdDSA");
+  const { proof: _proof, ...vcWithoutProof } = credential;
+  const payload = new TextEncoder().encode(JSON.stringify(vcWithoutProof));
+  const jws = await new CompactSign(payload).setProtectedHeader({ alg: "EdDSA", kid }).sign(key);
+  const proof = {
+    type: "JsonWebSignature2020",
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    verificationMethod: kid,
+    proofPurpose: "assertionMethod",
+    jws
+  };
+  return { ...credential, proof };
+}
+async function signAsJwt(credential, config) {
+  const { issuerDid, privateKeyJwk } = config;
+  const ttl = config.defaultTtl ?? DEFAULT_TTL_SECONDS2;
+  const kid = `${issuerDid}#${issuerDid.split(":").pop() ?? "key-1"}`;
+  const key = await importJWK(privateKeyJwk, "EdDSA");
+  const { proof: _proof, ...vcWithoutProof } = credential;
+  const builder = new SignJWT({ vc: vcWithoutProof }).setProtectedHeader({ alg: "EdDSA", kid, typ: "JWT" }).setIssuer(issuerDid).setIssuedAt().setExpirationTime(Math.floor(Date.now() / 1e3) + ttl);
+  if (credential.id) builder.setJti(credential.id);
+  if (credential.credentialSubject.id) builder.setSubject(credential.credentialSubject.id);
+  const jwt = await builder.sign(key);
+  return { credential, jwt };
+}
+async function signPresentationAsJsonLd(presentation, config) {
+  const { issuerDid, privateKeyJwk } = config;
+  const kid = `${issuerDid}#${issuerDid.split(":").pop() ?? "key-1"}`;
+  const key = await importJWK(privateKeyJwk, "EdDSA");
+  const { proof: _proof, ...vpWithoutProof } = presentation;
+  const payload = new TextEncoder().encode(JSON.stringify(vpWithoutProof));
+  const jws = await new CompactSign(payload).setProtectedHeader({ alg: "EdDSA", kid }).sign(key);
+  const proof = {
+    type: "JsonWebSignature2020",
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    verificationMethod: kid,
+    proofPurpose: "assertionMethod",
+    jws
+  };
+  return { ...presentation, proof };
+}
+async function exportAuditAsVC(options) {
+  const {
+    since,
+    until,
+    issuerDid,
+    issuerConfig,
+    format = "ldp_vc",
+    output = "individual",
+    filter,
+    records
+  } = options;
+  const inRange = records.filter((r) => {
+    const t = r.timestamp.getTime();
+    return t >= since.getTime() && t <= until.getTime();
+  });
+  const filtered = filter ? inRange.filter(filter) : inRange;
+  if (filtered.length === 0) {
+    return {
+      credentials: [],
+      format,
+      issuedAt: /* @__PURE__ */ new Date(),
+      count: 0
+    };
+  }
+  const credentials = [];
+  const jwts = [];
+  for (const record of filtered) {
+    const base = buildAuditCredential(record, issuerDid);
+    if (format === "jwt_vc") {
+      const { credential, jwt } = await signAsJwt(base, issuerConfig);
+      credentials.push(credential);
+      jwts.push(jwt);
+    } else {
+      const signed = await signAsJsonLd(base, issuerConfig);
+      credentials.push(signed);
+    }
+  }
+  const issuedAt = /* @__PURE__ */ new Date();
+  if (output === "individual") {
+    return {
+      credentials,
+      ...format === "jwt_vc" ? { jwts } : {},
+      format,
+      issuedAt,
+      count: credentials.length
+    };
+  }
+  const basePresentation = {
+    "@context": [VC_CONTEXT_V2, KAVACHOS_AUDIT_CONTEXT],
+    id: `urn:uuid:${generateId()}`,
+    type: [VC_TYPE_PRESENTATION],
+    holder: issuerDid,
+    verifiableCredential: credentials
+  };
+  const presentation = format === "jwt_vc" ? basePresentation : await signPresentationAsJsonLd(basePresentation, issuerConfig);
+  return {
+    credentials,
+    ...format === "jwt_vc" ? { jwts } : {},
+    presentation,
+    format,
+    issuedAt,
+    count: credentials.length
+  };
+}
+function listAuditRecords(records, since, until, filter) {
+  const inRange = records.filter((r) => {
+    const t = r.timestamp.getTime();
+    return t >= since.getTime() && t <= until.getTime();
+  });
+  return filter ? inRange.filter(filter) : inRange;
+}
+var DEFAULT_TTL_SECONDS3 = 86400;
 function makeError8(code2, message, details) {
   return { code: code2, message, ...{} };
 }
@@ -20374,9 +21158,9 @@ function futureISO(seconds) {
   return new Date(Date.now() + seconds * 1e3).toISOString();
 }
 function createVCIssuer(config) {
-  const { issuerDid, privateKeyJwk, defaultTtl = DEFAULT_TTL_SECONDS2 } = config;
+  const { issuerDid, privateKeyJwk, defaultTtl = DEFAULT_TTL_SECONDS3 } = config;
   const kid = `${issuerDid}#${issuerDid.split(":").pop() ?? "key-1"}`;
-  async function signAsJwt(credential, subject, ttl) {
+  async function signAsJwt2(credential, subject, ttl) {
     try {
       const key = await importJWK(privateKeyJwk, "EdDSA");
       const { proof: _proof, ...vcWithoutProof } = credential;
@@ -20401,13 +21185,13 @@ function createVCIssuer(config) {
       };
     }
   }
-  async function signAsJsonLd(credential) {
+  async function signAsJsonLd2(credential) {
     try {
       const key = await importJWK(privateKeyJwk, "EdDSA");
       const { proof: _proof, ...vcWithoutProof } = credential;
       const payload = new TextEncoder().encode(JSON.stringify(vcWithoutProof));
-      const { CompactSign } = await import('jose');
-      const jws = await new CompactSign(payload).setProtectedHeader({ alg: "EdDSA", kid }).sign(key);
+      const { CompactSign: CompactSign2 } = await import('jose');
+      const jws = await new CompactSign2(payload).setProtectedHeader({ alg: "EdDSA", kid }).sign(key);
       const proof = {
         type: "JsonWebSignature2020",
         created: nowISO(),
@@ -20443,9 +21227,9 @@ function createVCIssuer(config) {
   }
   async function signCredential(credential, subject, ttl, format) {
     if (format === "jwt") {
-      return signAsJwt(credential, subject, ttl);
+      return signAsJwt2(credential, subject, ttl);
     }
-    return signAsJsonLd(credential);
+    return signAsJsonLd2(credential);
   }
   async function issueAgentCredential(input) {
     const {
@@ -20970,6 +21754,6 @@ async function verifyWebhookSignature3(secret, rawBody, signature) {
   return diff === 0;
 }
 
-export { CredentialStatusSchema, CredentialSubjectSchema, EVENT_TYPES, HibpApiError, HibpBreachedError, KAVACH_AGENT_CREDENTIAL, KAVACH_DELEGATION_CREDENTIAL, KAVACH_PERMISSION_CREDENTIAL, KVStore, MemoryStore, MultiSessionLimitError, OAuthProxyError, OneTapVerifyError, ProofSchema, RefreshTokenError, SSO_ERROR, SsoError, VC_CONTEXT_V1, VC_CONTEXT_V2, VC_TYPE_CREDENTIAL, VC_TYPE_PRESENTATION, VerifiableCredentialSchema, VerifiablePresentationSchema, additionalFields, admin, agentCards, agentDids, agents, anonymousAuth, apiKeys2 as apiKeys, apiKeys as apiKeysTable, approvalRequests, auditLogs, bearerAuth, budgetPolicies, buildDidDocument, buildSessionMetadata, classifyViolation, constantTimeEqual, createAdditionalFieldsModule, createAdminModule, createAgentModule, createAnonymousAuthModule, createApiKeyManagerModule, createAppleProvider, createApprovalModule, createAuditModule, createCaptchaModule, createCookieSessionManager, createCostAttributionModule, createCustomSessionModule, createDatabase, createDatabaseSync, createDelegationModule, createDeviceAuthModule, createDidModule, createDiscordProvider, createEmailOtpModule, createEmailTemplates, createEmailVerificationModule, createEphemeralSessionModule, createEventStreamModule, createFederationModule, createGdprModule, createGithubProvider, createGitlabProvider, createGoogleProvider, createHibpModule, createI18n, createJwtSessionModule, createKavach, createLastLoginModule, createLinkedInProvider, createMagicLinkModule, createMicrosoftProvider, createMultiSessionModule, createOAuthModule, createOAuthProxyModule, createOidcProviderModule, createOneTapModule, createOneTimeTokenModule, createOpenApiModule, createOrgModule, createPasskeyModule, createPasswordResetModule, createPermissionEngine, createPhoneAuthModule, createPluginRouter, createPolarModule, createPolicyModule, createPresentation, createPrivilegeAnalyzer, createRateLimiter, createReBACModule, createRedirectChain, createScimModule, createSessionFreshnessModule, createSessionManager, createSessionRefresher, createSiweModule, createSlackProvider, createSsoModule, createStripeModule, createTables, createTenantModule, createTokenFamilyStore, createTotpModule, createTrustModule, createTrustedDeviceModule, createTwitterProvider, createUsernameAuthModule, createVCIssuer, createVCVerifier, createWebhookModule2 as createWebhookModule, customAuth, customSession, de, delegationChains, deviceAuth, deviceLabelFromRequest, emailOtp, emailOtps, en, es, fr, fromBase64Url, fromHex, gdpr, generateCsrfToken, generateDidKey, generateDidWeb, generateId, generateOpenAPISpec, getCookie2 as getCookie, getDidWebUrl, getPermissionTemplate, headerAuth, hmacSha1Raw, hmacSha256, hmacSha256Raw, importHmacKey, initializePlugins, ja, kvStore, magicLink, magicLinks, mcpServers, oauth, oauthAccessTokens, oauthAuthorizationCodes, oauthClients, oauthProxy, oneTap, orgInvitations, orgMembers, orgRoles, organization, organizations, parseCookies2 as parseCookies, parseCookiesFromRequest, passkey, passkeyChallenges, passkeyCredentials, pbkdf2Hash, pbkdf2Verify, permissionTemplates, permissions, polar, randomBytes, randomBytesHex, rateLimit, rateLimits, resolveDidKey, resolveDidWeb, scim, serializeCookie, serializeCookieDeletion, sessions, sha1, sha256, sha256Raw, signPayload2 as signPayload, siwe, ssoConnections, stripe, tenants, toBase64Url, toHex, totpRecords, trustScores, twoFactor, users, validateCsrfToken, validateOrigin, verifyPayload, verifyPresentation, verifyWebhookSignature3 as verifyWebhookSignature, withRateLimit, zh };
+export { CredentialStatusSchema, CredentialSubjectSchema, EVENT_TYPES, HibpApiError, HibpBreachedError, KAVACHOS_AUDIT_CONTEXT, KAVACHOS_AUDIT_CREDENTIAL, KAVACH_AGENT_CREDENTIAL, KAVACH_DELEGATION_CREDENTIAL, KAVACH_PERMISSION_CREDENTIAL, KVStore, MemoryStore, MultiSessionLimitError, OAuthProxyError, OneTapVerifyError, ProofSchema, RefreshTokenError, SSO_ERROR, SsoError, VC_CONTEXT_V1, VC_CONTEXT_V2, VC_TYPE_CREDENTIAL, VC_TYPE_PRESENTATION, VerifiableCredentialSchema, VerifiablePresentationSchema, additionalFields, admin, agentCards, agentDids, agents, anonymousAuth, apiKeys2 as apiKeys, apiKeys as apiKeysTable, approvalRequests, auditLogs, bearerAuth, budgetPolicies, buildDidDocument, buildSessionMetadata, classifyViolation, constantTimeEqual, createAdditionalFieldsModule, createAdminModule, createAgentModule, createAnonymousAuthModule, createApiKeyManagerModule, createAppleProvider, createApprovalModule, createAuditModule, createCaptchaModule, createCookieSessionManager, createCostAttributionModule, createCustomSessionModule, createDatabase, createDatabaseSync, createDelegationModule, createDeviceAuthModule, createDidModule, createDiscordProvider, createEmailOtpModule, createEmailTemplates, createEmailVerificationModule, createEphemeralSessionModule, createEventStreamModule, createFederationModule, createGdprModule, createGithubProvider, createGitlabProvider, createGoogleProvider, createHibpModule, createI18n, createJwtSessionModule, createKavach, createLastLoginModule, createLinkedInProvider, createMagicLinkModule, createMicrosoftProvider, createMultiSessionModule, createOAuthModule, createOAuthProxyModule, createOidcProviderModule, createOneTapModule, createOneTimeTokenModule, createOpenApiModule, createOrgModule, createPasskeyModule, createPasswordResetModule, createPermissionEngine, createPhoneAuthModule, createPluginRouter, createPolarModule, createPolicyModule, createPresentation, createPrivilegeAnalyzer, createRateLimiter, createReBACModule, createRedirectChain, createScimModule, createSessionFreshnessModule, createSessionManager, createSessionRefresher, createSiweModule, createSlackProvider, createSsoModule, createStripeModule, createTables, createTenantModule, createTokenFamilyStore, createTotpModule, createTrustModule, createTrustedDeviceModule, createTwitterProvider, createUsernameAuthModule, createVCIssuer, createVCVerifier, createWebhookModule2 as createWebhookModule, customAuth, customSession, de, delegationChains, deviceAuth, deviceLabelFromRequest, emailOtp, emailOtps, en, es, exportAuditAsVC, fr, fromBase64Url, fromHex, gdpr, generateCsrfToken, generateDidKey, generateDidWeb, generateId, generateOpenAPISpec, getCookie2 as getCookie, getDidWebUrl, getPermissionTemplate, headerAuth, hmacSha1Raw, hmacSha256, hmacSha256Raw, importHmacKey, initializePlugins, ja, kvStore, listAuditRecords, magicLink, magicLinks, mcpServers, oauth, oauthAccessTokens, oauthAuthorizationCodes, oauthClients, oauthProxy, oneTap, orgInvitations, orgMembers, orgRoles, organization, organizations, parseCookies2 as parseCookies, parseCookiesFromRequest, passkey, passkeyChallenges, passkeyCredentials, pbkdf2Hash, pbkdf2Verify, permissionTemplates, permissions, polar, randomBytes, randomBytesHex, rateLimit, rateLimits, resolveDidKey, resolveDidWeb, scim, serializeCookie, serializeCookieDeletion, sessions, sha1, sha256, sha256Raw, signPayload2 as signPayload, siwe, ssoConnections, stripe, tenants, toBase64Url, toHex, totpRecords, trustScores, twoFactor, users, validateCsrfToken, validateOrigin, verifyPayload, verifyPresentation, verifyWebhookSignature3 as verifyWebhookSignature, withRateLimit, zh };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map