@milaboratories/pl-middle-layer 1.64.41 → 1.65.0

package/dist/model/sharing_model.cjs

@@ -0,0 +1,98 @@
+let _milaboratories_pl_client = require("@milaboratories/pl-client");
+let node_crypto = require("node:crypto");
+//#region src/model/sharing_model.ts
+/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */
+function newShareId() {
+	return (0, node_crypto.randomUUID)();
+}
+/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`
+*  field name) as a {@link ShareId}, without minting a new one. */
+function asShareId(id) {
+	return id;
+}
+/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */
+const SharingOutboxField = "sharingOutbox";
+/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */
+const SharingStateField = "sharingState";
+const SharingOutboxResourceType = {
+	name: "SharingOutbox",
+	version: "1"
+};
+const SharedEnvelopeResourceType = {
+	name: "SharedEnvelope",
+	version: "1"
+};
+const SharingStateResourceType = {
+	name: "SharingState",
+	version: "1"
+};
+/**
+* Whether a role may make a resource public (grant to everyone): true for controller,
+* admin, and user; false for workflow and unspecified. The middle layer carries no policy
+* of its own here — a crafted call still hits the backend's role + permission-ceiling gate.
+* `null` (no-auth mode) returns false.
+*/
+function canGrantToEveryone(role) {
+	switch (role) {
+		case _milaboratories_pl_client.Role.CONTROLLER:
+		case _milaboratories_pl_client.Role.ADMIN:
+		case _milaboratories_pl_client.Role.USER: return true;
+		default: return false;
+	}
+}
+/**
+* Whether a role may impersonate another user: open/create another user's root and list
+* the resources that user can access. Mirrors the backend's authorization rule
+* `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is
+* the admin gate for the "open another user's root" feature and is intentionally stricter
+* than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user
+* may share their own projects, but must never be offered impersonation). `null` (no-auth
+* mode) returns false.
+*/
+function canImpersonate(role) {
+	switch (role) {
+		case _milaboratories_pl_client.Role.CONTROLLER:
+		case _milaboratories_pl_client.Role.ADMIN: return true;
+		default: return false;
+	}
+}
+/** Dynamic field on SharingState, one per handled share, keyed by shareId. */
+const decisionField = (shareId) => `decision/${shareId}`;
+/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed
+*  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,
+*  Live collaboration) — the acceptor's writable envelope grant is what permits the
+*  write; read-only shares omit it. The donor reads these from its own outbox to see
+*  who responded and when. Informational, not authoritative (a writable grant holder
+*  could write under another login — same trust assumption as the sender field).
+*  Copied forward when a share is changed. */
+const AcceptanceFieldPrefix = "acceptance/";
+const acceptanceField = (login) => `${AcceptanceFieldPrefix}${login}`;
+const isAcceptanceField = (name) => name.startsWith(AcceptanceFieldPrefix);
+const acceptanceFieldLogin = (name) => name.slice(11);
+/**
+* Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`
+* blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource
+* `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node
+* path uses `node.getDataAsJson<EnvelopeData>()`, which decodes the same JSON.
+*/
+function decodeEnvelopeData(data) {
+	return JSON.parse(Buffer.from(data).toString("utf-8"));
+}
+//#endregion
+exports.AcceptanceFieldPrefix = AcceptanceFieldPrefix;
+exports.SharedEnvelopeResourceType = SharedEnvelopeResourceType;
+exports.SharingOutboxField = SharingOutboxField;
+exports.SharingOutboxResourceType = SharingOutboxResourceType;
+exports.SharingStateField = SharingStateField;
+exports.SharingStateResourceType = SharingStateResourceType;
+exports.acceptanceField = acceptanceField;
+exports.acceptanceFieldLogin = acceptanceFieldLogin;
+exports.asShareId = asShareId;
+exports.canGrantToEveryone = canGrantToEveryone;
+exports.canImpersonate = canImpersonate;
+exports.decisionField = decisionField;
+exports.decodeEnvelopeData = decodeEnvelopeData;
+exports.isAcceptanceField = isAcceptanceField;
+exports.newShareId = newShareId;
+
+//# sourceMappingURL=sharing_model.cjs.map

package/dist/model/sharing_model.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing_model.cjs","names":["RoleEnum"],"sources":["../../src/model/sharing_model.ts"],"sourcesContent":["import type { ResourceType, Role } from \"@milaboratories/pl-client\";\nimport { Role as RoleEnum } from \"@milaboratories/pl-client\";\nimport type { Branded, ProjectId } from \"@milaboratories/pl-model-common\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Logical identity of a share, stable across replaces. A donor-generated UUID string,\n * branded so it cannot be silently confused with a project id, a login, or a raw field\n * name. Minted once with {@link newShareId}; every other site receives it (from decoded\n * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it\n * through unchanged.\n */\nexport type ShareId = Branded<string, \"ShareId\">;\n\n/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */\nexport function newShareId(): ShareId {\n  return randomUUID() as ShareId;\n}\n\n/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`\n *  field name) as a {@link ShareId}, without minting a new one. */\nexport function asShareId(id: string): ShareId {\n  return id as ShareId;\n}\n\n//\n// Pl Model — Project Sharing\n//\n// All sharing structures are defined and managed by the middle layer; the\n// backend knows nothing about envelopes.\n//\n\n/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */\nexport const SharingOutboxField = \"sharingOutbox\";\n/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */\nexport const SharingStateField = \"sharingState\";\n\nexport const SharingOutboxResourceType: ResourceType = { name: \"SharingOutbox\", version: \"1\" };\nexport const SharedEnvelopeResourceType: ResourceType = { name: \"SharedEnvelope\", version: \"1\" };\nexport const SharingStateResourceType: ResourceType = { name: \"SharingState\", version: \"1\" };\n\nexport type EnvelopeMode = \"copy\" | \"read-only\" | \"collaboration\";\n\n/** Per-project decision on change, matching the UI labels: re-snapshot the live source (\"update\"),\n *  carry the existing snapshot (\"keep\"), or drop the project from the pack (\"remove\"). */\nexport type ProjectChangeAction = \"keep\" | \"update\" | \"remove\";\n\n/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`\n *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */\nexport type ProjectFieldUuid = Branded<string, \"ProjectFieldUuid\">;\n\n/**\n * Whether a role may make a resource public (grant to everyone): true for controller,\n * admin, and user; false for workflow and unspecified. The middle layer carries no policy\n * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.\n * `null` (no-auth mode) returns false.\n */\nexport function canGrantToEveryone(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n    case RoleEnum.USER:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Whether a role may impersonate another user: open/create another user's root and list\n * the resources that user can access. Mirrors the backend's authorization rule\n * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is\n * the admin gate for the \"open another user's root\" feature and is intentionally stricter\n * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user\n * may share their own projects, but must never be offered impersonation). `null` (no-auth\n * mode) returns false.\n */\nexport function canImpersonate(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in {@link EnvelopeData.projects}. */\nexport interface EnvelopeProject {\n  label: string; // carried so the pending-share UI renders without traversing into the project\n  source: ProjectId; // donor's source projectId; supersedes a prior share and matches the snapshot to its live source on change\n  updatedAt: number; // ms epoch of the last (re)snapshot\n}\n\n/** Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated. */\nexport interface EnvelopeData {\n  schemaVersion: 1;\n  shareId: ShareId; // donor-generated UUID; logical share identity, stable across changes\n  sharedAt: number; // ms epoch; this instance's creation time — distinguishes instances of one shareId\n  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)\n  mode: EnvelopeMode; // what the acceptor's app should do with the contents\n  sender: string; // donor login (informational; backend granted_by is authoritative)\n  title: string; // display name shown to recipients; defaults to the first project's name\n  projects: Record<ProjectFieldUuid, EnvelopeProject>; // contained projects, keyed by project field uuid\n}\n\n/** Dynamic field on SharingState, one per handled share, keyed by shareId. */\nexport const decisionField = (shareId: ShareId) => `decision/${shareId}`;\n\nexport interface SharingDecision {\n  decision: \"accepted\" | \"rejected\";\n  timestamp: number; // ms epoch — when the acceptor acted\n  envelopeSharedAt: number; // the acted-on envelope instance's sharedAt — pins which instance was handled (paired with the shareId key; the resource id is never stored)\n  acceptedProjects: string[]; // ids of the projects created in the acceptor's list ([] for a rejected share)\n}\n\n/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed\n *  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,\n *  Live collaboration) — the acceptor's writable envelope grant is what permits the\n *  write; read-only shares omit it. The donor reads these from its own outbox to see\n *  who responded and when. Informational, not authoritative (a writable grant holder\n *  could write under another login — same trust assumption as the sender field).\n *  Copied forward when a share is changed. */\nexport const AcceptanceFieldPrefix = \"acceptance/\";\nexport const acceptanceField = (login: string) => `${AcceptanceFieldPrefix}${login}`;\nexport const isAcceptanceField = (name: string) => name.startsWith(AcceptanceFieldPrefix);\nexport const acceptanceFieldLogin = (name: string) => name.slice(AcceptanceFieldPrefix.length);\n\nexport interface EnvelopeAcceptance {\n  action: \"accepted\" | \"rejected\";\n  timestamp: number; // ms since epoch\n}\n\n/**\n * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`\n * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource\n * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node\n * path uses `node.getDataAsJson<EnvelopeData>()`, which decodes the same JSON.\n */\nexport function decodeEnvelopeData(data: Uint8Array): EnvelopeData {\n  return JSON.parse(Buffer.from(data).toString(\"utf-8\")) as EnvelopeData;\n}\n\n/**\n * Options for {@link MiddleLayer.shareProjects}.\n *\n * Recipients XOR everyone — two clean variants, not one struct with mutually exclusive\n * optional fields. The everyone variant issues a single make-public grant (the envelope's\n * `expiresAt` is set to `null`, so it never expires); the recipients variant grants each\n * named recipient and the envelope expires after the default TTL.\n */\nexport type ShareProjectsOptions =\n  | {\n      recipients: string[]; // recipient logins\n      title: string; // display name shown to recipients; defaults to the first project's name\n      mode: EnvelopeMode; // v1 UI always sends \"copy\"\n    }\n  | {\n      everyone: true; // share with all users on the server\n      /**\n       * When true and an everyone-share of the same project already exists, refresh it under its\n       * stable shareId (recipients who already accepted or rejected are not re-prompted) instead of\n       * minting a new share. No-op when no prior everyone-share of the project exists. Callers that\n       * don't care pass `false`.\n       */\n      replace: boolean;\n      title: string;\n      mode: EnvelopeMode;\n    };\n"],"mappings":";;;;AAeA,SAAgB,aAAsB;CACpC,QAAA,GAAA,YAAA,WAAA,CAAkB;AACpB;;;AAIA,SAAgB,UAAU,IAAqB;CAC7C,OAAO;AACT;;AAUA,MAAa,qBAAqB;;AAElC,MAAa,oBAAoB;AAEjC,MAAa,4BAA0C;CAAE,MAAM;CAAiB,SAAS;AAAI;AAC7F,MAAa,6BAA2C;CAAE,MAAM;CAAkB,SAAS;AAAI;AAC/F,MAAa,2BAAyC;CAAE,MAAM;CAAgB,SAAS;AAAI;;;;;;;AAkB3F,SAAgB,mBAAmB,MAA4B;CAC7D,QAAQ,MAAR;EACE,KAAKA,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS,MACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;;;;;;;;;AAWA,SAAgB,eAAe,MAA4B;CACzD,QAAQ,MAAR;EACE,KAAKA,0BAAAA,KAAS;EACd,KAAKA,0BAAAA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;AAsBA,MAAa,iBAAiB,YAAqB,YAAY;;;;;;;;AAgB/D,MAAa,wBAAwB;AACrC,MAAa,mBAAmB,UAAkB,GAAG,wBAAwB;AAC7E,MAAa,qBAAqB,SAAiB,KAAK,WAAW,qBAAqB;AACxF,MAAa,wBAAwB,SAAiB,KAAK,MAAM,EAA4B;;;;;;;AAa7F,SAAgB,mBAAmB,MAAgC;CACjE,OAAO,KAAK,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC;AACvD"}

