@contractspec/lib.overlay-engine 1.56.1 → 1.58.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { AddHelpTextModification, HideFieldModification, MakeRequiredModification, OVERLAY_SCOPE_ORDER, OverlayAppliesTo, OverlayFieldModificationBase, OverlayInput, OverlayModification, OverlayScopeContext, OverlayScopeKey, OverlaySignatureAlgorithm, OverlaySignatureBlock, OverlaySpec, OverlayTargetRef, RenameLabelModification, ReorderFieldsModification, SetDefaultModification, SignedOverlaySpec, defineOverlay } from "./spec.js";
-import { OverlayAuditEvent, OverlayLayoutConfig, OverlayMatchContext, OverlayRenderable, OverlayRenderableField } from "./types.js";
-import { OverlayValidationIssue, OverlayValidationResult, OverlayValidator, assertOverlayValid, defaultOverlayValidator, validateOverlaySpec } from "./validator.js";
-import { OverlayLookup, OverlayRegistry, OverlayRegistryOptions } from "./registry.js";
-import { ApplyOverlayOptions, applyOverlayModifications } from "./merger.js";
-import { OverlayApplyParams, OverlayEngine, OverlayEngineOptions, OverlayRuntimeResult } from "./runtime.js";
-import { SignOverlayOptions, canonicalizeOverlay, signOverlay, stripSignature, verifyOverlaySignature } from "./signer.js";
-export { AddHelpTextModification, ApplyOverlayOptions, HideFieldModification, MakeRequiredModification, OVERLAY_SCOPE_ORDER, OverlayAppliesTo, OverlayApplyParams, OverlayAuditEvent, OverlayEngine, OverlayEngineOptions, OverlayFieldModificationBase, OverlayInput, OverlayLayoutConfig, OverlayLookup, OverlayMatchContext, OverlayModification, OverlayRegistry, OverlayRegistryOptions, OverlayRenderable, OverlayRenderableField, OverlayRuntimeResult, OverlayScopeContext, OverlayScopeKey, OverlaySignatureAlgorithm, OverlaySignatureBlock, OverlaySpec, OverlayTargetRef, OverlayValidationIssue, OverlayValidationResult, OverlayValidator, RenameLabelModification, ReorderFieldsModification, SetDefaultModification, SignOverlayOptions, SignedOverlaySpec, applyOverlayModifications, assertOverlayValid, canonicalizeOverlay, defaultOverlayValidator, defineOverlay, signOverlay, stripSignature, validateOverlaySpec, verifyOverlaySignature };
+export * from './spec';
+export * from './types';
+export * from './registry';
+export * from './validator';
+export * from './runtime';
+export * from './merger';
+export * from './signer';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -1,8 +1,535 @@
-import { OVERLAY_SCOPE_ORDER, defineOverlay } from "./spec.js";
-import { assertOverlayValid, defaultOverlayValidator, validateOverlaySpec } from "./validator.js";
-import { OverlayRegistry } from "./registry.js";
-import { applyOverlayModifications } from "./merger.js";
-import { OverlayEngine } from "./runtime.js";
-import { canonicalizeOverlay, signOverlay, stripSignature, verifyOverlaySignature } from "./signer.js";
-
-export { OVERLAY_SCOPE_ORDER, OverlayEngine, OverlayRegistry, applyOverlayModifications, assertOverlayValid, canonicalizeOverlay, defaultOverlayValidator, defineOverlay, signOverlay, stripSignature, validateOverlaySpec, verifyOverlaySignature };
+// @bun
+// src/spec.ts
+var OVERLAY_SCOPE_ORDER = [
+  "tenantId",
+  "role",
+  "userId",
+  "device",
+  "tags"
+];
+function defineOverlay(spec) {
+  return spec;
+}
+// src/validator.ts
+var TARGET_KEYS = [
+  "capability",
+  "workflow",
+  "dataView",
+  "presentation",
+  "operation"
+];
+var defaultOverlayValidator = (spec) => validateOverlaySpec(spec);
+function validateOverlaySpec(spec) {
+  const issues = [];
+  if (!spec.overlayId?.trim()) {
+    issues.push({
+      code: "overlay.id",
+      message: "overlayId is required",
+      path: ["overlayId"]
+    });
+  }
+  if (!spec.version?.trim()) {
+    issues.push({
+      code: "overlay.version",
+      message: "version is required",
+      path: ["version"]
+    });
+  }
+  const hasTarget = TARGET_KEYS.some((key) => {
+    const value = spec.appliesTo?.[key];
+    return typeof value === "string" && value.trim().length > 0;
+  });
+  if (!hasTarget) {
+    issues.push({
+      code: "overlay.target",
+      message: "Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",
+      path: ["appliesTo"]
+    });
+  }
+  if (!spec.modifications?.length) {
+    issues.push({
+      code: "overlay.modifications.empty",
+      message: "Overlay must include at least one modification.",
+      path: ["modifications"]
+    });
+  } else {
+    spec.modifications.forEach((mod, idx) => {
+      const path = ["modifications", String(idx)];
+      validateModification(mod, path, issues);
+    });
+  }
+  return {
+    valid: issues.length === 0,
+    issues
+  };
+}
+function validateModification(modification, path, issues) {
+  const push = (code, message, extraPath) => {
+    issues.push({
+      code,
+      message,
+      path: extraPath ? [...path, ...extraPath] : path
+    });
+  };
+  if (isFieldModification(modification)) {
+    if (!modification.field?.trim()) {
+      push("overlay.mod.field", "field is required for this modification", [
+        "field"
+      ]);
+    }
+  }
+  switch (modification.type) {
+    case "renameLabel": {
+      if (!modification.newLabel?.trim()) {
+        push("overlay.mod.renameLabel.newLabel", "newLabel is required", [
+          "newLabel"
+        ]);
+      }
+      break;
+    }
+    case "reorderFields": {
+      if (!modification.fields?.length) {
+        push("overlay.mod.reorderFields.fields", "fields list cannot be empty", ["fields"]);
+      }
+      const seen = new Set;
+      for (const field of modification.fields ?? []) {
+        if (!field?.trim()) {
+          push("overlay.mod.reorderFields.fields.blank", "fields entries must be non-empty");
+          break;
+        }
+        if (seen.has(field)) {
+          push("overlay.mod.reorderFields.fields.duplicate", `field "${field}" was listed multiple times`);
+          break;
+        }
+        seen.add(field);
+      }
+      break;
+    }
+    case "setDefault": {
+      if (modification.value === undefined) {
+        push("overlay.mod.setDefault.value", "value is required", ["value"]);
+      }
+      break;
+    }
+    case "addHelpText": {
+      if (!modification.text?.trim()) {
+        push("overlay.mod.addHelpText.text", "text is required", ["text"]);
+      }
+      break;
+    }
+    case "makeRequired":
+    case "hideField":
+      break;
+    default: {
+      const exhaustive = modification;
+      throw new Error(`Unsupported overlay modification ${exhaustive?.type ?? "unknown"}`);
+    }
+  }
+}
+function isFieldModification(mod) {
+  return "field" in mod;
+}
+function assertOverlayValid(spec, validator = defaultOverlayValidator) {
+  const result = validator(spec);
+  if (!result.valid) {
+    const message = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+    throw new Error(`Invalid OverlaySpec "${spec.overlayId}": ${message}`);
+  }
+}
+
+// src/registry.ts
+var TARGET_KEYS2 = [
+  "capability",
+  "workflow",
+  "dataView",
+  "presentation",
+  "operation"
+];
+var SCOPE_WEIGHTS = {
+  tenantId: 8,
+  role: 4,
+  userId: 16,
+  device: 2,
+  tags: 1
+};
+
+class OverlayRegistry {
+  options;
+  overlays = new Map;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  register(overlay, options) {
+    if (!options?.skipValidation) {
+      const validator = this.options.validator ?? defaultOverlayValidator;
+      const result = validator(overlay);
+      if (!result.valid) {
+        const reason = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+        throw new Error(`Overlay "${overlay.overlayId}" failed validation: ${reason}`);
+      }
+    }
+    const normalized = this.ensureSigned(overlay);
+    const key = this.getKey(normalized.overlayId, normalized.version);
+    const stored = {
+      overlay: normalized,
+      specificity: computeSpecificity(normalized.appliesTo),
+      registeredAt: Date.now()
+    };
+    this.overlays.set(key, stored);
+    return normalized;
+  }
+  unregister(overlayId, version) {
+    if (version) {
+      this.overlays.delete(this.getKey(overlayId, version));
+      return;
+    }
+    for (const key of Array.from(this.overlays.keys())) {
+      if (key.startsWith(`${overlayId}@`)) {
+        this.overlays.delete(key);
+      }
+    }
+  }
+  list() {
+    return Array.from(this.overlays.values()).map((entry) => entry.overlay);
+  }
+  get(overlayId, version) {
+    return this.overlays.get(this.getKey(overlayId, version))?.overlay;
+  }
+  forContext(query) {
+    return Array.from(this.overlays.values()).filter((entry) => matches(entry.overlay.appliesTo, query)).sort((a, b) => {
+      if (a.specificity !== b.specificity) {
+        return a.specificity - b.specificity;
+      }
+      return a.registeredAt - b.registeredAt;
+    }).map((entry) => entry.overlay);
+  }
+  clear() {
+    this.overlays.clear();
+  }
+  size() {
+    return this.overlays.size;
+  }
+  ensureSigned(input) {
+    if (isSignedOverlay(input)) {
+      if (!input.signature?.signature && !this.options.allowUnsigned) {
+        throw new Error(`Overlay "${input.overlayId}" is missing a signature.`);
+      }
+      return input;
+    }
+    if (!this.options.allowUnsigned) {
+      throw new Error(`Overlay "${input.overlayId}" must be signed before registration.`);
+    }
+    return input;
+  }
+  getKey(overlayId, version) {
+    return `${overlayId}@${version}`;
+  }
+}
+function isSignedOverlay(spec) {
+  return Boolean(spec.signature);
+}
+function computeSpecificity(appliesTo) {
+  let score = 0;
+  Object.keys(SCOPE_WEIGHTS).forEach((key) => {
+    const hasValue = key === "tags" ? Array.isArray(appliesTo.tags) && appliesTo.tags.length > 0 : Boolean(appliesTo[key]);
+    if (hasValue) {
+      score += SCOPE_WEIGHTS[key];
+    }
+  });
+  return score;
+}
+function matches(appliesTo, ctx) {
+  for (const key of TARGET_KEYS2) {
+    const expected = appliesTo[key];
+    if (expected && expected !== ctx[key]) {
+      return false;
+    }
+  }
+  if (appliesTo.tenantId && appliesTo.tenantId !== ctx.tenantId) {
+    return false;
+  }
+  if (appliesTo.role && appliesTo.role !== ctx.role) {
+    return false;
+  }
+  if (appliesTo.userId && appliesTo.userId !== ctx.userId) {
+    return false;
+  }
+  if (appliesTo.device && appliesTo.device !== ctx.device) {
+    return false;
+  }
+  if (appliesTo.tags?.length) {
+    if (!ctx.tags?.length) {
+      return false;
+    }
+    const ctxTags = new Set(ctx.tags);
+    const satisfies = appliesTo.tags.every((tag) => ctxTags.has(tag));
+    if (!satisfies) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/merger.ts
+function applyOverlayModifications(target, overlays, options = {}) {
+  if (!overlays.length) {
+    return target;
+  }
+  const states = target.fields.map((field) => ({
+    key: field.key,
+    field: { ...field },
+    hidden: field.visible === false
+  }));
+  const fieldMap = new Map(states.map((state) => [state.key, state]));
+  let orderSequence = target.fields.map((field) => field.key);
+  const handleMissing = (field, overlayId) => {
+    if (options.strict) {
+      throw new Error(`Overlay "${overlayId}" referenced unknown field "${field}".`);
+    }
+  };
+  overlays.forEach((overlay) => {
+    overlay.modifications.forEach((modification) => {
+      switch (modification.type) {
+        case "hideField": {
+          const state = fieldMap.get(modification.field);
+          if (!state)
+            return handleMissing(modification.field, overlay.overlayId);
+          state.hidden = true;
+          state.field.visible = false;
+          break;
+        }
+        case "renameLabel": {
+          const state = fieldMap.get(modification.field);
+          if (!state)
+            return handleMissing(modification.field, overlay.overlayId);
+          state.field.label = modification.newLabel;
+          break;
+        }
+        case "setDefault": {
+          const state = fieldMap.get(modification.field);
+          if (!state)
+            return handleMissing(modification.field, overlay.overlayId);
+          state.field.defaultValue = modification.value;
+          break;
+        }
+        case "addHelpText": {
+          const state = fieldMap.get(modification.field);
+          if (!state)
+            return handleMissing(modification.field, overlay.overlayId);
+          state.field.helpText = modification.text;
+          break;
+        }
+        case "makeRequired": {
+          const state = fieldMap.get(modification.field);
+          if (!state)
+            return handleMissing(modification.field, overlay.overlayId);
+          state.field.required = modification.required ?? true;
+          break;
+        }
+        case "reorderFields": {
+          const { filtered, missing } = normalizeOrderList(modification.fields, fieldMap);
+          if (missing.length && options.strict) {
+            missing.forEach((field) => handleMissing(field, overlay.overlayId));
+          }
+          orderSequence = applyReorder(orderSequence, filtered);
+          break;
+        }
+        default:
+          break;
+      }
+    });
+  });
+  const visibleFields = [];
+  const seen = new Set;
+  orderSequence.forEach((key) => {
+    const state = fieldMap.get(key);
+    if (!state || state.hidden) {
+      return;
+    }
+    seen.add(key);
+    visibleFields.push(state.field);
+  });
+  states.forEach((state) => {
+    if (state.hidden || seen.has(state.key)) {
+      return;
+    }
+    visibleFields.push(state.field);
+  });
+  visibleFields.forEach((field, index) => {
+    field.order = index;
+    field.visible = true;
+  });
+  return {
+    ...target,
+    fields: visibleFields
+  };
+}
+function normalizeOrderList(fields, fieldMap) {
+  const filtered = [];
+  const missing = [];
+  const seen = new Set;
+  fields.forEach((field) => {
+    if (!field?.trim()) {
+      return;
+    }
+    if (!fieldMap.has(field)) {
+      missing.push(field);
+      return;
+    }
+    if (seen.has(field)) {
+      return;
+    }
+    seen.add(field);
+    filtered.push(field);
+  });
+  return { filtered, missing };
+}
+function applyReorder(sequence, orderedFields) {
+  if (!orderedFields.length) {
+    return sequence;
+  }
+  const orderedSet = new Set(orderedFields);
+  const remainder = sequence.filter((key) => !orderedSet.has(key));
+  return [...orderedFields, ...remainder];
+}
+
+// src/runtime.ts
+class OverlayEngine {
+  registry;
+  audit;
+  constructor(options) {
+    this.registry = options.registry;
+    this.audit = options.audit;
+  }
+  apply(params) {
+    const overlays = params.overlays ?? this.registry.forContext({
+      capability: params.capability,
+      workflow: params.workflow,
+      dataView: params.dataView,
+      presentation: params.presentation,
+      operation: params.operation,
+      tenantId: params.tenantId,
+      role: params.role,
+      userId: params.userId,
+      device: params.device,
+      tags: params.tags
+    });
+    const merged = applyOverlayModifications(params.target, overlays, {
+      strict: params.strict
+    });
+    const context = extractContext(params);
+    overlays.forEach((overlay) => {
+      this.audit?.({
+        overlay: {
+          overlayId: overlay.overlayId,
+          version: overlay.version
+        },
+        context,
+        timestamp: new Date().toISOString()
+      });
+    });
+    return {
+      target: merged,
+      overlaysApplied: overlays
+    };
+  }
+}
+function extractContext(params) {
+  return {
+    tenantId: params.tenantId,
+    role: params.role,
+    userId: params.userId,
+    device: params.device,
+    tags: params.tags
+  };
+}
+
+// src/signer.ts
+import stringify from "fast-json-stable-stringify";
+import {
+  constants,
+  createPrivateKey,
+  createPublicKey,
+  sign,
+  verify
+} from "crypto";
+function signOverlay(spec, privateKey, options = {}) {
+  const algorithm = options.algorithm ?? "ed25519";
+  const keyObject = typeof privateKey === "string" || Buffer.isBuffer(privateKey) ? createPrivateKey(privateKey) : privateKey;
+  const payload = Buffer.from(canonicalizeOverlay(spec), "utf8");
+  let rawSignature;
+  if (algorithm === "ed25519") {
+    rawSignature = sign(null, payload, keyObject);
+  } else if (algorithm === "rsa-pss-sha256") {
+    rawSignature = sign("sha256", payload, {
+      key: keyObject,
+      padding: constants.RSA_PKCS1_PSS_PADDING,
+      saltLength: 32
+    });
+  } else {
+    throw new Error(`Unsupported overlay signature algorithm: ${algorithm}`);
+  }
+  const publicKey = options.publicKey ?? createPublicKey(keyObject).export({ format: "pem", type: "spki" }).toString();
+  return {
+    ...spec,
+    signature: {
+      algorithm,
+      signature: rawSignature.toString("base64"),
+      publicKey,
+      keyId: options.keyId,
+      issuedAt: toIso(options.issuedAt) ?? new Date().toISOString(),
+      expiresAt: toIso(options.expiresAt),
+      metadata: options.metadata
+    }
+  };
+}
+function verifyOverlaySignature(overlay) {
+  if (!overlay.signature?.signature) {
+    throw new Error(`Overlay "${overlay.overlayId}" is missing signature metadata.`);
+  }
+  const payload = Buffer.from(canonicalizeOverlay(overlay), "utf8");
+  const signature = Buffer.from(overlay.signature.signature, "base64");
+  const publicKey = createPublicKey(overlay.signature.publicKey);
+  if (overlay.signature.algorithm === "ed25519") {
+    return verify(null, payload, publicKey, signature);
+  }
+  if (overlay.signature.algorithm === "rsa-pss-sha256") {
+    return verify("sha256", payload, {
+      key: publicKey,
+      padding: constants.RSA_PKCS1_PSS_PADDING,
+      saltLength: 32
+    }, signature);
+  }
+  throw new Error(`Unsupported overlay signature algorithm: ${overlay.signature.algorithm}`);
+}
+function canonicalizeOverlay(spec) {
+  const { signature, ...rest } = spec;
+  return stringify(rest);
+}
+function stripSignature(spec) {
+  const { signature, ...rest } = spec;
+  return { ...rest };
+}
+function toIso(value) {
+  if (!value) {
+    return;
+  }
+  if (typeof value === "string") {
+    return new Date(value).toISOString();
+  }
+  return value.toISOString();
+}
+export {
+  verifyOverlaySignature,
+  validateOverlaySpec,
+  stripSignature,
+  signOverlay,
+  defineOverlay,
+  defaultOverlayValidator,
+  canonicalizeOverlay,
+  assertOverlayValid,
+  applyOverlayModifications,
+  OverlayRegistry,
+  OverlayEngine,
+  OVERLAY_SCOPE_ORDER
+};

package/dist/merger.d.ts

@@ -1,11 +1,7 @@
-import { SignedOverlaySpec } from "./spec.js";
-import { OverlayRenderable } from "./types.js";
-
-//#region src/merger.d.ts
-interface ApplyOverlayOptions {
-  strict?: boolean;
+import type { SignedOverlaySpec } from './spec';
+import type { OverlayRenderable } from './types';
+export interface ApplyOverlayOptions {
+    strict?: boolean;
 }
-declare function applyOverlayModifications<T extends OverlayRenderable>(target: T, overlays: SignedOverlaySpec[], options?: ApplyOverlayOptions): T;
-//#endregion
-export { ApplyOverlayOptions, applyOverlayModifications };
+export declare function applyOverlayModifications<T extends OverlayRenderable>(target: T, overlays: SignedOverlaySpec[], options?: ApplyOverlayOptions): T;
 //# sourceMappingURL=merger.d.ts.map

package/dist/merger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merger.d.ts","names":[],"sources":["../src/merger.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,mBAAA;;AAAjB;AAUgB,iBAAA,yBAAyB,CAAA,UAAW,iBAAX,CAAA,CAAA,MAAA,EAC/B,CAD+B,EAAA,QAAA,EAE7B,iBAF6B,EAAA,EAAA,OAAA,CAAA,EAG9B,mBAH8B,CAAA,EAItC,CAJsC"}
+{"version":3,"file":"merger.d.ts","sourceRoot":"","sources":["../src/merger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAA0B,MAAM,SAAS,CAAC;AAEzE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAQD,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,iBAAiB,EACnE,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,GAAE,mBAAwB,GAChC,CAAC,CA4GH"}