assign-gingerly 0.0.71 → 0.0.72

package/inferencer/types/assign-gingerly/types.d.ts

@@ -252,6 +252,12 @@ export interface IAssignGingerlyOptions {
   bypassChecks?: boolean;
   /**
    * Method names to call during path evaluation (e.g., for `?.method()` calls)
+   *
+   * Append `|` to a path segment (e.g., `?.deref|?.classList?.add`) to call a
+   * listed method with zero arguments instead of consuming the next path segment
+   * as its argument. On the last segment, `|` calls the method with no arguments
+   * and ignores the value. The `|` suffix only applies to names listed here —
+   * for any other segment it is treated as part of a literal property name.
    */
   withMethods?: string[] | Set<string>;
   /**
@@ -343,7 +349,7 @@ export interface AssignFromOptions {
   /** Protocol handlers (sync or async) */
   protocols?: Record<string, (key: string) => any | Promise<any>>;
 
-  /** Method names to call during path evaluation */
+  /** Method names to call during path evaluation (append `|` to a path segment for a zero-argument call) */
   withMethods?: string[] | Set<string>;
 
   /** Alias mappings for path segments */
@@ -701,7 +707,7 @@ export interface HandlerConfig {
  * Handlers are invoked when a LHS key ends with ' =>'.
  */
 export interface AssignFromHandler {
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any): Promise<void> | void;
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any, permissions?: AssignPermissions): Promise<void> | void;
 }
 
 /**
@@ -879,7 +885,7 @@ export interface LazyLoadInstantiatedContext {
 export declare class LazyLoadHandler implements AssignFromHandler {
     config: any;
     constructor(config: any);
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any): Promise<void>;
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any, permissions?: AssignPermissions): Promise<void>;
     protected onCloneInserted(nodes: Node[], lhsTarget: Element, resolvedParams: Record<string, any>): Promise<void>;
 }
 
@@ -927,3 +933,54 @@ export interface AddEventListenerConfig extends AssignDispatchVector  {
    
 }
 //#endregion
+
+
+// =============================================================================
+// Permissions
+// =============================================================================
+
+/**
+ * Phase II+: object form for a restricted property setting.
+ */
+export interface RestrictedPropSetting {
+    prop: string;
+    useMethod?: string;          // Phase II: redirect to a safe method
+    attr?: string;               // Phase III: also watch setAttribute for this attr
+    allowFromSameHost?: boolean; // Phase III
+    allowCrossDomain?: boolean;  // Phase III
+}
+
+/**
+ * Phase IV+: object form for a restricted method setting.
+ */
+export interface RestrictedMethodConfig {
+    method: string;
+    addArgs?: string[];          // Phase V: append sanitizer args
+}
+
+/**
+ * Permissions interface for controlling security-sensitive operations.
+ * Only trusted script can set these — never parsed from HTML attributes.
+ */
+export interface AssignPermissions {
+    /** Allow imports from cross-domain URLs (default: false) */
+    crossDomainImports?: boolean;
+
+    /**
+     * Restricted property settings.
+     * Phase I: string entries are property names that cannot be assigned.
+     * Phase II: an object with useMethod redirects ordinary assignment to that
+     * method; command operations remain blocked. Phase III+ adds attr support.
+     *
+     * NOTE: This is a property-assignment guard only. Method calls (setAttribute, etc.)
+     * are not blocked — see Phase III+. Event listeners can still be registered, but
+     * assignments performed by their vectors inherit these permissions.
+     */
+    restrictedPropSettings?: Array<string | RestrictedPropSetting>;
+
+    /** Sanitizer options (Phase III+) */
+    sanitizerOptions?: Record<string, any>;
+
+    /** Restricted method settings (Phase IV+) */
+    restrictedMethodSettings?: Array<string | RestrictedMethodConfig>;
+}

package/isAllowedImportPath.js

@@ -15,6 +15,68 @@
  * isAllowedImportPath('https://evil.com/x.js'); // false
  * isAllowedImportPath('//cdn.example.com/x.js'); // false
  */