package/dist/model/sharing_model.d.ts

@@ -0,0 +1,122 @@
+import { ResourceType, Role } from "@milaboratories/pl-client";
+import { Branded, ProjectId } from "@milaboratories/pl-model-common";
+
+//#region src/model/sharing_model.d.ts
+/**
+ * Logical identity of a share, stable across replaces. A donor-generated UUID string,
+ * branded so it cannot be silently confused with a project id, a login, or a raw field
+ * name. Minted once with {@link newShareId}; every other site receives it (from decoded
+ * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it
+ * through unchanged.
+ */
+type ShareId = Branded<string, "ShareId">;
+/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */
+declare function newShareId(): ShareId;
+/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`
+ *  field name) as a {@link ShareId}, without minting a new one. */
+declare function asShareId(id: string): ShareId;
+/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */
+declare const SharingOutboxField = "sharingOutbox";
+/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */
+declare const SharingStateField = "sharingState";
+declare const SharingOutboxResourceType: ResourceType;
+declare const SharedEnvelopeResourceType: ResourceType;
+declare const SharingStateResourceType: ResourceType;
+type EnvelopeMode = "copy" | "read-only" | "collaboration";
+/** Per-project decision on change, matching the UI labels: re-snapshot the live source ("update"),
+ *  carry the existing snapshot ("keep"), or drop the project from the pack ("remove"). */
+type ProjectChangeAction = "keep" | "update" | "remove";
+/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`
+ *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */
+type ProjectFieldUuid = Branded<string, "ProjectFieldUuid">;
+/**
+ * Whether a role may make a resource public (grant to everyone): true for controller,
+ * admin, and user; false for workflow and unspecified. The middle layer carries no policy
+ * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.
+ * `null` (no-auth mode) returns false.
+ */
+declare function canGrantToEveryone(role: Role | null): boolean;
+/**
+ * Whether a role may impersonate another user: open/create another user's root and list
+ * the resources that user can access. Mirrors the backend's authorization rule
+ * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is
+ * the admin gate for the "open another user's root" feature and is intentionally stricter
+ * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user
+ * may share their own projects, but must never be offered impersonation). `null` (no-auth
+ * mode) returns false.
+ */
+declare function canImpersonate(role: Role | null): boolean;
+/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in {@link EnvelopeData.projects}. */
+interface EnvelopeProject {
+  label: string;
+  source: ProjectId;
+  updatedAt: number;
+}
+/** Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated. */
+interface EnvelopeData {
+  schemaVersion: 1;
+  shareId: ShareId;
+  sharedAt: number;
+  expiresAt: number | null;
+  mode: EnvelopeMode;
+  sender: string;
+  title: string;
+  projects: Record<ProjectFieldUuid, EnvelopeProject>;
+}
+/** Dynamic field on SharingState, one per handled share, keyed by shareId. */
+declare const decisionField: (shareId: ShareId) => string;
+interface SharingDecision {
+  decision: "accepted" | "rejected";
+  timestamp: number;
+  envelopeSharedAt: number;
+  acceptedProjects: string[];
+}
+/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed
+ *  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,
+ *  Live collaboration) — the acceptor's writable envelope grant is what permits the
+ *  write; read-only shares omit it. The donor reads these from its own outbox to see
+ *  who responded and when. Informational, not authoritative (a writable grant holder
+ *  could write under another login — same trust assumption as the sender field).
+ *  Copied forward when a share is changed. */
+declare const AcceptanceFieldPrefix = "acceptance/";
+declare const acceptanceField: (login: string) => string;
+declare const isAcceptanceField: (name: string) => boolean;
+declare const acceptanceFieldLogin: (name: string) => string;
+interface EnvelopeAcceptance {
+  action: "accepted" | "rejected";
+  timestamp: number;
+}
+/**
+ * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`
+ * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource
+ * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node
+ * path uses `node.getDataAsJson<EnvelopeData>()`, which decodes the same JSON.
+ */
+declare function decodeEnvelopeData(data: Uint8Array): EnvelopeData;
+/**
+ * Options for {@link MiddleLayer.shareProjects}.
+ *
+ * Recipients XOR everyone — two clean variants, not one struct with mutually exclusive
+ * optional fields. The everyone variant issues a single make-public grant (the envelope's
+ * `expiresAt` is set to `null`, so it never expires); the recipients variant grants each
+ * named recipient and the envelope expires after the default TTL.
+ */
+type ShareProjectsOptions = {
+  recipients: string[];
+  title: string;
+  mode: EnvelopeMode;
+} | {
+  everyone: true;
+  /**
+   * When true and an everyone-share of the same project already exists, refresh it under its
+   * stable shareId (recipients who already accepted or rejected are not re-prompted) instead of
+   * minting a new share. No-op when no prior everyone-share of the project exists. Callers that
+   * don't care pass `false`.
+   */
+  replace: boolean;
+  title: string;
+  mode: EnvelopeMode;
+};
+//#endregion
+export { AcceptanceFieldPrefix, EnvelopeAcceptance, EnvelopeData, EnvelopeMode, EnvelopeProject, ProjectChangeAction, ProjectFieldUuid, ShareId, ShareProjectsOptions, SharedEnvelopeResourceType, SharingDecision, SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, acceptanceField, acceptanceFieldLogin, asShareId, canGrantToEveryone, canImpersonate, decisionField, decodeEnvelopeData, isAcceptanceField, newShareId };
+//# sourceMappingURL=sharing_model.d.ts.map

