@lssm/lib.contracts-spec 17.3.2

package/dist/ownership.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Ownership, stability, and tagging types for ContractSpec.
+ *
+ * Provides canonical enums and metadata interfaces for spec ownership,
+ * lifecycle stages, and categorization.
+ *
+ * @module ownership
+ */
+import type { DocId } from './docs/index.js';
+/**
+ * Lifecycle stability stages for specs.
+ *
+ * Specs progress through these stages as they mature:
+ * - `idea`: Initial concept, not implemented
+ * - `in_creation`: Currently being built
+ * - `experimental`: Working but may change significantly
+ * - `beta`: Feature-complete, seeking feedback
+ * - `stable`: Production-ready, breaking changes require major version bump
+ * - `deprecated`: Scheduled for removal, use alternatives
+ */
+export declare const StabilityEnum: {
+    /** Initial concept, not yet implemented. */
+    readonly Idea: 'idea';
+    /** Currently being built, not ready for use. */
+    readonly InCreation: 'in_creation';
+    /** Working but unstable, may change significantly. */
+    readonly Experimental: 'experimental';
+    /** Feature-complete, seeking feedback before stabilization. */
+    readonly Beta: 'beta';
+    /** Production-ready, follows semantic versioning. */
+    readonly Stable: 'stable';
+    /** Scheduled for removal, use alternatives. */
+    readonly Deprecated: 'deprecated';
+};
+/** Stability level for a spec's lifecycle stage. */
+export type Stability = (typeof StabilityEnum)[keyof typeof StabilityEnum];
+/**
+ * Curated owner identifiers for business/product ownership.
+ *
+ * Used for CODEOWNERS, on-call routing, and approval workflows.
+ * Custom owner strings are also allowed for flexibility.
+ */
+export declare const OwnersEnum: {
+    /** Core platform team. */
+    readonly PlatformCore: 'platform.core';
+    /** Sigil/auth team. */
+    readonly PlatformSigil: 'platform.sigil';
+    /** Marketplace team. */
+    readonly PlatformMarketplace: 'platform.marketplace';
+    /** Messaging/notifications team. */
+    readonly PlatformMessaging: 'platform.messaging';
+    /** Content/CMS team. */
+    readonly PlatformContent: 'platform.content';
+    /** Feature flags team. */
+    readonly PlatformFeatureFlags: 'platform.featureflags';
+    /** Finance/billing team. */
+    readonly PlatformFinance: 'platform.finance';
+};
+/**
+ * Owner identifier for a spec.
+ * Can be a predefined OwnersEnum value or any custom string.
+ */
+export type Owner = (typeof OwnersEnum)[keyof typeof OwnersEnum] | (string & {});
+export declare const Owners: {
+    /** Core platform team. */
+    readonly PlatformCore: 'platform.core';
+    /** Sigil/auth team. */
+    readonly PlatformSigil: 'platform.sigil';
+    /** Marketplace team. */
+    readonly PlatformMarketplace: 'platform.marketplace';
+    /** Messaging/notifications team. */
+    readonly PlatformMessaging: 'platform.messaging';
+    /** Content/CMS team. */
+    readonly PlatformContent: 'platform.content';
+    /** Feature flags team. */
+    readonly PlatformFeatureFlags: 'platform.featureflags';
+    /** Finance/billing team. */
+    readonly PlatformFinance: 'platform.finance';
+};
+/**
+ * Common tags for categorizing specs.
+ *
+ * Used for search, grouping, and documentation navigation.
+ * Custom tag strings are also allowed for flexibility.
+ */
+export declare const TagsEnum: {
+    /** Spots/locations domain. */
+    readonly Spots: 'spots';
+    /** Collectivity/community domain. */
+    readonly Collectivity: 'collectivity';
+    /** Marketplace domain. */
+    readonly Marketplace: 'marketplace';
+    /** Seller-related features. */
+    readonly Sellers: 'sellers';
+    /** Authentication features. */
+    readonly Auth: 'auth';
+    /** Login flows. */
+    readonly Login: 'login';
+    /** Signup flows. */
+    readonly Signup: 'signup';
+    /** Onboarding/guides. */
+    readonly Guide: 'guide';
+    /** Documentation. */
+    readonly Docs: 'docs';
+    /** Internationalization. */
+    readonly I18n: 'i18n';
+    /** Incident management. */
+    readonly Incident: 'incident';
+    /** Automation/workflows. */
+    readonly Automation: 'automation';
+    /** Code hygiene/maintenance. */
+    readonly Hygiene: 'hygiene';
+};
+/**
+ * Tag for categorizing a spec.
+ * Can be a predefined TagsEnum value or any custom string.
+ */
+export type Tag = (typeof TagsEnum)[keyof typeof TagsEnum] | (string & {});
+export declare const Tags: {
+    /** Spots/locations domain. */
+    readonly Spots: 'spots';
+    /** Collectivity/community domain. */
+    readonly Collectivity: 'collectivity';
+    /** Marketplace domain. */
+    readonly Marketplace: 'marketplace';
+    /** Seller-related features. */
+    readonly Sellers: 'sellers';
+    /** Authentication features. */
+    readonly Auth: 'auth';
+    /** Login flows. */
+    readonly Login: 'login';
+    /** Signup flows. */
+    readonly Signup: 'signup';
+    /** Onboarding/guides. */
+    readonly Guide: 'guide';
+    /** Documentation. */
+    readonly Docs: 'docs';
+    /** Internationalization. */
+    readonly I18n: 'i18n';
+    /** Incident management. */
+    readonly Incident: 'incident';
+    /** Automation/workflows. */
+    readonly Automation: 'automation';
+    /** Code hygiene/maintenance. */
+    readonly Hygiene: 'hygiene';
+};
+/**
+ * Common metadata interface for all ContractSpec specifications.
+ *
+ * Every spec type (operations, events, presentations, etc.) extends this
+ * interface to provide consistent ownership, versioning, and discoverability.
+ *
+ * @example
+ * ```typescript
+ * const meta: OwnerShipMeta = {
+ *   key: 'auth.login',
+ *   version: '1.0.0',
+ *   description: 'Authenticates a user with email and password',
+ *   stability: StabilityEnum.Stable,
+ *   owners: [OwnersEnum.PlatformSigil],
+ *   tags: [TagsEnum.Auth, TagsEnum.Login],
+ * };
+ * ```
+ */
+export interface OwnerShipMeta {
+    /**
+     * Semantic version string (e.g., "1.0.0").
+     * Bump for breaking changes according to semver rules.
+     */
+    version: string;
+    /**
+     * Fully-qualified spec key (e.g., "sigil.beginSignup", "user.created").
+     * Must be unique within the spec type.
+     */
+    key: string;
+    /**
+     * Human-friendly title (e.g., "Begin Signup").
+     * Used in documentation and UI.
+     */
+    title?: string;
+    /**
+     * Short human-friendly summary of what this spec does.
+     * Should be concise (1-2 sentences).
+     */
+    description: string;
+    /**
+     * Business domain this spec belongs to (e.g., "auth", "marketplace").
+     * Used for grouping and discovery.
+     */
+    domain?: string;
+    /**
+     * Lifecycle stability marker.
+     * Indicates maturity level and change expectations.
+     */
+    stability: Stability;
+    /**
+     * Team/individual owners responsible for this spec.
+     * Used for CODEOWNERS, on-call routing, and approvals.
+     */
+    owners: Owner[];
+    /**
+     * Tags for search, grouping, and documentation navigation.
+     */
+    tags: Tag[];
+    /**
+     * Associated DocBlock identifiers for documentation linkage.
+     */
+    docId?: DocId[];
+}