+/**
+ * Module-level warn dedup — one warning per property key per process lifetime.
+ */
+const warnedOnce = new Set();
+/**
+ * Warn once per key that a restricted property assignment was skipped.
+ */
+function warnRestricted(key) {
+    if (!warnedOnce.has(key)) {
+        warnedOnce.add(key);
+        console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
+    }
+}
+/**
+ * Normalize the restrictedPropSettings from permissions into a fast-lookup Set.
+ * Phase I: extracts string entries only (object entries are Phase II+).
+ * Returns undefined when nothing is restricted (fast-bail in callers).
+ */
+export function buildRestrictedPropSet(permissions) {
+    const settings = permissions?.restrictedPropSettings;
+    if (!settings || settings.length === 0)
+        return undefined;
+    const restrictedPropSet = new Map();
+    for (const setting of settings) {
+        const prop = typeof setting === 'string' ? setting : setting.prop;
+        if (restrictedPropSet.has(prop)) {
+            throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${prop}'.`);
+        }
+        restrictedPropSet.set(prop, typeof setting === 'string' ? undefined : setting);
+    }
+    return restrictedPropSet;
+}
+/**
+ * Check if a property key is restricted. If so, warn (once) and return true.
+ * Call sites should `continue` or skip the assignment when this returns true.
+ */
+export function checkRestrictedProp(restrictedPropSet, key) {
+    if (!restrictedPropSet || !restrictedPropSet.has(key))
+        return false;
+    warnRestricted(key);
+    return true;
+}
+/**
+ * Redirect an ordinary assignment through its configured safe method.
+ * Returns true when the property is restricted, whether redirected or skipped.
+ */
+export function redirectRestrictedProp(restrictedPropSet, target, key, value) {
+    if (!restrictedPropSet || !restrictedPropSet.has(key))
+        return false;
+    const setting = restrictedPropSet.get(key);
+    if (!setting?.useMethod) {
+        warnRestricted(key);
+        return true;
+    }
+    const method = target?.[setting.useMethod];
+    if (typeof method !== 'function') {
+        warnRestricted(key);
+        return true;
+    }
+    method.call(target, value);
+    return true;
+}
 /**
  * Check if an import path is allowed (non-cross-domain).
  *

package/isAllowedImportPath.ts

@@ -16,16 +16,81 @@
  * isAllowedImportPath('//cdn.example.com/x.js'); // false
  */
 
+// Re-export AssignPermissions from canonical location for backwards compatibility
+export type { AssignPermissions } from './types/assign-gingerly/types.js';
+import type { AssignPermissions, RestrictedPropSetting } from './types/assign-gingerly/types.js';
+
+export type RestrictedPropSettingsMap = Map<string, RestrictedPropSetting | undefined>;
+
+/**
+ * Module-level warn dedup — one warning per property key per process lifetime.
+ */
+const warnedOnce = new Set<string>();
+
+/**
+ * Warn once per key that a restricted property assignment was skipped.
+ */
+function warnRestricted(key: string): void {
+    if (!warnedOnce.has(key)) {
+        warnedOnce.add(key);
+        console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
+    }
+}
+
 /**
- * Permissions interface for controlling security-sensitive operations.
- * Passed as the last parameter to assignGingerly, assignFrom, and enhanceAll.
- * Only trusted script can set these — they are never parsed from HTML attributes.
+ * Normalize the restrictedPropSettings from permissions into a fast-lookup Set.
+ * Phase I: extracts string entries only (object entries are Phase II+).
+ * Returns undefined when nothing is restricted (fast-bail in callers).
  */