package/dist/model/sharing_model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing_model.d.ts","names":[],"sources":["../../src/model/sharing_model.ts"],"mappings":";;;;;;AAYA;;;;AAA6B;KAAjB,OAAA,GAAU,OAAO;;iBAGb,UAAA,IAAc,OAAO;;AAAA;iBAMrB,SAAA,CAAU,EAAA,WAAa,OAAO;;cAYjC,kBAAA;;cAEA,iBAAA;AAAA,cAEA,yBAAA,EAA2B,YAAsD;AAAA,cACjF,0BAAA,EAA4B,YAAuD;AAAA,cACnF,wBAAA,EAA0B,YAAqD;AAAA,KAEhF,YAAA;AARmB;AAE/B;AAF+B,KAYnB,mBAAA;;;KAIA,gBAAA,GAAmB,OAAO;AAZtC;;;;AAA8F;AAC9F;AADA,iBAoBgB,kBAAA,CAAmB,IAAiB,EAAX,IAAI;;;AAnBmD;AAChG;;;;AAA4F;AAE5F;iBAoCgB,cAAA,CAAe,IAAiB,EAAX,IAAI;;UAWxB,eAAA;EACf,KAAA;EACA,MAAA,EAAQ,SAAS;EACjB,SAAA;AAAA;;UAIe,YAAA;EACf,aAAA;EACA,OAAA,EAAS,OAAA;EACT,QAAA;EACA,SAAA;EACA,IAAA,EAAM,YAAA;EACN,MAAA;EACA,KAAA;EACA,QAAA,EAAU,MAAA,CAAO,gBAAA,EAAkB,eAAA;AAAA;AA9Ce;AAAA,cAkDvC,aAAA,GAAiB,OAAgB,EAAP,OAAO;AAAA,UAE7B,eAAA;EACf,QAAA;EACA,SAAA;EACA,gBAAA;EACA,gBAAA;AAAA;;;;;;;;cAUW,qBAAA;AAAA,cACA,eAAA,GAAmB,KAAa;AAAA,cAChC,iBAAA,GAAqB,IAAY;AAAA,cACjC,oBAAA,GAAwB,IAAY;AAAA,UAEhC,kBAAA;EACf,MAAA;EACA,SAAS;AAAA;;;;;;;iBASK,kBAAA,CAAmB,IAAA,EAAM,UAAA,GAAa,YAAY;;;;;;;;;KAYtD,oBAAA;EAEN,UAAA;EACA,KAAA;EACA,IAAA,EAAM,YAAA;AAAA;EAGN,QAAA;EAnDiC;AAAO;AAE9C;;;;EAwDM,OAAA;EACA,KAAA;EACA,IAAA,EAAM,YAAY;AAAA"}

package/dist/model/sharing_model.js

@@ -0,0 +1,84 @@
+import { Role } from "@milaboratories/pl-client";
+import { randomUUID } from "node:crypto";
+//#region src/model/sharing_model.ts
+/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */
+function newShareId() {
+	return randomUUID();
+}
+/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`
+*  field name) as a {@link ShareId}, without minting a new one. */
+function asShareId(id) {
+	return id;
+}
+/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */
+const SharingOutboxField = "sharingOutbox";
+/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */
+const SharingStateField = "sharingState";
+const SharingOutboxResourceType = {
+	name: "SharingOutbox",
+	version: "1"
+};
+const SharedEnvelopeResourceType = {
+	name: "SharedEnvelope",
+	version: "1"
+};
+const SharingStateResourceType = {
+	name: "SharingState",
+	version: "1"
+};
+/**
+* Whether a role may make a resource public (grant to everyone): true for controller,
+* admin, and user; false for workflow and unspecified. The middle layer carries no policy
+* of its own here — a crafted call still hits the backend's role + permission-ceiling gate.
+* `null` (no-auth mode) returns false.
+*/
+function canGrantToEveryone(role) {
+	switch (role) {
+		case Role.CONTROLLER:
+		case Role.ADMIN:
+		case Role.USER: return true;
+		default: return false;
+	}
+}
+/**
+* Whether a role may impersonate another user: open/create another user's root and list
+* the resources that user can access. Mirrors the backend's authorization rule
+* `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is
+* the admin gate for the "open another user's root" feature and is intentionally stricter
+* than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user
+* may share their own projects, but must never be offered impersonation). `null` (no-auth
+* mode) returns false.
+*/
+function canImpersonate(role) {
+	switch (role) {
+		case Role.CONTROLLER:
+		case Role.ADMIN: return true;
+		default: return false;
+	}
+}
+/** Dynamic field on SharingState, one per handled share, keyed by shareId. */
+const decisionField = (shareId) => `decision/${shareId}`;
+/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed
+*  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,
+*  Live collaboration) — the acceptor's writable envelope grant is what permits the
+*  write; read-only shares omit it. The donor reads these from its own outbox to see
+*  who responded and when. Informational, not authoritative (a writable grant holder
+*  could write under another login — same trust assumption as the sender field).
+*  Copied forward when a share is changed. */
+const AcceptanceFieldPrefix = "acceptance/";
+const acceptanceField = (login) => `${AcceptanceFieldPrefix}${login}`;
+const isAcceptanceField = (name) => name.startsWith(AcceptanceFieldPrefix);
+const acceptanceFieldLogin = (name) => name.slice(11);
+/**
+* Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`
+* blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource
+* `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node
+* path uses `node.getDataAsJson<EnvelopeData>()`, which decodes the same JSON.
+*/
+function decodeEnvelopeData(data) {
+	return JSON.parse(Buffer.from(data).toString("utf-8"));
+}
+//#endregion
+export { AcceptanceFieldPrefix, SharedEnvelopeResourceType, SharingOutboxField, SharingOutboxResourceType, SharingStateField, SharingStateResourceType, acceptanceField, acceptanceFieldLogin, asShareId, canGrantToEveryone, canImpersonate, decisionField, decodeEnvelopeData, isAcceptanceField, newShareId };
+
+//# sourceMappingURL=sharing_model.js.map

