@matter/node 0.11.0-alpha.0-20241005-e3e4e4a7a

package/dist/esm/behavior/AccessControl.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AccessLevel, DataModelPath } from "#model";
+import { ClusterId, FabricIndex, SubjectId } from "#types";
+import { Schema } from "./supervision/Schema.js";
+/**
+ * Enforces access control for a specific schema.
+ */
+export interface AccessControl {
+    /**
+     * Operational access control metadata.
+     */
+    limits: AccessControl.Limits;
+    /**
+     * Assert read is authorized.
+     */
+    authorizeRead: AccessControl.Assertion;
+    /**
+     * Determine if read is authorized.
+     */
+    mayRead: AccessControl.Verification;
+    /**
+     * Assert write is authorized.
+     */
+    authorizeWrite: AccessControl.Assertion;
+    /**
+     * Determine if write is authorized.
+     */
+    mayWrite: AccessControl.Verification;
+    /**
+     * Assert invoke is authorized.
+     */
+    authorizeInvoke: AccessControl.Assertion;
+    /**
+     * Determine if invoke is authorized.
+     */
+    mayInvoke: AccessControl.Verification;
+}
+/**
+ * Obtain an enforcer for specific schema.
+ *
+ * This is central to security.  Implementation is explicit, all objects are involved are frozen and cache is stored as
+ * module-private.
+ *
+ * Pure function; returned value is cached.
+ */
+export declare function AccessControl(schema: Schema): AccessControl;
+export declare namespace AccessControl {
+    /**
+     * Operational access control metadata for a schema.
+     */
+    interface Limits {
+        readonly readable: boolean;
+        readonly readLevel: AccessLevel;
+        readonly writable: boolean;
+        readonly writeLevel: AccessLevel;
+        readonly fabricScoped: boolean;
+        readonly fabricSensitive: boolean;
+        readonly timed: boolean;
+    }
+    /**
+     * A function that asserts access control requirements are met.
+     */
+    type Assertion = (session: Session, location: Location) => void;
+    /**
+     * A function that returns true if access control requirements are met.
+     */
+    type Verification = (session: Session, location: Location) => boolean;
+    /**
+     * Metadata that varies with position in the data model.
+     */
+    interface Location {
+        /**
+         * The diagnostic path to the location.
+         */
+        path: DataModelPath;
+        /**
+         * The owning behavior.
+         */
+        cluster?: ClusterId;
+        /**
+         * The fabric that owns the data subtree.  Undefined or {@link FabricIndex.NO_FABRIC} disables fabric
+         * enforcement.
+         */
+        owningFabric?: FabricIndex;
+        /**
+         * The access levels already retrieved for this location. With this subtree elements can access the same
+         * access levels without re-evaluating.
+         */
+        accessLevels?: AccessLevel[];
+    }
+    /**
+     * Authorization metadata that varies with session.
+     */
+    interface Session {
+        /**
+         * Checks if the authorized client has a certain Access Privilege granted.
+         */
+        authorizedFor(desiredAccessLevel: AccessLevel, location?: Location): boolean;
+        /**
+         * The fabric of the authorized client.
+         */
+        readonly fabric?: FabricIndex;
+        /**
+         * The authenticated {@link SubjectId} for online sessions.
+         */
+        readonly subject?: SubjectId;
+        /**
+         * If this is true, fabric-scoped lists are filtered to the accessing
+         * fabric.
+         */
+        readonly fabricFiltered?: boolean;
+        /**
+         * If this is true a timed transaction is in effect.
+         */
+        readonly timed?: boolean;
+        /**
+         * If this is true then data access levels are not enforced.  Datatypes and command-related access controls are
+         * active.
+         */
+        readonly command?: boolean;
+        /**
+         * If this is true then access levels are not enforced and all values are read/write.  Datatypes are still
+         * enforced.
+         *
+         * Tracks "offline" rather than "online" because this makes the safer mode (full enforcement) the default.
+         */
+        offline?: boolean;
+    }
+}
+//# sourceMappingURL=AccessControl.d.ts.map