-export interface AssignPermissions {
-    /** Allow imports from cross-domain URLs (default: false) */
-    crossDomainImports?: boolean;
+export function buildRestrictedPropSet(permissions: AssignPermissions | undefined): RestrictedPropSettingsMap | undefined {
+    const settings = permissions?.restrictedPropSettings;
+    if (!settings || settings.length === 0) return undefined;
+    const restrictedPropSet: RestrictedPropSettingsMap = new Map();
+    for (const setting of settings) {
+        const prop = typeof setting === 'string' ? setting : setting.prop;
+        if (restrictedPropSet.has(prop)) {
+            throw new Error(`assignGingerly: duplicate restrictedPropSettings entry for '${prop}'.`);
+        }
+        restrictedPropSet.set(prop, typeof setting === 'string' ? undefined : setting);
+    }
+    return restrictedPropSet;
 }
 
+/**
+ * Check if a property key is restricted. If so, warn (once) and return true.
+ * Call sites should `continue` or skip the assignment when this returns true.
+ */
+export function checkRestrictedProp(restrictedPropSet: RestrictedPropSettingsMap | undefined, key: string): boolean {
+    if (!restrictedPropSet || !restrictedPropSet.has(key)) return false;
+    warnRestricted(key);
+    return true;
+}
+
+/**
+ * Redirect an ordinary assignment through its configured safe method.
+ * Returns true when the property is restricted, whether redirected or skipped.
+ */
+export function redirectRestrictedProp(
+    restrictedPropSet: RestrictedPropSettingsMap | undefined,
+    target: any,
+    key: string,
+    value: any
+): boolean {
+    if (!restrictedPropSet || !restrictedPropSet.has(key)) return false;
+    const setting = restrictedPropSet.get(key);
+    if (!setting?.useMethod) {
+        warnRestricted(key);
+        return true;
+    }
+    const method = target?.[setting.useMethod];
+    if (typeof method !== 'function') {
+        warnRestricted(key);
+        return true;
+    }
+    method.call(target, value);
+    return true;
+}
+
 /**
  * Check if an import path is allowed (non-cross-domain).
  * 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.71",
+  "version": "0.0.72",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -203,7 +203,7 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "@playwright/test": "1.62.0",
+    "@playwright/test": "1.62.1",
     "spa-ssi": "0.0.27"
   }
 }

package/processHandlerCommands.js

@@ -6,7 +6,7 @@
 import { resolveValues } from './resolveValues.js';
 import { getValues } from './getValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
-import { isAllowedImportPath } from './isAllowedImportPath.js';
+import { buildRestrictedPropSet, isAllowedImportPath, redirectRestrictedProp } from './isAllowedImportPath.js';
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
@@ -102,6 +102,7 @@ async function resolveFromHandlers(name, handlers, permissions) {
  * @param handlerRegistry - The registry of handler classes
  */
 export async function processHandlerCommands(target, handlerKeys, pattern, options, permissions) {
+    const restrictedPropSet = buildRestrictedPropSet(permissions);
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
         const rhs = pattern[key];
@@ -211,11 +212,12 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
             // Instantiate and invoke the handler
             const handler = new HandlerClass(config);
             //return; //1.5ms
-            const result = await handler.assign(lhsTarget, resolvedParams, options);
+            const result = await handler.assign(lhsTarget, resolvedParams, options, permissions);
             //return; //1.5ms
             // Return-value protocol: if handler returns a non-undefined value,
             // assign it back to the LHS path
-            if (result !== undefined && lhsParent != null && lhsKey != null) {
+            if (result !== undefined && lhsParent != null && lhsKey != null
+                && !redirectRestrictedProp(restrictedPropSet, lhsParent, lhsKey, result)) {
                 lhsParent[lhsKey] = result;
             }
         }

package/processHandlerCommands.ts

@@ -7,7 +7,7 @@
 import { resolveValues } from './resolveValues.js';
 import { getValues } from './getValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
-import { isAllowedImportPath } from './isAllowedImportPath.js';
+import { buildRestrictedPropSet, isAllowedImportPath, redirectRestrictedProp } from './isAllowedImportPath.js';
 import type { AssignPermissions } from './isAllowedImportPath.js';
 import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFromAsync.js';
 
@@ -125,8 +125,9 @@ export async function processHandlerCommands(
     pattern: Record<string, any>,
     options: AssignFromOptions,
     permissions?: AssignPermissions
-): Promise<void> {
-    
+): Promise<void> {
+    const restrictedPropSet = buildRestrictedPropSet(permissions);
+
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
         const rhs = pattern[key];
@@ -238,12 +239,13 @@ export async function processHandlerCommands(
             // Instantiate and invoke the handler
             const handler = new HandlerClass(config);
             //return; //1.5ms
-            const result = await handler.assign(lhsTarget, resolvedParams, options);
+            const result = await handler.assign(lhsTarget, resolvedParams, options, permissions);
             //return; //1.5ms
-            // Return-value protocol: if handler returns a non-undefined value,
-            // assign it back to the LHS path
-            if (result !== undefined && lhsParent != null && lhsKey != null) {
-                lhsParent[lhsKey] = result;
+            // Return-value protocol: if handler returns a non-undefined value,
+            // assign it back to the LHS path
+            if (result !== undefined && lhsParent != null && lhsKey != null
+                && !redirectRestrictedProp(restrictedPropSet, lhsParent, lhsKey, result)) {
+                lhsParent[lhsKey] = result;
             }
         }
     }

package/types/assign-gingerly/types.d.ts

@@ -252,6 +252,12 @@ export interface IAssignGingerlyOptions {
   bypassChecks?: boolean;
   /**
    * Method names to call during path evaluation (e.g., for `?.method()` calls)
+   *
+   * Append `|` to a path segment (e.g., `?.deref|?.classList?.add`) to call a
+   * listed method with zero arguments instead of consuming the next path segment
+   * as its argument. On the last segment, `|` calls the method with no arguments
+   * and ignores the value. The `|` suffix only applies to names listed here —
+   * for any other segment it is treated as part of a literal property name.
    */
   withMethods?: string[] | Set<string>;
   /**
@@ -343,7 +349,7 @@ export interface AssignFromOptions {
   /** Protocol handlers (sync or async) */
   protocols?: Record<string, (key: string) => any | Promise<any>>;
 
-  /** Method names to call during path evaluation */
+  /** Method names to call during path evaluation (append `|` to a path segment for a zero-argument call) */
   withMethods?: string[] | Set<string>;
 
   /** Alias mappings for path segments */
@@ -700,8 +706,8 @@ export interface HandlerConfig {
  * Interface for assignFrom handler classes.
  * Handlers are invoked when a LHS key ends with ' =>'.
  */
-export interface AssignFromHandler {
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any): Promise<void> | void;
+export interface AssignFromHandler {
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any, permissions?: AssignPermissions): Promise<void> | void;
 }
 
 /**
@@ -879,7 +885,7 @@ export interface LazyLoadInstantiatedContext {
 export declare class LazyLoadHandler implements AssignFromHandler {
     config: any;
     constructor(config: any);
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any): Promise<void>;
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any, permissions?: AssignPermissions): Promise<void>;
     protected onCloneInserted(nodes: Node[], lhsTarget: Element, resolvedParams: Record<string, any>): Promise<void>;
 }
 
@@ -927,3 +933,54 @@ export interface AddEventListenerConfig extends AssignDispatchVector  {
    
 }
 //#endregion
+
+
+// =============================================================================
+// Permissions
+// =============================================================================
+
+/**
+ * Phase II+: object form for a restricted property setting.
+ */
+export interface RestrictedPropSetting {
+    prop: string;
+    useMethod?: string;          // Phase II: redirect to a safe method
+    attr?: string;               // Phase III: also watch setAttribute for this attr
+    allowFromSameHost?: boolean; // Phase III
+    allowCrossDomain?: boolean;  // Phase III
+}
+
+/**
+ * Phase IV+: object form for a restricted method setting.
+ */
+export interface RestrictedMethodConfig {
+    method: string;
+    addArgs?: string[];          // Phase V: append sanitizer args
+}
+
+/**
+ * Permissions interface for controlling security-sensitive operations.
+ * Only trusted script can set these — never parsed from HTML attributes.
+ */
+export interface AssignPermissions {
+    /** Allow imports from cross-domain URLs (default: false) */
+    crossDomainImports?: boolean;
+
+    /**
+     * Restricted property settings.
+     * Phase I: string entries are property names that cannot be assigned.
+     * Phase II: an object with useMethod redirects ordinary assignment to that
+     * method; command operations remain blocked. Phase III+ adds attr support.
+     *
+     * NOTE: This is a property-assignment guard only. Method calls (setAttribute, etc.)
+     * are not blocked — see Phase III+. Event listeners can still be registered, but
+     * assignments performed by their vectors inherit these permissions.
+     */
+    restrictedPropSettings?: Array<string | RestrictedPropSetting>;
+
+    /** Sanitizer options (Phase III+) */
+    sanitizerOptions?: Record<string, any>;
+
+    /** Restricted method settings (Phase IV+) */
+    restrictedMethodSettings?: Array<string | RestrictedMethodConfig>;
+}