@contractspec/lib.contracts 1.49.0 → 1.51.0

package/dist/policy/context.js

@@ -0,0 +1,227 @@
+//#region src/policy/context.ts
+/**
+* Runtime policy context for opt-in policy enforcement.
+*
+* Provides a context object that can be used to check if a user/tenant
+* has specific roles, permissions, and attributes at runtime.
+*
+* @module policy/context
+*
+* @example
+* ```typescript
+* import { createPolicyContext } from '@contractspec/lib.contracts';
+*
+* // Create context from user's roles and permissions
+* const ctx = createPolicyContext({
+*   id: 'user-123',
+*   tenantId: 'tenant-456',
+*   roles: ['admin', 'editor'],
+*   permissions: ['read:articles', 'write:articles'],
+*   attributes: { department: 'engineering' },
+* });
+*
+* // Check roles and permissions
+* if (ctx.hasRole('admin')) {
+*   // User has admin role
+* }
+*
+* // Audit access attempts
+* ctx.auditAccess('article.update', 'allowed');
+* ```
+*/
+/**
+* Error thrown when a policy violation occurs.
+*/
+var PolicyViolationError = class 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"}`;
+	}
+}
+var PolicyContextImpl = class {
+	user;
+	roles;
+	permissions;
+	rateLimitStates = /* @__PURE__ */ 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) return {
+			allowed: false,
+			remaining: 0,
+			resetAt: new Date(state.windowStart + config.windowMs),
+			retryAfterMs: state.windowStart + config.windowMs - now
+		};
+		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: /* @__PURE__ */ new Date(),
+			operation,
+			result,
+			reason,
+			userId: this.user.id,
+			tenantId: this.user.tenantId,
+			attributes: this.user.attributes
+		};
+		Promise.resolve(this.auditHandler(entry)).catch(() => {});
+	}
+};
+/**
+* Creates a policy context from user information.
+*
+* @param user - User information for policy evaluation
+* @param options - Additional context options
+* @returns PolicyContext for checking/requiring policy compliance
+*
+* @example
+* ```typescript
+* const ctx = createPolicyContext({
+*   id: 'user-123',
+*   roles: ['editor'],
+*   permissions: ['read:articles'],
+*   attributes: { department: 'marketing' },
+* });
+*
+* ctx.requireRole('editor');
+* ctx.requirePermission('read:articles');
+* ```
+*/
+function createPolicyContext(user, options) {
+	return new PolicyContextImpl(user, options);
+}
+/**
+* Creates an empty policy context (no roles/permissions).
+* Useful for anonymous users or testing.
+*/
+function createAnonymousPolicyContext(options) {
+	return new PolicyContextImpl({
+		id: "anonymous",
+		roles: [],
+		permissions: [],
+		attributes: {}
+	}, options);
+}
+/**
+* Creates a bypass policy context with all roles/permissions.
+* Useful for admin users or internal services.
+*
+* @param allRoles - All roles to grant
+* @param allPermissions - All permissions to grant
+*/
+function createBypassPolicyContext(allRoles, allPermissions, options) {
+	return new PolicyContextImpl({
+		id: "system",
+		roles: allRoles,
+		permissions: allPermissions,
+		attributes: { bypass: true }
+	}, options);
+}
+
+//#endregion
+export { PolicyViolationError, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext };

package/dist/policy/guards.d.ts