package/dist/esm/behavior/AccessControl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessControl.d.ts","sourceRoot":"","sources":["../../../src/behavior/AccessControl.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAU,WAAW,EAAE,aAAa,EAA0B,MAAM,QAAQ,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAc,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEvE,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B;;OAEG;IACH,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC;IAE7B;;OAEG;IACH,aAAa,EAAE,aAAa,CAAC,SAAS,CAAC;IAEvC;;OAEG;IACH,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC;IAEpC;;OAEG;IACH,cAAc,EAAE,aAAa,CAAC,SAAS,CAAC;IAExC;;OAEG;IACH,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC;IAErC;;OAEG;IACH,eAAe,EAAE,aAAa,CAAC,SAAS,CAAC;IAEzC;;OAEG;IACH,SAAS,EAAE,aAAa,CAAC,YAAY,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,iBAM3C;AAED,yBAAiB,aAAa,CAAC;IAC3B;;OAEG;IACH,UAAiB,MAAM;QACnB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;QAEhC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;QAEjC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;QAC/B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;QAElC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;KAC3B;IAED;;OAEG;IACH,KAAY,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IAEvE;;OAEG;IACH,KAAY,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC;IAE7E;;OAEG;IACH,UAAiB,QAAQ;QACrB;;WAEG;QACH,IAAI,EAAE,aAAa,CAAC;QAEpB;;WAEG;QACH,OAAO,CAAC,EAAE,SAAS,CAAC;QAEpB;;;WAGG;QACH,YAAY,CAAC,EAAE,WAAW,CAAC;QAE3B;;;WAGG;QACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;KAChC;IAED;;OAEG;IACH,UAAiB,OAAO;QACpB;;WAEG;QACH,aAAa,CAAC,kBAAkB,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;QAE7E;;WAEG;QACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAE9B;;WAEG;QACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;QAE7B;;;WAGG;QACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAElC;;WAEG;QACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAEzB;;;WAGG;QACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAE3B;;;;;WAKG;QACH,OAAO,CAAC,EAAE,OAAO,CAAC;KACrB;CACJ"}

package/dist/esm/behavior/AccessControl.js

