@kya-os/contracts 1.5.3-canary.16 → 1.5.3-canary.17

package/src/delegation/constraints.ts

@@ -0,0 +1,267 @@
+/**
+ * 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
+ */
+
+import { z } from 'zod';
+
+/**
+ * Currency types for CRISP budgets
+ */
+export const CurrencySchema = z.enum(['USD', 'ops', 'points']);
+export type Currency = z.infer<typeof CurrencySchema>;
+
+/**
+ * Window kind for budget enforcement
+ */
+export const WindowKindSchema = z.enum(['rolling', 'fixed']);
+export type WindowKind = z.infer<typeof WindowKindSchema>;
+
+/**
+ * Budget Window Schema
+ *
+ * Defines the time window for budget enforcement
+ */
+export const BudgetWindowSchema = z.object({
+  /** Type of window (rolling or fixed) */
+  kind: WindowKindSchema,
+
+  /** Duration in seconds */
+  durationSec: z.number().int().positive(),
+});
+
+export type BudgetWindow = z.infer<typeof BudgetWindowSchema>;
+
+/**
+ * CRISP Budget Schema
+ *
+ * Defines spending/usage limits for a delegation
+ */
+export const CrispBudgetSchema = z.object({
+  /** Unit of the budget */
+  unit: CurrencySchema,
+
+  /** Cap/limit for the budget */
+  cap: z.number().nonnegative(),
+
+  /** Optional time window for the budget */
+  window: BudgetWindowSchema.optional(),
+});
+
+export type CrispBudget = z.infer<typeof CrispBudgetSchema>;
+
+/**
+ * Scope matcher types
+ */
+export const ScopeMatcherSchema = z.enum(['exact', 'prefix', 'regex']);
+export type ScopeMatcher = z.infer<typeof ScopeMatcherSchema>;
+
+/**
+ * CRISP Scope Schema
+ *
+ * Defines what resources/actions are allowed in a delegation
+ */
+export const CrispScopeSchema = z.object({
+  /** Resource identifier (e.g., "api:users", "data:emails") */
+  resource: z.string().min(1),
+
+  /** How to match the resource */
+  matcher: ScopeMatcherSchema,
+
+  /** Optional additional constraints on this scope */
+  constraints: z.record(z.any()).optional(),
+});
+
+export type CrispScope = z.infer<typeof CrispScopeSchema>;
+
+/**
+ * Delegation Constraints Schema (CRISP)
+ *
+ * Complete constraint specification for a delegation
+ */
+export const DelegationConstraintsSchema = z.object({
+  /** Not valid before (Unix timestamp in seconds) */
+  notBefore: z.number().int().optional(),
+
+  /** Not valid after (Unix timestamp in seconds) */
+  notAfter: z.number().int().optional(),
+
+  /** Simple scopes array (for Phase 1 bouncer - simplified model) */
+  scopes: z.array(z.string()).optional(),
+
+  /**
+   * Optional target server DID(s) for this delegation
+   * If omitted, delegation is valid on any server accepting the scopes
+   * If specified, delegation is only valid on the specified server(s)
+   */
+  audience: z.union([
+    z.string().startsWith("did:"),
+    z.array(z.string().startsWith("did:"))
+  ]).optional(),
+
+  /** CRISP-specific constraints (full model) */
+  crisp: z.object({
+    /** Optional budget constraint */
+    budget: CrispBudgetSchema.optional(),
+
+    /** Required: at least one scope */
+    scopes: z.array(CrispScopeSchema).min(1),
+
+    /** Optional additional CRISP fields */
+  }).passthrough().optional(),
+}).passthrough(); // Allow extensibility
+
+export type DelegationConstraints = z.infer<typeof DelegationConstraintsSchema>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate delegation constraints
+ *
+ * @param constraints - The constraints to validate
+ * @returns Validation result
+ */
+export function validateDelegationConstraints(constraints: unknown) {
+  return 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
+ */
+export function hasValidTimeRange(constraints: DelegationConstraints): boolean {
+  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
+ */
+export function areChildConstraintsValid(
+  parent: DelegationConstraints,
+  child: DelegationConstraints
+): boolean {
+  // 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
+  if (parent.crisp && child.crisp) {
+    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;
+  }
+
+  return true; // Can't validate if crisp is not present
+}
+
+/**
+ * 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
+ */
+export function doesResourceMatchScope(
+  resource: string,
+  scope: CrispScope
+): boolean {
+  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
+ */
+export const SUPPORTED_CURRENCIES: Currency[] = ['USD', 'ops', 'points'];
+
+/**
+ * Supported scope matchers
+ */
+export const SUPPORTED_MATCHERS: ScopeMatcher[] = ['exact', 'prefix', 'regex'];
+
+/**
+ * Maximum reasonable budget cap (for validation)
+ */
+export const MAX_BUDGET_CAP = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Maximum reasonable window duration (10 years in seconds)
+ */
+export const MAX_WINDOW_DURATION_SEC = 10 * 365 * 24 * 60 * 60;

package/src/delegation/index.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';