@@ -0,0 +1,145 @@
+import { AnyOperationSpec } from "../operations/operation.js";
+import { PolicyContext } from "./context.js";
+
+//#region src/policy/guards.d.ts
+
+/** Result of a policy guard check. */
+interface PolicyGuardResult {
+  /** Whether the guard passed. */
+  allowed: boolean;
+  /** Reason for denial if guard failed. */
+  reason?: string;
+  /** Missing requirements if guard failed. */
+  missing?: {
+    roles?: string[];
+    permissions?: string[];
+    flags?: string[];
+  };
+}
+/**
+ * Check if an operation's policy constraints are satisfied.
+ *
+ * @param ctx - Policy context to check against
+ * @param operation - Operation spec to check
+ * @param flags - Available feature flags
+ * @returns Guard result indicating if operation is allowed
+ *
+ * @example
+ * ```typescript
+ * const result = checkPolicyForOperation(ctx, myOperation, ['feature-x']);
+ * if (!result.allowed) {
+ *   console.log('Denied:', result.reason);
+ * }
+ * ```
+ */
+declare function checkPolicyForOperation(ctx: PolicyContext, operation: AnyOperationSpec, flags?: string[]): PolicyGuardResult;
+/**
+ * Assert that an operation's policy constraints are satisfied.
+ *
+ * @param ctx - Policy context to check against
+ * @param operation - Operation spec to check
+ * @param flags - Available feature flags
+ * @throws {PolicyViolationError} If policy is not satisfied
+ *
+ * @example
+ * ```typescript
+ * // Throws if policy not satisfied
+ * assertPolicyForOperation(ctx, myOperation);
+ *
+ * // Safe to proceed with operation
+ * await handler(input);
+ * ```
+ */
+declare function assertPolicyForOperation(ctx: PolicyContext, operation: AnyOperationSpec, flags?: string[]): void;
+/**
+ * Filter operations to only those with satisfied policy constraints.
+ *
+ * @param ctx - Policy context to check against
+ * @param operations - Operations to filter
+ * @param flags - Available feature flags
+ * @returns Operations that have their policies satisfied
+ */
+declare function filterOperationsByPolicy(ctx: PolicyContext, operations: AnyOperationSpec[], flags?: string[]): AnyOperationSpec[];
+/**
+ * Check if user has the required role for an operation.
+ *
+ * @param ctx - Policy context to check against
+ * @param requiredRole - Role required for the operation
+ * @param operation - Optional operation name for error messages
+ * @returns Guard result
+ */
+declare function checkRole(ctx: PolicyContext, requiredRole: string, operation?: string): PolicyGuardResult;
+/**
+ * Assert user has the required role.
+ *
+ * @param ctx - Policy context to check against
+ * @param requiredRole - Role required
+ * @param operation - Optional operation name for error messages
+ * @throws {PolicyViolationError} If role is missing
+ */
+declare function assertRole(ctx: PolicyContext, requiredRole: string, operation?: string): void;
+/**
+ * Check if user has any of the required roles.
+ *
+ * @param ctx - Policy context to check against
+ * @param requiredRoles - Any of these roles is sufficient
+ * @param operation - Optional operation name for error messages
+ * @returns Guard result
+ */
+declare function checkAnyRole(ctx: PolicyContext, requiredRoles: string[], operation?: string): PolicyGuardResult;
+/**
+ * Check if user has the required permission.
+ *
+ * @param ctx - Policy context to check against
+ * @param requiredPermission - Permission required
+ * @param operation - Optional operation name for error messages
+ * @returns Guard result
+ */
+declare function checkPermission(ctx: PolicyContext, requiredPermission: string, operation?: string): PolicyGuardResult;
+/**
+ * Assert user has the required permission.
+ *
+ * @param ctx - Policy context to check against
+ * @param requiredPermission - Permission required
+ * @param operation - Optional operation name for error messages
+ * @throws {PolicyViolationError} If permission is missing
+ */
+declare function assertPermission(ctx: PolicyContext, requiredPermission: string, operation?: string): void;
+/**
+ * Check if user has all of the required permissions.
+ *
+ * @param ctx - Policy context to check against
+ * @param requiredPermissions - All of these permissions are required
+ * @param operation - Optional operation name for error messages
+ * @returns Guard result
+ */
+declare function checkAllPermissions(ctx: PolicyContext, requiredPermissions: string[], operation?: string): PolicyGuardResult;
+interface CombinedPolicyRequirements {
+  roles?: string[];
+  anyRole?: string[];
+  permissions?: string[];
+  anyPermission?: string[];
+  flags?: string[];
+}
+/**
+ * Check multiple policy requirements at once.
+ *
+ * @param ctx - Policy context to check against
+ * @param requirements - Combined requirements to check
+ * @param flags - Available feature flags
+ * @param operation - Optional operation name for error messages
+ * @returns Guard result
+ */
+declare function checkCombinedPolicy(ctx: PolicyContext, requirements: CombinedPolicyRequirements, flags?: string[], operation?: string): PolicyGuardResult;
+/**
+ * Assert multiple policy requirements at once.
+ *
+ * @param ctx - Policy context to check against
+ * @param requirements - Combined requirements to check
+ * @param flags - Available feature flags
+ * @param operation - Optional operation name for error messages
+ * @throws {PolicyViolationError} If any requirement is not met
+ */
+declare function assertCombinedPolicy(ctx: PolicyContext, requirements: CombinedPolicyRequirements, flags?: string[], operation?: string): void;
+//#endregion
+export { CombinedPolicyRequirements, PolicyGuardResult, assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy };

package/dist/policy/guards.js

