assign-gingerly 0.0.75 → 0.0.77

package/assignPermissions/PermissionProcessor.js

@@ -0,0 +1,166 @@
+import { isAllowedUrl } from './isAllowedUrl.js';
+export class PermissionProcessor {
+    constructor(permissions) {
+        this.permissions = permissions;
+        const { props, attrs } = buildMaps(permissions);
+        this.props = props;
+        this.attrs = attrs;
+        this.methods = buildMethodSet(permissions);
+        this.warned = new Set();
+        this.warnedMethods = new Set();
+    }
+    get crossDomainImports() {
+        return !!this.permissions?.crossDomainImports;
+    }
+    get hasProps() {
+        return this.props.size > 0;
+    }
+    get hasAttrs() {
+        return this.attrs.size > 0;
+    }
+    checkRestrictedProp(key) {
+        if (!this.props.has(key))
+            return false;
+        this.warnRestricted(key);
+        return true;
+    }
+    checkRestrictedMethod(methodName) {
+        if (!this.methods.has(methodName))
+            return false;
+        this.warnRestrictedMethod(methodName);
+        return true;
+    }
+    redirectRestrictedProp(target, key, value) {
+        if (!this.props.has(key))
+            return false;
+        const setting = this.props.get(key);
+        const { allowCrossDomain, allowFromSameDomain } = setting || {};
+        if (allowCrossDomain) {
+            return this.applyAllowedSetting(setting, target, key, value);
+        }
+        if (allowFromSameDomain) {
+            if (isAllowedUrl(value)) {
+                return this.applyAllowedSetting(setting, target, key, value);
+            }
+            this.warnRestricted(key);
+            return true;
+        }
+        if (setting?.useMethod) {
+            const method = target?.[setting.useMethod];
+            if (typeof method === 'function') {
+                method.call(target, value);
+                return true;
+            }
+        }
+        this.warnRestricted(key);
+        return true;
+    }
+    checkRestrictedAttributeCall(methodName, args) {
+        if (methodName !== 'setAttribute' || args.length === 0 || this.attrs.size === 0) {
+            return { blocked: false };
+        }
+        const attrName = String(args[0]);
+        if (!this.attrs.has(attrName)) {
+            return { blocked: false };
+        }
+        const setting = this.attrs.get(attrName);
+        const value = args[1];
+        const { allowCrossDomain, allowFromSameDomain } = setting || {};
+        if (allowCrossDomain) {
+            return { blocked: false, attrName };
+        }
+        if (allowFromSameDomain) {
+            if (isAllowedUrl(value)) {
+                return { blocked: false, attrName };
+            }
+            this.warnRestricted(attrName);
+            return { blocked: true, attrName };
+        }
+        this.warnRestricted(attrName);
+        return { blocked: true, attrName };
+    }
+    applyAllowedSetting(setting, target, key, value) {
+        if (setting?.useMethod) {
+            const method = target?.[setting.useMethod];
+            if (typeof method === 'function') {
+                method.call(target, value);
+                return true;
+            }
+            this.warnRestricted(key);
+            return true;
+        }
+        return false;
+    }
+    warnRestricted(key) {
+        if (!this.warned.has(key)) {
+            this.warned.add(key);
+            console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
+        }
+    }
+    warnRestrictedMethod(methodName) {
+        if (!this.warnedMethods.has(methodName)) {
+            this.warnedMethods.add(methodName);
+            console.warn(`assignGingerly: method '${methodName}' is in restrictedMethodSettings — method call skipped.`);
+        }
+    }
+}
+function buildMaps(permissions) {
+    const settings = permissions?.restrictedPropSettings;
+    const props = new Map();
+    const attrs = new Map();
+    if (!settings || settings.length === 0) {
+        return { props, attrs };
+    }
+    for (const setting of settings) {
+        if (typeof setting === 'string') {
+            if (props.has(setting)) {
+                throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${setting}'.`);
+            }
+            props.set(setting, undefined);
+            continue;
+        }
+        const propNames = normalizeStrings(setting.props);
+        if (propNames.length === 0) {
+            throw new Error('assignGingerly: restrictedPropSettings object entry must have a props value.');
+        }
+        for (const prop of propNames) {
+            if (props.has(prop)) {
+                throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${prop}'.`);
+            }
+            props.set(prop, setting);
+        }
+        const attrNames = normalizeAttrNames(setting.attr, propNames);
+        for (const attr of attrNames) {
+            if (attrs.has(attr)) {
+                throw new Error(`assignGingerly: duplicate restrictedPropSettings attr entry for '${attr}'.`);
+            }
+            attrs.set(attr, setting);
+        }
+    }
+    return { props, attrs };
+}
+function normalizeStrings(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function normalizeAttrNames(attr, propNames) {
+    if (attr === undefined || attr === false)
+        return [];
+    if (attr === true)
+        return propNames;
+    return normalizeStrings(attr);
+}
+function buildMethodSet(permissions) {
+    const methodSettings = permissions?.restrictedMethodSettings;
+    const methods = new Set();
+    if (!methodSettings || methodSettings.length === 0) {
+        return methods;
+    }
+    for (const setting of methodSettings) {
+        if (typeof setting === 'string') {
+            methods.add(setting);
+        }
+    }
+    return methods;
+}

package/assignPermissions/PermissionProcessor.ts

@@ -0,0 +1,210 @@
+import type { AssignPermissions, RestrictedPropSetting } from '../types/assign-gingerly/types.js';
+import { isAllowedUrl } from './isAllowedUrl.js';
+
+export interface RestrictedPropSettingsMap {
+    props: Map<string, RestrictedPropSetting | undefined>;
+    attrs: Map<string, RestrictedPropSetting | undefined>;
+}
+
+export class PermissionProcessor {
+    private readonly permissions: AssignPermissions | undefined;
+    private readonly props: Map<string, RestrictedPropSetting | undefined>;
+    private readonly attrs: Map<string, RestrictedPropSetting | undefined>;
+    private readonly methods: Set<string>;
+    private readonly warned = new Set<string>();
+    private readonly warnedMethods = new Set<string>();
+
+    constructor(permissions: AssignPermissions | undefined) {
+        this.permissions = permissions;
+        const { props, attrs } = buildMaps(permissions);
+        this.props = props;
+        this.attrs = attrs;
+        this.methods = buildMethodSet(permissions);
+    }
+
+    get crossDomainImports(): boolean {
+        return !!this.permissions?.crossDomainImports;
+    }
+
+    get hasProps(): boolean {
+        return this.props.size > 0;
+    }
+
+    get hasAttrs(): boolean {
+        return this.attrs.size > 0;
+    }
+
+    checkRestrictedProp(key: string): boolean {
+        if (!this.props.has(key)) return false;
+        this.warnRestricted(key);
+        return true;
+    }
+
+    checkRestrictedMethod(methodName: string): boolean {
+        if (!this.methods.has(methodName)) return false;
+        this.warnRestrictedMethod(methodName);
+        return true;
+    }
+
+    redirectRestrictedProp(target: any, key: string, value: any): boolean {
+        if (!this.props.has(key)) return false;
+        const setting = this.props.get(key);
+        const { allowCrossDomain, allowFromSameDomain } = setting || {};
+
+        if (allowCrossDomain) {
+            return this.applyAllowedSetting(setting, target, key, value);
+        }
+
+        if (allowFromSameDomain) {
+            if (isAllowedUrl(value)) {
+                return this.applyAllowedSetting(setting, target, key, value);
+            }
+            this.warnRestricted(key);
+            return true;
+        }
+
+        if (setting?.useMethod) {
+            const method = target?.[setting.useMethod];
+            if (typeof method === 'function') {
+                method.call(target, value);
+                return true;
+            }
+        }
+
+        this.warnRestricted(key);
+        return true;
+    }
+
+    checkRestrictedAttributeCall(
+        methodName: string,
+        args: any[]
+    ): { blocked: boolean; attrName?: string } {
+        if (methodName !== 'setAttribute' || args.length === 0 || this.attrs.size === 0) {
+            return { blocked: false };
+        }
+        const attrName = String(args[0]);
+        if (!this.attrs.has(attrName)) {
+            return { blocked: false };
+        }
+        const setting = this.attrs.get(attrName);
+        const value = args[1];
+        const { allowCrossDomain, allowFromSameDomain } = setting || {};
+
+        if (allowCrossDomain) {
+            return { blocked: false, attrName };
+        }
+
+        if (allowFromSameDomain) {
+            if (isAllowedUrl(value)) {
+                return { blocked: false, attrName };
+            }
+            this.warnRestricted(attrName);
+            return { blocked: true, attrName };
+        }
+
+        this.warnRestricted(attrName);
+        return { blocked: true, attrName };
+    }
+
+    private applyAllowedSetting(
+        setting: RestrictedPropSetting | undefined,
+        target: any,
+        key: string,
+        value: any
+    ): boolean {
+        if (setting?.useMethod) {
+            const method = target?.[setting.useMethod];
+            if (typeof method === 'function') {
+                method.call(target, value);
+                return true;
+            }
+            this.warnRestricted(key);
+            return true;
+        }
+        return false;
+    }
+
+    private warnRestricted(key: string): void {
+        if (!this.warned.has(key)) {
+            this.warned.add(key);
+            console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
+        }
+    }
+
+    private warnRestrictedMethod(methodName: string): void {
+        if (!this.warnedMethods.has(methodName)) {
+            this.warnedMethods.add(methodName);
+            console.warn(`assignGingerly: method '${methodName}' is in restrictedMethodSettings — method call skipped.`);
+        }
+    }
+}
+
+function buildMaps(permissions: AssignPermissions | undefined): RestrictedPropSettingsMap {
+    const settings = permissions?.restrictedPropSettings;
+    const props = new Map<string, RestrictedPropSetting | undefined>();
+    const attrs = new Map<string, RestrictedPropSetting | undefined>();
+    if (!settings || settings.length === 0) {
+        return { props, attrs };
+    }
+
+    for (const setting of settings) {
+        if (typeof setting === 'string') {
+            if (props.has(setting)) {
+                throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${setting}'.`);
+            }
+            props.set(setting, undefined);
+            continue;
+        }
+
+        const propNames = normalizeStrings(setting.props);
+        if (propNames.length === 0) {
+            throw new Error('assignGingerly: restrictedPropSettings object entry must have a props value.');
+        }
+        for (const prop of propNames) {
+            if (props.has(prop)) {
+                throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${prop}'.`);
+            }
+            props.set(prop, setting);
+        }
+
+        const attrNames = normalizeAttrNames(setting.attr, propNames);
+        for (const attr of attrNames) {
+            if (attrs.has(attr)) {
+                throw new Error(`assignGingerly: duplicate restrictedPropSettings attr entry for '${attr}'.`);
+            }
+            attrs.set(attr, setting);
+        }
+    }
+    return { props, attrs };
+}
+
+function normalizeStrings(value: string | string[] | undefined): string[] {
+    if (value === undefined) return [];
+    return Array.isArray(value) ? value : [value];
+}
+
+function normalizeAttrNames(
+    attr: boolean | string | string[] | undefined,
+    propNames: string[]
+): string[] {
+    if (attr === undefined || attr === false) return [];
+    if (attr === true) return propNames;
+    return normalizeStrings(attr);
+}
+
+function buildMethodSet(permissions: AssignPermissions | undefined): Set<string> {
+    const methodSettings = permissions?.restrictedMethodSettings;
+    const methods = new Set<string>();
+    if (!methodSettings || methodSettings.length === 0) {
+        return methods;
+    }
+
+    for (const setting of methodSettings) {
+        if (typeof setting === 'string') {
+            methods.add(setting);
+        }
+        // Phase II: object-form RestrictedMethodConfig entries are ignored for now.
+    }
+
+    return methods;
+}

package/assignPermissions/isAllowedImportPath.js

@@ -1,3 +1,4 @@
+import { isAllowedUrl } from './isAllowedUrl.js';
 /**
  * Check whether an import specifier resolves to the current origin or is
  * covered by an import-map entry.
@@ -8,12 +9,7 @@ export function isAllowedImportPath(value) {
     if (!value || !(value.startsWith('./') || value.startsWith('../') || value.startsWith('/'))) {
         return isImportMapSpecifier(value);
     }
-    try {
-        return new URL(value, document.baseURI).origin === location.origin;
-    }
-    catch {
-        return false;
-    }
+    return isAllowedUrl(value);
 }
 function isImportMapSpecifier(value) {
     const importMaps = document.querySelectorAll('script[type="importmap"]');

package/assignPermissions/isAllowedImportPath.ts

@@ -1,3 +1,5 @@
+import { isAllowedUrl } from './isAllowedUrl.js';
+
 /**
  * Check whether an import specifier resolves to the current origin or is
  * covered by an import-map entry.
@@ -8,11 +10,7 @@ export function isAllowedImportPath(value: string): boolean {
         return isImportMapSpecifier(value);
     }
 
-    try {
-        return new URL(value, document.baseURI).origin === location.origin;
-    } catch {
-        return false;
-    }
+    return isAllowedUrl(value);
 }
 
 function isImportMapSpecifier(value: string): boolean {

package/assignPermissions/isAllowedUrl.js

@@ -0,0 +1,18 @@
+/**
+ * Check whether a URL string resolves to the current origin.
+ *
+ * Returns false for non-strings, empty strings, malformed URLs, or
+ * any URL whose origin differs from `location.origin`.
+ */
+export function isAllowedUrl(value, base = document.baseURI) {
+    if (typeof document === 'undefined' || typeof location === 'undefined')
+        return false;
+    if (typeof value !== 'string' || value === '')
+        return false;
+    try {
+        return new URL(value, base).origin === location.origin;
+    }
+    catch {
+        return false;
+    }
+}

package/assignPermissions/isAllowedUrl.ts

@@ -0,0 +1,15 @@
+/**
+ * Check whether a URL string resolves to the current origin.
+ *
+ * Returns false for non-strings, empty strings, malformed URLs, or
+ * any URL whose origin differs from `location.origin`.
+ */
+export function isAllowedUrl(value: string, base = document.baseURI): boolean {
+    if (typeof document === 'undefined' || typeof location === 'undefined') return false;
+    if (typeof value !== 'string' || value === '') return false;
+    try {
+        return new URL(value, base).origin === location.origin;
+    } catch {
+        return false;
+    }
+}

package/assignTentatively.js

@@ -1,4 +1,3 @@
-import { buildRestrictedPropSet, checkRestrictedProp } from './assignPermissions/restrictedProps.js';
 /**
  * Helper function to check if a string key represents an += command
  */
@@ -114,13 +113,12 @@ function getTopLevelKey(path) {
 /**
  * Main assignTentatively function with reversal support
  */
-export function assignTentatively(target, source, options, permissions) {
+export function assignTentatively(target, source, options, permissionProcessor) {
     if (!target || typeof target !== 'object') {
         return target;
     }
     const reversal = options?.reversal || {};
     const trackedCreatedPaths = new Set();
-    const restrictedPropSet = buildRestrictedPropSet(permissions);
     // Process all keys from source
     for (const key of Object.keys(source)) {
         const value = source[key];
@@ -132,7 +130,7 @@ export function assignTentatively(target, source, options, permissions) {
                     const pathParts = parsePath(path);
                     const topLevelKey = pathParts[0];
                     const lastKey = pathParts[pathParts.length - 1];
-                    if (checkRestrictedProp(restrictedPropSet, lastKey)) {
+                    if (permissionProcessor?.checkRestrictedProp(lastKey)) {
                         continue;
                     }
                     // Track if we created a new top-level path (BEFORE calling ensureNestedPath)
@@ -155,7 +153,7 @@ export function assignTentatively(target, source, options, permissions) {
                 }
                 else {
                     // Plain key - direct operation on target
-                    if (checkRestrictedProp(restrictedPropSet, path)) {
+                    if (permissionProcessor?.checkRestrictedProp(path)) {
                         continue;
                     }
                     if (path in target) {
@@ -183,7 +181,7 @@ export function assignTentatively(target, source, options, permissions) {
                     lhsPathParts = parsePath(lhsPath);
                     const topLevelKey = lhsPathParts[0];
                     lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
-                    if (checkRestrictedProp(restrictedPropSet, lhsLastKey)) {
+                    if (permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
                         continue;
                     }
                     // Track if we created a new top-level path (BEFORE calling ensureNestedPath)
@@ -195,7 +193,7 @@ export function assignTentatively(target, source, options, permissions) {
                 else {
                     lhsPathParts = [lhsPath];
                     lhsLastKey = lhsPath;
-                    if (checkRestrictedProp(restrictedPropSet, lhsLastKey)) {
+                    if (permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
                         continue;
                     }
                     lhsParent = target;
@@ -301,7 +299,7 @@ export function assignTentatively(target, source, options, permissions) {
             const pathParts = parsePath(key);
             const topLevelKey = pathParts[0];
             const lastKey = pathParts[pathParts.length - 1];
-            if (checkRestrictedProp(restrictedPropSet, lastKey)) {
+            if (permissionProcessor?.checkRestrictedProp(lastKey)) {
                 continue;
             }
             // Track if we created a new top-level path (BEFORE calling ensureNestedPath)
@@ -323,7 +321,7 @@ export function assignTentatively(target, source, options, permissions) {
                 }
                 // For nested objects, recursively apply with nested reversal tracking
                 const nestedReversal = {};
-                assignTentatively(parent[lastKey], value, { reversal: nestedReversal }, permissions);
+                assignTentatively(parent[lastKey], value, { reversal: nestedReversal }, permissionProcessor);
                 // Merge nested reversals
                 for (const revKey of Object.keys(nestedReversal)) {
                     if (!(revKey in reversal)) {
@@ -344,7 +342,7 @@ export function assignTentatively(target, source, options, permissions) {
         }
         else {
             // Non-nested key
-            if (checkRestrictedProp(restrictedPropSet, key)) {
+            if (permissionProcessor?.checkRestrictedProp(key)) {
                 continue;
             }
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
@@ -359,7 +357,7 @@ export function assignTentatively(target, source, options, permissions) {
                     target[key] = {};
                 }
                 const nestedReversal = {};
-                assignTentatively(target[key], value, { reversal: nestedReversal }, permissions);
+                assignTentatively(target[key], value, { reversal: nestedReversal }, permissionProcessor);
                 // Merge nested reversals
                 for (const revKey of Object.keys(nestedReversal)) {
                     if (!(revKey in reversal)) {

package/assignTentatively.ts

@@ -1,9 +1,7 @@
 /**
  * assignTentatively — reversible assignment with change tracking.
  */
-import type { IAssignTentativelyOptions } from './types/assign-gingerly/types.js';
-import type { AssignPermissions } from './types/assign-gingerly/types.js';
-import { buildRestrictedPropSet, checkRestrictedProp } from './assignPermissions/restrictedProps.js';
+import type { IAssignTentativelyOptions, PermissionProcessor } from './types/assign-gingerly/types.js';
 export type { IAssignTentativelyOptions };
 
 /**
@@ -137,7 +135,7 @@ export function assignTentatively(
   target: any,
   source: Record<string | symbol, any>,
   options?: IAssignTentativelyOptions,
-  permissions?: AssignPermissions
+  permissionProcessor?: PermissionProcessor
 ): any {
   if (!target || typeof target !== 'object') {
     return target;
@@ -145,7 +143,7 @@ export function assignTentatively(
 
   const reversal = options?.reversal || {};
   const trackedCreatedPaths = new Set<string>();
-  const restrictedPropSet = buildRestrictedPropSet(permissions);
+
 
   // Process all keys from source
   for (const key of Object.keys(source)) {
@@ -160,7 +158,7 @@ export function assignTentatively(
           const topLevelKey = pathParts[0];
           const lastKey = pathParts[pathParts.length - 1];
 
-          if (checkRestrictedProp(restrictedPropSet, lastKey)) {
+          if (permissionProcessor?.checkRestrictedProp(lastKey)) {
             continue;
           }
           
@@ -184,7 +182,7 @@ export function assignTentatively(
           }
         } else {
           // Plain key - direct operation on target
-          if (checkRestrictedProp(restrictedPropSet, path)) {
+          if (permissionProcessor?.checkRestrictedProp(path)) {
             continue;
           }
           if (path in target) {
@@ -215,7 +213,7 @@ export function assignTentatively(
           const topLevelKey = lhsPathParts[0];
           lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
 
-          if (checkRestrictedProp(restrictedPropSet, lhsLastKey)) {
+          if (permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
             continue;
           }
           
@@ -228,7 +226,7 @@ export function assignTentatively(
         } else {
           lhsPathParts = [lhsPath];
           lhsLastKey = lhsPath;
-          if (checkRestrictedProp(restrictedPropSet, lhsLastKey)) {
+          if (permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
             continue;
           }
           lhsParent = target;
@@ -337,7 +335,7 @@ export function assignTentatively(
       const topLevelKey = pathParts[0];
       const lastKey = pathParts[pathParts.length - 1];
 
-      if (checkRestrictedProp(restrictedPropSet, lastKey)) {
+      if (permissionProcessor?.checkRestrictedProp(lastKey)) {
         continue;
       }
 
@@ -362,7 +360,7 @@ export function assignTentatively(
         }
         // For nested objects, recursively apply with nested reversal tracking
         const nestedReversal: Record<string | symbol, any> = {};
-        assignTentatively(parent[lastKey], value, { reversal: nestedReversal }, permissions);
+        assignTentatively(parent[lastKey], value, { reversal: nestedReversal }, permissionProcessor);
         // Merge nested reversals
         for (const revKey of Object.keys(nestedReversal)) {
           if (!(revKey in reversal)) {
@@ -381,7 +379,7 @@ export function assignTentatively(
       }
     } else {
       // Non-nested key
-      if (checkRestrictedProp(restrictedPropSet, key)) {
+      if (permissionProcessor?.checkRestrictedProp(key)) {
         continue;
       }
       if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
@@ -396,7 +394,7 @@ export function assignTentatively(
           target[key] = {};
         }
         const nestedReversal: Record<string | symbol, any> = {};
-        assignTentatively(target[key], value, { reversal: nestedReversal }, permissions);
+        assignTentatively(target[key], value, { reversal: nestedReversal }, permissionProcessor);
         // Merge nested reversals
         for (const revKey of Object.keys(nestedReversal)) {
           if (!(revKey in reversal)) {

package/beVigilant.js

@@ -9,7 +9,7 @@
  */
 import { Infer } from './inferencer/inferencer.js';
 import { withScopePerimeter } from './inferencer/withScopePerimeter.js';
-import { registerInCache } from './resolveIdRef.js';
+import { registerInCache } from './resolve/resolveIdRef.js';
 /**
  * Set up a MutationObserver that watches for new [itemprop] elements
  * and applies inferred assignments from the live `from` object.

package/beVigilant.ts

@@ -10,7 +10,7 @@
 
 import { Infer } from './inferencer/inferencer.js';
 import { withScopePerimeter } from './inferencer/withScopePerimeter.js';
-import { registerInCache } from './resolveIdRef.js';
+import { registerInCache } from './resolve/resolveIdRef.js';
 
 /**
  * Set up a MutationObserver that watches for new [itemprop] elements

package/buildCSSQuery.js

@@ -1,4 +1,4 @@
-import { resolveTemplate } from './resolveTemplate.js';
+import { resolveTemplate } from './resolve/resolveTemplate.js';
 /**
  * Extracts attribute names from withAttrs configuration
  * Resolves template variables and excludes underscore-prefixed config keys

package/buildCSSQuery.ts

@@ -1,5 +1,5 @@
 import { EnhancementConfig, AttrPatterns } from './types/assign-gingerly/types';
-import { resolveTemplate } from './resolveTemplate.js';
+import { resolveTemplate } from './resolve/resolveTemplate.js';
 
 /**
  * Extracts attribute names from withAttrs configuration