@@ -0,0 +1,258 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Access, AccessLevel, ElementTag, ValueModel } from "#model";
+import { StatusCode } from "#types";
+import { InvokeError, ReadError, SchemaImplementationError, WriteError } from "./errors.js";
+const cache = /* @__PURE__ */ new WeakMap();
+function AccessControl(schema) {
+  let enforcer = cache.get(schema);
+  if (enforcer === void 0) {
+    enforcer = enforcerFor(schema);
+  }
+  return enforcer;
+}
+Object.freeze(AccessControl);
+function enforcerFor(schema) {
+  if (schema.tag === ElementTag.Command) {
+    return commandEnforcerFor(schema);
+  }
+  return dataEnforcerFor(schema);
+}
+function dataEnforcerFor(schema) {
+  const limits = limitsFor(schema);
+  let mayRead = (session, location) => {
+    if (session.offline || session.command) {
+      return true;
+    }
+    return session.authorizedFor(limits.readLevel, location);
+  };
+  let mayWrite = (session, location) => {
+    if (session.offline || session.command) {
+      return true;
+    }
+    return session.authorizedFor(limits.writeLevel, location);
+  };
+  let authorizeRead = (session, location) => {
+    if (session.offline || session.command) {
+      return;
+    }
+    if (session.authorizedFor(limits.readLevel, location)) {
+      return;
+    }
+    throw new ReadError(location, "Permission denied", StatusCode.UnsupportedAccess);
+  };
+  let authorizeWrite = (session, location) => {
+    if (session.offline || session.command) {
+      return;
+    }
+    if (session.authorizedFor(limits.writeLevel, location)) {
+      return;
+    }
+    throw new WriteError(location, "Permission denied", StatusCode.UnsupportedAccess);
+  };
+  if (limits.timed) {
+    const wrappedAuthorizeWrite = authorizeWrite;
+    const wrappedMayWrite = mayWrite;
+    authorizeWrite = (session, location) => {
+      if (!session.offline && !session.timed) {
+        throw new WriteError(
+          location,
+          "Permission denied because interaction is not timed",
+          StatusCode.NeedsTimedInteraction
+        );
+      }
+      wrappedAuthorizeWrite?.(session, location);
+    };
+    mayWrite = (session, location) => {
+      if (!session.offline && !session.timed) {
+        return false;
+      }
+      return wrappedMayWrite(session, location);
+    };
+  }
+  if (limits.fabricSensitive) {
+    const wrappedAuthorizeRead = authorizeRead;
+    const wrappedMayRead = mayRead;
+    const wrappedAuthorizeWrite = authorizeWrite;
+    const wrappedMayWrite = mayWrite;
+    authorizeRead = (session, location) => {
+      if (session.offline || session.command) {
+        return;
+      }
+      if (session.fabricFiltered) {
+        if (session.fabric === void 0) {
+          throw new ReadError(
+            location,
+            "Permission denied: No accessing fabric",
+            StatusCode.UnsupportedAccess
+          );
+        }
+        if (location?.owningFabric && location.owningFabric !== session.fabric) {
+          throw new ReadError(
+            location,
+            "Permission denied: Owning/accessing fabric mismatch",
+            StatusCode.UnsupportedAccess
+          );
+        }
+      }
+      wrappedAuthorizeRead(session, location);
+    };
+    mayRead = (session, location) => {
+      if (session.offline || session.command) {
+        return true;
+      }
+      if (session.fabric === void 0) {
+        return false;
+      }
+      if (location?.owningFabric && location.owningFabric !== session.fabric) {
+        return false;
+      }
+      return wrappedMayRead(session, location);
+    };
+    authorizeWrite = (session, location) => {
+      if (session.offline || session.command) {
+        return;
+      }
+      if (session.fabric === void 0) {
+        throw new WriteError(location, "Permission denied: No accessing fabric", StatusCode.UnsupportedAccess);
+      }
+      if (location?.owningFabric && location.owningFabric !== session.fabric) {
+        throw new WriteError(location, "Permission denied: Owning/accessing fabric mismatch");
+      }
+      wrappedAuthorizeWrite(session, location);
+    };
+    mayWrite = (session, location) => {
+      if (session.offline || session.command) {
+        return true;
+      }
+      if (session.fabric === void 0) {
+        return false;
+      }
+      if (location?.owningFabric && location.owningFabric !== session.fabric) {
+        return false;
+      }
+      return wrappedMayWrite(session, location);
+    };
+  }
+  if (!limits.readable) {
+    authorizeRead = (session, location) => {
+      if (session.offline || session.command) {
+        return;
+      }
+      throw new ReadError(location, "Permission defined: Value is write-only");
+    };
+    mayRead = (session) => {
+      return !!session.offline || !!session.command;
+    };
+  }
+  if (!limits.writable) {
+    authorizeWrite = (session, location) => {
+      if (session.offline || session.command) {
+        return;
+      }
+      throw new WriteError(location, "Permission denied: Value is read-only");
+    };
+    mayWrite = (session) => {
+      return !!session.offline || !!session.command;
+    };
+  }
+  return Object.freeze({
+    limits,
+    authorizeRead,
+    mayRead,
+    authorizeWrite,
+    mayWrite,
+    authorizeInvoke(_session, location) {
+      throw new SchemaImplementationError(location, "Permission denied: Invoke request but non-command schema");
+    },
+    mayInvoke() {
+      return false;
+    }
+  });
+}
+function commandEnforcerFor(schema) {
+  const limits = limitsFor(schema);
+  const timed = schema.effectiveAccess.timed;
+  const fabric = schema.effectiveAccess.fabric;
+  return {
+    limits,
+    authorizeRead(_session, location) {
+      throw new SchemaImplementationError(location, "Permission denied: Read request but command schema");
+    },
+    mayRead() {
+      return false;
+    },
+    authorizeWrite(_session, location) {
+      throw new SchemaImplementationError(location, "Permission denied: Write request but command schema");
+    },
+    mayWrite() {
+      return false;
+    },
+    authorizeInvoke(session, location) {
+      if (session.offline) {
+        return;
+      }
+      if (!session.command) {
+        throw new InvokeError(location, "Invoke attempt without command context");
+      }
+      if (timed && !session.timed) {
+        throw new InvokeError(
+          location,
+          "Invoke attempt without required timed context",
+          StatusCode.TimedRequestMismatch
+        );
+      }
+      if (fabric && session.fabric === void 0) {
+        throw new WriteError(location, "Permission denied: No accessing fabric", StatusCode.UnsupportedAccess);
+      }
+      if (session.authorizedFor(limits.writeLevel, location)) {
+        return;
+      }
+      throw new InvokeError(location, "Permission denied", StatusCode.UnsupportedAccess);
+    },
+    mayInvoke(session, location) {
+      if (session.offline) {
+        return true;
+      }
+      if (!session.command) {
+        return false;
+      }
+      if (timed && !session.timed) {
+        return false;
+      }
+      if (fabric && session.fabric === void 0) {
+        return false;
+      }
+      return session.authorizedFor(limits.writeLevel, location);
+    }
+  };
+}
+function limitsFor(schema) {
+  const access = schema.effectiveAccess;
+  const quality = schema instanceof ValueModel ? schema.effectiveQuality : void 0;
+  let fixed = quality?.fixed;
+  for (let s = schema.parent; !fixed && s instanceof ValueModel; s = s.parent) {
+    if (s.effectiveQuality.fixed) {
+      fixed = true;
+    }
+  }
+  const limits = Object.freeze({
+    readable: access.readable,
+    writable: access.writable && !fixed,
+    fabricScoped: access.fabric === Access.Fabric.Scoped || access.fabric === Access.Fabric.Sensitive,
+    fabricSensitive: access.fabric === Access.Fabric.Sensitive,
+    timed: access.timed === true,
+    // Official Matter defaults are View for read and Operate for write. However, the schema's effective access
+    // should already have these defaults.  Here we just adopt minimum needed rights as a safe fallback access level.
+    readLevel: access.readPriv === void 0 ? AccessLevel.View : Access.PrivilegeLevel[access.readPriv],
+    writeLevel: access.writePriv === void 0 ? AccessLevel.Operate : Access.PrivilegeLevel[access.writePriv]
+  });
+  return limits;
+}
+export {
+  AccessControl
+};
+//# sourceMappingURL=AccessControl.js.map