@@ -0,0 +1,254 @@
+import { PolicyViolationError } from "./context.js";
+
+//#region 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;
+}
+/**
+* Check if an operation's policy constraints are satisfied.
+*
+* @param ctx - Policy context to check against
+* @param operation - Operation spec to check
+* @param flags - Available feature flags
+* @returns Guard result indicating if operation is allowed
+*
+* @example
+* ```typescript
+* const result = checkPolicyForOperation(ctx, myOperation, ['feature-x']);
+* if (!result.allowed) {
+*   console.log('Denied:', result.reason);
+* }
+* ```
+*/
+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"] : void 0 }
+	};
+	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 };
+}
+/**
+* Assert that an operation's policy constraints are satisfied.
+*
+* @param ctx - Policy context to check against
+* @param operation - Operation spec to check
+* @param flags - Available feature flags
+* @throws {PolicyViolationError} If policy is not satisfied
+*
+* @example
+* ```typescript
+* // Throws if policy not satisfied
+* assertPolicyForOperation(ctx, myOperation);
+*
+* // Safe to proceed with operation
+* await handler(input);
+* ```
+*/
+function assertPolicyForOperation(ctx, operation, flags = []) {
+	const result = checkPolicyForOperation(ctx, operation, flags);
+	if (!result.allowed) {
+		const operationName$1 = `${operation.meta.key}.v${operation.meta.version}`;
+		ctx.auditAccess(operationName$1, "denied", result.reason);
+		throw new PolicyViolationError("access_denied", {
+			operation: operationName$1,
+			reason: result.reason
+		});
+	}
+	const operationName = `${operation.meta.key}.v${operation.meta.version}`;
+	ctx.auditAccess(operationName, "allowed");
+}
+/**
+* Filter operations to only those with satisfied policy constraints.
+*
+* @param ctx - Policy context to check against
+* @param operations - Operations to filter
+* @param flags - Available feature flags
+* @returns Operations that have their policies satisfied
+*/
+function filterOperationsByPolicy(ctx, operations, flags = []) {
+	return operations.filter((op) => checkPolicyForOperation(ctx, op, flags).allowed);
+}
+/**
+* Check if user has the required role for an operation.
+*
+* @param ctx - Policy context to check against
+* @param requiredRole - Role required for the operation
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+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] }
+	};
+}
+/**
+* Assert user has the required role.
+*
+* @param ctx - Policy context to check against
+* @param requiredRole - Role required
+* @param operation - Optional operation name for error messages
+* @throws {PolicyViolationError} If role is missing
+*/
+function assertRole(ctx, requiredRole, operation) {
+	if (!checkRole(ctx, requiredRole, operation).allowed) throw new PolicyViolationError("missing_role", {
+		operation,
+		requiredRole
+	});
+}
+/**
+* Check if user has any of the required roles.
+*
+* @param ctx - Policy context to check against
+* @param requiredRoles - Any of these roles is sufficient
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+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 }
+	};
+}
+/**
+* Check if user has the required permission.
+*
+* @param ctx - Policy context to check against
+* @param requiredPermission - Permission required
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+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] }
+	};
+}
+/**
+* Assert user has the required permission.
+*
+* @param ctx - Policy context to check against
+* @param requiredPermission - Permission required
+* @param operation - Optional operation name for error messages
+* @throws {PolicyViolationError} If permission is missing
+*/
+function assertPermission(ctx, requiredPermission, operation) {
+	if (!checkPermission(ctx, requiredPermission, operation).allowed) throw new PolicyViolationError("missing_permission", {
+		operation,
+		requiredPermission
+	});
+}
+/**
+* Check if user has all of the required permissions.
+*
+* @param ctx - Policy context to check against
+* @param requiredPermissions - All of these permissions are required
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+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 }
+	};
+}
+/**
+* Check multiple policy requirements at once.
+*
+* @param ctx - Policy context to check against
+* @param requirements - Combined requirements to check
+* @param flags - Available feature flags
+* @param operation - Optional operation name for error messages
+* @returns Guard result
+*/
+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) return {
+		allowed: false,
+		reason: (operation ? `Operation "${operation}": ` : "") + reasons.join("; "),
+		missing
+	};
+	return { allowed: true };
+}
+/**
+* Assert multiple policy requirements at once.
+*
+* @param ctx - Policy context to check against
+* @param requirements - Combined requirements to check
+* @param flags - Available feature flags
+* @param operation - Optional operation name for error messages
+* @throws {PolicyViolationError} If any requirement is not met
+*/
+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
+	});
+}
+
+//#endregion
+export { assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy };

package/dist/policy/index.d.ts

