@contractspec/lib.contracts-spec 2.0.0

package/dist/node/policy/index.js

@@ -0,0 +1,1313 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/registry-utils.ts
+var exports_registry_utils = {};
+__export(exports_registry_utils, {
+  groupByToArray: () => groupByToArray,
+  groupByMultiple: () => groupByMultiple,
+  groupBy: () => groupBy,
+  getUniqueTags: () => getUniqueTags,
+  getUniqueOwners: () => getUniqueOwners,
+  getUniqueDomains: () => getUniqueDomains,
+  filterBy: () => filterBy,
+  GroupingStrategies: () => GroupingStrategies
+});
+function filterBy(items, filter) {
+  return items.filter((item) => {
+    if (filter.tags?.length) {
+      const hasMatchingTag = filter.tags.some((tag) => item.meta.tags?.includes(tag));
+      if (!hasMatchingTag)
+        return false;
+    }
+    if (filter.owners?.length) {
+      const hasMatchingOwner = filter.owners.some((owner) => item.meta.owners?.includes(owner));
+      if (!hasMatchingOwner)
+        return false;
+    }
+    if (filter.stability?.length) {
+      if (!filter.stability.includes(item.meta.stability ?? "stable")) {
+        return false;
+      }
+    }
+    if (filter.domain) {
+      const itemDomain = GroupingStrategies.byDomain(item);
+      if (itemDomain !== filter.domain)
+        return false;
+    }
+    if (filter.keyPattern) {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      const pattern = filter.keyPattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+      const regex = new RegExp(`^${pattern}$`, "i");
+      if (!regex.test(name))
+        return false;
+    }
+    return true;
+  });
+}
+function groupBy(items, keyFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      groups.set(key, [item]);
+    }
+  }
+  return groups;
+}
+function groupByToArray(items, keyFn) {
+  const map = groupBy(items, keyFn);
+  return Array.from(map.entries()).map(([key, items2]) => ({ key, items: items2 }));
+}
+function groupByMultiple(items, keysFn) {
+  const groups = new Map;
+  for (const item of items) {
+    const keys = keysFn(item);
+    for (const key of keys) {
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+  }
+  return groups;
+}
+function getUniqueTags(items) {
+  const tags = new Set;
+  for (const item of items) {
+    for (const tag of item.meta.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+  return Array.from(tags).sort();
+}
+function getUniqueOwners(items) {
+  const owners = new Set;
+  for (const item of items) {
+    for (const owner of item.meta.owners ?? []) {
+      owners.add(owner);
+    }
+  }
+  return Array.from(owners).sort();
+}
+function getUniqueDomains(items) {
+  const domains = new Set;
+  for (const item of items) {
+    domains.add(GroupingStrategies.byDomain(item));
+  }
+  return Array.from(domains).sort();
+}
+var GroupingStrategies;
+var init_registry_utils = __esm(() => {
+  GroupingStrategies = {
+    byTag: (item) => item.meta.tags?.[0] ?? "untagged",
+    byAllTags: (item) => item.meta.tags?.length ? item.meta.tags : ["untagged"],
+    byOwner: (item) => item.meta.owners?.[0] ?? "unowned",
+    byDomain: (item) => {
+      const name = item.meta.key ?? item.meta.key ?? "";
+      return name.split(".")[0] ?? "default";
+    },
+    byStability: (item) => item.meta.stability ?? "stable",
+    byUrlPath: (level) => (item) => {
+      if (!item.path)
+        return "root";
+      const segments = item.path.split("/").filter(Boolean);
+      return segments.slice(0, level).join("/") || "root";
+    }
+  };
+});
+
+// src/registry.ts
+init_registry_utils();
+import { compareVersions } from "compare-versions";
+var keyOfSpecContract = (spec) => `${spec.meta.key}.v${spec.meta.version}`;
+
+class SpecContractRegistry {
+  contractType;
+  items = new Map;
+  constructor(contractType, items) {
+    this.contractType = contractType;
+    if (items) {
+      items.forEach((p) => this.register(p));
+    }
+  }
+  register(p) {
+    const key = keyOfSpecContract(p);
+    if (this.items.has(key))
+      throw new Error(`Duplicate contract \`${this.contractType}\` ${key}`);
+    this.items.set(key, p);
+    return this;
+  }
+  count() {
+    return this.items.size;
+  }
+  list() {
+    return [...this.items.values()];
+  }
+  get(key, version) {
+    if (version != null)
+      return this.items.get(`${key}.v${version}`);
+    let candidate;
+    for (const [k, p] of this.items.entries()) {
+      if (!k.startsWith(`${key}.v`))
+        continue;
+      if (!candidate || compareVersions(p.meta.version, candidate.meta.version) > 0) {
+        candidate = p;
+      }
+    }
+    return candidate;
+  }
+  has(key, version) {
+    return !!this.get(key, version);
+  }
+  filter(criteria) {
+    return filterBy(this.list(), criteria);
+  }
+  listByTag(tag) {
+    return this.list().filter((p) => p.meta.tags?.includes(tag));
+  }
+  listByOwner(owner) {
+    return this.list().filter((p) => p.meta.owners?.includes(owner));
+  }
+  groupBy(keyFn) {
+    return groupBy(this.list(), keyFn);
+  }
+  getUniqueTags() {
+    return getUniqueTags(this.list());
+  }
+}
+
+// src/policy/context.ts
+class PolicyViolationError extends Error {
+  violationType;
+  details;
+  constructor(type, details) {
+    const message = formatPolicyViolationMessage(type, details);
+    super(message);
+    this.name = "PolicyViolationError";
+    this.violationType = type;
+    this.details = details;
+  }
+}
+function formatPolicyViolationMessage(type, details) {
+  const prefix = details.operation ? `Policy violation for "${details.operation}": ` : "Policy violation: ";
+  switch (type) {
+    case "missing_role":
+      return `${prefix}Missing required role "${details.requiredRole}"`;
+    case "missing_permission":
+      return `${prefix}Missing required permission "${details.requiredPermission}"`;
+    case "missing_attribute":
+      return `${prefix}Missing or invalid attribute "${details.requiredAttribute?.key}"`;
+    case "rate_limit_exceeded":
+      return `${prefix}Rate limit exceeded for key "${details.rateLimitKey}"`;
+    case "consent_required":
+      return `${prefix}Consent required: ${details.consentIds?.join(", ")}`;
+    case "access_denied":
+      return `${prefix}${details.reason ?? "Access denied"}`;
+  }
+}
+
+class PolicyContextImpl {
+  user;
+  roles;
+  permissions;
+  rateLimitStates = new Map;
+  rateLimitConfigs;
+  auditHandler;
+  constructor(user, options = {}) {
+    this.user = user;
+    this.roles = new Set(user.roles);
+    this.permissions = new Set(user.permissions);
+    this.rateLimitConfigs = options.rateLimits ?? {};
+    this.auditHandler = options.auditHandler;
+  }
+  hasRole(role) {
+    return this.roles.has(role);
+  }
+  hasAnyRole(roles) {
+    return roles.some((r) => this.roles.has(r));
+  }
+  hasAllRoles(roles) {
+    return roles.every((r) => this.roles.has(r));
+  }
+  requireRole(role) {
+    if (!this.hasRole(role)) {
+      throw new PolicyViolationError("missing_role", { requiredRole: role });
+    }
+  }
+  hasPermission(permission) {
+    return this.permissions.has(permission);
+  }
+  hasAnyPermission(permissions) {
+    return permissions.some((p) => this.permissions.has(p));
+  }
+  hasAllPermissions(permissions) {
+    return permissions.every((p) => this.permissions.has(p));
+  }
+  requirePermission(permission) {
+    if (!this.hasPermission(permission)) {
+      throw new PolicyViolationError("missing_permission", {
+        requiredPermission: permission
+      });
+    }
+  }
+  getAttribute(key) {
+    return this.user.attributes[key];
+  }
+  checkAttribute(key, expected) {
+    return this.user.attributes[key] === expected;
+  }
+  checkAttributeOneOf(key, allowedValues) {
+    return allowedValues.includes(this.user.attributes[key]);
+  }
+  checkRateLimit(key) {
+    const config = this.rateLimitConfigs[key];
+    if (!config) {
+      return { allowed: true, remaining: Infinity };
+    }
+    const now = Date.now();
+    const state = this.rateLimitStates.get(key);
+    if (!state || now - state.windowStart >= config.windowMs) {
+      return { allowed: true, remaining: config.limit };
+    }
+    const remaining = Math.max(0, config.limit - state.count);
+    if (remaining <= 0) {
+      const resetAt = new Date(state.windowStart + config.windowMs);
+      const retryAfterMs = state.windowStart + config.windowMs - now;
+      return { allowed: false, remaining: 0, resetAt, retryAfterMs };
+    }
+    return { allowed: true, remaining };
+  }
+  consumeRateLimit(key, cost = 1) {
+    const config = this.rateLimitConfigs[key];
+    if (!config) {
+      return { allowed: true, remaining: Infinity };
+    }
+    const now = Date.now();
+    let state = this.rateLimitStates.get(key);
+    if (!state || now - state.windowStart >= config.windowMs) {
+      state = {
+        key,
+        count: 0,
+        windowStart: now,
+        windowMs: config.windowMs,
+        limit: config.limit
+      };
+    }
+    if (state.count + cost > config.limit) {
+      const resetAt = new Date(state.windowStart + config.windowMs);
+      const retryAfterMs = state.windowStart + config.windowMs - now;
+      this.rateLimitStates.set(key, state);
+      return {
+        allowed: false,
+        remaining: Math.max(0, config.limit - state.count),
+        resetAt,
+        retryAfterMs
+      };
+    }
+    state.count += cost;
+    this.rateLimitStates.set(key, state);
+    return {
+      allowed: true,
+      remaining: Math.max(0, config.limit - state.count)
+    };
+  }
+  auditAccess(operation, result, reason) {
+    if (!this.auditHandler)
+      return;
+    const entry = {
+      timestamp: new Date,
+      operation,
+      result,
+      reason,
+      userId: this.user.id,
+      tenantId: this.user.tenantId,
+      attributes: this.user.attributes
+    };
+    Promise.resolve(this.auditHandler(entry)).catch(() => {});
+  }
+}
+function createPolicyContext(user, options) {
+  return new PolicyContextImpl(user, options);
+}
+function createAnonymousPolicyContext(options) {
+  return new PolicyContextImpl({
+    id: "anonymous",
+    roles: [],
+    permissions: [],
+    attributes: {}
+  }, options);
+}
+function createBypassPolicyContext(allRoles, allPermissions, options) {
+  return new PolicyContextImpl({
+    id: "system",
+    roles: allRoles,
+    permissions: allPermissions,
+    attributes: { bypass: true }
+  }, options);
+}
+
+// src/policy/engine.ts
+class PolicyEngine {
+  registry;
+  constructor(registry) {
+    this.registry = registry;
+  }
+  decide(input) {
+    const policies = this.resolvePolicies(input.policies);
+    let allowReason;
+    let appliedRateLimit;
+    let escalate;
+    for (const policy of policies) {
+      const match = this.matchRuleSet(policy, input);
+      if (!match)
+        continue;
+      if (match.rule.effect === "deny") {
+        return {
+          effect: "deny",
+          reason: match.rule.reason ?? policy.meta.key,
+          requiredConsents: match.missingConsents.length ? match.missingConsents : undefined,
+          evaluatedBy: "engine"
+        };
+      }
+      if (match.rule.effect === "allow") {
+        if (match.missingConsents.length) {
+          return {
+            effect: "deny",
+            reason: "consent_required",
+            requiredConsents: match.missingConsents,
+            evaluatedBy: "engine"
+          };
+        }
+        if (!allowReason) {
+          allowReason = match.rule.reason ?? policy.meta.key;
+        }
+        if (!appliedRateLimit && match.rateLimit) {
+          appliedRateLimit = match.rateLimit;
+        }
+        if (!escalate && match.rule.escalate) {
+          escalate = match.rule.escalate;
+        }
+      }
+    }
+    const fieldDecisions = this.evaluateFields(policies, input);
+    const pii = policies.find((p) => p.pii)?.pii;
+    const escalateValue = typeof escalate === "undefined" ? undefined : escalate;
+    return {
+      effect: allowReason ? "allow" : "deny",
+      reason: allowReason,
+      rateLimit: appliedRateLimit,
+      escalate: escalateValue,
+      fieldDecisions: fieldDecisions.length ? fieldDecisions : undefined,
+      pii,
+      evaluatedBy: "engine"
+    };
+  }
+  resolvePolicies(refs) {
+    const specs = [];
+    for (const ref of refs) {
+      const spec = this.registry.get(ref.key, ref.version);
+      if (!spec)
+        throw new Error(`PolicyEngine: policy not found ${ref.key}.v${ref.version}`);
+      specs.push(spec);
+    }
+    return specs;
+  }
+  matchRuleSet(policy, input) {
+    let allowMatch;
+    for (const rule of policy.rules) {
+      if (!rule.actions.includes(input.action))
+        continue;
+      if (!matchesSubject(rule, input.subject))
+        continue;
+      if (!matchesResource(rule, input.resource))
+        continue;
+      if (!matchesFlags(rule, input))
+        continue;
+      if (!matchesRelationships(rule.relationships, input))
+        continue;
+      if (!matchesConditions(rule, input))
+        continue;
+      const missingConsents = collectMissingConsents(rule, policy, input);
+      const rateLimit = resolveRateLimit(rule, policy, input);
+      const evaluation = {
+        rule,
+        missingConsents,
+        rateLimit
+      };
+      if (rule.effect === "deny")
+        return evaluation;
+      if (rule.effect === "allow" && !allowMatch)
+        allowMatch = evaluation;
+    }
+    return allowMatch;
+  }
+  evaluateFields(policies, input) {
+    const out = new Map;
+    for (const policy of policies) {
+      if (!policy.fieldPolicies)
+        continue;
+      for (const rule of policy.fieldPolicies) {
+        if (!rule.actions.includes(mapActionToFieldAction(input.action)))
+          continue;
+        if (!matchesSubject(rule, input.subject))
+          continue;
+        if (!matchesResource(rule, input.resource))
+          continue;
+        if (!matchesConditions(rule, input))
+          continue;
+        const existing = out.get(rule.field);
+        if (rule.effect === "deny") {
+          out.set(rule.field, {
+            field: rule.field,
+            effect: "deny",
+            reason: rule.reason ?? policy.meta.key
+          });
+        } else if (!existing) {
+          out.set(rule.field, {
+            field: rule.field,
+            effect: "allow",
+            reason: rule.reason ?? policy.meta.key
+          });
+        }
+      }
+    }
+    return [...out.values()];
+  }
+}
+function mapActionToFieldAction(action) {
+  if (action.startsWith("write"))
+    return "write";
+  return "read";
+}
+function matchesSubject(rule, subject) {
+  const matcher = rule.subject;
+  if (!matcher)
+    return true;
+  if (matcher.roles?.length) {
+    const roles = subject.roles ?? [];
+    const hasRole = matcher.roles.some((role) => roles.includes(role));
+    if (!hasRole)
+      return false;
+  }
+  if (matcher.attributes) {
+    const attributes = subject.attributes ?? {};
+    if (!matchAttributes(matcher.attributes, attributes))
+      return false;
+  }
+  return true;
+}
+function matchesResource(rule, resource) {
+  const matcher = rule.resource;
+  if (!matcher)
+    return true;
+  if (matcher.type && matcher.type !== resource.type)
+    return false;
+  if (matcher.fields?.length) {
+    const targetFields = resource.fields ?? [];
+    if (!matcher.fields.some((field) => targetFields.includes(field)))
+      return false;
+  }
+  if (matcher.attributes) {
+    const attributes = resource.attributes ?? {};
+    if (!matchAttributes(matcher.attributes, attributes))
+      return false;
+  }
+  return true;
+}
+function matchesFlags(rule, input) {
+  if (!rule.flags?.length)
+    return true;
+  const available = new Set;
+  if (input.flags) {
+    for (const flag of input.flags)
+      available.add(flag);
+  }
+  const attributeFlags = input.subject.attributes?.featureFlags;
+  if (Array.isArray(attributeFlags)) {
+    for (const flag of attributeFlags)
+      available.add(flag);
+  }
+  return rule.flags.every((flag) => available.has(flag));
+}
+function matchesRelationships(matchers, input) {
+  if (!matchers || matchers.length === 0)
+    return true;
+  const relationships = input.subject.relationships ?? [];
+  const resourceId = getResourceId(input.resource);
+  const resourceType = input.resource.type;
+  return matchers.every((matcher) => relationships.some((relation) => {
+    if (relation.relation !== matcher.relation)
+      return false;
+    const typeMatches = !matcher.objectType || relation.objectType === matcher.objectType || matcher.objectType === resourceType;
+    if (!typeMatches)
+      return false;
+    if (!matcher.objectId)
+      return true;
+    if (matcher.objectId === "$resource") {
+      if (resourceId) {
+        return relation.object === resourceId;
+      }
+      return relation.object === resourceType || relation.objectType === resourceType;
+    }
+    return relation.object === matcher.objectId;
+  }));
+}
+function matchesConditions(rule, input) {
+  if (!rule.conditions || rule.conditions.length === 0)
+    return true;
+  return rule.conditions.every((condition) => evaluateCondition(condition.expression, input));
+}
+function matchAttributes(matcher, actual) {
+  for (const [key, attrMatcher] of Object.entries(matcher)) {
+    const value = actual[key];
+    if (attrMatcher.exists && typeof value === "undefined")
+      return false;
+    if (typeof attrMatcher.equals !== "undefined") {
+      if (value !== attrMatcher.equals)
+        return false;
+    }
+    if (attrMatcher.oneOf && !attrMatcher.oneOf.includes(value))
+      return false;
+  }
+  return true;
+}
+function collectMissingConsents(rule, policy, input) {
+  if (!rule.requiresConsent?.length)
+    return [];
+  const granted = new Set(input.consents ?? []);
+  const missingIds = rule.requiresConsent.filter((id) => !granted.has(id));
+  if (missingIds.length === 0)
+    return [];
+  return resolveConsentDefinitions(policy, missingIds);
+}
+function resolveConsentDefinitions(policy, ids) {
+  const catalog = policy.consents ?? [];
+  return ids.map((id) => {
+    const found = catalog.find((consent) => consent.id === id);
+    return found ?? {
+      id,
+      scope: "unspecified",
+      purpose: "unspecified",
+      description: `Consent "${id}" required by ${policy.meta.key}`,
+      required: true
+    };
+  });
+}
+function resolveRateLimit(rule, policy, input) {
+  if (!rule.rateLimit)
+    return;
+  const definition = typeof rule.rateLimit === "string" ? (policy.rateLimits ?? []).find((item) => item.id === rule.rateLimit) : rule.rateLimit;
+  if (!definition) {
+    throw new Error(`PolicyEngine: rate limit "${String(rule.rateLimit)}" not declared in ${policy.meta.key}`);
+  }
+  return {
+    rpm: definition.rpm,
+    key: definition.key ?? input.resource.type,
+    windowSeconds: definition.windowSeconds,
+    burst: definition.burst
+  };
+}
+function evaluateCondition(expression, input) {
+  const trimmed = expression.trim();
+  if (!trimmed)
+    return true;
+  const context = {
+    subject: input.subject,
+    resource: input.resource,
+    context: input.context ?? {}
+  };
+  try {
+    const fn = new Function("subject", "resource", "context", `return (${transformExpression(trimmed)});`);
+    const result = fn(context.subject, context.resource, context.context);
+    return Boolean(result);
+  } catch (_error) {
+    return false;
+  }
+}
+function transformExpression(expression) {
+  return expression.replace(/&&/g, "&&").replace(/\|\|/g, "||");
+}
+function getResourceId(resource) {
+  if (resource.id)
+    return resource.id;
+  const candidate = resource.attributes?.id;
+  if (typeof candidate === "string")
+    return candidate;
+  if (typeof candidate === "number")
+    return String(candidate);
+  return;
+}
+
+// src/policy/guards.ts
+function checkAuthLevel(ctx, required) {
+  if (required === "anonymous")
+    return true;
+  if (required === "user") {
+    return ctx.user.id !== "anonymous";
+  }
+  if (required === "admin") {
+    return ctx.hasRole("admin");
+  }
+  return false;
+}
+function checkPolicyForOperation(ctx, operation, flags = []) {
+  const { policy } = operation;
+  const operationName = `${operation.meta.key}.v${operation.meta.version}`;
+  const missing = {};
+  if (!checkAuthLevel(ctx, policy.auth)) {
+    return {
+      allowed: false,
+      reason: `Operation "${operationName}" requires "${policy.auth}" auth level`,
+      missing: {
+        roles: policy.auth === "admin" ? ["admin"] : undefined
+      }
+    };
+  }
+  if (policy.flags?.length) {
+    const availableFlags = new Set(flags);
+    const missingFlags = policy.flags.filter((f) => !availableFlags.has(f));
+    if (missingFlags.length > 0) {
+      missing.flags = missingFlags;
+      return {
+        allowed: false,
+        reason: `Operation "${operationName}" requires feature flags: ${missingFlags.join(", ")}`,
+        missing
+      };
+    }
+  }
+  return { allowed: true };
+}
+function assertPolicyForOperation(ctx, operation, flags = []) {
+  const result = checkPolicyForOperation(ctx, operation, flags);
+  if (!result.allowed) {
+    const operationName2 = `${operation.meta.key}.v${operation.meta.version}`;
+    ctx.auditAccess(operationName2, "denied", result.reason);
+    throw new PolicyViolationError("access_denied", {
+      operation: operationName2,
+      reason: result.reason
+    });
+  }
+  const operationName = `${operation.meta.key}.v${operation.meta.version}`;
+  ctx.auditAccess(operationName, "allowed");
+}
+function filterOperationsByPolicy(ctx, operations, flags = []) {
+  return operations.filter((op) => checkPolicyForOperation(ctx, op, flags).allowed);
+}
+function checkRole(ctx, requiredRole, operation) {
+  if (ctx.hasRole(requiredRole)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    reason: operation ? `Operation "${operation}" requires role "${requiredRole}"` : `Missing required role "${requiredRole}"`,
+    missing: { roles: [requiredRole] }
+  };
+}
+function assertRole(ctx, requiredRole, operation) {
+  const result = checkRole(ctx, requiredRole, operation);
+  if (!result.allowed) {
+    throw new PolicyViolationError("missing_role", {
+      operation,
+      requiredRole
+    });
+  }
+}
+function checkAnyRole(ctx, requiredRoles, operation) {
+  if (ctx.hasAnyRole(requiredRoles)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    reason: operation ? `Operation "${operation}" requires one of roles: ${requiredRoles.join(", ")}` : `Missing required role (need one of: ${requiredRoles.join(", ")})`,
+    missing: { roles: requiredRoles }
+  };
+}
+function checkPermission(ctx, requiredPermission, operation) {
+  if (ctx.hasPermission(requiredPermission)) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    reason: operation ? `Operation "${operation}" requires permission "${requiredPermission}"` : `Missing required permission "${requiredPermission}"`,
+    missing: { permissions: [requiredPermission] }
+  };
+}
+function assertPermission(ctx, requiredPermission, operation) {
+  const result = checkPermission(ctx, requiredPermission, operation);
+  if (!result.allowed) {
+    throw new PolicyViolationError("missing_permission", {
+      operation,
+      requiredPermission
+    });
+  }
+}
+function checkAllPermissions(ctx, requiredPermissions, operation) {
+  const missing = requiredPermissions.filter((p) => !ctx.hasPermission(p));
+  if (missing.length === 0) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    reason: operation ? `Operation "${operation}" requires permissions: ${missing.join(", ")}` : `Missing required permissions: ${missing.join(", ")}`,
+    missing: { permissions: missing }
+  };
+}
+function checkCombinedPolicy(ctx, requirements, flags = [], operation) {
+  const missing = {};
+  const reasons = [];
+  if (requirements.roles?.length) {
+    const missingRoles = requirements.roles.filter((r) => !ctx.hasRole(r));
+    if (missingRoles.length > 0) {
+      missing.roles = missingRoles;
+      reasons.push(`Missing roles: ${missingRoles.join(", ")}`);
+    }
+  }
+  if (requirements.anyRole?.length) {
+    if (!ctx.hasAnyRole(requirements.anyRole)) {
+      missing.roles = [...missing.roles ?? [], ...requirements.anyRole];
+      reasons.push(`Need one of roles: ${requirements.anyRole.join(", ")}`);
+    }
+  }
+  if (requirements.permissions?.length) {
+    const missingPerms = requirements.permissions.filter((p) => !ctx.hasPermission(p));
+    if (missingPerms.length > 0) {
+      missing.permissions = missingPerms;
+      reasons.push(`Missing permissions: ${missingPerms.join(", ")}`);
+    }
+  }
+  if (requirements.anyPermission?.length) {
+    if (!ctx.hasAnyPermission(requirements.anyPermission)) {
+      missing.permissions = [
+        ...missing.permissions ?? [],
+        ...requirements.anyPermission
+      ];
+      reasons.push(`Need one of permissions: ${requirements.anyPermission.join(", ")}`);
+    }
+  }
+  if (requirements.flags?.length) {
+    const availableFlags = new Set(flags);
+    const missingFlags = requirements.flags.filter((f) => !availableFlags.has(f));
+    if (missingFlags.length > 0) {
+      missing.flags = missingFlags;
+      reasons.push(`Missing feature flags: ${missingFlags.join(", ")}`);
+    }
+  }
+  if (reasons.length > 0) {
+    const prefix = operation ? `Operation "${operation}": ` : "";
+    return {
+      allowed: false,
+      reason: prefix + reasons.join("; "),
+      missing
+    };
+  }
+  return { allowed: true };
+}
+function assertCombinedPolicy(ctx, requirements, flags = [], operation) {
+  const result = checkCombinedPolicy(ctx, requirements, flags, operation);
+  if (!result.allowed) {
+    throw new PolicyViolationError("access_denied", {
+      operation,
+      reason: result.reason
+    });
+  }
+}
+
+// src/policy/opa-adapter.ts
+class OPAPolicyAdapter {
+  client;
+  options;
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+  }
+  async evaluate(context, policies, engineDecision) {
+    const input = buildOPAInput(context, policies, engineDecision);
+    const raw = await this.client.evaluate(this.options.decisionPath, input);
+    const resolved = this.options.mapResult ? this.options.mapResult(raw) : raw;
+    if (!resolved) {
+      return {
+        ...engineDecision,
+        evaluatedBy: engineDecision.evaluatedBy ?? "engine"
+      };
+    }
+    const opaResult = resolved;
+    const mergedRequiredConsents = mergeRequiredConsents(policies, engineDecision.requiredConsents ?? [], opaResult.requiredConsents ?? []);
+    return {
+      ...engineDecision,
+      effect: opaResult.effect ?? engineDecision.effect,
+      reason: opaResult.reason ?? engineDecision.reason,
+      fieldDecisions: opaResult.fieldDecisions ?? engineDecision.fieldDecisions,
+      requiredConsents: mergedRequiredConsents.length ? mergedRequiredConsents : undefined,
+      evaluatedBy: "opa"
+    };
+  }
+}
+function buildOPAInput(context, policies, engineDecision) {
+  return {
+    context,
+    decision: engineDecision,
+    policies: policies.map((policy) => ({
+      meta: policy.meta,
+      rules: policy.rules,
+      fieldPolicies: policy.fieldPolicies,
+      pii: policy.pii,
+      relationships: policy.relationships,
+      consents: policy.consents,
+      rateLimits: policy.rateLimits
+    }))
+  };
+}
+function mergeRequiredConsents(policies, existing, incomingIds) {
+  if (incomingIds.length === 0)
+    return existing;
+  const existingIds = new Set(existing.map((consent) => consent.id));
+  const merged = [...existing];
+  for (const id of incomingIds) {
+    if (existingIds.has(id))
+      continue;
+    const resolved = resolveConsentAcrossPolicies(policies, id);
+    if (resolved) {
+      merged.push(resolved);
+      existingIds.add(resolved.id);
+    }
+  }
+  return merged;
+}
+function resolveConsentAcrossPolicies(policies, id) {
+  for (const policy of policies) {
+    const match = policy.consents?.find((consent) => consent.id === id);
+    if (match)
+      return match;
+  }
+  return {
+    id,
+    scope: "unspecified",
+    purpose: "unspecified",
+    description: `Consent "${id}" returned by OPA`,
+    required: true
+  };
+}
+// src/policy/registry.ts
+class PolicyRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("policy", items);
+  }
+}
+
+// src/policy/validation.ts
+function validatePolicySpec(spec) {
+  const issues = [];
+  validateMeta(spec, issues);
+  validateRules(spec, issues);
+  validateFieldPolicies(spec, issues);
+  validateRateLimits(spec, issues);
+  validateConsents(spec, issues);
+  validateRelationships(spec, issues);
+  return {
+    valid: issues.filter((i) => i.level === "error").length === 0,
+    issues
+  };
+}
+function validateMeta(spec, issues) {
+  const { meta } = spec;
+  if (!meta.key?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Policy must have a non-empty key",
+      path: "meta.key"
+    });
+  }
+  if (!meta.version?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Policy must have a non-empty version",
+      path: "meta.version"
+    });
+  }
+  if (!meta.owners?.length) {
+    issues.push({
+      level: "warning",
+      message: "Policy should specify owners",
+      path: "meta.owners"
+    });
+  }
+}
+function validateRules(spec, issues) {
+  if (!spec.rules?.length) {
+    issues.push({
+      level: "warning",
+      message: "Policy has no rules defined",
+      path: "rules"
+    });
+    return;
+  }
+  const seenRateRefs = new Set;
+  spec.rules.forEach((rule, index) => {
+    const path = `rules[${index}]`;
+    if (!rule.actions?.length) {
+      issues.push({
+        level: "error",
+        message: "Rule must specify at least one action",
+        path: `${path}.actions`
+      });
+    }
+    if (!["allow", "deny"].includes(rule.effect)) {
+      issues.push({
+        level: "error",
+        message: `Invalid rule effect: ${rule.effect}`,
+        path: `${path}.effect`
+      });
+    }
+    if (typeof rule.rateLimit === "string") {
+      seenRateRefs.add(rule.rateLimit);
+      if (!spec.rateLimits?.some((rl) => rl.id === rule.rateLimit)) {
+        issues.push({
+          level: "error",
+          message: `Rate limit "${rule.rateLimit}" referenced but not defined`,
+          path: `${path}.rateLimit`
+        });
+      }
+    }
+    if (rule.requiresConsent?.length) {
+      for (const consentId of rule.requiresConsent) {
+        if (!spec.consents?.some((c) => c.id === consentId)) {
+          issues.push({
+            level: "error",
+            message: `Consent "${consentId}" referenced but not defined`,
+            path: `${path}.requiresConsent`
+          });
+        }
+      }
+    }
+    validateConditions(rule.conditions, `${path}.conditions`, issues);
+  });
+  if (spec.rateLimits?.length) {
+    for (const rl of spec.rateLimits) {
+      if (!seenRateRefs.has(rl.id)) {
+        const hasInline = spec.rules.some((r) => typeof r.rateLimit === "object" && r.rateLimit.id === rl.id);
+        if (!hasInline) {
+          issues.push({
+            level: "info",
+            message: `Rate limit "${rl.id}" is defined but not referenced`,
+            path: `rateLimits`
+          });
+        }
+      }
+    }
+  }
+}
+function validateFieldPolicies(spec, issues) {
+  if (!spec.fieldPolicies?.length)
+    return;
+  const seenFields = new Map;
+  spec.fieldPolicies.forEach((rule, index) => {
+    const path = `fieldPolicies[${index}]`;
+    if (!rule.field?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Field policy must specify a field",
+        path: `${path}.field`
+      });
+    }
+    if (!rule.actions?.length) {
+      issues.push({
+        level: "error",
+        message: "Field policy must specify at least one action",
+        path: `${path}.actions`
+      });
+    }
+    for (const action of rule.actions) {
+      if (!["read", "write"].includes(action)) {
+        issues.push({
+          level: "error",
+          message: `Invalid field action: ${action}`,
+          path: `${path}.actions`
+        });
+      }
+    }
+    const existing = seenFields.get(rule.field) ?? [];
+    existing.push(rule);
+    seenFields.set(rule.field, existing);
+    validateConditions(rule.conditions, `${path}.conditions`, issues);
+  });
+  for (const [field, rules] of seenFields.entries()) {
+    if (rules.length > 1) {
+      const hasConflict = rules.some((r) => r.effect === "allow") && rules.some((r) => r.effect === "deny");
+      if (hasConflict) {
+        issues.push({
+          level: "warning",
+          message: `Field "${field}" has potentially conflicting allow/deny policies`,
+          path: "fieldPolicies",
+          context: { field, ruleCount: rules.length }
+        });
+      }
+    }
+  }
+}
+function validateRateLimits(spec, issues) {
+  if (!spec.rateLimits?.length)
+    return;
+  const seenIds = new Set;
+  spec.rateLimits.forEach((rl, index) => {
+    const path = `rateLimits[${index}]`;
+    if (!rl.id?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Rate limit must have an id",
+        path: `${path}.id`
+      });
+    } else if (seenIds.has(rl.id)) {
+      issues.push({
+        level: "error",
+        message: `Duplicate rate limit id: ${rl.id}`,
+        path: `${path}.id`
+      });
+    } else {
+      seenIds.add(rl.id);
+    }
+    if (typeof rl.rpm !== "number" || rl.rpm <= 0) {
+      issues.push({
+        level: "error",
+        message: "Rate limit rpm must be a positive number",
+        path: `${path}.rpm`
+      });
+    }
+    if (rl.windowSeconds !== undefined && rl.windowSeconds <= 0) {
+      issues.push({
+        level: "error",
+        message: "Rate limit windowSeconds must be positive if specified",
+        path: `${path}.windowSeconds`
+      });
+    }
+    if (rl.burst !== undefined && rl.burst < 0) {
+      issues.push({
+        level: "error",
+        message: "Rate limit burst must be non-negative if specified",
+        path: `${path}.burst`
+      });
+    }
+  });
+}
+function validateConsents(spec, issues) {
+  if (!spec.consents?.length)
+    return;
+  const seenIds = new Set;
+  spec.consents.forEach((consent, index) => {
+    const path = `consents[${index}]`;
+    if (!consent.id?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Consent must have an id",
+        path: `${path}.id`
+      });
+    } else if (seenIds.has(consent.id)) {
+      issues.push({
+        level: "error",
+        message: `Duplicate consent id: ${consent.id}`,
+        path: `${path}.id`
+      });
+    } else {
+      seenIds.add(consent.id);
+    }
+    if (!consent.scope?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Consent must specify a scope",
+        path: `${path}.scope`
+      });
+    }
+    if (!consent.purpose?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Consent must specify a purpose",
+        path: `${path}.purpose`
+      });
+    }
+    if (consent.expiresInDays !== undefined && consent.expiresInDays <= 0) {
+      issues.push({
+        level: "error",
+        message: "Consent expiresInDays must be positive if specified",
+        path: `${path}.expiresInDays`
+      });
+    }
+  });
+}
+function validateRelationships(spec, issues) {
+  if (!spec.relationships?.length)
+    return;
+  const seenRelations = new Set;
+  spec.relationships.forEach((rel, index) => {
+    const path = `relationships[${index}]`;
+    const key = `${rel.subjectType}:${rel.relation}:${rel.objectType}`;
+    if (!rel.subjectType?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Relationship must specify subjectType",
+        path: `${path}.subjectType`
+      });
+    }
+    if (!rel.relation?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Relationship must specify relation",
+        path: `${path}.relation`
+      });
+    }
+    if (!rel.objectType?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Relationship must specify objectType",
+        path: `${path}.objectType`
+      });
+    }
+    if (seenRelations.has(key)) {
+      issues.push({
+        level: "warning",
+        message: `Duplicate relationship definition: ${key}`,
+        path
+      });
+    } else {
+      seenRelations.add(key);
+    }
+  });
+}
+function validateConditions(conditions, path, issues) {
+  if (!conditions?.length)
+    return;
+  conditions.forEach((cond, index) => {
+    if (!cond.expression?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Condition must have a non-empty expression",
+        path: `${path}[${index}].expression`
+      });
+    }
+  });
+}
+function validatePolicyConsistency(deps) {
+  const issues = [];
+  for (const policy of deps.policies.list()) {
+    const specResult = validatePolicySpec(policy);
+    issues.push(...specResult.issues.map((i) => ({
+      ...i,
+      path: `${policy.meta.key}.v${policy.meta.version}${i.path ? `.${i.path}` : ""}`
+    })));
+  }
+  if (deps.operations) {
+    for (const operation of deps.operations.list()) {
+      const policyRefs = operation.policy.policies ?? [];
+      for (const ref of policyRefs) {
+        const policy = deps.policies.get(ref.key, ref.version);
+        if (!policy) {
+          issues.push({
+            level: "error",
+            message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown policy "${ref.key}.v${ref.version}"`,
+            path: `operations.${operation.meta.key}.policy.policies`
+          });
+        }
+      }
+      const fieldPolicies = operation.policy.fieldPolicies ?? [];
+      for (const fp of fieldPolicies) {
+        if (fp.policy) {
+          const policy = deps.policies.get(fp.policy.key, fp.policy.version);
+          if (!policy) {
+            issues.push({
+              level: "error",
+              message: `Operation "${operation.meta.key}.v${operation.meta.version}" references unknown field policy "${fp.policy.key}.v${fp.policy.version}"`,
+              path: `operations.${operation.meta.key}.policy.fieldPolicies`
+            });
+          }
+        }
+      }
+    }
+  }
+  return {
+    valid: issues.filter((i) => i.level === "error").length === 0,
+    issues
+  };
+}
+
+class PolicyValidationError extends Error {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+    this.name = "PolicyValidationError";
+  }
+}
+function assertPolicySpecValid(spec) {
+  const result = validatePolicySpec(spec);
+  if (!result.valid) {
+    throw new PolicyValidationError(`Policy ${spec.meta.key}.v${spec.meta.version} is invalid`, result.issues);
+  }
+}
+function assertPolicyConsistency(deps) {
+  const result = validatePolicyConsistency(deps);
+  if (!result.valid) {
+    throw new PolicyValidationError("Policy consistency check failed", result.issues);
+  }
+}
+
+// src/policy/index.ts
+var definePolicy = (spec2) => spec2;
+export {
+  validatePolicySpec,
+  validatePolicyConsistency,
+  filterOperationsByPolicy,
+  definePolicy,
+  createPolicyContext,
+  createBypassPolicyContext,
+  createAnonymousPolicyContext,
+  checkRole,
+  checkPolicyForOperation,
+  checkPermission,
+  checkCombinedPolicy,
+  checkAnyRole,
+  checkAllPermissions,
+  buildOPAInput,
+  assertRole,
+  assertPolicySpecValid,
+  assertPolicyForOperation,
+  assertPolicyConsistency,
+  assertPermission,
+  assertCombinedPolicy,
+  PolicyViolationError,
+  PolicyValidationError,
+  PolicyRegistry,
+  PolicyEngine,
+  OPAPolicyAdapter
+};