package/dist/esm/behavior/AccessControl.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/behavior/AccessControl.ts"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/behavior/Behavior.d.ts

@@ -0,0 +1,203 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Agent } from "#endpoint/Agent.js";
+import { EventEmitter, MaybePromise, Observable } from "#general";
+import type { ClusterType } from "#types";
+import { Reactor } from "./Reactor.js";
+import type { BehaviorBacking } from "./internal/BehaviorBacking.js";
+import { Resource } from "./state/transaction/Resource.js";
+import { RootSupervisor } from "./supervision/RootSupervisor.js";
+import { Schema } from "./supervision/Schema.js";
+/**
+ * Behavior implements functionality for an Endpoint.  Endpoint agents are implemented as a composition of behaviors.
+ *
+ * Most behaviors associated 1:1 with a Matter cluster type as implemented by ClusterBehavior.  But you can also extend
+ * Behavior directly to add other types of composable logic to an endpoint.
+ *
+ * You probably want to build your behavior using one of the standard implementations offered by Matter.js.
+ */
+export declare abstract class Behavior {
+    #private;
+    /**
+     * Each behavior implementation has an ID that uniquely identifies the type of behavior.  An Endpoint may only have
+     * one behavior with the specified ID.
+     *
+     * Endpoint instances store each behavior in a property with the same name as the behavior's ID.
+     *
+     * EndpointBuilder also uses the ID when replacing behaviors using the with() builder method.
+     */
+    static readonly id: string;
+    /**
+     * A behavior's schema controls access to data, commands and events.
+     *
+     * Schema is inferred from the methods and properties of the behavior but you can specify explicitly for additional
+     * control.
+     */
+    static readonly schema?: Schema;
+    /**
+     * By default behaviors load lazily as they are accessed.  You can set this flag to true to force behaviors to load
+     * immediately when the endpoint initializes.
+     */
+    static readonly early: boolean;
+    /**
+     * The agent that owns the behavior.
+     */
+    get agent(): Agent;
+    /**
+     * The endpoint that owns behavior's agent.
+     */
+    get endpoint(): import("../index.js").Endpoint<import("../index.js").EndpointType.Empty>;
+    /**
+     * The context in which the behavior operates.
+     */
+    get context(): import("./index.js").ActionContext;
+    /**
+     * The endpoint's environment.
+     */
+    get env(): import("#general").Environment;
+    /**
+     * The session in which the behavior has been invoked.
+     */
+    get session(): import("@matter/protocol").SecureSession;
+    /**
+     * Execute logic with elevated privileges.
+     *
+     * The provided function executes with privileges escalated to offline mode.  This is not commonly necessary.
+     *
+     * Elevated logic effectively ignores ACLs so should be used with care.
+     *
+     * Note that interactions with the behavior will remain elevated until the synchronous completion of this call.
+     * You should only elevate privileges for synchronous logic.
+     *
+     * @param fn the elevated logic
+     */
+    asAdmin(fn: () => void): void;
+    /**
+     * Access the behavior's state.
+     */
+    readonly state: {};
+    /**
+     * Access the behavior's events.
+     */
+    readonly events: EventEmitter;
+    constructor(agent: Agent, backing: BehaviorBacking);
+    /**
+     * The data supervisor for the behavior.  The supervisor controls validation and access to behavior data.
+     */
+    static get supervisor(): RootSupervisor;
+    /**
+     * Implementation of endpoint-scoped state.  Subclasses may override to extend.
+     */
+    static State: new () => {};
+    /**
+     * Implementation of internal state.  Subclasses may override to extend.
+     */
+    static Internal: new () => {};
+    /**
+     * Implementation of the events property.  Subclasses may override to extend.
+     */
+    static Events: typeof EventEmitter;
+    /**
+     * Behaviors are ephemeral and should not perform initialization in their constructor.  They can override this
+     * method instead.
+     *
+     * This method may be synchronous or asyncronous.  If asynchronous, the behavior will not be available for external
+     * use until initialization completes.
+     */
+    initialize(_options?: {}): MaybePromise;
+    /**
+     * Release resources.  This is the public API for releasing application resources held by behaviors in internal
+     * state.
+     */
+    [Symbol.asyncDispose](): MaybePromise;
+    /**
+     * Description used in diagnostic messages.
+     */
+    toString(): string;
+    /**
+     * Install a {@link Reactor}.
+     *
+     * Important: The reactor MUST be a real JS function - arrow functions will not work!
+     */
+    protected reactTo<O extends Observable<any[], any>>(observable: O, reactor: Reactor<Parameters<O["emit"]>, ReturnType<O["emit"]>>, options?: Reactor.Options): void;
+    /**
+     * Create a generic callback function that has the same properties as a {@link Reactor}.
+     *
+     * Like a reactor, the callback's "this" will be bound to an active Behavior instance.
+     * Because of this: The reactor MUST be a real JS function - arrow functions will not work!
+     */
+    protected callback<A extends any[], R>(reactor: Reactor<A, R>, options?: Reactor.Options): (...args: A) => R | undefined;
+    /**
+     * Does this behavior support functionality of a specific implementation?
+     */
+    static supports(other: Behavior.Type): boolean;
+    /**
+     * Default state values.
+     */
+    static get defaults(): Record<string, any>;
+    /**
+     * Create a new behavior with different default state values.
+     */
+    static set<This extends Behavior.Type>(this: This, defaults: Behavior.InputStateOf<This>): This;
+    /**
+     * Explicitly reference other {@link Behavior}s as dependencies, ensuring this behavior is destroyed first.
+     *
+     * This probably won't be commonly necessary.  If it is we can instrument Agent to collect dependencies
+     * automatically.
+     */
+    static dependencies?: Iterable<Behavior.Type>;
+    get [Resource.reference](): import("./state/managed/Datasource.js").Datasource<import("./state/StateType.js").StateType>;
+}
+export declare namespace Behavior {
+    /**
+     * Static properties supported by all behaviors.
+     */
+    interface Type {
+        new (agent: Agent, backing: BehaviorBacking): Behavior;
+        readonly name: string;
+        readonly id: typeof Behavior.id;
+        readonly set: typeof Behavior.set;
+        readonly supports: typeof Behavior.supports;
+        readonly defaults: Record<string, any>;
+        readonly schema?: Schema;
+        readonly early: boolean;
+        readonly supervisor: RootSupervisor;
+        readonly dependencies?: Iterable<Behavior.Type>;
+        readonly State: new () => {};
+        readonly Internal: new () => {};
+        readonly Events: typeof EventEmitter;
+    }
+    /**
+     * This function simply throws NotImplementedError.  More importantly, its presence in any command implementation
+     * method informs the endpoint that the command is not implemented.
+     */
+    function unimplemented(..._args: any[]): Promise<any>;
+    /**
+     * The state type of a behavior {@link Type}.
+     */
+    type StateOf<B extends Type> = InstanceType<B["State"]>;
+    /**
+     * Input variant of StateOf.
+     */
+    type InputStateOf<B extends Type> = Partial<ClusterType.RelaxTypes<StateOf<B>>>;
+    /**
+     * Patch variant of StateOf.
+     */
+    type PatchStateOf<B extends Type> = ClusterType.PatchType<StateOf<B>>;
+    /**
+     * The events type of a behavior {@link Type}.
+     */
+    type EventsOf<B extends Type> = InstanceType<B["Events"]>;
+    /**
+     * Initialization options.
+     */
+    type InitializationOptionsOf<B extends Type> = Parameters<InstanceType<B>["initialize"]> extends [infer P extends object] ? P : {};
+    /**
+     * Configuration options you may set when adding a {@link Behavior} to an endpoint.
+     */
+    type Options<T extends Behavior.Type = Behavior.Type> = Behavior.InputStateOf<T> & Behavior.InitializationOptionsOf<T>;
+}
+//# sourceMappingURL=Behavior.d.ts.map

package/dist/esm/behavior/Behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Behavior.d.ts","sourceRoot":"","sources":["../../../src/behavior/Behavior.ts"],"names":[],"mappings":"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"}