@@ -2,4 +2,15 @@ import { AttributeMatcher, ConsentDefinition, FieldPolicyRule, PIIPolicy, Policy
 import { PolicyRegistry } from "./registry.js";
 import { DecisionContext, PolicyEngine, ResourceContext, SubjectContext, SubjectRelationship } from "./engine.js";
 import { OPAAdapterOptions, OPAClient, OPAEvaluationResult, OPAPolicyAdapter, buildOPAInput } from "./opa-adapter.js";
-export { AttributeMatcher, ConsentDefinition, DecisionContext, FieldPolicyRule, OPAAdapterOptions, OPAClient, OPAEvaluationResult, OPAPolicyAdapter, PIIPolicy, PolicyCondition, PolicyEffect, PolicyEngine, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRegistry, PolicyRule, PolicySpec, RateLimitDefinition, RelationshipDefinition, RelationshipMatcher, ResourceContext, ResourceMatcher, SubjectContext, SubjectMatcher, SubjectRelationship, buildOPAInput };
+import { AuditEntry, AuditHandler, PolicyContext, PolicyContextOptions, PolicyUser, PolicyViolationDetails, PolicyViolationError, PolicyViolationType, RateLimitResult, RateLimitState, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext } from "./context.js";
+import { CombinedPolicyRequirements, PolicyGuardResult, assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy } from "./guards.js";
+import { PolicyConsistencyDeps, PolicyValidationError, PolicyValidationIssue, PolicyValidationLevel, PolicyValidationResult, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec } from "./validation.js";
+
+//#region src/policy/index.d.ts
+
+/**
+ * Helper to define a Policy.
+ */
+declare const definePolicy: (spec: PolicySpec) => PolicySpec;
+//#endregion
+export { AttributeMatcher, AuditEntry, AuditHandler, CombinedPolicyRequirements, ConsentDefinition, DecisionContext, FieldPolicyRule, OPAAdapterOptions, OPAClient, OPAEvaluationResult, OPAPolicyAdapter, PIIPolicy, PolicyCondition, PolicyConsistencyDeps, PolicyContext, PolicyContextOptions, PolicyEffect, PolicyEngine, PolicyGuardResult, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRegistry, PolicyRule, PolicySpec, PolicyUser, PolicyValidationError, PolicyValidationIssue, PolicyValidationLevel, PolicyValidationResult, PolicyViolationDetails, PolicyViolationError, PolicyViolationType, RateLimitDefinition, RateLimitResult, RateLimitState, RelationshipDefinition, RelationshipMatcher, ResourceContext, ResourceMatcher, SubjectContext, SubjectMatcher, SubjectRelationship, assertCombinedPolicy, assertPermission, assertPolicyConsistency, assertPolicyForOperation, assertPolicySpecValid, assertRole, buildOPAInput, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext, definePolicy, filterOperationsByPolicy, validatePolicyConsistency, validatePolicySpec };

package/dist/policy/index.js

@@ -1,5 +1,15 @@
 import { PolicyRegistry } from "./registry.js";
 import { PolicyEngine } from "./engine.js";
 import { OPAPolicyAdapter, buildOPAInput } from "./opa-adapter.js";
+import { PolicyViolationError, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext } from "./context.js";
+import { assertCombinedPolicy, assertPermission, assertPolicyForOperation, assertRole, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, filterOperationsByPolicy } from "./guards.js";
+import { PolicyValidationError, assertPolicyConsistency, assertPolicySpecValid, validatePolicyConsistency, validatePolicySpec } from "./validation.js";
 
-export { OPAPolicyAdapter, PolicyEngine, PolicyRegistry, buildOPAInput };
+//#region src/policy/index.ts
+/**
+* Helper to define a Policy.
+*/
+const definePolicy = (spec) => spec;
+
+//#endregion
+export { OPAPolicyAdapter, PolicyEngine, PolicyRegistry, PolicyValidationError, PolicyViolationError, assertCombinedPolicy, assertPermission, assertPolicyConsistency, assertPolicyForOperation, assertPolicySpecValid, assertRole, buildOPAInput, checkAllPermissions, checkAnyRole, checkCombinedPolicy, checkPermission, checkPolicyForOperation, checkRole, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext, definePolicy, filterOperationsByPolicy, validatePolicyConsistency, validatePolicySpec };

package/dist/policy/spec.d.ts

@@ -1,6 +1,8 @@
+import { VersionedSpecRef } from "../versioning/refs.js";
 import { OwnerShipMeta } from "../ownership.js";
 
 //#region src/policy/spec.d.ts
+/** Effect of a policy rule: allow or deny access. */
 type PolicyEffect = 'allow' | 'deny';
 interface RelationshipDefinition {
   subjectType: string;
@@ -95,9 +97,10 @@ interface PolicySpec {
   rateLimits?: RateLimitDefinition[];
   opa?: PolicyOPAConfig;
 }
-interface PolicyRef {
-  key: string;
-  version: string;
-}
+/**
+ * Reference to a policy spec.
+ * Uses key and version to identify a specific policy.
+ */
+type PolicyRef = VersionedSpecRef;
 //#endregion
 export { AttributeMatcher, ConsentDefinition, FieldPolicyRule, PIIPolicy, PolicyCondition, PolicyEffect, PolicyMeta, PolicyOPAConfig, PolicyRef, PolicyRule, PolicySpec, RateLimitDefinition, RelationshipDefinition, RelationshipMatcher, ResourceMatcher, SubjectMatcher };