package/dist/model/sharing_model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing_model.js","names":["RoleEnum"],"sources":["../../src/model/sharing_model.ts"],"sourcesContent":["import type { ResourceType, Role } from \"@milaboratories/pl-client\";\nimport { Role as RoleEnum } from \"@milaboratories/pl-client\";\nimport type { Branded, ProjectId } from \"@milaboratories/pl-model-common\";\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * Logical identity of a share, stable across replaces. A donor-generated UUID string,\n * branded so it cannot be silently confused with a project id, a login, or a raw field\n * name. Minted once with {@link newShareId}; every other site receives it (from decoded\n * {@link EnvelopeData} or by parsing a `decision/{shareId}` field name) and threads it\n * through unchanged.\n */\nexport type ShareId = Branded<string, \"ShareId\">;\n\n/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */\nexport function newShareId(): ShareId {\n  return randomUUID() as ShareId;\n}\n\n/** Brands a string already known to be a share id (e.g. parsed from a `decision/{shareId}`\n *  field name) as a {@link ShareId}, without minting a new one. */\nexport function asShareId(id: string): ShareId {\n  return id as ShareId;\n}\n\n//\n// Pl Model — Project Sharing\n//\n// All sharing structures are defined and managed by the middle layer; the\n// backend knows nothing about envelopes.\n//\n\n/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */\nexport const SharingOutboxField = \"sharingOutbox\";\n/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */\nexport const SharingStateField = \"sharingState\";\n\nexport const SharingOutboxResourceType: ResourceType = { name: \"SharingOutbox\", version: \"1\" };\nexport const SharedEnvelopeResourceType: ResourceType = { name: \"SharedEnvelope\", version: \"1\" };\nexport const SharingStateResourceType: ResourceType = { name: \"SharingState\", version: \"1\" };\n\nexport type EnvelopeMode = \"copy\" | \"read-only\" | \"collaboration\";\n\n/** Per-project decision on change, matching the UI labels: re-snapshot the live source (\"update\"),\n *  carry the existing snapshot (\"keep\"), or drop the project from the pack (\"remove\"). */\nexport type ProjectChangeAction = \"keep\" | \"update\" | \"remove\";\n\n/** Key of the per-project envelope maps: a uuid minted per snapshot to name the `project/{uuid}`\n *  field. Distinct from {@link ProjectId} — re-snapshotting one source yields a new uuid each time. */\nexport type ProjectFieldUuid = Branded<string, \"ProjectFieldUuid\">;\n\n/**\n * Whether a role may make a resource public (grant to everyone): true for controller,\n * admin, and user; false for workflow and unspecified. The middle layer carries no policy\n * of its own here — a crafted call still hits the backend's role + permission-ceiling gate.\n * `null` (no-auth mode) returns false.\n */\nexport function canGrantToEveryone(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n    case RoleEnum.USER:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/**\n * Whether a role may impersonate another user: open/create another user's root and list\n * the resources that user can access. Mirrors the backend's authorization rule\n * `util/misecurity/role.go` `CanImpersonate` — true for controller and admin only. This is\n * the admin gate for the \"open another user's root\" feature and is intentionally stricter\n * than {@link canGrantToEveryone}, which also returns true for a regular user (a normal user\n * may share their own projects, but must never be offered impersonation). `null` (no-auth\n * mode) returns false.\n */\nexport function canImpersonate(role: Role | null): boolean {\n  switch (role) {\n    case RoleEnum.CONTROLLER:\n    case RoleEnum.ADMIN:\n      return true;\n    default:\n      return false;\n  }\n}\n\n/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in {@link EnvelopeData.projects}. */\nexport interface EnvelopeProject {\n  label: string; // carried so the pending-share UI renders without traversing into the project\n  source: ProjectId; // donor's source projectId; supersedes a prior share and matches the snapshot to its live source on change\n  updatedAt: number; // ms epoch of the last (re)snapshot\n}\n\n/** Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated. */\nexport interface EnvelopeData {\n  schemaVersion: 1;\n  shareId: ShareId; // donor-generated UUID; logical share identity, stable across changes\n  sharedAt: number; // ms epoch; this instance's creation time — distinguishes instances of one shareId\n  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)\n  mode: EnvelopeMode; // what the acceptor's app should do with the contents\n  sender: string; // donor login (informational; backend granted_by is authoritative)\n  title: string; // display name shown to recipients; defaults to the first project's name\n  projects: Record<ProjectFieldUuid, EnvelopeProject>; // contained projects, keyed by project field uuid\n}\n\n/** Dynamic field on SharingState, one per handled share, keyed by shareId. */\nexport const decisionField = (shareId: ShareId) => `decision/${shareId}`;\n\nexport interface SharingDecision {\n  decision: \"accepted\" | \"rejected\";\n  timestamp: number; // ms epoch — when the acceptor acted\n  envelopeSharedAt: number; // the acted-on envelope instance's sharedAt — pins which instance was handled (paired with the shareId key; the resource id is never stored)\n  acceptedProjects: string[]; // ids of the projects created in the acceptor's list ([] for a rejected share)\n}\n\n/** Dynamic field on SharedEnvelope, one per recipient who accepted or rejected, keyed\n *  by recipient login. Written by the acceptor in read-write shares only (Copy & Share,\n *  Live collaboration) — the acceptor's writable envelope grant is what permits the\n *  write; read-only shares omit it. The donor reads these from its own outbox to see\n *  who responded and when. Informational, not authoritative (a writable grant holder\n *  could write under another login — same trust assumption as the sender field).\n *  Copied forward when a share is changed. */\nexport const AcceptanceFieldPrefix = \"acceptance/\";\nexport const acceptanceField = (login: string) => `${AcceptanceFieldPrefix}${login}`;\nexport const isAcceptanceField = (name: string) => name.startsWith(AcceptanceFieldPrefix);\nexport const acceptanceFieldLogin = (name: string) => name.slice(AcceptanceFieldPrefix.length);\n\nexport interface EnvelopeAcceptance {\n  action: \"accepted\" | \"rejected\";\n  timestamp: number; // ms since epoch\n}\n\n/**\n * Single owner of the raw-data → {@link EnvelopeData} decode. The envelope's immutable `data`\n * blob is UTF-8 JSON set once at createEphemeral; every site that reads it from a raw resource\n * `data` byte buffer (the basic-resource read path) goes through here. The reactive tree-node\n * path uses `node.getDataAsJson<EnvelopeData>()`, which decodes the same JSON.\n */\nexport function decodeEnvelopeData(data: Uint8Array): EnvelopeData {\n  return JSON.parse(Buffer.from(data).toString(\"utf-8\")) as EnvelopeData;\n}\n\n/**\n * Options for {@link MiddleLayer.shareProjects}.\n *\n * Recipients XOR everyone — two clean variants, not one struct with mutually exclusive\n * optional fields. The everyone variant issues a single make-public grant (the envelope's\n * `expiresAt` is set to `null`, so it never expires); the recipients variant grants each\n * named recipient and the envelope expires after the default TTL.\n */\nexport type ShareProjectsOptions =\n  | {\n      recipients: string[]; // recipient logins\n      title: string; // display name shown to recipients; defaults to the first project's name\n      mode: EnvelopeMode; // v1 UI always sends \"copy\"\n    }\n  | {\n      everyone: true; // share with all users on the server\n      /**\n       * When true and an everyone-share of the same project already exists, refresh it under its\n       * stable shareId (recipients who already accepted or rejected are not re-prompted) instead of\n       * minting a new share. No-op when no prior everyone-share of the project exists. Callers that\n       * don't care pass `false`.\n       */\n      replace: boolean;\n      title: string;\n      mode: EnvelopeMode;\n    };\n"],"mappings":";;;;AAeA,SAAgB,aAAsB;CACpC,OAAO,WAAW;AACpB;;;AAIA,SAAgB,UAAU,IAAqB;CAC7C,OAAO;AACT;;AAUA,MAAa,qBAAqB;;AAElC,MAAa,oBAAoB;AAEjC,MAAa,4BAA0C;CAAE,MAAM;CAAiB,SAAS;AAAI;AAC7F,MAAa,6BAA2C;CAAE,MAAM;CAAkB,SAAS;AAAI;AAC/F,MAAa,2BAAyC;CAAE,MAAM;CAAgB,SAAS;AAAI;;;;;;;AAkB3F,SAAgB,mBAAmB,MAA4B;CAC7D,QAAQ,MAAR;EACE,KAAKA,KAAS;EACd,KAAKA,KAAS;EACd,KAAKA,KAAS,MACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;;;;;;;;;AAWA,SAAgB,eAAe,MAA4B;CACzD,QAAQ,MAAR;EACE,KAAKA,KAAS;EACd,KAAKA,KAAS,OACZ,OAAO;EACT,SACE,OAAO;CACX;AACF;;AAsBA,MAAa,iBAAiB,YAAqB,YAAY;;;;;;;;AAgB/D,MAAa,wBAAwB;AACrC,MAAa,mBAAmB,UAAkB,GAAG,wBAAwB;AAC7E,MAAa,qBAAqB,SAAiB,KAAK,WAAW,qBAAqB;AACxF,MAAa,wBAAwB,SAAiB,KAAK,MAAM,EAA4B;;;;;;;AAa7F,SAAgB,mBAAmB,MAAgC;CACjE,OAAO,KAAK,MAAM,OAAO,KAAK,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC;AACvD"}

