@kya-os/contracts 1.0.0-alpha → 1.2.2

package/dist/delegation/constraints.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * CRISP Delegation Constraints
+ *
+ * Types and schemas for CRISP (Constrained Resource Intent Specification Protocol)
+ * constraints on delegations. CRISP enables fine-grained authorization control.
+ *
+ * Related Spec: MCP-I §4.2
+ * Python Reference: Delegation-Documentation.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WINDOW_DURATION_SEC = exports.MAX_BUDGET_CAP = exports.SUPPORTED_MATCHERS = exports.SUPPORTED_CURRENCIES = exports.DelegationConstraintsSchema = exports.CrispScopeSchema = exports.ScopeMatcherSchema = exports.CrispBudgetSchema = exports.BudgetWindowSchema = exports.WindowKindSchema = exports.CurrencySchema = void 0;
+exports.validateDelegationConstraints = validateDelegationConstraints;
+exports.hasValidTimeRange = hasValidTimeRange;
+exports.areChildConstraintsValid = areChildConstraintsValid;
+exports.doesResourceMatchScope = doesResourceMatchScope;
+const zod_1 = require("zod");
+/**
+ * Currency types for CRISP budgets
+ */
+exports.CurrencySchema = zod_1.z.enum(['USD', 'ops', 'points']);
+/**
+ * Window kind for budget enforcement
+ */
+exports.WindowKindSchema = zod_1.z.enum(['rolling', 'fixed']);
+/**
+ * Budget Window Schema
+ *
+ * Defines the time window for budget enforcement
+ */
+exports.BudgetWindowSchema = zod_1.z.object({
+    /** Type of window (rolling or fixed) */
+    kind: exports.WindowKindSchema,
+    /** Duration in seconds */
+    durationSec: zod_1.z.number().int().positive(),
+});
+/**
+ * CRISP Budget Schema
+ *
+ * Defines spending/usage limits for a delegation
+ */
+exports.CrispBudgetSchema = zod_1.z.object({
+    /** Unit of the budget */
+    unit: exports.CurrencySchema,
+    /** Cap/limit for the budget */
+    cap: zod_1.z.number().nonnegative(),
+    /** Optional time window for the budget */
+    window: exports.BudgetWindowSchema.optional(),
+});
+/**
+ * Scope matcher types
+ */
+exports.ScopeMatcherSchema = zod_1.z.enum(['exact', 'prefix', 'regex']);
+/**
+ * CRISP Scope Schema
+ *
+ * Defines what resources/actions are allowed in a delegation
+ */
+exports.CrispScopeSchema = zod_1.z.object({
+    /** Resource identifier (e.g., "api:users", "data:emails") */
+    resource: zod_1.z.string().min(1),
+    /** How to match the resource */
+    matcher: exports.ScopeMatcherSchema,
+    /** Optional additional constraints on this scope */
+    constraints: zod_1.z.record(zod_1.z.any()).optional(),
+});
+/**
+ * Delegation Constraints Schema (CRISP)
+ *
+ * Complete constraint specification for a delegation
+ */
+exports.DelegationConstraintsSchema = zod_1.z.object({
+    /** Not valid before (Unix timestamp in seconds) */
+    notBefore: zod_1.z.number().int().optional(),
+    /** Not valid after (Unix timestamp in seconds) */
+    notAfter: zod_1.z.number().int().optional(),
+    /** CRISP-specific constraints */
+    crisp: zod_1.z.object({
+        /** Optional budget constraint */
+        budget: exports.CrispBudgetSchema.optional(),
+        /** Required: at least one scope */
+        scopes: zod_1.z.array(exports.CrispScopeSchema).min(1),
+        /** Optional additional CRISP fields */
+    }).passthrough(),
+}).passthrough(); // Allow extensibility
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate delegation constraints
+ *
+ * @param constraints - The constraints to validate
+ * @returns Validation result
+ */
+function validateDelegationConstraints(constraints) {
+    return exports.DelegationConstraintsSchema.safeParse(constraints);
+}
+/**
+ * Check if constraints have a valid time range
+ *
+ * @param constraints - The constraints to check
+ * @returns true if time range is valid or no time range specified
+ */
+function hasValidTimeRange(constraints) {
+    if (constraints.notBefore === undefined && constraints.notAfter === undefined) {
+        return true;
+    }
+    if (constraints.notBefore !== undefined && constraints.notAfter !== undefined) {
+        return constraints.notBefore < constraints.notAfter;
+    }
+    return true;
+}
+/**
+ * Check if child constraints are within parent constraints
+ *
+ * This performs basic structural checks. Full chain validation
+ * requires runtime implementation.
+ *
+ * @param parent - Parent delegation constraints
+ * @param child - Child delegation constraints
+ * @returns true if child is within parent bounds
+ */
+function areChildConstraintsValid(parent, child) {
+    // Time bounds: child must be within parent
+    if (parent.notBefore !== undefined && child.notBefore !== undefined) {
+        if (child.notBefore < parent.notBefore) {
+            return false;
+        }
+    }
+    if (parent.notAfter !== undefined && child.notAfter !== undefined) {
+        if (child.notAfter > parent.notAfter) {
+            return false;
+        }
+    }
+    // Budget: child must be ≤ parent (if same unit)
+    if (parent.crisp.budget &&
+        child.crisp.budget &&
+        parent.crisp.budget.unit === child.crisp.budget.unit) {
+        if (child.crisp.budget.cap > parent.crisp.budget.cap) {
+            return false;
+        }
+    }
+    // Scopes: child scopes must be subset of parent scopes
+    // This is a simplified check - full validation is complex
+    const parentResources = new Set(parent.crisp.scopes.map((s) => s.resource));
+    const allChildResourcesInParent = child.crisp.scopes.every((childScope) => {
+        // Check if child resource matches any parent resource
+        return parent.crisp.scopes.some((parentScope) => {
+            if (parentScope.matcher === 'exact') {
+                return parentScope.resource === childScope.resource;
+            }
+            if (parentScope.matcher === 'prefix') {
+                return childScope.resource.startsWith(parentScope.resource);
+            }
+            // regex matching would require runtime regex evaluation
+            return true; // Can't validate regex at type level
+        });
+    });
+    return allChildResourcesInParent;
+}
+/**
+ * Check if a resource matches a scope
+ *
+ * @param resource - The resource to check
+ * @param scope - The scope to match against
+ * @returns true if resource matches scope
+ */
+function doesResourceMatchScope(resource, scope) {
+    switch (scope.matcher) {
+        case 'exact':
+            return resource === scope.resource;
+        case 'prefix':
+            return resource.startsWith(scope.resource);
+        case 'regex':
+            try {
+                const regex = new RegExp(scope.resource);
+                return regex.test(resource);
+            }
+            catch {
+                return false;
+            }
+        default:
+            return false;
+    }
+}
+/**
+ * Constants
+ */
+/**
+ * Supported currency types
+ */
+exports.SUPPORTED_CURRENCIES = ['USD', 'ops', 'points'];
+/**
+ * Supported scope matchers
+ */
+exports.SUPPORTED_MATCHERS = ['exact', 'prefix', 'regex'];
+/**
+ * Maximum reasonable budget cap (for validation)
+ */
+exports.MAX_BUDGET_CAP = Number.MAX_SAFE_INTEGER;
+/**
+ * Maximum reasonable window duration (10 years in seconds)
+ */
+exports.MAX_WINDOW_DURATION_SEC = 10 * 365 * 24 * 60 * 60;
+//# sourceMappingURL=constraints.js.map

package/dist/delegation/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Delegation Module Exports
+ *
+ * Types and schemas for delegation records and CRISP constraints
+ */
+export * from './schemas.js';
+export * from './constraints.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/delegation/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Delegation Module Exports
+ *
+ * Types and schemas for delegation records and CRISP constraints
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schemas.js"), exports);
+__exportStar(require("./constraints.js"), exports);
+//# sourceMappingURL=index.js.map