package/dist/ownership.js

@@ -0,0 +1 @@
+export const StabilityEnum={Idea:"idea",InCreation:"in_creation",Experimental:"experimental",Beta:"beta",Stable:"stable",Deprecated:"deprecated"};export const OwnersEnum={PlatformCore:"platform.core",PlatformSigil:"platform.sigil",PlatformMarketplace:"platform.marketplace",PlatformMessaging:"platform.messaging",PlatformContent:"platform.content",PlatformFeatureFlags:"platform.featureflags",PlatformFinance:"platform.finance"};export const Owners=OwnersEnum;export const TagsEnum={Spots:"spots",Collectivity:"collectivity",Marketplace:"marketplace",Sellers:"sellers",Auth:"auth",Login:"login",Signup:"signup",Guide:"guide",Docs:"docs",I18n:"i18n",Incident:"incident",Automation:"automation",Hygiene:"hygiene"};export const Tags=TagsEnum;

package/dist/policy/context.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 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 '@lssm/lib.contracts-spec';
+ *
+ * // 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;

package/dist/policy/context.js

@@ -0,0 +1 @@
+class s{user;roles;permissions;rateLimitStates=new Map;rateLimitConfigs;auditHandler;constructor(e,t={}){this.user=e;this.roles=new Set(e.roles);this.permissions=new Set(e.permissions);this.rateLimitConfigs=t.rateLimits??{};this.auditHandler=t.auditHandler}hasRole(e){return this.roles.has(e)}hasAnyRole(e){return e.some((t)=>this.roles.has(t))}hasAllRoles(e){return e.every((t)=>this.roles.has(t))}requireRole(e){if(!this.hasRole(e))throw new PolicyViolationError("missing_role",{requiredRole:e})}hasPermission(e){return this.permissions.has(e)}hasAnyPermission(e){return e.some((t)=>this.permissions.has(t))}hasAllPermissions(e){return e.every((t)=>this.permissions.has(t))}requirePermission(e){if(!this.hasPermission(e))throw new PolicyViolationError("missing_permission",{requiredPermission:e})}getAttribute(e){return this.user.attributes[e]}checkAttribute(e,t){return this.user.attributes[e]===t}checkAttributeOneOf(e,t){return t.includes(this.user.attributes[e])}checkRateLimit(e){const t=this.rateLimitConfigs[e];if(!t)return{allowed:!0,remaining:1/0};const i=Date.now(),r=this.rateLimitStates.get(e);if(!r||i-r.windowStart>=t.windowMs)return{allowed:!0,remaining:t.limit};const n=Math.max(0,t.limit-r.count);if(n<=0){const o=new Date(r.windowStart+t.windowMs),a=r.windowStart+t.windowMs-i;return{allowed:!1,remaining:0,resetAt:o,retryAfterMs:a}}return{allowed:!0,remaining:n}}consumeRateLimit(e,t=1){const i=this.rateLimitConfigs[e];if(!i)return{allowed:!0,remaining:1/0};const r=Date.now();let n=this.rateLimitStates.get(e);if(!n||r-n.windowStart>=i.windowMs)n={key:e,count:0,windowStart:r,windowMs:i.windowMs,limit:i.limit};if(n.count+t>i.limit){const o=new Date(n.windowStart+i.windowMs),a=n.windowStart+i.windowMs-r;this.rateLimitStates.set(e,n);return{allowed:!1,remaining:Math.max(0,i.limit-n.count),resetAt:o,retryAfterMs:a}}n.count+=t;this.rateLimitStates.set(e,n);return{allowed:!0,remaining:Math.max(0,i.limit-n.count)}}auditAccess(e,t,i){if(!this.auditHandler)return;const r={timestamp:new Date,operation:e,result:t,reason:i,userId:this.user.id,tenantId:this.user.tenantId,attributes:this.user.attributes};Promise.resolve(this.auditHandler(r)).catch(()=>{})}}export class PolicyViolationError extends Error{violationType;details;constructor(e,t){const i=l(e,t);super(i);this.name="PolicyViolationError";this.violationType=e;this.details=t}}function l(e,t){const i=t.operation?`Policy violation for "${t.operation}": `:"Policy violation: ";switch(e){case"missing_role":return`${i}Missing required role "${t.requiredRole}"`;case"missing_permission":return`${i}Missing required permission "${t.requiredPermission}"`;case"missing_attribute":return`${i}Missing or invalid attribute "${t.requiredAttribute?.key}"`;case"rate_limit_exceeded":return`${i}Rate limit exceeded for key "${t.rateLimitKey}"`;case"consent_required":return`${i}Consent required: ${t.consentIds?.join(", ")}`;case"access_denied":return`${i}${t.reason??"Access denied"}`}}export function createPolicyContext(e,t){return new s(e,t)}export function createAnonymousPolicyContext(e){return new s({id:"anonymous",roles:[],permissions:[],attributes:{}},e)}export function createBypassPolicyContext(e,t,i){return new s({id:"system",roles:e,permissions:t,attributes:{bypass:!0}},i)}