package/dist/mutator/block-pack/frontend.cjs

@@ -1,4 +1,5 @@
 const require_block_pack_spec = require("../../model/block_pack_spec.cjs");
+require("../../model/index.cjs");
 let _milaboratories_ts_helpers = require("@milaboratories/ts-helpers");
 //#region src/mutator/block-pack/frontend.ts
 function createFrontend(tx, spec) {

package/dist/mutator/block-pack/frontend.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"frontend.cjs","names":["FrontendFromUrlResourceType","FrontendFromFolderResourceType","FrontendFromLocalTgzResourceType"],"sources":["../../../src/mutator/block-pack/frontend.ts"],"sourcesContent":["import type { AnyResourceRef, PlTransaction } from \"@milaboratories/pl-client\";\nimport type {\n  FrontendFromFolderData,\n  FrontendFromLocalTgzData,\n  FrontendFromUrlData,\n  FrontendSpec,\n} from \"../../model\";\nimport {\n  FrontendFromFolderResourceType,\n  FrontendFromLocalTgzResourceType,\n  FrontendFromUrlResourceType,\n} from \"../../model\";\nimport { assertNever } from \"@milaboratories/ts-helpers\";\n\nexport function createFrontend(tx: PlTransaction, spec: FrontendSpec): AnyResourceRef {\n  switch (spec.type) {\n    case \"url\":\n      return tx.createValue(\n        FrontendFromUrlResourceType,\n        JSON.stringify({ url: spec.url } as FrontendFromUrlData),\n      );\n    case \"local\":\n      return tx.createValue(\n        FrontendFromFolderResourceType,\n        JSON.stringify({\n          path: spec.path,\n          signature: spec.signature,\n        } as FrontendFromFolderData),\n      );\n    case \"local-tgz\":\n      return tx.createValue(\n        FrontendFromLocalTgzResourceType,\n        JSON.stringify({\n          path: spec.path,\n          mtime: spec.mtime,\n          signature: spec.signature,\n        } as FrontendFromLocalTgzData),\n      );\n    default:\n      return assertNever(spec);\n  }\n}\n"],"mappings":";;;AAcA,SAAgB,eAAe,IAAmB,MAAoC;CACpF,QAAQ,KAAK,MAAb;EACE,KAAK,OACH,OAAO,GAAG,YACRA,wBAAAA,6BACA,KAAK,UAAU,EAAE,KAAK,KAAK,IAAI,CAAwB,CACzD;EACF,KAAK,SACH,OAAO,GAAG,YACRC,wBAAAA,gCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,WAAW,KAAK;EAClB,CAA2B,CAC7B;EACF,KAAK,aACH,OAAO,GAAG,YACRC,wBAAAA,kCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,WAAW,KAAK;EAClB,CAA6B,CAC/B;EACF,SACE,QAAA,GAAA,2BAAA,YAAA,CAAmB,IAAI;CAC3B;AACF"}
+{"version":3,"file":"frontend.cjs","names":["FrontendFromUrlResourceType","FrontendFromFolderResourceType","FrontendFromLocalTgzResourceType"],"sources":["../../../src/mutator/block-pack/frontend.ts"],"sourcesContent":["import type { AnyResourceRef, PlTransaction } from \"@milaboratories/pl-client\";\nimport type {\n  FrontendFromFolderData,\n  FrontendFromLocalTgzData,\n  FrontendFromUrlData,\n  FrontendSpec,\n} from \"../../model\";\nimport {\n  FrontendFromFolderResourceType,\n  FrontendFromLocalTgzResourceType,\n  FrontendFromUrlResourceType,\n} from \"../../model\";\nimport { assertNever } from \"@milaboratories/ts-helpers\";\n\nexport function createFrontend(tx: PlTransaction, spec: FrontendSpec): AnyResourceRef {\n  switch (spec.type) {\n    case \"url\":\n      return tx.createValue(\n        FrontendFromUrlResourceType,\n        JSON.stringify({ url: spec.url } as FrontendFromUrlData),\n      );\n    case \"local\":\n      return tx.createValue(\n        FrontendFromFolderResourceType,\n        JSON.stringify({\n          path: spec.path,\n          signature: spec.signature,\n        } as FrontendFromFolderData),\n      );\n    case \"local-tgz\":\n      return tx.createValue(\n        FrontendFromLocalTgzResourceType,\n        JSON.stringify({\n          path: spec.path,\n          mtime: spec.mtime,\n          signature: spec.signature,\n        } as FrontendFromLocalTgzData),\n      );\n    default:\n      return assertNever(spec);\n  }\n}\n"],"mappings":";;;;AAcA,SAAgB,eAAe,IAAmB,MAAoC;CACpF,QAAQ,KAAK,MAAb;EACE,KAAK,OACH,OAAO,GAAG,YACRA,wBAAAA,6BACA,KAAK,UAAU,EAAE,KAAK,KAAK,IAAI,CAAwB,CACzD;EACF,KAAK,SACH,OAAO,GAAG,YACRC,wBAAAA,gCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,WAAW,KAAK;EAClB,CAA2B,CAC7B;EACF,KAAK,aACH,OAAO,GAAG,YACRC,wBAAAA,kCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,WAAW,KAAK;EAClB,CAA6B,CAC/B;EACF,SACE,QAAA,GAAA,2BAAA,YAAA,CAAmB,IAAI;CAC3B;AACF"}

package/dist/mutator/block-pack/frontend.js

@@ -1,4 +1,5 @@
 import { FrontendFromFolderResourceType, FrontendFromLocalTgzResourceType, FrontendFromUrlResourceType } from "../../model/block_pack_spec.js";
+import "../../model/index.js";
 import { assertNever } from "@milaboratories/ts-helpers";
 //#region src/mutator/block-pack/frontend.ts
 function createFrontend(tx, spec) {

package/dist/mutator/block-pack/frontend.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend.js","names":[],"sources":["../../../src/mutator/block-pack/frontend.ts"],"sourcesContent":["import type { AnyResourceRef, PlTransaction } from \"@milaboratories/pl-client\";\nimport type {\n  FrontendFromFolderData,\n  FrontendFromLocalTgzData,\n  FrontendFromUrlData,\n  FrontendSpec,\n} from \"../../model\";\nimport {\n  FrontendFromFolderResourceType,\n  FrontendFromLocalTgzResourceType,\n  FrontendFromUrlResourceType,\n} from \"../../model\";\nimport { assertNever } from \"@milaboratories/ts-helpers\";\n\nexport function createFrontend(tx: PlTransaction, spec: FrontendSpec): AnyResourceRef {\n  switch (spec.type) {\n    case \"url\":\n      return tx.createValue(\n        FrontendFromUrlResourceType,\n        JSON.stringify({ url: spec.url } as FrontendFromUrlData),\n      );\n    case \"local\":\n      return tx.createValue(\n        FrontendFromFolderResourceType,\n        JSON.stringify({\n          path: spec.path,\n          signature: spec.signature,\n        } as FrontendFromFolderData),\n      );\n    case \"local-tgz\":\n      return tx.createValue(\n        FrontendFromLocalTgzResourceType,\n        JSON.stringify({\n          path: spec.path,\n          mtime: spec.mtime,\n          signature: spec.signature,\n        } as FrontendFromLocalTgzData),\n      );\n    default:\n      return assertNever(spec);\n  }\n}\n"],"mappings":";;;AAcA,SAAgB,eAAe,IAAmB,MAAoC;CACpF,QAAQ,KAAK,MAAb;EACE,KAAK,OACH,OAAO,GAAG,YACR,6BACA,KAAK,UAAU,EAAE,KAAK,KAAK,IAAI,CAAwB,CACzD;EACF,KAAK,SACH,OAAO,GAAG,YACR,gCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,WAAW,KAAK;EAClB,CAA2B,CAC7B;EACF,KAAK,aACH,OAAO,GAAG,YACR,kCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,WAAW,KAAK;EAClB,CAA6B,CAC/B;EACF,SACE,OAAO,YAAY,IAAI;CAC3B;AACF"}
+{"version":3,"file":"frontend.js","names":[],"sources":["../../../src/mutator/block-pack/frontend.ts"],"sourcesContent":["import type { AnyResourceRef, PlTransaction } from \"@milaboratories/pl-client\";\nimport type {\n  FrontendFromFolderData,\n  FrontendFromLocalTgzData,\n  FrontendFromUrlData,\n  FrontendSpec,\n} from \"../../model\";\nimport {\n  FrontendFromFolderResourceType,\n  FrontendFromLocalTgzResourceType,\n  FrontendFromUrlResourceType,\n} from \"../../model\";\nimport { assertNever } from \"@milaboratories/ts-helpers\";\n\nexport function createFrontend(tx: PlTransaction, spec: FrontendSpec): AnyResourceRef {\n  switch (spec.type) {\n    case \"url\":\n      return tx.createValue(\n        FrontendFromUrlResourceType,\n        JSON.stringify({ url: spec.url } as FrontendFromUrlData),\n      );\n    case \"local\":\n      return tx.createValue(\n        FrontendFromFolderResourceType,\n        JSON.stringify({\n          path: spec.path,\n          signature: spec.signature,\n        } as FrontendFromFolderData),\n      );\n    case \"local-tgz\":\n      return tx.createValue(\n        FrontendFromLocalTgzResourceType,\n        JSON.stringify({\n          path: spec.path,\n          mtime: spec.mtime,\n          signature: spec.signature,\n        } as FrontendFromLocalTgzData),\n      );\n    default:\n      return assertNever(spec);\n  }\n}\n"],"mappings":";;;;AAcA,SAAgB,eAAe,IAAmB,MAAoC;CACpF,QAAQ,KAAK,MAAb;EACE,KAAK,OACH,OAAO,GAAG,YACR,6BACA,KAAK,UAAU,EAAE,KAAK,KAAK,IAAI,CAAwB,CACzD;EACF,KAAK,SACH,OAAO,GAAG,YACR,gCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,WAAW,KAAK;EAClB,CAA2B,CAC7B;EACF,KAAK,aACH,OAAO,GAAG,YACR,kCACA,KAAK,UAAU;GACb,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,WAAW,KAAK;EAClB,CAA6B,CAC/B;EACF,SACE,OAAO,YAAY,IAAI;CAC3B;AACF"}

