@contractspec/lib.contracts 1.50.0 → 1.51.0

package/dist/policy/context.d.ts

@@ -0,0 +1,237 @@
+//#region src/policy/context.d.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.
+ */
+declare class PolicyViolationError extends Error {
+  readonly violationType: PolicyViolationType;
+  readonly details: PolicyViolationDetails;
+  constructor(type: PolicyViolationType, details: PolicyViolationDetails);
+}
+type PolicyViolationType = 'missing_role' | 'missing_permission' | 'missing_attribute' | 'rate_limit_exceeded' | 'consent_required' | 'access_denied';
+interface PolicyViolationDetails {
+  operation?: string;
+  requiredRole?: string;
+  requiredPermission?: string;
+  requiredAttribute?: {
+    key: string;
+    expected: unknown;
+  };
+  rateLimitKey?: string;
+  consentIds?: string[];
+  reason?: string;
+}
+interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetAt?: Date;
+  retryAfterMs?: number;
+}
+interface RateLimitState {
+  key: string;
+  count: number;
+  windowStart: number;
+  windowMs: number;
+  limit: number;
+}
+interface AuditEntry {
+  timestamp: Date;
+  operation: string;
+  result: 'allowed' | 'denied';
+  reason?: string;
+  userId?: string;
+  tenantId?: string;
+  attributes?: Record<string, unknown>;
+}
+type AuditHandler = (entry: AuditEntry) => void | Promise<void>;
+/**
+ * User information for policy evaluation.
+ */
+interface PolicyUser {
+  /** Unique user identifier. */
+  id: string;
+  /** Optional tenant/organization ID for multi-tenant contexts. */
+  tenantId?: string;
+  /** Roles assigned to the user. */
+  roles: string[];
+  /** Permissions granted to the user. */
+  permissions: string[];
+  /** Additional attributes for ABAC evaluation. */
+  attributes: Record<string, unknown>;
+}
+/**
+ * Runtime context for checking policy access.
+ *
+ * Created from user information (roles, permissions, attributes).
+ * Provides methods to check and require policy compliance at runtime.
+ */
+interface PolicyContext {
+  /** The user for this context. */
+  readonly user: PolicyUser;
+  /** Set of user roles. */
+  readonly roles: ReadonlySet<string>;
+  /** Set of user permissions. */
+  readonly permissions: ReadonlySet<string>;
+  /**
+   * Check if user has a specific role.
+   * @param role - Role to check
+   * @returns True if user has the role
+   */
+  hasRole(role: string): boolean;
+  /**
+   * Check if user has any of the specified roles.
+   * @param roles - Roles to check
+   * @returns True if user has at least one role
+   */
+  hasAnyRole(roles: string[]): boolean;
+  /**
+   * Check if user has all of the specified roles.
+   * @param roles - Roles to check
+   * @returns True if user has all roles
+   */
+  hasAllRoles(roles: string[]): boolean;
+  /**
+   * Require a role, throwing if not present.
+   * @param role - Role to require
+   * @throws {PolicyViolationError} If role is missing
+   */
+  requireRole(role: string): void;
+  /**
+   * Check if user has a specific permission.
+   * @param permission - Permission to check
+   * @returns True if user has the permission
+   */
+  hasPermission(permission: string): boolean;
+  /**
+   * Check if user has any of the specified permissions.
+   * @param permissions - Permissions to check
+   * @returns True if user has at least one permission
+   */
+  hasAnyPermission(permissions: string[]): boolean;
+  /**
+   * Check if user has all of the specified permissions.
+   * @param permissions - Permissions to check
+   * @returns True if user has all permissions
+   */
+  hasAllPermissions(permissions: string[]): boolean;
+  /**
+   * Require a permission, throwing if not present.
+   * @param permission - Permission to require
+   * @throws {PolicyViolationError} If permission is missing
+   */
+  requirePermission(permission: string): void;
+  /**
+   * Get a user attribute value.
+   * @param key - Attribute key
+   * @returns Attribute value or undefined
+   */
+  getAttribute<T = unknown>(key: string): T | undefined;
+  /**
+   * Check if an attribute matches an expected value.
+   * @param key - Attribute key
+   * @param expected - Expected value
+   * @returns True if attribute equals expected value
+   */
+  checkAttribute(key: string, expected: unknown): boolean;
+  /**
+   * Check if an attribute is one of the allowed values.
+   * @param key - Attribute key
+   * @param allowedValues - Array of allowed values
+   * @returns True if attribute is in allowed values
+   */
+  checkAttributeOneOf(key: string, allowedValues: unknown[]): boolean;
+  /**
+   * Check rate limit for a key.
+   * @param key - Rate limit key (e.g., operation name)
+   * @returns Rate limit result
+   */
+  checkRateLimit(key: string): RateLimitResult;
+  /**
+   * Consume rate limit for a key (increment counter).
+   * @param key - Rate limit key
+   * @param cost - Cost of the operation (default: 1)
+   * @returns Rate limit result after consumption
+   */
+  consumeRateLimit(key: string, cost?: number): RateLimitResult;
+  /**
+   * Record an access attempt for audit purposes.
+   * @param operation - Operation being accessed
+   * @param result - Whether access was allowed or denied
+   * @param reason - Optional reason for the decision
+   */
+  auditAccess(operation: string, result: 'allowed' | 'denied', reason?: string): void;
+}
+interface PolicyContextOptions {
+  /** Rate limit configurations by key. */
+  rateLimits?: Record<string, {
+    limit: number;
+    windowMs: number;
+  }>;
+  /** Handler for audit entries. */
+  auditHandler?: AuditHandler;
+}
+/**
+ * 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');
+ * ```
+ */
+declare function createPolicyContext(user: PolicyUser, options?: PolicyContextOptions): PolicyContext;
+/**
+ * Creates an empty policy context (no roles/permissions).
+ * Useful for anonymous users or testing.
+ */
+declare function createAnonymousPolicyContext(options?: PolicyContextOptions): PolicyContext;
+/**
+ * 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
+ */
+declare function createBypassPolicyContext(allRoles: string[], allPermissions: string[], options?: PolicyContextOptions): PolicyContext;
+//#endregion
+export { AuditEntry, AuditHandler, PolicyContext, PolicyContextOptions, PolicyUser, PolicyViolationDetails, PolicyViolationError, PolicyViolationType, RateLimitResult, RateLimitState, createAnonymousPolicyContext, createBypassPolicyContext, createPolicyContext };

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 };