@contractspec/lib.contracts 1.61.0 → 1.63.0

package/dist/policy/context.d.ts

@@ -1,235 +0,0 @@
-/**
- * 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.
- */
-export declare class PolicyViolationError extends Error {
-    readonly violationType: PolicyViolationType;
-    readonly details: PolicyViolationDetails;
-    constructor(type: PolicyViolationType, details: PolicyViolationDetails);
-}
-export type PolicyViolationType = 'missing_role' | 'missing_permission' | 'missing_attribute' | 'rate_limit_exceeded' | 'consent_required' | 'access_denied';
-export interface PolicyViolationDetails {
-    operation?: string;
-    requiredRole?: string;
-    requiredPermission?: string;
-    requiredAttribute?: {
-        key: string;
-        expected: unknown;
-    };
-    rateLimitKey?: string;
-    consentIds?: string[];
-    reason?: string;
-}
-export interface RateLimitResult {
-    allowed: boolean;
-    remaining: number;
-    resetAt?: Date;
-    retryAfterMs?: number;
-}
-export interface RateLimitState {
-    key: string;
-    count: number;
-    windowStart: number;
-    windowMs: number;
-    limit: number;
-}
-export interface AuditEntry {
-    timestamp: Date;
-    operation: string;
-    result: 'allowed' | 'denied';
-    reason?: string;
-    userId?: string;
-    tenantId?: string;
-    attributes?: Record<string, unknown>;
-}
-export type AuditHandler = (entry: AuditEntry) => void | Promise<void>;
-/**
- * User information for policy evaluation.
- */
-export 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.
- */
-export 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;
-}
-export 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');
- * ```
- */
-export declare function createPolicyContext(user: PolicyUser, options?: PolicyContextOptions): PolicyContext;
-/**
- * Creates an empty policy context (no roles/permissions).
- * Useful for anonymous users or testing.
- */
-export 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
- */
-export declare function createBypassPolicyContext(allRoles: string[], allPermissions: string[], options?: PolicyContextOptions): PolicyContext;
-//# sourceMappingURL=context.d.ts.map

package/dist/policy/context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/policy/context.ts"],"names":[],"mappings":"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"}

package/dist/policy/context.js

@@ -1,206 +0,0 @@
-// @bun
-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 = import.meta.require;
-
-// 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);
-}
-export {
-  createPolicyContext,
-  createBypassPolicyContext,
-  createAnonymousPolicyContext,
-  PolicyViolationError
-};

package/dist/policy/context.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=context.test.d.ts.map

package/dist/policy/context.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../../src/policy/context.test.ts"],"names":[],"mappings":""}

package/dist/policy/docs/policy.docblock.d.ts

@@ -1,3 +0,0 @@
-import type { DocBlock } from '@contractspec/lib.contracts/docs';
-export declare const tech_contracts_policy_DocBlocks: DocBlock[];
-//# sourceMappingURL=policy.docblock.d.ts.map

package/dist/policy/docs/policy.docblock.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"policy.docblock.d.ts","sourceRoot":"","sources":["../../../src/policy/docs/policy.docblock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,eAAO,MAAM,+BAA+B,EAAE,QAAQ,EAYrD,CAAC"}