package/dist/policy/engine.d.ts

@@ -0,0 +1,36 @@
+import type { PolicyDecision } from '../types.js';
+import { PolicyRegistry } from './registry.js';
+import { type PolicyRef } from './spec.js';
+export interface SubjectRelationship {
+    relation: string;
+    object: string;
+    objectType?: string;
+}
+export interface SubjectContext {
+    roles?: string[];
+    attributes?: Record<string, unknown>;
+    relationships?: SubjectRelationship[];
+}
+export interface ResourceContext {
+    type: string;
+    id?: string;
+    fields?: string[];
+    attributes?: Record<string, unknown>;
+}
+export interface DecisionContext {
+    subject: SubjectContext;
+    resource: ResourceContext;
+    context?: Record<string, unknown>;
+    action: string;
+    policies: PolicyRef[];
+    consents?: string[];
+    flags?: string[];
+}
+export declare class PolicyEngine {
+    private readonly registry;
+    constructor(registry: PolicyRegistry);
+    decide(input: DecisionContext): PolicyDecision;
+    private resolvePolicies;
+    private matchRuleSet;
+    private evaluateFields;
+}

package/dist/policy/engine.js

@@ -0,0 +1 @@
+export class PolicyEngine{registry;constructor(n){this.registry=n}decide(n){const t=this.resolvePolicies(n.policies);let i,e,o;for(const u of t){const r=this.matchRuleSet(u,n);if(!r)continue;if(r.rule.effect==="deny")return{effect:"deny",reason:r.rule.reason??u.meta.key,requiredConsents:r.missingConsents.length?r.missingConsents:void 0,evaluatedBy:"engine"};if(r.rule.effect==="allow"){if(r.missingConsents.length)return{effect:"deny",reason:"consent_required",requiredConsents:r.missingConsents,evaluatedBy:"engine"};if(!i)i=r.rule.reason??u.meta.key;if(!e&&r.rateLimit)e=r.rateLimit;if(!o&&r.rule.escalate)o=r.rule.escalate}}const s=this.evaluateFields(t,n),c=t.find((u)=>u.pii)?.pii;return{effect:i?"allow":"deny",reason:i,rateLimit:e,escalate:typeof o>"u"?void 0:o,fieldDecisions:s.length?s:void 0,pii:c,evaluatedBy:"engine"}}resolvePolicies(n){const t=[];for(const i of n){const e=this.registry.get(i.key,i.version);if(!e)throw Error(`PolicyEngine: policy not found ${i.key}.v${i.version}`);t.push(e)}return t}matchRuleSet(n,t){let i;for(const e of n.rules){if(!e.actions.includes(t.action))continue;if(!l(e,t.subject))continue;if(!f(e,t.resource))continue;if(!p(e,t))continue;if(!b(e.relationships,t))continue;if(!a(e,t))continue;const o=m(e,n,t),s=h(e,n,t),c={rule:e,missingConsents:o,rateLimit:s};if(e.effect==="deny")return c;if(e.effect==="allow"&&!i)i=c}return i}evaluateFields(n,t){const i=new Map;for(const e of n){if(!e.fieldPolicies)continue;for(const o of e.fieldPolicies){if(!o.actions.includes(g(t.action)))continue;if(!l(o,t.subject))continue;if(!f(o,t.resource))continue;if(!a(o,t))continue;const s=i.get(o.field);if(o.effect==="deny")i.set(o.field,{field:o.field,effect:"deny",reason:o.reason??e.meta.key});else if(!s)i.set(o.field,{field:o.field,effect:"allow",reason:o.reason??e.meta.key})}}return[...i.values()]}}function g(n){if(n.startsWith("write"))return"write";return"read"}function l(n,t){const i=n.subject;if(!i)return!0;if(i.roles?.length){const e=t.roles??[];if(!i.roles.some((s)=>e.includes(s)))return!1}if(i.attributes){const e=t.attributes??{};if(!d(i.attributes,e))return!1}return!0}function f(n,t){const i=n.resource;if(!i)return!0;if(i.type&&i.type!==t.type)return!1;if(i.fields?.length){const e=t.fields??[];if(!i.fields.some((o)=>e.includes(o)))return!1}if(i.attributes){const e=t.attributes??{};if(!d(i.attributes,e))return!1}return!0}function p(n,t){if(!n.flags?.length)return!0;const i=new Set;if(t.flags)for(const o of t.flags)i.add(o);const e=t.subject.attributes?.featureFlags;if(Array.isArray(e))for(const o of e)i.add(o);return n.flags.every((o)=>i.has(o))}function b(n,t){if(!n||n.length===0)return!0;const i=t.subject.relationships??[],e=j(t.resource),o=t.resource.type;return n.every((s)=>i.some((c)=>{if(c.relation!==s.relation)return!1;if(!(!s.objectType||c.objectType===s.objectType||s.objectType===o))return!1;if(!s.objectId)return!0;if(s.objectId==="$resource"){if(e)return c.object===e;return c.object===o||c.objectType===o}return c.object===s.objectId}))}function a(n,t){if(!n.conditions||n.conditions.length===0)return!0;return n.conditions.every((i)=>C(i.expression,t))}function d(n,t){for(const[i,e]of Object.entries(n)){const o=t[i];if(e.exists&&typeof o>"u")return!1;if(typeof e.equals<"u"){if(o!==e.equals)return!1}if(e.oneOf&&!e.oneOf.includes(o))return!1}return!0}function m(n,t,i){if(!n.requiresConsent?.length)return[];const e=new Set(i.consents??[]),o=n.requiresConsent.filter((s)=>!e.has(s));if(o.length===0)return[];return R(t,o)}function R(n,t){const i=n.consents??[];return t.map((e)=>{return i.find((s)=>s.id===e)??{id:e,scope:"unspecified",purpose:"unspecified",description:`Consent "${e}" required by ${n.meta.key}`,required:!0}})}function h(n,t,i){if(!n.rateLimit)return;const e=typeof n.rateLimit==="string"?(t.rateLimits??[]).find((o)=>o.id===n.rateLimit):n.rateLimit;if(!e)throw Error(`PolicyEngine: rate limit "${String(n.rateLimit)}" not declared in ${t.meta.key}`);return{rpm:e.rpm,key:e.key??i.resource.type,windowSeconds:e.windowSeconds,burst:e.burst}}function C(n,t){const i=n.trim();if(!i)return!0;const e={subject:t.subject,resource:t.resource,context:t.context??{}};try{const s=Function("subject","resource","context",`return (${P(i)});`)(e.subject,e.resource,e.context);return Boolean(s)}catch(o){return!1}}function P(n){return n.replace(/&&/g,"&&").replace(/\|\|/g,"||")}function j(n){if(n.id)return n.id;const t=n.attributes?.id;if(typeof t==="string")return t;if(typeof t==="number")return String(t);return}

