@contractspec/lib.overlay-engine 3.7.20 → 3.7.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -7,3 +7,4 @@ export * from './spec';
7
7
  export * from './types';
8
8
  export * from './validator';
9
9
  export declare const tech_contracts_overlays_DocBlocks: DocBlock[];
10
+ export * from './overlay-engine.feature';
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  // @bun
2
- function g(e,r,t={}){if(!r.length)return e;let n=e.fields.map((i)=>({key:i.key,field:{...i},hidden:i.visible===!1})),a=new Map(n.map((i)=>[i.key,i])),o=e.fields.map((i)=>i.key),y=(i,s)=>{if(t.strict)throw Error(`Overlay "${s}" referenced unknown field "${i}".`)};r.forEach((i)=>{i.modifications.forEach((s)=>{switch(s.type){case"hideField":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.hidden=!0,l.field.visible=!1;break}case"renameLabel":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.label=s.newLabel;break}case"setDefault":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.defaultValue=s.value;break}case"addHelpText":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.helpText=s.text;break}case"makeRequired":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.required=s.required??!0;break}case"reorderFields":{let{filtered:l,missing:p}=w(s.fields,a);if(p.length&&t.strict)p.forEach((x)=>y(x,i.overlayId));o=I(o,l);break}default:break}})});let v=[],c=new Set;return o.forEach((i)=>{let s=a.get(i);if(!s||s.hidden)return;c.add(i),v.push(s.field)}),n.forEach((i)=>{if(i.hidden||c.has(i.key))return;v.push(i.field)}),v.forEach((i,s)=>{i.order=s,i.visible=!0}),{...e,fields:v}}function w(e,r){let t=[],n=[],a=new Set;return e.forEach((o)=>{if(!o?.trim())return;if(!r.has(o)){n.push(o);return}if(a.has(o))return;a.add(o),t.push(o)}),{filtered:t,missing:n}}function I(e,r){if(!r.length)return e;let t=new Set(r),n=e.filter((a)=>!t.has(a));return[...r,...n]}var k=["capability","workflow","dataView","presentation","operation"],u=(e)=>A(e);function A(e){let r=[];if(!e.overlayId?.trim())r.push({code:"overlay.id",message:"overlayId is required",path:["overlayId"]});if(!e.version?.trim())r.push({code:"overlay.version",message:"version is required",path:["version"]});if(!k.some((n)=>{let a=e.appliesTo?.[n];return typeof a==="string"&&a.trim().length>0}))r.push({code:"overlay.target",message:"Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",path:["appliesTo"]});if(!e.modifications?.length)r.push({code:"overlay.modifications.empty",message:"Overlay must include at least one modification.",path:["modifications"]});else e.modifications.forEach((n,a)=>{let o=["modifications",String(a)];R(n,o,r)});return{valid:r.length===0,issues:r}}function R(e,r,t){let n=(a,o,y)=>{t.push({code:a,message:o,path:y?[...r,...y]:r})};if(E(e)){if(!e.field?.trim())n("overlay.mod.field","field is required for this modification",["field"])}switch(e.type){case"renameLabel":{if(!e.newLabel?.trim())n("overlay.mod.renameLabel.newLabel","newLabel is required",["newLabel"]);break}case"reorderFields":{if(!e.fields?.length)n("overlay.mod.reorderFields.fields","fields list cannot be empty",["fields"]);let a=new Set;for(let o of e.fields??[]){if(!o?.trim()){n("overlay.mod.reorderFields.fields.blank","fields entries must be non-empty");break}if(a.has(o)){n("overlay.mod.reorderFields.fields.duplicate",`field "${o}" was listed multiple times`);break}a.add(o)}break}case"setDefault":{if(e.value===void 0)n("overlay.mod.setDefault.value","value is required",["value"]);break}case"addHelpText":{if(!e.text?.trim())n("overlay.mod.addHelpText.text","text is required",["text"]);break}case"makeRequired":case"hideField":break;default:throw Error(`Unsupported overlay modification ${e?.type??"unknown"}`)}}function E(e){return"field"in e}function U(e,r=u){let t=r(e);if(!t.valid){let n=t.issues.map((a)=>`${a.code}: ${a.message}`).join("; ");throw Error(`Invalid OverlaySpec "${e.overlayId}": ${n}`)}}var V=["capability","workflow","dataView","presentation","operation"],d={tenantId:8,role:4,userId:16,device:2,tags:1};class T{options;overlays=new Map;constructor(e={}){this.options=e}register(e,r){if(!r?.skipValidation){let y=(this.options.validator??u)(e);if(!y.valid){let v=y.issues.map((c)=>`${c.code}: ${c.message}`).join("; ");throw Error(`Overlay "${e.overlayId}" failed validation: ${v}`)}}let t=this.ensureSigned(e),n=this.getKey(t.overlayId,t.version),a={overlay:t,specificity:$(t.appliesTo),registeredAt:Date.now()};return this.overlays.set(n,a),t}unregister(e,r){if(r){this.overlays.delete(this.getKey(e,r));return}for(let t of Array.from(this.overlays.keys()))if(t.startsWith(`${e}@`))this.overlays.delete(t)}list(){return Array.from(this.overlays.values()).map((e)=>e.overlay)}get(e,r){return this.overlays.get(this.getKey(e,r))?.overlay}forContext(e){return Array.from(this.overlays.values()).filter((r)=>D(r.overlay.appliesTo,e)).sort((r,t)=>{if(r.specificity!==t.specificity)return r.specificity-t.specificity;return r.registeredAt-t.registeredAt}).map((r)=>r.overlay)}clear(){this.overlays.clear()}size(){return this.overlays.size}ensureSigned(e){if(L(e)){if(!e.signature?.signature&&!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" is missing a signature.`);return e}if(!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" must be signed before registration.`);return e}getKey(e,r){return`${e}@${r}`}}function L(e){return Boolean(e.signature)}function $(e){let r=0;return Object.keys(d).forEach((t)=>{if(t==="tags"?Array.isArray(e.tags)&&e.tags.length>0:Boolean(e[t]))r+=d[t]}),r}function D(e,r){for(let t of V){let n=e[t];if(n&&n!==r[t])return!1}if(e.tenantId&&e.tenantId!==r.tenantId)return!1;if(e.role&&e.role!==r.role)return!1;if(e.userId&&e.userId!==r.userId)return!1;if(e.device&&e.device!==r.device)return!1;if(e.tags?.length){if(!r.tags?.length)return!1;let t=new Set(r.tags);if(!e.tags.every((a)=>t.has(a)))return!1}return!0}class K{registry;audit;constructor(e){this.registry=e.registry,this.audit=e.audit}apply(e){let r=e.overlays??this.registry.forContext({capability:e.capability,workflow:e.workflow,dataView:e.dataView,presentation:e.presentation,operation:e.operation,tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}),t=g(e.target,r,{strict:e.strict}),n=C(e);return r.forEach((a)=>{this.audit?.({overlay:{overlayId:a.overlayId,version:a.version},context:n,timestamp:new Date().toISOString()})}),{target:t,overlaysApplied:r}}}function C(e){return{tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}}import{constants as m,createPrivateKey as P,createPublicKey as h,sign as O,verify as f}from"crypto";import B from"fast-json-stable-stringify";function Y(e,r,t={}){let n=t.algorithm??"ed25519",a=typeof r==="string"||Buffer.isBuffer(r)?P(r):r,o=Buffer.from(b(e),"utf8"),y;if(n==="ed25519")y=O(null,o,a);else if(n==="rsa-pss-sha256")y=O("sha256",o,{key:a,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32});else throw Error(`Unsupported overlay signature algorithm: ${n}`);let v=t.publicKey??h(a).export({format:"pem",type:"spki"}).toString();return{...e,signature:{algorithm:n,signature:y.toString("base64"),publicKey:v,keyId:t.keyId,issuedAt:S(t.issuedAt)??new Date().toISOString(),expiresAt:S(t.expiresAt),metadata:t.metadata}}}function q(e){if(!e.signature?.signature)throw Error(`Overlay "${e.overlayId}" is missing signature metadata.`);let r=Buffer.from(b(e),"utf8"),t=Buffer.from(e.signature.signature,"base64"),n=h(e.signature.publicKey);if(e.signature.algorithm==="ed25519")return f(null,r,n,t);if(e.signature.algorithm==="rsa-pss-sha256")return f("sha256",r,{key:n,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32},t);throw Error(`Unsupported overlay signature algorithm: ${e.signature.algorithm}`)}function b(e){let{signature:r,...t}=e;return B(t)}function J(e){let{signature:r,...t}=e;return{...t}}function S(e){if(!e)return;if(typeof e==="string")return new Date(e).toISOString();return e.toISOString()}var X=["tenantId","role","userId","device","tags"];function Z(e){return e}var ee=[{id:"docs.tech.contracts.overlays",title:"OverlaySpec Implementation",summary:"OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@contractspec/lib.overlay-engine`.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/overlays",tags:["tech","contracts","overlays"],body:`# OverlaySpec Implementation
2
+ function g(e,r,t={}){if(!r.length)return e;let n=e.fields.map((i)=>({key:i.key,field:{...i},hidden:i.visible===!1})),a=new Map(n.map((i)=>[i.key,i])),o=e.fields.map((i)=>i.key),y=(i,s)=>{if(t.strict)throw Error(`Overlay "${s}" referenced unknown field "${i}".`)};r.forEach((i)=>{i.modifications.forEach((s)=>{switch(s.type){case"hideField":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.hidden=!0,l.field.visible=!1;break}case"renameLabel":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.label=s.newLabel;break}case"setDefault":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.defaultValue=s.value;break}case"addHelpText":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.helpText=s.text;break}case"makeRequired":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.required=s.required??!0;break}case"reorderFields":{let{filtered:l,missing:p}=w(s.fields,a);if(p.length&&t.strict)p.forEach((b)=>y(b,i.overlayId));o=I(o,l);break}default:break}})});let v=[],c=new Set;return o.forEach((i)=>{let s=a.get(i);if(!s||s.hidden)return;c.add(i),v.push(s.field)}),n.forEach((i)=>{if(i.hidden||c.has(i.key))return;v.push(i.field)}),v.forEach((i,s)=>{i.order=s,i.visible=!0}),{...e,fields:v}}function w(e,r){let t=[],n=[],a=new Set;return e.forEach((o)=>{if(!o?.trim())return;if(!r.has(o)){n.push(o);return}if(a.has(o))return;a.add(o),t.push(o)}),{filtered:t,missing:n}}function I(e,r){if(!r.length)return e;let t=new Set(r),n=e.filter((a)=>!t.has(a));return[...r,...n]}var k=["capability","workflow","dataView","presentation","operation"],u=(e)=>A(e);function A(e){let r=[];if(!e.overlayId?.trim())r.push({code:"overlay.id",message:"overlayId is required",path:["overlayId"]});if(!e.version?.trim())r.push({code:"overlay.version",message:"version is required",path:["version"]});if(!k.some((n)=>{let a=e.appliesTo?.[n];return typeof a==="string"&&a.trim().length>0}))r.push({code:"overlay.target",message:"Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",path:["appliesTo"]});if(!e.modifications?.length)r.push({code:"overlay.modifications.empty",message:"Overlay must include at least one modification.",path:["modifications"]});else e.modifications.forEach((n,a)=>{let o=["modifications",String(a)];R(n,o,r)});return{valid:r.length===0,issues:r}}function R(e,r,t){let n=(a,o,y)=>{t.push({code:a,message:o,path:y?[...r,...y]:r})};if(E(e)){if(!e.field?.trim())n("overlay.mod.field","field is required for this modification",["field"])}switch(e.type){case"renameLabel":{if(!e.newLabel?.trim())n("overlay.mod.renameLabel.newLabel","newLabel is required",["newLabel"]);break}case"reorderFields":{if(!e.fields?.length)n("overlay.mod.reorderFields.fields","fields list cannot be empty",["fields"]);let a=new Set;for(let o of e.fields??[]){if(!o?.trim()){n("overlay.mod.reorderFields.fields.blank","fields entries must be non-empty");break}if(a.has(o)){n("overlay.mod.reorderFields.fields.duplicate",`field "${o}" was listed multiple times`);break}a.add(o)}break}case"setDefault":{if(e.value===void 0)n("overlay.mod.setDefault.value","value is required",["value"]);break}case"addHelpText":{if(!e.text?.trim())n("overlay.mod.addHelpText.text","text is required",["text"]);break}case"makeRequired":case"hideField":break;default:throw Error(`Unsupported overlay modification ${e?.type??"unknown"}`)}}function E(e){return"field"in e}function G(e,r=u){let t=r(e);if(!t.valid){let n=t.issues.map((a)=>`${a.code}: ${a.message}`).join("; ");throw Error(`Invalid OverlaySpec "${e.overlayId}": ${n}`)}}var V=["capability","workflow","dataView","presentation","operation"],d={tenantId:8,role:4,userId:16,device:2,tags:1};class T{options;overlays=new Map;constructor(e={}){this.options=e}register(e,r){if(!r?.skipValidation){let y=(this.options.validator??u)(e);if(!y.valid){let v=y.issues.map((c)=>`${c.code}: ${c.message}`).join("; ");throw Error(`Overlay "${e.overlayId}" failed validation: ${v}`)}}let t=this.ensureSigned(e),n=this.getKey(t.overlayId,t.version),a={overlay:t,specificity:$(t.appliesTo),registeredAt:Date.now()};return this.overlays.set(n,a),t}unregister(e,r){if(r){this.overlays.delete(this.getKey(e,r));return}for(let t of Array.from(this.overlays.keys()))if(t.startsWith(`${e}@`))this.overlays.delete(t)}list(){return Array.from(this.overlays.values()).map((e)=>e.overlay)}get(e,r){return this.overlays.get(this.getKey(e,r))?.overlay}forContext(e){return Array.from(this.overlays.values()).filter((r)=>D(r.overlay.appliesTo,e)).sort((r,t)=>{if(r.specificity!==t.specificity)return r.specificity-t.specificity;return r.registeredAt-t.registeredAt}).map((r)=>r.overlay)}clear(){this.overlays.clear()}size(){return this.overlays.size}ensureSigned(e){if(L(e)){if(!e.signature?.signature&&!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" is missing a signature.`);return e}if(!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" must be signed before registration.`);return e}getKey(e,r){return`${e}@${r}`}}function L(e){return Boolean(e.signature)}function $(e){let r=0;return Object.keys(d).forEach((t)=>{if(t==="tags"?Array.isArray(e.tags)&&e.tags.length>0:Boolean(e[t]))r+=d[t]}),r}function D(e,r){for(let t of V){let n=e[t];if(n&&n!==r[t])return!1}if(e.tenantId&&e.tenantId!==r.tenantId)return!1;if(e.role&&e.role!==r.role)return!1;if(e.userId&&e.userId!==r.userId)return!1;if(e.device&&e.device!==r.device)return!1;if(e.tags?.length){if(!r.tags?.length)return!1;let t=new Set(r.tags);if(!e.tags.every((a)=>t.has(a)))return!1}return!0}class K{registry;audit;constructor(e){this.registry=e.registry,this.audit=e.audit}apply(e){let r=e.overlays??this.registry.forContext({capability:e.capability,workflow:e.workflow,dataView:e.dataView,presentation:e.presentation,operation:e.operation,tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}),t=g(e.target,r,{strict:e.strict}),n=C(e);return r.forEach((a)=>{this.audit?.({overlay:{overlayId:a.overlayId,version:a.version},context:n,timestamp:new Date().toISOString()})}),{target:t,overlaysApplied:r}}}function C(e){return{tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}}import{constants as m,createPrivateKey as P,createPublicKey as h,sign as O,verify as f}from"crypto";import B from"fast-json-stable-stringify";function q(e,r,t={}){let n=t.algorithm??"ed25519",a=typeof r==="string"||Buffer.isBuffer(r)?P(r):r,o=Buffer.from(x(e),"utf8"),y;if(n==="ed25519")y=O(null,o,a);else if(n==="rsa-pss-sha256")y=O("sha256",o,{key:a,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32});else throw Error(`Unsupported overlay signature algorithm: ${n}`);let v=t.publicKey??h(a).export({format:"pem",type:"spki"}).toString();return{...e,signature:{algorithm:n,signature:y.toString("base64"),publicKey:v,keyId:t.keyId,issuedAt:S(t.issuedAt)??new Date().toISOString(),expiresAt:S(t.expiresAt),metadata:t.metadata}}}function J(e){if(!e.signature?.signature)throw Error(`Overlay "${e.overlayId}" is missing signature metadata.`);let r=Buffer.from(x(e),"utf8"),t=Buffer.from(e.signature.signature,"base64"),n=h(e.signature.publicKey);if(e.signature.algorithm==="ed25519")return f(null,r,n,t);if(e.signature.algorithm==="rsa-pss-sha256")return f("sha256",r,{key:n,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32},t);throw Error(`Unsupported overlay signature algorithm: ${e.signature.algorithm}`)}function x(e){let{signature:r,...t}=e;return B(t)}function Q(e){let{signature:r,...t}=e;return{...t}}function S(e){if(!e)return;if(typeof e==="string")return new Date(e).toISOString();return e.toISOString()}var Z=["tenantId","role","userId","device","tags"];function M(e){return e}import{defineFeature as _}from"@contractspec/lib.contracts-spec/features";var te=_({meta:{key:"libs.overlay-engine",version:"1.0.0",title:"Overlay Engine",description:"Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",domain:"overlay-engine",owners:["@contractspec-core"],tags:["package","libs","overlay-engine"],stability:"experimental"}});var ae=[{id:"docs.tech.contracts.overlays",title:"OverlaySpec Implementation",summary:"OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@contractspec/lib.overlay-engine`.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/overlays",tags:["tech","contracts","overlays"],body:`# OverlaySpec Implementation
3
3
 
4
4
  OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in \`@contractspec/lib.overlay-engine\`.
5
5
 
@@ -66,4 +66,4 @@ Keys are stored in \`OverlaySigningKey\` (Prisma) and referenced by the \`Overla
66
66
 
67
67
 
68
68
 
69
- `}];export{q as verifyOverlaySignature,A as validateOverlaySpec,ee as tech_contracts_overlays_DocBlocks,J as stripSignature,Y as signOverlay,Z as defineOverlay,u as defaultOverlayValidator,b as canonicalizeOverlay,U as assertOverlayValid,g as applyOverlayModifications,T as OverlayRegistry,K as OverlayEngine,X as OVERLAY_SCOPE_ORDER};
69
+ `}];export{J as verifyOverlaySignature,A as validateOverlaySpec,ae as tech_contracts_overlays_DocBlocks,Q as stripSignature,q as signOverlay,M as defineOverlay,u as defaultOverlayValidator,x as canonicalizeOverlay,G as assertOverlayValid,g as applyOverlayModifications,T as OverlayRegistry,te as OverlayEngineFeature,K as OverlayEngine,Z as OVERLAY_SCOPE_ORDER};
@@ -1,4 +1,4 @@
1
- function g(e,r,t={}){if(!r.length)return e;let n=e.fields.map((i)=>({key:i.key,field:{...i},hidden:i.visible===!1})),a=new Map(n.map((i)=>[i.key,i])),o=e.fields.map((i)=>i.key),y=(i,s)=>{if(t.strict)throw Error(`Overlay "${s}" referenced unknown field "${i}".`)};r.forEach((i)=>{i.modifications.forEach((s)=>{switch(s.type){case"hideField":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.hidden=!0,l.field.visible=!1;break}case"renameLabel":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.label=s.newLabel;break}case"setDefault":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.defaultValue=s.value;break}case"addHelpText":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.helpText=s.text;break}case"makeRequired":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.required=s.required??!0;break}case"reorderFields":{let{filtered:l,missing:p}=w(s.fields,a);if(p.length&&t.strict)p.forEach((x)=>y(x,i.overlayId));o=I(o,l);break}default:break}})});let v=[],c=new Set;return o.forEach((i)=>{let s=a.get(i);if(!s||s.hidden)return;c.add(i),v.push(s.field)}),n.forEach((i)=>{if(i.hidden||c.has(i.key))return;v.push(i.field)}),v.forEach((i,s)=>{i.order=s,i.visible=!0}),{...e,fields:v}}function w(e,r){let t=[],n=[],a=new Set;return e.forEach((o)=>{if(!o?.trim())return;if(!r.has(o)){n.push(o);return}if(a.has(o))return;a.add(o),t.push(o)}),{filtered:t,missing:n}}function I(e,r){if(!r.length)return e;let t=new Set(r),n=e.filter((a)=>!t.has(a));return[...r,...n]}var k=["capability","workflow","dataView","presentation","operation"],u=(e)=>A(e);function A(e){let r=[];if(!e.overlayId?.trim())r.push({code:"overlay.id",message:"overlayId is required",path:["overlayId"]});if(!e.version?.trim())r.push({code:"overlay.version",message:"version is required",path:["version"]});if(!k.some((n)=>{let a=e.appliesTo?.[n];return typeof a==="string"&&a.trim().length>0}))r.push({code:"overlay.target",message:"Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",path:["appliesTo"]});if(!e.modifications?.length)r.push({code:"overlay.modifications.empty",message:"Overlay must include at least one modification.",path:["modifications"]});else e.modifications.forEach((n,a)=>{let o=["modifications",String(a)];R(n,o,r)});return{valid:r.length===0,issues:r}}function R(e,r,t){let n=(a,o,y)=>{t.push({code:a,message:o,path:y?[...r,...y]:r})};if(E(e)){if(!e.field?.trim())n("overlay.mod.field","field is required for this modification",["field"])}switch(e.type){case"renameLabel":{if(!e.newLabel?.trim())n("overlay.mod.renameLabel.newLabel","newLabel is required",["newLabel"]);break}case"reorderFields":{if(!e.fields?.length)n("overlay.mod.reorderFields.fields","fields list cannot be empty",["fields"]);let a=new Set;for(let o of e.fields??[]){if(!o?.trim()){n("overlay.mod.reorderFields.fields.blank","fields entries must be non-empty");break}if(a.has(o)){n("overlay.mod.reorderFields.fields.duplicate",`field "${o}" was listed multiple times`);break}a.add(o)}break}case"setDefault":{if(e.value===void 0)n("overlay.mod.setDefault.value","value is required",["value"]);break}case"addHelpText":{if(!e.text?.trim())n("overlay.mod.addHelpText.text","text is required",["text"]);break}case"makeRequired":case"hideField":break;default:throw Error(`Unsupported overlay modification ${e?.type??"unknown"}`)}}function E(e){return"field"in e}function U(e,r=u){let t=r(e);if(!t.valid){let n=t.issues.map((a)=>`${a.code}: ${a.message}`).join("; ");throw Error(`Invalid OverlaySpec "${e.overlayId}": ${n}`)}}var V=["capability","workflow","dataView","presentation","operation"],d={tenantId:8,role:4,userId:16,device:2,tags:1};class T{options;overlays=new Map;constructor(e={}){this.options=e}register(e,r){if(!r?.skipValidation){let y=(this.options.validator??u)(e);if(!y.valid){let v=y.issues.map((c)=>`${c.code}: ${c.message}`).join("; ");throw Error(`Overlay "${e.overlayId}" failed validation: ${v}`)}}let t=this.ensureSigned(e),n=this.getKey(t.overlayId,t.version),a={overlay:t,specificity:$(t.appliesTo),registeredAt:Date.now()};return this.overlays.set(n,a),t}unregister(e,r){if(r){this.overlays.delete(this.getKey(e,r));return}for(let t of Array.from(this.overlays.keys()))if(t.startsWith(`${e}@`))this.overlays.delete(t)}list(){return Array.from(this.overlays.values()).map((e)=>e.overlay)}get(e,r){return this.overlays.get(this.getKey(e,r))?.overlay}forContext(e){return Array.from(this.overlays.values()).filter((r)=>D(r.overlay.appliesTo,e)).sort((r,t)=>{if(r.specificity!==t.specificity)return r.specificity-t.specificity;return r.registeredAt-t.registeredAt}).map((r)=>r.overlay)}clear(){this.overlays.clear()}size(){return this.overlays.size}ensureSigned(e){if(L(e)){if(!e.signature?.signature&&!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" is missing a signature.`);return e}if(!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" must be signed before registration.`);return e}getKey(e,r){return`${e}@${r}`}}function L(e){return Boolean(e.signature)}function $(e){let r=0;return Object.keys(d).forEach((t)=>{if(t==="tags"?Array.isArray(e.tags)&&e.tags.length>0:Boolean(e[t]))r+=d[t]}),r}function D(e,r){for(let t of V){let n=e[t];if(n&&n!==r[t])return!1}if(e.tenantId&&e.tenantId!==r.tenantId)return!1;if(e.role&&e.role!==r.role)return!1;if(e.userId&&e.userId!==r.userId)return!1;if(e.device&&e.device!==r.device)return!1;if(e.tags?.length){if(!r.tags?.length)return!1;let t=new Set(r.tags);if(!e.tags.every((a)=>t.has(a)))return!1}return!0}class K{registry;audit;constructor(e){this.registry=e.registry,this.audit=e.audit}apply(e){let r=e.overlays??this.registry.forContext({capability:e.capability,workflow:e.workflow,dataView:e.dataView,presentation:e.presentation,operation:e.operation,tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}),t=g(e.target,r,{strict:e.strict}),n=C(e);return r.forEach((a)=>{this.audit?.({overlay:{overlayId:a.overlayId,version:a.version},context:n,timestamp:new Date().toISOString()})}),{target:t,overlaysApplied:r}}}function C(e){return{tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}}import{constants as m,createPrivateKey as P,createPublicKey as h,sign as O,verify as f}from"crypto";import B from"fast-json-stable-stringify";function Y(e,r,t={}){let n=t.algorithm??"ed25519",a=typeof r==="string"||Buffer.isBuffer(r)?P(r):r,o=Buffer.from(b(e),"utf8"),y;if(n==="ed25519")y=O(null,o,a);else if(n==="rsa-pss-sha256")y=O("sha256",o,{key:a,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32});else throw Error(`Unsupported overlay signature algorithm: ${n}`);let v=t.publicKey??h(a).export({format:"pem",type:"spki"}).toString();return{...e,signature:{algorithm:n,signature:y.toString("base64"),publicKey:v,keyId:t.keyId,issuedAt:S(t.issuedAt)??new Date().toISOString(),expiresAt:S(t.expiresAt),metadata:t.metadata}}}function q(e){if(!e.signature?.signature)throw Error(`Overlay "${e.overlayId}" is missing signature metadata.`);let r=Buffer.from(b(e),"utf8"),t=Buffer.from(e.signature.signature,"base64"),n=h(e.signature.publicKey);if(e.signature.algorithm==="ed25519")return f(null,r,n,t);if(e.signature.algorithm==="rsa-pss-sha256")return f("sha256",r,{key:n,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32},t);throw Error(`Unsupported overlay signature algorithm: ${e.signature.algorithm}`)}function b(e){let{signature:r,...t}=e;return B(t)}function J(e){let{signature:r,...t}=e;return{...t}}function S(e){if(!e)return;if(typeof e==="string")return new Date(e).toISOString();return e.toISOString()}var X=["tenantId","role","userId","device","tags"];function Z(e){return e}var ee=[{id:"docs.tech.contracts.overlays",title:"OverlaySpec Implementation",summary:"OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@contractspec/lib.overlay-engine`.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/overlays",tags:["tech","contracts","overlays"],body:`# OverlaySpec Implementation
1
+ function g(e,r,t={}){if(!r.length)return e;let n=e.fields.map((i)=>({key:i.key,field:{...i},hidden:i.visible===!1})),a=new Map(n.map((i)=>[i.key,i])),o=e.fields.map((i)=>i.key),y=(i,s)=>{if(t.strict)throw Error(`Overlay "${s}" referenced unknown field "${i}".`)};r.forEach((i)=>{i.modifications.forEach((s)=>{switch(s.type){case"hideField":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.hidden=!0,l.field.visible=!1;break}case"renameLabel":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.label=s.newLabel;break}case"setDefault":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.defaultValue=s.value;break}case"addHelpText":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.helpText=s.text;break}case"makeRequired":{let l=a.get(s.field);if(!l)return y(s.field,i.overlayId);l.field.required=s.required??!0;break}case"reorderFields":{let{filtered:l,missing:p}=w(s.fields,a);if(p.length&&t.strict)p.forEach((b)=>y(b,i.overlayId));o=I(o,l);break}default:break}})});let v=[],c=new Set;return o.forEach((i)=>{let s=a.get(i);if(!s||s.hidden)return;c.add(i),v.push(s.field)}),n.forEach((i)=>{if(i.hidden||c.has(i.key))return;v.push(i.field)}),v.forEach((i,s)=>{i.order=s,i.visible=!0}),{...e,fields:v}}function w(e,r){let t=[],n=[],a=new Set;return e.forEach((o)=>{if(!o?.trim())return;if(!r.has(o)){n.push(o);return}if(a.has(o))return;a.add(o),t.push(o)}),{filtered:t,missing:n}}function I(e,r){if(!r.length)return e;let t=new Set(r),n=e.filter((a)=>!t.has(a));return[...r,...n]}var k=["capability","workflow","dataView","presentation","operation"],u=(e)=>A(e);function A(e){let r=[];if(!e.overlayId?.trim())r.push({code:"overlay.id",message:"overlayId is required",path:["overlayId"]});if(!e.version?.trim())r.push({code:"overlay.version",message:"version is required",path:["version"]});if(!k.some((n)=>{let a=e.appliesTo?.[n];return typeof a==="string"&&a.trim().length>0}))r.push({code:"overlay.target",message:"Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",path:["appliesTo"]});if(!e.modifications?.length)r.push({code:"overlay.modifications.empty",message:"Overlay must include at least one modification.",path:["modifications"]});else e.modifications.forEach((n,a)=>{let o=["modifications",String(a)];R(n,o,r)});return{valid:r.length===0,issues:r}}function R(e,r,t){let n=(a,o,y)=>{t.push({code:a,message:o,path:y?[...r,...y]:r})};if(E(e)){if(!e.field?.trim())n("overlay.mod.field","field is required for this modification",["field"])}switch(e.type){case"renameLabel":{if(!e.newLabel?.trim())n("overlay.mod.renameLabel.newLabel","newLabel is required",["newLabel"]);break}case"reorderFields":{if(!e.fields?.length)n("overlay.mod.reorderFields.fields","fields list cannot be empty",["fields"]);let a=new Set;for(let o of e.fields??[]){if(!o?.trim()){n("overlay.mod.reorderFields.fields.blank","fields entries must be non-empty");break}if(a.has(o)){n("overlay.mod.reorderFields.fields.duplicate",`field "${o}" was listed multiple times`);break}a.add(o)}break}case"setDefault":{if(e.value===void 0)n("overlay.mod.setDefault.value","value is required",["value"]);break}case"addHelpText":{if(!e.text?.trim())n("overlay.mod.addHelpText.text","text is required",["text"]);break}case"makeRequired":case"hideField":break;default:throw Error(`Unsupported overlay modification ${e?.type??"unknown"}`)}}function E(e){return"field"in e}function G(e,r=u){let t=r(e);if(!t.valid){let n=t.issues.map((a)=>`${a.code}: ${a.message}`).join("; ");throw Error(`Invalid OverlaySpec "${e.overlayId}": ${n}`)}}var V=["capability","workflow","dataView","presentation","operation"],d={tenantId:8,role:4,userId:16,device:2,tags:1};class T{options;overlays=new Map;constructor(e={}){this.options=e}register(e,r){if(!r?.skipValidation){let y=(this.options.validator??u)(e);if(!y.valid){let v=y.issues.map((c)=>`${c.code}: ${c.message}`).join("; ");throw Error(`Overlay "${e.overlayId}" failed validation: ${v}`)}}let t=this.ensureSigned(e),n=this.getKey(t.overlayId,t.version),a={overlay:t,specificity:$(t.appliesTo),registeredAt:Date.now()};return this.overlays.set(n,a),t}unregister(e,r){if(r){this.overlays.delete(this.getKey(e,r));return}for(let t of Array.from(this.overlays.keys()))if(t.startsWith(`${e}@`))this.overlays.delete(t)}list(){return Array.from(this.overlays.values()).map((e)=>e.overlay)}get(e,r){return this.overlays.get(this.getKey(e,r))?.overlay}forContext(e){return Array.from(this.overlays.values()).filter((r)=>D(r.overlay.appliesTo,e)).sort((r,t)=>{if(r.specificity!==t.specificity)return r.specificity-t.specificity;return r.registeredAt-t.registeredAt}).map((r)=>r.overlay)}clear(){this.overlays.clear()}size(){return this.overlays.size}ensureSigned(e){if(L(e)){if(!e.signature?.signature&&!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" is missing a signature.`);return e}if(!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" must be signed before registration.`);return e}getKey(e,r){return`${e}@${r}`}}function L(e){return Boolean(e.signature)}function $(e){let r=0;return Object.keys(d).forEach((t)=>{if(t==="tags"?Array.isArray(e.tags)&&e.tags.length>0:Boolean(e[t]))r+=d[t]}),r}function D(e,r){for(let t of V){let n=e[t];if(n&&n!==r[t])return!1}if(e.tenantId&&e.tenantId!==r.tenantId)return!1;if(e.role&&e.role!==r.role)return!1;if(e.userId&&e.userId!==r.userId)return!1;if(e.device&&e.device!==r.device)return!1;if(e.tags?.length){if(!r.tags?.length)return!1;let t=new Set(r.tags);if(!e.tags.every((a)=>t.has(a)))return!1}return!0}class K{registry;audit;constructor(e){this.registry=e.registry,this.audit=e.audit}apply(e){let r=e.overlays??this.registry.forContext({capability:e.capability,workflow:e.workflow,dataView:e.dataView,presentation:e.presentation,operation:e.operation,tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}),t=g(e.target,r,{strict:e.strict}),n=C(e);return r.forEach((a)=>{this.audit?.({overlay:{overlayId:a.overlayId,version:a.version},context:n,timestamp:new Date().toISOString()})}),{target:t,overlaysApplied:r}}}function C(e){return{tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}}import{constants as m,createPrivateKey as P,createPublicKey as h,sign as O,verify as f}from"crypto";import B from"fast-json-stable-stringify";function q(e,r,t={}){let n=t.algorithm??"ed25519",a=typeof r==="string"||Buffer.isBuffer(r)?P(r):r,o=Buffer.from(x(e),"utf8"),y;if(n==="ed25519")y=O(null,o,a);else if(n==="rsa-pss-sha256")y=O("sha256",o,{key:a,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32});else throw Error(`Unsupported overlay signature algorithm: ${n}`);let v=t.publicKey??h(a).export({format:"pem",type:"spki"}).toString();return{...e,signature:{algorithm:n,signature:y.toString("base64"),publicKey:v,keyId:t.keyId,issuedAt:S(t.issuedAt)??new Date().toISOString(),expiresAt:S(t.expiresAt),metadata:t.metadata}}}function J(e){if(!e.signature?.signature)throw Error(`Overlay "${e.overlayId}" is missing signature metadata.`);let r=Buffer.from(x(e),"utf8"),t=Buffer.from(e.signature.signature,"base64"),n=h(e.signature.publicKey);if(e.signature.algorithm==="ed25519")return f(null,r,n,t);if(e.signature.algorithm==="rsa-pss-sha256")return f("sha256",r,{key:n,padding:m.RSA_PKCS1_PSS_PADDING,saltLength:32},t);throw Error(`Unsupported overlay signature algorithm: ${e.signature.algorithm}`)}function x(e){let{signature:r,...t}=e;return B(t)}function Q(e){let{signature:r,...t}=e;return{...t}}function S(e){if(!e)return;if(typeof e==="string")return new Date(e).toISOString();return e.toISOString()}var Z=["tenantId","role","userId","device","tags"];function M(e){return e}import{defineFeature as _}from"@contractspec/lib.contracts-spec/features";var te=_({meta:{key:"libs.overlay-engine",version:"1.0.0",title:"Overlay Engine",description:"Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",domain:"overlay-engine",owners:["@contractspec-core"],tags:["package","libs","overlay-engine"],stability:"experimental"}});var ae=[{id:"docs.tech.contracts.overlays",title:"OverlaySpec Implementation",summary:"OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in `@contractspec/lib.overlay-engine`.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/overlays",tags:["tech","contracts","overlays"],body:`# OverlaySpec Implementation
2
2
 
3
3
  OverlaySpecs allow tenants/users to adapt presentation without duplicating code. Implementation lives in \`@contractspec/lib.overlay-engine\`.
4
4
 
@@ -65,4 +65,4 @@ Keys are stored in \`OverlaySigningKey\` (Prisma) and referenced by the \`Overla
65
65
 
66
66
 
67
67
 
68
- `}];export{q as verifyOverlaySignature,A as validateOverlaySpec,ee as tech_contracts_overlays_DocBlocks,J as stripSignature,Y as signOverlay,Z as defineOverlay,u as defaultOverlayValidator,b as canonicalizeOverlay,U as assertOverlayValid,g as applyOverlayModifications,T as OverlayRegistry,K as OverlayEngine,X as OVERLAY_SCOPE_ORDER};
68
+ `}];export{J as verifyOverlaySignature,A as validateOverlaySpec,ae as tech_contracts_overlays_DocBlocks,Q as stripSignature,q as signOverlay,M as defineOverlay,u as defaultOverlayValidator,x as canonicalizeOverlay,G as assertOverlayValid,g as applyOverlayModifications,T as OverlayRegistry,te as OverlayEngineFeature,K as OverlayEngine,Z as OVERLAY_SCOPE_ORDER};
@@ -0,0 +1 @@
1
+ import{defineFeature as g}from"@contractspec/lib.contracts-spec/features";var j=g({meta:{key:"libs.overlay-engine",version:"1.0.0",title:"Overlay Engine",description:"Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",domain:"overlay-engine",owners:["@contractspec-core"],tags:["package","libs","overlay-engine"],stability:"experimental"}});export{j as OverlayEngineFeature};
@@ -0,0 +1 @@
1
+ export declare const OverlayEngineFeature: import("@contractspec/lib.contracts-spec").FeatureModuleSpec;
@@ -0,0 +1,2 @@
1
+ // @bun
2
+ import{defineFeature as g}from"@contractspec/lib.contracts-spec/features";var j=g({meta:{key:"libs.overlay-engine",version:"1.0.0",title:"Overlay Engine",description:"Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",domain:"overlay-engine",owners:["@contractspec-core"],tags:["package","libs","overlay-engine"],stability:"experimental"}});export{j as OverlayEngineFeature};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@contractspec/lib.overlay-engine",
3
- "version": "3.7.20",
3
+ "version": "3.7.22",
4
4
  "description": "Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",
5
5
  "keywords": [
6
6
  "contractspec",
@@ -32,11 +32,11 @@
32
32
  "typecheck": "tsc --noEmit"
33
33
  },
34
34
  "dependencies": {
35
- "@contractspec/lib.contracts-spec": "5.4.0",
35
+ "@contractspec/lib.contracts-spec": "5.5.1",
36
36
  "fast-json-stable-stringify": "^2.1.0"
37
37
  },
38
38
  "peerDependencies": {
39
- "react": "^19.0.0"
39
+ "react": "19.2.0"
40
40
  },
41
41
  "peerDependenciesMeta": {
42
42
  "react": {
@@ -46,7 +46,7 @@
46
46
  "devDependencies": {
47
47
  "@contractspec/tool.typescript": "3.7.13",
48
48
  "typescript": "^5.9.3",
49
- "@contractspec/tool.bun": "3.7.14"
49
+ "@contractspec/tool.bun": "3.7.17"
50
50
  },
51
51
  "exports": {
52
52
  ".": {
@@ -61,6 +61,12 @@
61
61
  "node": "./dist/node/merger.js",
62
62
  "default": "./dist/merger.js"
63
63
  },
64
+ "./overlay-engine.feature": {
65
+ "types": "./dist/overlay-engine.feature.d.ts",
66
+ "bun": "./dist/overlay-engine.feature.js",
67
+ "node": "./dist/node/overlay-engine.feature.js",
68
+ "default": "./dist/overlay-engine.feature.js"
69
+ },
64
70
  "./react": {
65
71
  "types": "./dist/react.d.ts",
66
72
  "bun": "./dist/react.js",
@@ -119,6 +125,12 @@
119
125
  "node": "./dist/node/merger.js",
120
126
  "default": "./dist/merger.js"
121
127
  },
128
+ "./overlay-engine.feature": {
129
+ "types": "./dist/overlay-engine.feature.d.ts",
130
+ "bun": "./dist/overlay-engine.feature.js",
131
+ "node": "./dist/node/overlay-engine.feature.js",
132
+ "default": "./dist/overlay-engine.feature.js"
133
+ },
122
134
  "./react": {
123
135
  "types": "./dist/react.d.ts",
124
136
  "bun": "./dist/react.js",