assign-gingerly 0.0.74 → 0.0.76

package/{resolveIdRef.js → resolve/resolveIdRef.js}

@@ -78,7 +78,7 @@ export function resolveIdVariable(varName, target, pin) {
                 // Fire-and-forget: log correction suggestion
                 const capturedConfig = config;
                 const capturedVarName = varName;
-                import('./DX/pinCorrector.js').then(module => {
+                import('../DX/pinCorrector.js').then(module => {
                     module.logConfigCorrection(target, capturedVarName, capturedConfig);
                 }).catch(() => { });
             }

package/{resolveIdRef.ts → resolve/resolveIdRef.ts}

@@ -91,7 +91,7 @@ export function resolveIdVariable(
                 // Fire-and-forget: log correction suggestion
                 const capturedConfig = config;
                 const capturedVarName = varName;
-                import('./DX/pinCorrector.js').then(module => {
+                import('../DX/pinCorrector.js').then(module => {
                     module.logConfigCorrection(target, capturedVarName, capturedConfig);
                 }).catch(() => {});
             }

package/{resolveValues.ts → resolve/resolveValues.ts}

@@ -8,7 +8,7 @@
  */
 
 import { getValue, getValues } from './getValues.js';
-import type { ResolveValuesOptions } from './types/assign-gingerly/types.js';
+import type { ResolveValuesOptions } from '../types/assign-gingerly/types.js';
 
 export type { ResolveValuesOptions };
 

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

@@ -424,6 +424,11 @@ export interface GetValuesOptions extends IAssignGingerlyOptions {
    */
   root?: any;
 
+  /**
+   * Optional permission processor for guarding method calls during RHS resolution.
+   */
+  permissionProcessor?: PermissionProcessor;
+
   /**
    * Synchronous protocol handlers for resolving protocol-prefixed values.
    * Each handler receives the key portion and MUST return synchronously.
@@ -449,6 +454,11 @@ export interface ResolveValuesOptions extends IAssignGingerlyOptions {
    */
   root?: any;
 
+  /**
+   * Optional permission processor for guarding method calls during RHS resolution.
+   */
+  permissionProcessor?: PermissionProcessor;
+
   /**
    * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
    * Each handler receives the key portion and returns the resolved value (sync or async).
@@ -695,7 +705,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, permissions?: AssignPermissions): Promise<void> | void;
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: any, permissionProcessor?: PermissionProcessor): Promise<void> | void;
 }
 
 /**
@@ -873,7 +883,7 @@ export interface LazyLoadInstantiatedContext {
 export declare class LazyLoadHandler implements AssignFromHandler {
     config: any;
     constructor(config: any);
-    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any, permissions?: AssignPermissions): Promise<void>;
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any, permissionProcessor?: PermissionProcessor): Promise<void>;
     protected onCloneInserted(nodes: Node[], lhsTarget: Element, resolvedParams: Record<string, any>): Promise<void>;
 }
 
@@ -931,11 +941,11 @@ export interface AddEventListenerConfig extends AssignDispatchVector  {
  * 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
+    props: string | string[];
+    useMethod?: string;            // Phase II: redirect to a safe method
+    attr?: boolean | string | string[]; // Phase III: also watch setAttribute for these attrs
+    allowFromSameDomain?: boolean; // Phase III: allow same-origin URLs
+    allowCrossDomain?: boolean;    // Phase III: allow any URL
 }
 
 /**
@@ -958,7 +968,8 @@ export interface AssignPermissions {
      * 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.
+     * method; command operations remain blocked. Phase III+ adds props, attr,
+     * allowFromSameDomain, and allowCrossDomain 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
@@ -972,3 +983,21 @@ export interface AssignPermissions {
     /** Restricted method settings (Phase IV+) */
     restrictedMethodSettings?: Array<string | RestrictedMethodConfig>;
 }
+
+//#region Permissions
+export interface RestrictedPropSettingsMap {
+    props: Map<string, RestrictedPropSetting | undefined>;
+    attrs: Map<string, RestrictedPropSetting | undefined>;
+}
+
+export declare class PermissionProcessor {
+    constructor(permissions: AssignPermissions | undefined);
+    get crossDomainImports(): boolean;
+    get hasProps(): boolean;
+    get hasAttrs(): boolean;
+    checkRestrictedProp(key: string): boolean;
+    checkRestrictedMethod(methodName: string): boolean;
+    redirectRestrictedProp(target: any, key: string, value: any): boolean;
+    checkRestrictedAttributeCall(methodName: string, args: any[]): { blocked: boolean; attrName?: string };
+}
+//#endregion

package/utils/findClassPrototypeInPath.js

@@ -0,0 +1,57 @@
+import { isAllowedImportPath } from '../assignPermissions/isAllowedImportPath.js';
+/**
+ * Thrown when a dynamic import path is not covered by the allowed-import policy.
+ */
+export class ImportNotAllowedError extends Error {
+    path;
+    constructor(path) {
+        super(`Import path "${path}" is not allowed.`);
+        this.path = path;
+        this.name = 'ImportNotAllowedError';
+        console.error(`ImportNotAllowedError: ${path}`);
+    }
+}
+/**
+ * Thrown when a module does not export a class that satisfies the required criteria.
+ */
+export class NoMatchingExportError extends Error {
+    path;
+    constructor(path) {
+        super(`Module "${path}" does not export a matching class with a prototype.`);
+        this.path = path;
+        this.name = 'NoMatchingExportError';
+        console.error(`NoMatchingExportError: ${path}`);
+    }
+}
+/**
+ * Base check: value must be a function with a prototype (i.e., a class constructor).
+ */
+function isClassWithPrototype(value) {
+    return typeof value === 'function' && value.prototype !== undefined;
+}
+/**
+ * Dynamically import a module at the given path, validate the path against the
+ * allowed-import policy, and return the first exported class whose prototype passes
+ * the optional criteria check.
+ *
+ * The default export is checked first. If it does not satisfy the checks, all named
+ * exports are scanned. If no matching class is found, a `NoMatchingExportError` is thrown.
+ */
+export async function findClassPrototypeInPath(path, criteria) {
+    if (!isAllowedImportPath(path)) {
+        throw new ImportNotAllowedError(path);
+    }
+    const module = await import(path);
+    const candidates = [
+        module.default,
+        ...Object.values(module).filter((exported) => exported !== module.default),
+    ];
+    for (const exported of candidates) {
+        if (!isClassWithPrototype(exported))
+            continue;
+        if (criteria && !criteria(exported))
+            continue;
+        return exported;
+    }
+    throw new NoMatchingExportError(path);
+}

package/utils/findClassPrototypeInPath.ts

@@ -0,0 +1,62 @@
+import { isAllowedImportPath } from '../assignPermissions/isAllowedImportPath.js';
+
+/**
+ * Thrown when a dynamic import path is not covered by the allowed-import policy.
+ */
+export class ImportNotAllowedError extends Error {
+    constructor(public readonly path: string) {
+        super(`Import path "${path}" is not allowed.`);
+        this.name = 'ImportNotAllowedError';
+        console.error(`ImportNotAllowedError: ${path}`);
+    }
+}
+
+/**
+ * Thrown when a module does not export a class that satisfies the required criteria.
+ */
+export class NoMatchingExportError extends Error {
+    constructor(public readonly path: string) {
+        super(`Module "${path}" does not export a matching class with a prototype.`);
+        this.name = 'NoMatchingExportError';
+        console.error(`NoMatchingExportError: ${path}`);
+    }
+}
+
+/**
+ * Base check: value must be a function with a prototype (i.e., a class constructor).
+ */
+function isClassWithPrototype(value: any): boolean {
+    return typeof value === 'function' && value.prototype !== undefined;
+}
+
+/**
+ * Dynamically import a module at the given path, validate the path against the
+ * allowed-import policy, and return the first exported class whose prototype passes
+ * the optional criteria check.
+ *
+ * The default export is checked first. If it does not satisfy the checks, all named
+ * exports are scanned. If no matching class is found, a `NoMatchingExportError` is thrown.
+ */
+export async function findClassPrototypeInPath<T = any>(
+    path: string,
+    criteria?: (proto: any) => boolean
+): Promise<{ new(): T }> {
+    if (!isAllowedImportPath(path)) {
+        throw new ImportNotAllowedError(path);
+    }
+
+    const module = await import(path);
+
+    const candidates = [
+        module.default,
+        ...Object.values(module).filter((exported: any) => exported !== module.default),
+    ];
+
+    for (const exported of candidates) {
+        if (!isClassWithPrototype(exported)) continue;
+        if (criteria && !criteria(exported)) continue;
+        return exported as { new(): T };
+    }
+
+    throw new NoMatchingExportError(path);
+}

package/utils/isAsyncSpawn.js

@@ -0,0 +1,20 @@
+/**
+ * Determines if a function is an async spawner (returns a Promise<Constructor>)
+ * rather than a synchronous constructor.
+ *
+ * Heuristic:
+ * - AsyncFunction (async () => ...) → async spawner
+ * - Arrow function (no .prototype) → async spawner (assumed to return Promise<Constructor>)
+ * - Class or function declaration (has .prototype) → synchronous constructor
+ */
+export function isAsyncSpawn(fn) {
+    if (typeof fn !== 'function')
+        return false;
+    // Explicit async function
+    if (fn.constructor.name === 'AsyncFunction')
+        return true;
+    // Arrow function or non-constructor function (no .prototype)
+    if (fn.prototype === undefined)
+        return true;
+    return false;
+}

package/utils/isAsyncSpawn.ts

@@ -0,0 +1,17 @@
+/**
+ * Determines if a function is an async spawner (returns a Promise<Constructor>)
+ * rather than a synchronous constructor.
+ *
+ * Heuristic:
+ * - AsyncFunction (async () => ...) → async spawner
+ * - Arrow function (no .prototype) → async spawner (assumed to return Promise<Constructor>)
+ * - Class or function declaration (has .prototype) → synchronous constructor
+ */
+export function isAsyncSpawn(fn: any): boolean {
+    if (typeof fn !== 'function') return false;
+    // Explicit async function
+    if (fn.constructor.name === 'AsyncFunction') return true;
+    // Arrow function or non-constructor function (no .prototype)
+    if (fn.prototype === undefined) return true;
+    return false;
+}

package/assignPermissions/restrictedProps.js

@@ -1,43 +0,0 @@
-const warnedOnce = new Set();
-function warnRestricted(key) {
-    if (!warnedOnce.has(key)) {
-        warnedOnce.add(key);
-        console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
-    }
-}
-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;
-}
-export function checkRestrictedProp(restrictedPropSet, key) {
-    if (!restrictedPropSet || !restrictedPropSet.has(key))
-        return false;
-    warnRestricted(key);
-    return true;
-}
-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;
-}

package/assignPermissions/restrictedProps.ts

@@ -1,53 +0,0 @@
-import type { AssignPermissions, RestrictedPropSetting } from '../types/assign-gingerly/types.js';
-
-export type RestrictedPropSettingsMap = Map<string, RestrictedPropSetting | undefined>;
-
-const warnedOnce = new Set<string>();
-
-function warnRestricted(key: string): void {
-    if (!warnedOnce.has(key)) {
-        warnedOnce.add(key);
-        console.warn(`assignGingerly: property '${key}' is in restrictedPropSettings — assignment skipped.`);
-    }
-}
-
-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;
-}
-
-export function checkRestrictedProp(restrictedPropSet: RestrictedPropSettingsMap | undefined, key: string): boolean {
-    if (!restrictedPropSet || !restrictedPropSet.has(key)) return false;
-    warnRestricted(key);
-    return true;
-}
-
-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;
-}

