@contractspec/lib.contracts-spec 2.0.0

package/dist/node/policy/docs/policy.docblock.js

@@ -0,0 +1,313 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/docs/presentations.ts
+var DEFAULT_TARGETS = [
+  "markdown",
+  "react"
+];
+function normalizeRoute(route) {
+  if (!route.length)
+    return "/";
+  const withLeading = route.startsWith("/") ? route : `/${route}`;
+  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
+}
+function deriveRoute(block, routePrefix) {
+  if (block.route)
+    return normalizeRoute(block.route);
+  const prefix = routePrefix ?? "/docs";
+  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
+  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
+  return normalizeRoute(path);
+}
+function buildName(block, namespace) {
+  return namespace ? `${namespace}.${block.id}` : block.id;
+}
+function docBlockToPresentationSpec(block, options) {
+  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
+  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
+  const stability = block.stability ?? options?.defaultStability ?? "stable";
+  return {
+    meta: {
+      key: buildName(block, options?.namespace),
+      title: block.title,
+      version,
+      description: block.summary ?? block.title,
+      tags: block.tags || [],
+      owners: block.owners || [],
+      domain: block.domain || "",
+      stability,
+      goal: `Documentation of: ${block.summary}`,
+      context: `Auto-generated`
+    },
+    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
+    source: {
+      type: "blocknotejs",
+      docJson: block.body
+    },
+    targets
+  };
+}
+function docBlocksToPresentationRoutes(blocks, options) {
+  return blocks.map((block) => ({
+    block,
+    route: deriveRoute(block, options?.routePrefix),
+    descriptor: docBlockToPresentationSpec(block, options)
+  }));
+}
+function docBlocksToPresentationSpecs(blocks, options) {
+  return blocks.map((block) => docBlockToPresentationSpec(block, options));
+}
+function mapDocRoutes(routes) {
+  return routes.map(({ route, descriptor }) => [route, descriptor]);
+}
+
+// src/docs/registry.ts
+class DocRegistry {
+  routes = new Map;
+  constructor(blocks = [], options) {
+    blocks.forEach((block) => this.register(block, options));
+  }
+  register(block, options) {
+    const [route] = docBlocksToPresentationRoutes([block], options);
+    if (route) {
+      this.routes.set(block.id, route);
+    }
+    return this;
+  }
+  list() {
+    return [...this.routes.values()];
+  }
+  get(id) {
+    return this.routes.get(id);
+  }
+  toRouteTuples() {
+    return this.list().map(({ route, descriptor }) => [route, descriptor]);
+  }
+  toPresentationSpecs(options) {
+    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
+  }
+}
+var requiredFields = [
+  "id",
+  "title",
+  "body",
+  "kind",
+  "visibility",
+  "route"
+];
+var defaultDocRegistry = new DocRegistry;
+function registerDocBlocks(blocks) {
+  for (const block of blocks) {
+    for (const field of requiredFields) {
+      if (!block[field]) {
+        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
+      }
+    }
+    defaultDocRegistry.register(block);
+  }
+}
+function listRegisteredDocBlocks() {
+  return defaultDocRegistry.list().map((r) => r.block);
+}
+function docId(id) {
+  const found = defaultDocRegistry.get(id);
+  if (!found)
+    throw new Error(`DocBlock not registered: ${id}`);
+  return id;
+}
+
+// src/policy/docs/policy.docblock.ts
+var tech_contracts_policy_DocBlocks = [
+  {
+    id: "docs.tech.contracts.policy",
+    title: "PolicySpec & PolicyEngine",
+    summary: "`PolicySpec` gives a declarative, typed home for access-control logic covering:",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/contracts/policy",
+    tags: ["tech", "contracts", "policy"],
+    body: `# PolicySpec & PolicyEngine
+
+## Purpose
+
+\`PolicySpec\` gives a declarative, typed home for access-control logic covering:
+- **Who** can perform an action (ABAC/ReBAC style rules)
+- **What** they can access (resources + optional field-level overrides)
+- **When** special conditions apply (contextual expressions)
+- **How** PII should be handled (consent/retention hints)
+
+\`PolicyEngine\` evaluates one or more policies and returns an \`allow\`/\`deny\` decision, field-level outcomes, and PII metadata suitable for downstream enforcement (\`OperationSpecRegistry\` → \`ctx.decide\`).
+
+## Location
+
+- Types & registry: \`packages/libs/contracts/src/policy/spec.ts\`
+- Runtime evaluation: \`packages/libs/contracts/src/policy/engine.ts\`
+- Tests: \`packages/.../policy/engine.test.ts\`
+
+## \`PolicySpec\`
+
+\`\`\`ts
+export interface PolicySpec {
+  meta: PolicyMeta;          // ownership metadata + { name, version, scope? }
+  rules: PolicyRule[];       // allow/deny rules for actions
+  fieldPolicies?: FieldPolicyRule[];
+  pii?: { fields: string[]; consentRequired?: boolean; retentionDays?: number };
+  relationships?: RelationshipDefinition[];
+  consents?: ConsentDefinition[];
+  rateLimits?: RateLimitDefinition[];
+  opa?: { package: string; decision?: string };
+}
+\`\`\`
+
+- \`PolicyRule\`
+  - \`effect\`: \`'allow' | 'deny'\`
+  - \`actions\`: e.g., \`['read', 'write', 'delete']\` (string namespace is flexible)
+  - \`subject\`: \`{ roles?: string[]; attributes?: { attr: matcher } }\`
+  - \`resource\`: \`{ type: string; fields?: string[]; attributes?: {...} }\`
+  - \`relationships\`: \`{ relation, objectId?, objectType? }[]\` → ReBAC checks (use \`objectId: '$resource'\` to target the current resource)
+  - \`requiresConsent\`: \`['consent_id']\` → references spec-level consent definitions
+  - \`flags\`: feature flags that must be enabled (\`DecisionContext.flags\`)
+  - \`rateLimit\`: string reference to \`rateLimits\` entry or inline object \`{ rpm, key?, windowSeconds?, burst? }\`
+  - \`escalate\`: \`'human_review' | null\` to indicate manual approval
+  - \`conditions\`: optional expression snippets evaluated against \`{ subject, resource, context }\`
+- \`FieldPolicyRule\`
+  - \`field\`: dot-path string (e.g., \`contact.email\`)
+  - \`actions\`: subset of \`['read', 'write']\`
+  - Same \`subject\` / \`resource\` / \`conditions\` shape
+  - Useful for redacting specific fields, even when the global action is allowed
+- \`RelationshipDefinition\`
+  - Canonical tuples for relationship graph (\`subjectType\`, \`relation\`, \`objectType\`, \`transitive?\`)
+- \`ConsentDefinition\`
+  - \`{ id, scope, purpose, lawfulBasis?, expiresInDays?, required? }\`
+- \`RateLimitDefinition\`
+  - \`{ id, rpm, key?, windowSeconds?, burst? }\`
+- \`PolicyRef\`
+  - \`{ name: string; version: string }\` → attach to contract specs / workflows
+
+## Registry
+
+\`\`\`ts
+const registry = new PolicyRegistry();
+registry.register(CorePolicySpec);
+const spec = registry.get('core.default', 1);
+\`\`\`
+
+Guarantees uniqueness per \`(name, version)\` and exposes helpers to resolve highest versions.
+
+## Engine
+
+\`\`\`ts
+const engine = new PolicyEngine(policyRegistry);
+
+const decision = engine.decide({
+  action: 'read',
+  subject: { roles: ['admin'] },
+  resource: { type: 'resident', fields: ['contact.email'] },
+  policies: [{ name: 'core.default', version: '1.0.0' }],
+});
+/*
+{
+  effect: 'allow',
+  reason: 'core.default',
+  fieldDecisions: [{ field: 'contact.email', effect: 'allow' }],
+  pii: { fields: ['contact.email'], consentRequired: true }
+}
+*/
+\`\`\`
+
+- First matching **deny** wins; otherwise the first **allow** is returned.
+- Field policies are aggregated across referenced policies:
+  - Later denies override earlier allows for a given field.
+  - Returned as \`fieldDecisions\` to simplify downstream masking.
+- PII metadata is surfaced when defined to help adapt logging/telemetry.
+
+### Expression Support
+
+Conditions accept small JS snippets (e.g., \`subject.attributes.orgId === context.orgId\`). The engine runs them in a constrained scope (\`subject\`, \`resource\`, \`context\`) without access to global state.
+
+### ReBAC & Relationships
+
+- Provide relationship tuples via \`PolicySpec.relationships\` for documentation/validation.
+- Reference them inside rules with \`relationships: [{ relation: 'manager_of', objectType: 'resident', objectId: '$resource' }]\`.
+- The execution context must populate \`subject.relationships\` (\`[{ relation, object, objectType }]\`) for the engine to evaluate ReBAC guards.
+
+### Consent & Rate Limits
+
+- Declare reusable consent definitions under \`consents\`. Rules list the IDs they require; if a user session lacks the consent (\`DecisionContext.consents\`), the engine returns \`effect: 'deny'\` with \`reason: 'consent_required'\` and enumerates missing consents.
+- Attach rate limits either inline or via \`rateLimits\` references. When a rule matches, the engine surfaces \`{ rpm, key, windowSeconds?, burst? }\` so callers can feed it to shared limiters.
+
+### OPA Adapter
+
+- \`OPAPolicyAdapter\` bridges engine decisions to Open Policy Agent (OPA). It forwards the evaluation context + policies to OPA and merges any override result (\`effect\`, \`reason\`, \`fieldDecisions\`, \`requiredConsents\`).
+- Use when migrating to OPA policies or running defense-in-depth: call \`engine.decide()\`, then pass the preliminary decision to \`adapter.evaluate(...)\`. The adapter marks merged decisions with \`evaluatedBy: 'opa'\`.
+- OPA inputs include meta, rules, relationships, rate limits, and consent catalogs to simplify policy authoring on the OPA side.
+
+## Contract Integration
+
+\`ContractSpec.policy\` now supports:
+
+\`\`\`ts
+policy: {
+  auth: 'anonymous' | 'user' | 'admin';
+  ...
+  policies?: PolicyRef[];                // policies evaluated before execution
+  fieldPolicies?: {                      // field hints (read/write) per policy
+    field: string;
+    actions: ('read' | 'write')[];
+    policy?: PolicyRef;
+  }[];
+}
+\`\`\`
+
+Adapters can resolve refs through a shared \`PolicyEngine\` and populate \`ctx.decide\` so \`OperationSpecRegistry.execute\` benefits from centralized enforcement.
+
+## Authoring Guidelines
+
+1. Prefer **allow-by-default** policies but explicitly deny sensitive flows (defense-in-depth).
+2. Keep rule scopes narrow (per feature/operation) and compose multiple \`PolicyRef\`s when necessary.
+3. Store PII field lists here to avoid duplication across logs/telemetry.
+4. Use explicit rule reasons for auditability and better developer feedback.
+5. Treat versioning seriously; bump \`meta.version\` whenever behavior changes.
+
+## Future Enhancements
+
+- Richer expression language (composable predicates, time-based conditions).
+- Multi-tenant relationship graph services (store/resolve relationships at scale).
+- Tooling that auto-generates docs/tests for policies referenced in specs.
+
+`
+  }
+];
+registerDocBlocks(tech_contracts_policy_DocBlocks);
+export {
+  tech_contracts_policy_DocBlocks
+};