package/dist/policy/guards.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Policy guards for runtime enforcement.
+ *
+ * Provides utilities to assert that operations have their required
+ * policy constraints satisfied before execution.
+ *
+ * @module policy/guards
+ *
+ * @example
+ * ```typescript
+ * import { assertPolicyForOperation } from '@lssm/lib.contracts-spec';
+ *
+ * // In a handler or middleware
+ * assertPolicyForOperation(ctx, operation);
+ * ```
+ */
+import type { AnyOperationSpec } from '../operations/operation.js';
+import type { PolicyContext } from './context.js';
+import type { CombinedPolicyRequirements } from './requirements.js';
+/** Result of a policy guard check. */
+export 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);
+ * }
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export declare function checkAllPermissions(ctx: PolicyContext, requiredPermissions: string[], operation?: string): PolicyGuardResult;
+/**
+ * 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
+ */
+export 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
+ */
+export declare function assertCombinedPolicy(ctx: PolicyContext, requirements: CombinedPolicyRequirements, flags?: string[], operation?: string): void;

package/dist/policy/guards.js

@@ -0,0 +1 @@
+import{PolicyViolationError as a}from"./context.js";const f=["anonymous","user","admin","internal"];function m(s){return f.indexOf(s)}function u(s,n){if(n==="anonymous")return!0;if(n==="user")return s.user.id!=="anonymous";if(n==="admin")return s.hasRole("admin");if(n==="internal")return s.hasRole("internal")||s.hasPermission("internal:invoke");return!1}export function checkPolicyForOperation(s,n,e=[]){const{policy:i}=n,o=`${n.meta.key}.v${n.meta.version}`,t={};if(!u(s,i.auth))return{allowed:!1,reason:`Operation "${o}" requires "${i.auth}" auth level`,missing:{roles:i.auth==="admin"?["admin"]:void 0}};if(i.flags?.length){const r=new Set(e),l=i.flags.filter((c)=>!r.has(c));if(l.length>0){t.flags=l;return{allowed:!1,reason:`Operation "${o}" requires feature flags: ${l.join(", ")}`,missing:t}}}return{allowed:!0}}export function assertPolicyForOperation(s,n,e=[]){const i=checkPolicyForOperation(s,n,e);if(!i.allowed){const t=`${n.meta.key}.v${n.meta.version}`;s.auditAccess(t,"denied",i.reason);throw new a("access_denied",{operation:t,reason:i.reason})}const o=`${n.meta.key}.v${n.meta.version}`;s.auditAccess(o,"allowed")}export function filterOperationsByPolicy(s,n,e=[]){return n.filter((i)=>checkPolicyForOperation(s,i,e).allowed)}export function checkRole(s,n,e){if(s.hasRole(n))return{allowed:!0};return{allowed:!1,reason:e?`Operation "${e}" requires role "${n}"`:`Missing required role "${n}"`,missing:{roles:[n]}}}export function assertRole(s,n,e){if(!checkRole(s,n,e).allowed)throw new a("missing_role",{operation:e,requiredRole:n})}export function checkAnyRole(s,n,e){if(s.hasAnyRole(n))return{allowed:!0};return{allowed:!1,reason:e?`Operation "${e}" requires one of roles: ${n.join(", ")}`:`Missing required role (need one of: ${n.join(", ")})`,missing:{roles:n}}}export function checkPermission(s,n,e){if(s.hasPermission(n))return{allowed:!0};return{allowed:!1,reason:e?`Operation "${e}" requires permission "${n}"`:`Missing required permission "${n}"`,missing:{permissions:[n]}}}export function assertPermission(s,n,e){if(!checkPermission(s,n,e).allowed)throw new a("missing_permission",{operation:e,requiredPermission:n})}export function checkAllPermissions(s,n,e){const i=n.filter((o)=>!s.hasPermission(o));if(i.length===0)return{allowed:!0};return{allowed:!1,reason:e?`Operation "${e}" requires permissions: ${i.join(", ")}`:`Missing required permissions: ${i.join(", ")}`,missing:{permissions:i}}}export function checkCombinedPolicy(s,n,e=[],i){const o={},t=[];if(n.roles?.length){const r=n.roles.filter((l)=>!s.hasRole(l));if(r.length>0){o.roles=r;t.push(`Missing roles: ${r.join(", ")}`)}}if(n.anyRole?.length){if(!s.hasAnyRole(n.anyRole)){o.roles=[...o.roles??[],...n.anyRole];t.push(`Need one of roles: ${n.anyRole.join(", ")}`)}}if(n.permissions?.length){const r=n.permissions.filter((l)=>!s.hasPermission(l));if(r.length>0){o.permissions=r;t.push(`Missing permissions: ${r.join(", ")}`)}}if(n.anyPermission?.length){if(!s.hasAnyPermission(n.anyPermission)){o.permissions=[...o.permissions??[],...n.anyPermission];t.push(`Need one of permissions: ${n.anyPermission.join(", ")}`)}}if(n.flags?.length){const r=new Set(e),l=n.flags.filter((c)=>!r.has(c));if(l.length>0){o.flags=l;t.push(`Missing feature flags: ${l.join(", ")}`)}}if(t.length>0)return{allowed:!1,reason:(i?`Operation "${i}": `:"")+t.join("; "),missing:o};return{allowed:!0}}export function assertCombinedPolicy(s,n,e=[],i){const o=checkCombinedPolicy(s,n,e,i);if(!o.allowed)throw new a("access_denied",{operation:i,reason:o.reason})}

package/dist/policy/index.d.ts

@@ -0,0 +1,13 @@
+export * from './context.js';
+export * from './engine.js';
+export * from './guards.js';
+export * from './opa-adapter.js';
+export * from './registry.js';
+export * from './requirements.js';
+export * from './spec.js';
+export * from './validation.js';
+import type { PolicySpec } from './spec.js';
+/**
+ * Helper to define a Policy.
+ */
+export declare const definePolicy: (spec: PolicySpec) => PolicySpec;

package/dist/policy/index.js

@@ -0,0 +1 @@
+export*from"./context.js";export*from"./engine.js";export*from"./guards.js";export*from"./opa-adapter.js";export*from"./registry.js";export*from"./requirements.js";export*from"./spec.js";export*from"./validation.js";export const definePolicy=(o)=>o;