package/resolveAndAssignFeatures.js

@@ -1,36 +0,0 @@
-/**
- * resolveAndAssignFeatures - Thin wrapper around assignFeatures for backward compatibility.
- *
- * Resolves all configured spawns (including async fallback spawns and string import paths)
- * and installs feature getters on the class prototype, then delegates to the registry's
- * assignFeatures implementation.
- *
- * This is kept as a convenience entry point for callers that already await this function.
- * The actual resolution logic lives in assignFeatures.
- *
- * @example
- * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
- *
- * await resolveAndAssignFeatures(MyElement, {
- *     roundabout: {
- *         customData: {...},
- *         withAttrs: {...},
- *         callbackForwarding: ['connectedCallback']
- *     },
- *     faceUp: {
- *         callbackForwarding: ['connectedCallback', 'disconnectedCallback']
- *     }
- * });
- */
-import { assignFeatures } from './assignFeatures.js';
-/**
- * Resolves all configured spawns and calls assignFeatures on the registry.
- *
- * @param ElementClass - The custom element class (must have static supportedFeatures)
- * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
- * @param registry - Optional CustomElementRegistry (defaults to global customElements)
- */
-export async function resolveAndAssignFeatures(ElementClass, featuresConfig, registry) {
-    const reg = registry || customElements;
-    await assignFeatures(ElementClass, featuresConfig, reg.featuresRegistry);
-}