package/dist/node/policy/engine.js

@@ -0,0 +1,325 @@
+import { createRequire } from "node:module";
+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 = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/policy/engine.ts
+class PolicyEngine {
+  registry;
+  constructor(registry) {
+    this.registry = registry;
+  }
+  decide(input) {
+    const policies = this.resolvePolicies(input.policies);
+    let allowReason;
+    let appliedRateLimit;
+    let escalate;
+    for (const policy of policies) {
+      const match = this.matchRuleSet(policy, input);
+      if (!match)
+        continue;
+      if (match.rule.effect === "deny") {
+        return {
+          effect: "deny",
+          reason: match.rule.reason ?? policy.meta.key,
+          requiredConsents: match.missingConsents.length ? match.missingConsents : undefined,
+          evaluatedBy: "engine"
+        };
+      }
+      if (match.rule.effect === "allow") {
+        if (match.missingConsents.length) {
+          return {
+            effect: "deny",
+            reason: "consent_required",
+            requiredConsents: match.missingConsents,
+            evaluatedBy: "engine"
+          };
+        }
+        if (!allowReason) {
+          allowReason = match.rule.reason ?? policy.meta.key;
+        }
+        if (!appliedRateLimit && match.rateLimit) {
+          appliedRateLimit = match.rateLimit;
+        }
+        if (!escalate && match.rule.escalate) {
+          escalate = match.rule.escalate;
+        }
+      }
+    }
+    const fieldDecisions = this.evaluateFields(policies, input);
+    const pii = policies.find((p) => p.pii)?.pii;
+    const escalateValue = typeof escalate === "undefined" ? undefined : escalate;
+    return {
+      effect: allowReason ? "allow" : "deny",
+      reason: allowReason,
+      rateLimit: appliedRateLimit,
+      escalate: escalateValue,
+      fieldDecisions: fieldDecisions.length ? fieldDecisions : undefined,
+      pii,
+      evaluatedBy: "engine"
+    };
+  }
+  resolvePolicies(refs) {
+    const specs = [];
+    for (const ref of refs) {
+      const spec = this.registry.get(ref.key, ref.version);
+      if (!spec)
+        throw new Error(`PolicyEngine: policy not found ${ref.key}.v${ref.version}`);
+      specs.push(spec);
+    }
+    return specs;
+  }
+  matchRuleSet(policy, input) {
+    let allowMatch;
+    for (const rule of policy.rules) {
+      if (!rule.actions.includes(input.action))
+        continue;
+      if (!matchesSubject(rule, input.subject))
+        continue;
+      if (!matchesResource(rule, input.resource))
+        continue;
+      if (!matchesFlags(rule, input))
+        continue;
+      if (!matchesRelationships(rule.relationships, input))
+        continue;
+      if (!matchesConditions(rule, input))
+        continue;
+      const missingConsents = collectMissingConsents(rule, policy, input);
+      const rateLimit = resolveRateLimit(rule, policy, input);
+      const evaluation = {
+        rule,
+        missingConsents,
+        rateLimit
+      };
+      if (rule.effect === "deny")
+        return evaluation;
+      if (rule.effect === "allow" && !allowMatch)
+        allowMatch = evaluation;
+    }
+    return allowMatch;
+  }
+  evaluateFields(policies, input) {
+    const out = new Map;
+    for (const policy of policies) {
+      if (!policy.fieldPolicies)
+        continue;
+      for (const rule of policy.fieldPolicies) {
+        if (!rule.actions.includes(mapActionToFieldAction(input.action)))
+          continue;
+        if (!matchesSubject(rule, input.subject))
+          continue;
+        if (!matchesResource(rule, input.resource))
+          continue;
+        if (!matchesConditions(rule, input))
+          continue;
+        const existing = out.get(rule.field);
+        if (rule.effect === "deny") {
+          out.set(rule.field, {
+            field: rule.field,
+            effect: "deny",
+            reason: rule.reason ?? policy.meta.key
+          });
+        } else if (!existing) {
+          out.set(rule.field, {
+            field: rule.field,
+            effect: "allow",
+            reason: rule.reason ?? policy.meta.key
+          });
+        }
+      }
+    }
+    return [...out.values()];
+  }
+}
+function mapActionToFieldAction(action) {
+  if (action.startsWith("write"))
+    return "write";
+  return "read";
+}
+function matchesSubject(rule, subject) {
+  const matcher = rule.subject;
+  if (!matcher)
+    return true;
+  if (matcher.roles?.length) {
+    const roles = subject.roles ?? [];
+    const hasRole = matcher.roles.some((role) => roles.includes(role));
+    if (!hasRole)
+      return false;
+  }
+  if (matcher.attributes) {
+    const attributes = subject.attributes ?? {};
+    if (!matchAttributes(matcher.attributes, attributes))
+      return false;
+  }
+  return true;
+}
+function matchesResource(rule, resource) {
+  const matcher = rule.resource;
+  if (!matcher)
+    return true;
+  if (matcher.type && matcher.type !== resource.type)
+    return false;
+  if (matcher.fields?.length) {
+    const targetFields = resource.fields ?? [];
+    if (!matcher.fields.some((field) => targetFields.includes(field)))
+      return false;
+  }
+  if (matcher.attributes) {
+    const attributes = resource.attributes ?? {};
+    if (!matchAttributes(matcher.attributes, attributes))
+      return false;
+  }
+  return true;
+}
+function matchesFlags(rule, input) {
+  if (!rule.flags?.length)
+    return true;
+  const available = new Set;
+  if (input.flags) {
+    for (const flag of input.flags)
+      available.add(flag);
+  }
+  const attributeFlags = input.subject.attributes?.featureFlags;
+  if (Array.isArray(attributeFlags)) {
+    for (const flag of attributeFlags)
+      available.add(flag);
+  }
+  return rule.flags.every((flag) => available.has(flag));
+}
+function matchesRelationships(matchers, input) {
+  if (!matchers || matchers.length === 0)
+    return true;
+  const relationships = input.subject.relationships ?? [];
+  const resourceId = getResourceId(input.resource);
+  const resourceType = input.resource.type;
+  return matchers.every((matcher) => relationships.some((relation) => {
+    if (relation.relation !== matcher.relation)
+      return false;
+    const typeMatches = !matcher.objectType || relation.objectType === matcher.objectType || matcher.objectType === resourceType;
+    if (!typeMatches)
+      return false;
+    if (!matcher.objectId)
+      return true;
+    if (matcher.objectId === "$resource") {
+      if (resourceId) {
+        return relation.object === resourceId;
+      }
+      return relation.object === resourceType || relation.objectType === resourceType;
+    }
+    return relation.object === matcher.objectId;
+  }));
+}
+function matchesConditions(rule, input) {
+  if (!rule.conditions || rule.conditions.length === 0)
+    return true;
+  return rule.conditions.every((condition) => evaluateCondition(condition.expression, input));
+}
+function matchAttributes(matcher, actual) {
+  for (const [key, attrMatcher] of Object.entries(matcher)) {
+    const value = actual[key];
+    if (attrMatcher.exists && typeof value === "undefined")
+      return false;
+    if (typeof attrMatcher.equals !== "undefined") {
+      if (value !== attrMatcher.equals)
+        return false;
+    }
+    if (attrMatcher.oneOf && !attrMatcher.oneOf.includes(value))
+      return false;
+  }
+  return true;
+}
+function collectMissingConsents(rule, policy, input) {
+  if (!rule.requiresConsent?.length)
+    return [];
+  const granted = new Set(input.consents ?? []);
+  const missingIds = rule.requiresConsent.filter((id) => !granted.has(id));
+  if (missingIds.length === 0)
+    return [];
+  return resolveConsentDefinitions(policy, missingIds);
+}
+function resolveConsentDefinitions(policy, ids) {
+  const catalog = policy.consents ?? [];
+  return ids.map((id) => {
+    const found = catalog.find((consent) => consent.id === id);
+    return found ?? {
+      id,
+      scope: "unspecified",
+      purpose: "unspecified",
+      description: `Consent "${id}" required by ${policy.meta.key}`,
+      required: true
+    };
+  });
+}
+function resolveRateLimit(rule, policy, input) {
+  if (!rule.rateLimit)
+    return;
+  const definition = typeof rule.rateLimit === "string" ? (policy.rateLimits ?? []).find((item) => item.id === rule.rateLimit) : rule.rateLimit;
+  if (!definition) {
+    throw new Error(`PolicyEngine: rate limit "${String(rule.rateLimit)}" not declared in ${policy.meta.key}`);
+  }
+  return {
+    rpm: definition.rpm,
+    key: definition.key ?? input.resource.type,
+    windowSeconds: definition.windowSeconds,
+    burst: definition.burst
+  };
+}
+function evaluateCondition(expression, input) {
+  const trimmed = expression.trim();
+  if (!trimmed)
+    return true;
+  const context = {
+    subject: input.subject,
+    resource: input.resource,
+    context: input.context ?? {}
+  };
+  try {
+    const fn = new Function("subject", "resource", "context", `return (${transformExpression(trimmed)});`);
+    const result = fn(context.subject, context.resource, context.context);
+    return Boolean(result);
+  } catch (_error) {
+    return false;
+  }
+}
+function transformExpression(expression) {
+  return expression.replace(/&&/g, "&&").replace(/\|\|/g, "||");
+}
+function getResourceId(resource) {
+  if (resource.id)
+    return resource.id;
+  const candidate = resource.attributes?.id;
+  if (typeof candidate === "string")
+    return candidate;
+  if (typeof candidate === "number")
+    return String(candidate);
+  return;
+}
+export {
+  PolicyEngine
+};