package/dist/mutator/sharing.cjs

@@ -0,0 +1,138 @@
+const require_project_model = require("../model/project_model.cjs");
+const require_sharing_model = require("../model/sharing_model.cjs");
+const require_project = require("./project.cjs");
+let _milaboratories_pl_client = require("@milaboratories/pl-client");
+let node_crypto = require("node:crypto");
+//#region src/mutator/sharing.ts
+/** Field name carrying a project snapshot inside a {@link SharedEnvelopeResourceType}. */
+const EnvelopeProjectFieldPrefix = "project/";
+const envelopeProjectField = (uuid) => `${EnvelopeProjectFieldPrefix}${uuid}`;
+/** True for an envelope field that carries a project snapshot. */
+function isEnvelopeProjectField(name) {
+	return name.startsWith(EnvelopeProjectFieldPrefix);
+}
+/** Extracts the project field uuid from a `project/{uuid}` field name. */
+function envelopeProjectFieldUuid(name) {
+	return name.slice(8);
+}
+/**
+* Builds one {@link SharedEnvelopeResourceType} on the donor side inside the given write
+* transaction: snapshots each source project by reference, seals the envelope with its
+* immutable {@link EnvelopeData}, and attaches the envelope under `{shareId}` on the donor's
+* outbox. The caller is responsible for issuing the per-recipient grants and committing the
+* transaction — keeping create + grant atomic.
+*
+* @returns the new envelope resource and the generated `EnvelopeData`.
+*/
+async function buildShareEnvelope(tx, outboxRid, sources, params) {
+	const shareId = params.shareId ?? require_sharing_model.newShareId();
+	const sharedAt = params.sharedAt ?? Date.now();
+	const projects = {};
+	const snapshots = [];
+	for (const src of sources) {
+		const uuid = (0, node_crypto.randomUUID)();
+		if (src.kind === "fresh") {
+			const meta = await tx.getKValueJson(src.sourceRid, require_project_model.ProjectMetaKey);
+			const ref = await require_project.duplicateProject(tx, src.sourceRid, { label: meta.label });
+			projects[uuid] = {
+				label: meta.label,
+				source: src.projectId,
+				updatedAt: sharedAt
+			};
+			snapshots.push({
+				uuid,
+				ref
+			});
+		} else {
+			projects[uuid] = {
+				label: src.label,
+				source: src.projectId,
+				updatedAt: src.updatedAt
+			};
+			snapshots.push({
+				uuid,
+				ref: src.snapshotRid
+			});
+		}
+	}
+	const data = {
+		schemaVersion: 1,
+		shareId,
+		sharedAt,
+		expiresAt: params.expiresAt,
+		mode: params.mode,
+		sender: params.sender,
+		title: params.title,
+		projects
+	};
+	const envelope = tx.createEphemeral(require_sharing_model.SharedEnvelopeResourceType, JSON.stringify(data));
+	for (const { uuid, ref } of snapshots) tx.createField((0, _milaboratories_pl_client.field)(envelope, envelopeProjectField(uuid)), "Input", ref);
+	tx.lockInputs(envelope);
+	tx.createField((0, _milaboratories_pl_client.field)(outboxRid, shareId), "Dynamic", envelope);
+	return {
+		envelope,
+		data
+	};
+}
+/**
+* Records a response onto the envelope as a dynamic `acceptance/{login}` field: the acceptor
+* writing their own decision (their writable grant permits it), or the donor transferring an
+* existing record onto a changed envelope. Accepts the envelope by ref or id.
+*/
+function writeEnvelopeAcceptance(tx, envelopeRid, login, action, timestamp) {
+	const acceptance = {
+		action,
+		timestamp
+	};
+	const value = tx.createJsonValue(acceptance);
+	tx.createField((0, _milaboratories_pl_client.field)(envelopeRid, require_sharing_model.acceptanceField(login)), "Dynamic", value);
+}
+/**
+* Records the acceptor's decision for a handled share on the acceptor's SharingState as a
+* dynamic `decision/{shareId}` field. Keyed on the logical shareId so discovery dedups on the
+* share, not on the envelope instance.
+*/
+function writeSharingDecision(tx, stateRid, shareId, decision) {
+	const value = tx.createJsonValue(decision);
+	tx.createField((0, _milaboratories_pl_client.field)(stateRid, require_sharing_model.decisionField(shareId)), "Dynamic", value);
+}
+/**
+* Copies every project snapshot inside an envelope into the acceptor's own project list — a
+* cross-color attach the backend permits. Mirrors {@link duplicateProject}'s `rename` contract,
+* but resolves the source against the envelope tree (not the acceptor's own list), so the
+* wrapper cannot be reused.
+*
+* @returns ids of the projects created in the acceptor's list.
+*/
+async function copyEnvelopeProjectsIntoList(tx, envelopeRid, projectListRid, rename) {
+	const existingRids = (await tx.getResourceData(projectListRid, true)).fields.map((f) => f.value).filter(_milaboratories_pl_client.isNotNullSignedResourceId);
+	const existingLabels = (await Promise.all(existingRids.map((rid) => tx.getKValueJson(rid, require_project_model.ProjectMetaKey)))).map((m) => m.label);
+	const sourceRids = (await tx.getResourceData(envelopeRid, true)).fields.filter((f) => isEnvelopeProjectField(f.name)).map((f) => f.value).filter(_milaboratories_pl_client.isNotNullSignedResourceId);
+	const created = [];
+	for (const sourceRid of sourceRids) {
+		const sourceMeta = await tx.getKValueJson(sourceRid, require_project_model.ProjectMetaKey);
+		const newLabel = rename ? rename(sourceMeta.label, existingLabels) : sourceMeta.label;
+		existingLabels.push(newLabel);
+		const newPrj = await require_project.duplicateProject(tx, sourceRid, { label: newLabel });
+		tx.createField((0, _milaboratories_pl_client.field)(projectListRid, (0, node_crypto.randomUUID)()), "Dynamic", newPrj);
+		const signedRid = await newPrj.globalId;
+		created.push(signedRid);
+	}
+	return created;
+}
+/** String-form ids of the projects created by {@link copyEnvelopeProjectsIntoList}. */
+function resourceIdsToStrings(ids) {
+	return ids.map((id) => (0, _milaboratories_pl_client.resourceIdToString)(id));
+}
+//#endregion
+exports.EnvelopeProjectFieldPrefix = EnvelopeProjectFieldPrefix;
+exports.buildShareEnvelope = buildShareEnvelope;
+exports.copyEnvelopeProjectsIntoList = copyEnvelopeProjectsIntoList;
+exports.envelopeProjectField = envelopeProjectField;
+exports.envelopeProjectFieldUuid = envelopeProjectFieldUuid;
+exports.isEnvelopeProjectField = isEnvelopeProjectField;
+exports.resourceIdsToStrings = resourceIdsToStrings;
+exports.writeEnvelopeAcceptance = writeEnvelopeAcceptance;
+exports.writeSharingDecision = writeSharingDecision;
+
+//# sourceMappingURL=sharing.cjs.map