package/resolveAndAssignFeatures.ts

@@ -1,43 +0,0 @@
-/**
- * resolveAndAssignFeatures - Thin wrapper around assignFeatures for backward compatibility.
- *
- * Resolves all configured spawns (including async fallback spawns and string import paths)
- * and installs feature getters on the class prototype, then delegates to the registry's
- * assignFeatures implementation.
- *
- * This is kept as a convenience entry point for callers that already await this function.
- * The actual resolution logic lives in assignFeatures.
- *
- * @example
- * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
- *
- * await resolveAndAssignFeatures(MyElement, {
- *     roundabout: {
- *         customData: {...},
- *         withAttrs: {...},
- *         callbackForwarding: ['connectedCallback']
- *     },
- *     faceUp: {
- *         callbackForwarding: ['connectedCallback', 'disconnectedCallback']
- *     }
- * });
- */
-
-import { FeatureConfigsMap } from './types/assign-gingerly/types.js';
-import { assignFeatures } from './assignFeatures.js';
-
-/**
- * Resolves all configured spawns and calls assignFeatures on the registry.
- *
- * @param ElementClass - The custom element class (must have static supportedFeatures)
- * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
- * @param registry - Optional CustomElementRegistry (defaults to global customElements)
- */
-export async function resolveAndAssignFeatures(
-    ElementClass: Function,
-    featuresConfig: FeatureConfigsMap,
-    registry?: any
-): Promise<void> {
-    const reg = registry || customElements;
-    await assignFeatures(ElementClass, featuresConfig, reg.featuresRegistry);
-}