package/dist/mutator/sharing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharing.cjs","names":["newShareId","ProjectMetaKey","duplicateProject","SharedEnvelopeResourceType","acceptanceField","decisionField","isNotNullSignedResourceId"],"sources":["../../src/mutator/sharing.ts"],"sourcesContent":["import type { PlTransaction, ResourceRef, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { field, isNotNullSignedResourceId, resourceIdToString } from \"@milaboratories/pl-client\";\nimport { randomUUID } from \"node:crypto\";\nimport type { ProjectMeta } from \"@milaboratories/pl-model-middle-layer\";\nimport type { ProjectId } from \"@milaboratories/pl-model-common\";\nimport { ProjectMetaKey } from \"../model/project_model\";\nimport { duplicateProject } from \"./project\";\nimport type {\n  EnvelopeData,\n  EnvelopeAcceptance,\n  EnvelopeMode,\n  EnvelopeProject,\n  ProjectFieldUuid,\n  ShareId,\n  SharingDecision,\n} from \"../model/sharing_model\";\nimport {\n  SharedEnvelopeResourceType,\n  acceptanceField,\n  decisionField,\n  newShareId,\n} from \"../model/sharing_model\";\n\n/** Field name carrying a project snapshot inside a {@link SharedEnvelopeResourceType}. */\nexport const EnvelopeProjectFieldPrefix = \"project/\";\nexport const envelopeProjectField = (uuid: ProjectFieldUuid) =>\n  `${EnvelopeProjectFieldPrefix}${uuid}`;\n\n/** True for an envelope field that carries a project snapshot. */\nexport function isEnvelopeProjectField(name: string): boolean {\n  return name.startsWith(EnvelopeProjectFieldPrefix);\n}\n\n/** Extracts the project field uuid from a `project/{uuid}` field name. */\nexport function envelopeProjectFieldUuid(name: string): ProjectFieldUuid {\n  return name.slice(EnvelopeProjectFieldPrefix.length) as ProjectFieldUuid;\n}\n\n//\n// Donor side\n//\n\n/**\n * One project going into an envelope: `fresh` snapshots a live source (normal path); `carry`\n * re-attaches an existing snapshot (change's \"keep\", or an \"update\" whose source is gone).\n */\nexport type EnvelopeProjectSource =\n  | { kind: \"fresh\"; projectId: ProjectId; sourceRid: SignedResourceId }\n  | {\n      kind: \"carry\";\n      projectId: ProjectId;\n      label: string;\n      snapshotRid: SignedResourceId;\n      /** ms epoch the carried snapshot was last taken; preserved so \"keep\" keeps its timestamp. */\n      updatedAt: number;\n    };\n\n/**\n * Builds one {@link SharedEnvelopeResourceType} on the donor side inside the given write\n * transaction: snapshots each source project by reference, seals the envelope with its\n * immutable {@link EnvelopeData}, and attaches the envelope under `{shareId}` on the donor's\n * outbox. The caller is responsible for issuing the per-recipient grants and committing the\n * transaction — keeping create + grant atomic.\n *\n * @returns the new envelope resource and the generated `EnvelopeData`.\n */\nexport async function buildShareEnvelope(\n  tx: PlTransaction,\n  outboxRid: SignedResourceId,\n  sources: EnvelopeProjectSource[],\n  params: {\n    mode: EnvelopeMode;\n    sender: string;\n    title: string;\n    /** ms epoch; sharedAt + ttl for a targeted share, null for share-with-everybody. */\n    expiresAt: number | null;\n    /** Existing shareId for a change; a fresh one is minted when omitted. */\n    shareId?: ShareId;\n    sharedAt?: number;\n  },\n): Promise<{ envelope: ResourceRef; data: EnvelopeData }> {\n  const shareId = params.shareId ?? newShareId();\n  const sharedAt = params.sharedAt ?? Date.now();\n\n  // Snapshot (fresh) or re-attach (carry) each project, collecting its metadata for the pack.\n  const projects: Record<ProjectFieldUuid, EnvelopeProject> = {};\n  const snapshots: { uuid: ProjectFieldUuid; ref: ResourceRef | SignedResourceId }[] = [];\n  for (const src of sources) {\n    const uuid = randomUUID() as ProjectFieldUuid;\n    if (src.kind === \"fresh\") {\n      const meta = await tx.getKValueJson<ProjectMeta>(src.sourceRid, ProjectMetaKey);\n      const ref = await duplicateProject(tx, src.sourceRid, { label: meta.label });\n      projects[uuid] = { label: meta.label, source: src.projectId, updatedAt: sharedAt }; // (re)snapshotted now\n      snapshots.push({ uuid, ref });\n    } else {\n      // Re-attach the prior snapshot; the new envelope references it before the old one is\n      // detached in the same tx, so it stays alive. Label and timestamp carry unchanged.\n      projects[uuid] = { label: src.label, source: src.projectId, updatedAt: src.updatedAt };\n      snapshots.push({ uuid, ref: src.snapshotRid });\n    }\n  }\n\n  const data: EnvelopeData = {\n    schemaVersion: 1,\n    shareId,\n    sharedAt,\n    expiresAt: params.expiresAt,\n    mode: params.mode,\n    sender: params.sender,\n    title: params.title,\n    projects,\n  };\n\n  // Immutable data set once at creation, never altered.\n  const envelope = tx.createEphemeral(SharedEnvelopeResourceType, JSON.stringify(data));\n\n  // Attach the project snapshots as Input fields, then seal the input set one-way.\n  for (const { uuid, ref } of snapshots) {\n    tx.createField(field(envelope, envelopeProjectField(uuid)), \"Input\", ref);\n  }\n  tx.lockInputs(envelope);\n\n  // Attach to the outbox under {shareId} in the same transaction so the held-resource rule\n  // keeps the ephemeral envelope alive.\n  tx.createField(field(outboxRid, shareId), \"Dynamic\", envelope);\n\n  return { envelope, data };\n}\n\n/**\n * Records a response onto the envelope as a dynamic `acceptance/{login}` field: the acceptor\n * writing their own decision (their writable grant permits it), or the donor transferring an\n * existing record onto a changed envelope. Accepts the envelope by ref or id.\n */\nexport function writeEnvelopeAcceptance(\n  tx: PlTransaction,\n  envelopeRid: ResourceRef | SignedResourceId,\n  login: string,\n  action: EnvelopeAcceptance[\"action\"],\n  timestamp: number,\n): void {\n  const acceptance: EnvelopeAcceptance = { action, timestamp };\n  const value = tx.createJsonValue(acceptance);\n  tx.createField(field(envelopeRid, acceptanceField(login)), \"Dynamic\", value);\n}\n\n//\n// Acceptor side\n//\n\n/**\n * Records the acceptor's decision for a handled share on the acceptor's SharingState as a\n * dynamic `decision/{shareId}` field. Keyed on the logical shareId so discovery dedups on the\n * share, not on the envelope instance.\n */\nexport function writeSharingDecision(\n  tx: PlTransaction,\n  stateRid: SignedResourceId,\n  shareId: ShareId,\n  decision: SharingDecision,\n): void {\n  const value = tx.createJsonValue(decision);\n  tx.createField(field(stateRid, decisionField(shareId)), \"Dynamic\", value);\n}\n\n/**\n * Copies every project snapshot inside an envelope into the acceptor's own project list — a\n * cross-color attach the backend permits. Mirrors {@link duplicateProject}'s `rename` contract,\n * but resolves the source against the envelope tree (not the acceptor's own list), so the\n * wrapper cannot be reused.\n *\n * @returns ids of the projects created in the acceptor's list.\n */\nexport async function copyEnvelopeProjectsIntoList(\n  tx: PlTransaction,\n  envelopeRid: SignedResourceId,\n  projectListRid: SignedResourceId,\n  rename?: (previousLabel: string, existingLabels: string[]) => string,\n): Promise<SignedResourceId[]> {\n  // Read the acceptor's existing project labels once (own color, no relaxation).\n  const projectListData = await tx.getResourceData(projectListRid, true);\n  const existingRids = projectListData.fields.map((f) => f.value).filter(isNotNullSignedResourceId);\n  const existingLabels = (\n    await Promise.all(existingRids.map((rid) => tx.getKValueJson<ProjectMeta>(rid, ProjectMetaKey)))\n  ).map((m) => m.label);\n\n  // Enumerate the envelope's project/{uuid} input field values (signed envelope-colored ids).\n  const envelopeData = await tx.getResourceData(envelopeRid, true);\n  const sourceRids = envelopeData.fields\n    .filter((f) => isEnvelopeProjectField(f.name))\n    .map((f) => f.value)\n    .filter(isNotNullSignedResourceId);\n\n  const created: SignedResourceId[] = [];\n  for (const sourceRid of sourceRids) {\n    const sourceMeta = await tx.getKValueJson<ProjectMeta>(sourceRid, ProjectMetaKey);\n    const newLabel = rename ? rename(sourceMeta.label, existingLabels) : sourceMeta.label;\n    existingLabels.push(newLabel);\n\n    // Cross-color attach: a new UserProject in the acceptor's color whose fields point at\n    // envelope-colored resources. Fails with PermissionDenied: color mismatch on a backend\n    // that lacks crossTreeRefs:v1.\n    const newPrj = await duplicateProject(tx, sourceRid, { label: newLabel });\n    tx.createField(field(projectListRid, randomUUID()), \"Dynamic\", newPrj);\n\n    const signedRid = await newPrj.globalId;\n    created.push(signedRid);\n  }\n\n  return created;\n}\n\n/** String-form ids of the projects created by {@link copyEnvelopeProjectsIntoList}. */\nexport function resourceIdsToStrings(ids: SignedResourceId[]): string[] {\n  return ids.map((id) => resourceIdToString(id));\n}\n"],"mappings":";;;;;;;AAwBA,MAAa,6BAA6B;AAC1C,MAAa,wBAAwB,SACnC,GAAG,6BAA6B;;AAGlC,SAAgB,uBAAuB,MAAuB;CAC5D,OAAO,KAAK,WAAW,0BAA0B;AACnD;;AAGA,SAAgB,yBAAyB,MAAgC;CACvE,OAAO,KAAK,MAAM,CAAiC;AACrD;;;;;;;;;;AA8BA,eAAsB,mBACpB,IACA,WACA,SACA,QAUwD;CACxD,MAAM,UAAU,OAAO,WAAWA,sBAAAA,WAAW;CAC7C,MAAM,WAAW,OAAO,YAAY,KAAK,IAAI;CAG7C,MAAM,WAAsD,CAAC;CAC7D,MAAM,YAA+E,CAAC;CACtF,KAAK,MAAM,OAAO,SAAS;EACzB,MAAM,QAAA,GAAA,YAAA,WAAA,CAAkB;EACxB,IAAI,IAAI,SAAS,SAAS;GACxB,MAAM,OAAO,MAAM,GAAG,cAA2B,IAAI,WAAWC,sBAAAA,cAAc;GAC9E,MAAM,MAAM,MAAMC,gBAAAA,iBAAiB,IAAI,IAAI,WAAW,EAAE,OAAO,KAAK,MAAM,CAAC;GAC3E,SAAS,QAAQ;IAAE,OAAO,KAAK;IAAO,QAAQ,IAAI;IAAW,WAAW;GAAS;GACjF,UAAU,KAAK;IAAE;IAAM;GAAI,CAAC;EAC9B,OAAO;GAGL,SAAS,QAAQ;IAAE,OAAO,IAAI;IAAO,QAAQ,IAAI;IAAW,WAAW,IAAI;GAAU;GACrF,UAAU,KAAK;IAAE;IAAM,KAAK,IAAI;GAAY,CAAC;EAC/C;CACF;CAEA,MAAM,OAAqB;EACzB,eAAe;EACf;EACA;EACA,WAAW,OAAO;EAClB,MAAM,OAAO;EACb,QAAQ,OAAO;EACf,OAAO,OAAO;EACd;CACF;CAGA,MAAM,WAAW,GAAG,gBAAgBC,sBAAAA,4BAA4B,KAAK,UAAU,IAAI,CAAC;CAGpF,KAAK,MAAM,EAAE,MAAM,SAAS,WAC1B,GAAG,aAAA,GAAA,0BAAA,MAAA,CAAkB,UAAU,qBAAqB,IAAI,CAAC,GAAG,SAAS,GAAG;CAE1E,GAAG,WAAW,QAAQ;CAItB,GAAG,aAAA,GAAA,0BAAA,MAAA,CAAkB,WAAW,OAAO,GAAG,WAAW,QAAQ;CAE7D,OAAO;EAAE;EAAU;CAAK;AAC1B;;;;;;AAOA,SAAgB,wBACd,IACA,aACA,OACA,QACA,WACM;CACN,MAAM,aAAiC;EAAE;EAAQ;CAAU;CAC3D,MAAM,QAAQ,GAAG,gBAAgB,UAAU;CAC3C,GAAG,aAAA,GAAA,0BAAA,MAAA,CAAkB,aAAaC,sBAAAA,gBAAgB,KAAK,CAAC,GAAG,WAAW,KAAK;AAC7E;;;;;;AAWA,SAAgB,qBACd,IACA,UACA,SACA,UACM;CACN,MAAM,QAAQ,GAAG,gBAAgB,QAAQ;CACzC,GAAG,aAAA,GAAA,0BAAA,MAAA,CAAkB,UAAUC,sBAAAA,cAAc,OAAO,CAAC,GAAG,WAAW,KAAK;AAC1E;;;;;;;;;AAUA,eAAsB,6BACpB,IACA,aACA,gBACA,QAC6B;CAG7B,MAAM,gBAAe,MADS,GAAG,gBAAgB,gBAAgB,IAAI,EAAA,CAChC,OAAO,KAAK,MAAM,EAAE,KAAK,CAAC,CAAC,OAAOC,0BAAAA,yBAAyB;CAChG,MAAM,kBACJ,MAAM,QAAQ,IAAI,aAAa,KAAK,QAAQ,GAAG,cAA2B,KAAKL,sBAAAA,cAAc,CAAC,CAAC,EAAA,CAC/F,KAAK,MAAM,EAAE,KAAK;CAIpB,MAAM,cAAa,MADQ,GAAG,gBAAgB,aAAa,IAAI,EAAA,CAC/B,OAC7B,QAAQ,MAAM,uBAAuB,EAAE,IAAI,CAAC,CAAC,CAC7C,KAAK,MAAM,EAAE,KAAK,CAAC,CACnB,OAAOK,0BAAAA,yBAAyB;CAEnC,MAAM,UAA8B,CAAC;CACrC,KAAK,MAAM,aAAa,YAAY;EAClC,MAAM,aAAa,MAAM,GAAG,cAA2B,WAAWL,sBAAAA,cAAc;EAChF,MAAM,WAAW,SAAS,OAAO,WAAW,OAAO,cAAc,IAAI,WAAW;EAChF,eAAe,KAAK,QAAQ;EAK5B,MAAM,SAAS,MAAMC,gBAAAA,iBAAiB,IAAI,WAAW,EAAE,OAAO,SAAS,CAAC;EACxE,GAAG,aAAA,GAAA,0BAAA,MAAA,CAAkB,iBAAA,GAAA,YAAA,WAAA,CAA2B,CAAC,GAAG,WAAW,MAAM;EAErE,MAAM,YAAY,MAAM,OAAO;EAC/B,QAAQ,KAAK,SAAS;CACxB;CAEA,OAAO;AACT;;AAGA,SAAgB,qBAAqB,KAAmC;CACtE,OAAO,IAAI,KAAK,QAAA,GAAA,0BAAA,mBAAA,CAA0B,EAAE,CAAC;AAC/C"}