@milaboratories/pl-middle-layer 1.64.40 → 1.64.42

package/src/middle_layer/ops.ts

@@ -248,6 +248,11 @@ export type MiddleLayerOpsSettings = DriverKitOpsSettings & {
 
   /** Prioritize this channel if update is available in this block */
   readonly preferredUpdateChannel?: string;
+
+  /** Default lifetime applied to a targeted shared envelope at creation, as
+   * `sharedAt + envelopeTtlMs`. Share-with-everybody envelopes never expire
+   * (`expiresAt: null`) and ignore this. */
+  readonly envelopeTtlMs: number;
 };
 
 export type MiddleLayerOps = MiddleLayerOpsSettings & MiddleLayerOpsPaths;
@@ -260,6 +265,7 @@ export const DefaultMiddleLayerOpsSettings: Pick<
   | "projectRefreshInterval"
   | "devBlockUpdateRecheckInterval"
   | "debugOps"
+  | "envelopeTtlMs"
 > = {
   ...DefaultDriverKitOpsSettings,
   defaultTreeOptions: {
@@ -272,6 +278,7 @@ export const DefaultMiddleLayerOpsSettings: Pick<
   },
   devBlockUpdateRecheckInterval: 1000,
   projectRefreshInterval: 2000,
+  envelopeTtlMs: 14 * 24 * 3600 * 1000, // 14 days
 };
 
 export function DefaultMiddleLayerOpsPaths(

package/src/middle_layer/sharing_list.ts

@@ -0,0 +1,343 @@
+import type { PruningFunction } from "@milaboratories/pl-tree";
+import { SynchronizedTreeState } from "@milaboratories/pl-tree";
+import type { Filter, PlClient, SignedResourceId } from "@milaboratories/pl-client";
+import {
+  isEveryoneUserLogin,
+  resourceIdToString,
+  resourceType,
+  resourceTypesEqual,
+  treeFilter,
+} from "@milaboratories/pl-client";
+import { Computable } from "@milaboratories/computable";
+import type { MiddleLayerEnvironment } from "./middle_layer";
+import type { ProjectId } from "@milaboratories/pl-model-common";
+import type {
+  EnvelopeAcceptance,
+  EnvelopeData,
+  EnvelopeMode,
+  ShareId,
+} from "../model/sharing_model";
+import {
+  AcceptanceFieldPrefix,
+  asShareId,
+  SharedEnvelopeResourceType,
+  SharingOutboxResourceType,
+  SharingStateResourceType,
+} from "../model/sharing_model";
+
+/** Donor-facing view of one outgoing share. */
+export interface OutgoingShare {
+  shareId: ShareId; // stable logical identity of the share, preserved across changes
+  sharedAt: number; // this instance's creation time (ms epoch)
+  expiresAt?: number; // EnvelopeData.expiresAt; null maps to undefined = never expires
+  mode: EnvelopeMode;
+  title: string; // display name shown to recipients; defaults to the first project's name
+  /** One entry per project in the pack, so the change UI can offer a per-project decision.
+   *  `projectId` is the donor's source project id; `updatedAt` is when this project's
+   *  snapshot was last (re)taken. */
+  projects: { projectId: ProjectId; label: string; updatedAt: number }[];
+  /** Full recipient logins, from `ListGrants` on the envelope; `["*"]` for everyone-shares. */
+  recipients: string[];
+  /** Per recipient who has responded: their decision and when, from acceptance/{login}. */
+  responses: Record<string, { action: "accepted" | "rejected"; timestamp: number }>;
+}
+
+/** Per-project view for the donor's change UI, from {@link EnvelopeData.projects}. */
+function envelopeProjects(data: EnvelopeData): OutgoingShare["projects"] {
+  return Object.values(data.projects).map((p) => ({
+    projectId: p.source,
+    label: p.label,
+    updatedAt: p.updatedAt,
+  }));
+}
+
+/** Acceptor-facing view of one pending share. */
+export interface PendingShare {
+  shareId: ShareId;
+  sender: string; // EnvelopeData.sender, display only
+  title: string; // display name shown to recipients; defaults to the first project's name
+  mode: EnvelopeMode; // v1 renders only "copy" entries
+  grantedAt: number;
+}
+
+const SharingOutboxPruningFunction: PruningFunction = (resource) => {
+  if (
+    !resourceTypesEqual(resource.type, SharingOutboxResourceType) &&
+    !resourceTypesEqual(resource.type, SharedEnvelopeResourceType)
+  )
+    return [];
+  return resource.fields;
+};
+
+// Server-side traversal scope (modern resourceTree path). Pruning is client-side ONLY and does
+// NOT stop the backend walk — without a fieldFilter the backend descends through the envelope's
+// project/{uuid} snapshots into the whole project graph (StreamManager etc.), whose field-driven
+// finality predicate then throws on the pruned-to-[] fields. Following fields only FROM the outbox
+// and the envelope stops the walk at the project snapshots (UserProject), which we never traverse.
+const SharingOutboxFieldFilter: Filter = treeFilter.or(
+  treeFilter.resourceTypeEq(SharingOutboxResourceType.name),
+  treeFilter.resourceTypeEq(SharedEnvelopeResourceType.name),
+);
+
+/** Intermediate of an outgoing share before its full recipient list is fetched: everything the
+ *  tree carries synchronously, plus the envelope's signed id for the async `ListGrants` enrich. */
+type OutgoingShareDraft = Omit<OutgoingShare, "recipients"> & { envelopeRid: SignedResourceId };
+
+/**
+ * Reactive view of the donor's own outbox. Reads each live envelope's immutable
+ * {@link EnvelopeData} plus the per-recipient `acceptance/{login}` records from the tree, then
+ * enriches each share's full recipient list via `ListGrants` on the envelope (`["*"]` for an
+ * everyone-share). `ListGrants` is gated backend-side to the envelope owner (the donor), which is
+ * exactly who reads this view.
+ *
+ * API-level only in M1 (no UI).
+ */
+export function createOutgoingSharesComputable(
+  pl: PlClient,
+  tree: SynchronizedTreeState,
+): Computable<OutgoingShare[] | undefined> {
+  return Computable.make(
+    (ctx) => {
+      const node = ctx.accessor(tree.entry()).node();
+      if (node === undefined) return undefined;
+
+      const drafts: OutgoingShareDraft[] = [];
+      // Outbox fields are keyed by shareId; each value is a SharedEnvelope.
+      for (const fieldName of node.listDynamicFields()) {
+        const envelope = node.traverse(fieldName);
+        if (envelope === undefined) continue;
+        if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
+
+        const data = envelope.getDataAsJson<EnvelopeData>();
+        if (data === undefined) continue;
+
+        const responses: OutgoingShare["responses"] = {};
+        for (const f of envelope.listDynamicFields()) {
+          if (!f.startsWith(AcceptanceFieldPrefix)) continue;
+          const login = f.slice(AcceptanceFieldPrefix.length);
+          const acc = envelope.traverse(f);
+          const accData = acc?.getDataAsJson<EnvelopeAcceptance>();
+          if (accData === undefined) continue;
+          responses[login] = { action: accData.action, timestamp: accData.timestamp };
+        }
+
+        drafts.push({
+          shareId: data.shareId,
+          sharedAt: data.sharedAt,
+          ...(data.expiresAt !== null ? { expiresAt: data.expiresAt } : {}),
+          mode: data.mode,
+          title: data.title,
+          projects: envelopeProjects(data),
+          responses,
+          envelopeRid: envelope.id,
+        });
+      }
+      drafts.sort((a, b) => b.sharedAt - a.sharedAt);
+      return drafts;
+    },
+    {
+      // Resolve each share's recipients via listGrants. An everyone-grant maps to "*"; the donor's
+      // own grant is dropped. One tx per envelope so a just-revoked rid faults only its own read,
+      // which allSettled degrades to []. Recipients aren't cached — a live share's recipient set can
+      // change. Transactional listGrants when available, else the standalone gRPC-only RPC.
+      postprocessValue: async (
+        drafts: OutgoingShareDraft[] | undefined,
+      ): Promise<OutgoingShare[] | undefined> => {
+        if (drafts === undefined) return undefined;
+        const self = pl.userResources.authUser;
+        const toRecipients = (grants: { user: string }[]): string[] =>
+          grants.some((g) => isEveryoneUserLogin(g.user))
+            ? ["*"]
+            : grants.map((g) => g.user).filter((u) => u !== self);
+
+        const txGrants = pl.hasCapability("txListGrants:v1");
+        const settled = await Promise.allSettled(
+          drafts.map((d) =>
+            txGrants
+              ? pl.withReadTx("ListShareGrant", (tx) => tx.listGrants(d.envelopeRid))
+              : pl.userResources.listGrants(d.envelopeRid),
+          ),
+        );
+
+        return drafts.map(({ envelopeRid: _envelopeRid, ...share }, i): OutgoingShare => {
+          const r = settled[i];
+          return { ...share, recipients: r.status === "fulfilled" ? toRecipients(r.value) : [] };
+        });
+      },
+    },
+  );
+}
+
+/**
+ * Creates the donor's outbox synchronized tree (single explicit root) plus the
+ * {@link OutgoingShare} computable over it.
+ */
+export async function createOutgoingShares(
+  pl: PlClient,
+  outboxRid: SignedResourceId,
+  env: MiddleLayerEnvironment,
+): Promise<{ tree: SynchronizedTreeState; computable: Computable<OutgoingShare[] | undefined> }> {
+  const tree = await SynchronizedTreeState.init(
+    pl,
+    outboxRid,
+    {
+      ...env.ops.defaultTreeOptions,
+      pruning: SharingOutboxPruningFunction,
+      fieldFilter: SharingOutboxFieldFilter,
+    },
+    env.logger,
+  );
+  return { computable: createOutgoingSharesComputable(pl, tree), tree };
+}
+
+const DecisionFieldPrefix = "decision/";
+
+const SharedEnvelopePruningFunction: PruningFunction = (resource) => {
+  if (!resourceTypesEqual(resource.type, SharedEnvelopeResourceType)) return [];
+  return resource.fields;
+};
+
+// Discovery only needs each envelope's immutable EnvelopeData (basic resource data); it must NOT
+// descend into the project snapshots. Following fields only FROM the envelope stops the walk at
+// the UserProject snapshots (their fields are never followed).
+const PendingSharesFieldFilter: Filter = treeFilter.resourceTypeEq(SharedEnvelopeResourceType.name);
+
+/**
+ * Creates the acceptor's shared-resource discovery tree (a `{kind:'shared'}` seed over
+ * {@link SharedEnvelopeResourceType}) plus the {@link PendingShare} computable over it.
+ *
+ * An envelope surfaces only when its shareId has NO decision/{shareId} on SharingState —
+ * the dedup is applied by the caller, which holds the SharingState tree.
+ */
+export async function createPendingSharesTree(
+  pl: PlClient,
+  env: MiddleLayerEnvironment,
+): Promise<SynchronizedTreeState> {
+  return await SynchronizedTreeState.init(
+    pl,
+    {
+      kind: "shared",
+      resourceType: resourceType(
+        SharedEnvelopeResourceType.name,
+        SharedEnvelopeResourceType.version,
+      ),
+    },
+    {
+      ...env.ops.defaultTreeOptions,
+      pruning: SharedEnvelopePruningFunction,
+      fieldFilter: PendingSharesFieldFilter,
+    },
+    env.logger,
+  );
+}
+
+/** A live envelope discovered in the acceptor's shared-resource tree: its signed resource id and
+ *  decoded {@link EnvelopeData}. The accept/reject flow keys these by `data.shareId`. */
+export type LiveEnvelope = { rid: SignedResourceId; data: EnvelopeData };
+
+/**
+ * Builds a Computable yielding the acceptor's currently-live envelopes, read from the
+ * shared-resource discovery tree the ML already maintains — the single discovery mechanism.
+ * Accept/reject `.getValue()` this instead of re-streaming `ListUserResources`, so there is no
+ * second discovery path. The envelope's signed `rid` (from the tree node) is what the write tx
+ * needs; `copyEnvelopeProjectsIntoList` reads the project snapshots itself inside the tx.
+ *
+ * Returns `undefined` while the tree is still empty/unresolved (mirrors the other tree-backed
+ * computables here). Yields a flat list; the caller dedups by `shareId` — at most one live
+ * envelope per shareId is expected (the donor keeps one), and a replace tears the old one down.
+ */
+export function createLiveEnvelopesComputable(
+  sharedTree: SynchronizedTreeState,
+): Computable<LiveEnvelope[] | undefined> {
+  return Computable.make((ctx) => {
+    const roots = ctx.accessor(sharedTree.rootsEntry()).nodes();
+    const result: LiveEnvelope[] = [];
+    for (const envelope of roots) {
+      if (envelope === undefined) continue;
+      if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
+      const data = envelope.getDataAsJson<EnvelopeData>();
+      if (data === undefined) continue;
+      result.push({ rid: envelope.id, data });
+    }
+    return result;
+  });
+}
+
+/**
+ * Builds the {@link PendingShare} computable over the shared-resource discovery tree, filtered
+ * against the set of already-handled shareIds (those with a decision/{shareId} in the acceptor's
+ * SharingState). Both trees feed one Computable so it recomputes when either changes.
+ *
+ * `currentUserLogin` (when known) suppresses the user's own shares: a share-with-everybody grants
+ * the everyone-user, so the donor discovers their own envelope as a pending share. There is no
+ * scenario where a user accepts their own share, so they are dropped from the pending view.
+ */
+export function createPendingSharesComputable(
+  sharedTree: SynchronizedTreeState,
+  sharingStateTree: SynchronizedTreeState,
+  currentUserLogin: string | null,
+): Computable<PendingShare[] | undefined> {
+  return Computable.make((ctx) => {
+    const roots = ctx.accessor(sharedTree.rootsEntry()).nodes();
+
+    // Set of shareIds already handled (accepted or rejected) — dedup discovery on the logical share.
+    const stateNode = ctx.accessor(sharingStateTree.entry()).node();
+    const handled = new Set<ShareId>();
+    if (stateNode !== undefined)
+      for (const f of stateNode.listDynamicFields())
+        if (f.startsWith(DecisionFieldPrefix))
+          handled.add(asShareId(f.slice(DecisionFieldPrefix.length)));
+
+    const result: PendingShare[] = [];
+    for (const envelope of roots) {
+      if (envelope === undefined) continue;
+      if (!resourceTypesEqual(envelope.resourceType, SharedEnvelopeResourceType)) continue;
+      const data = envelope.getDataAsJson<EnvelopeData>();
+      if (data === undefined) continue;
+      if (handled.has(data.shareId)) continue; // already accepted or rejected
+      if (currentUserLogin !== null && data.sender === currentUserLogin) continue; // own share
+      if (data.expiresAt !== null && data.expiresAt <= Date.now()) continue;
+
+      result.push({
+        shareId: data.shareId,
+        sender: data.sender,
+        title: data.title,
+        mode: data.mode,
+        grantedAt: data.sharedAt,
+      });
+    }
+    result.sort((a, b) => b.grantedAt - a.grantedAt);
+    return result;
+  });
+}
+
+const SharingStatePruningFunction: PruningFunction = (resource) => {
+  if (!resourceTypesEqual(resource.type, SharingStateResourceType)) return [];
+  return resource.fields;
+};
+
+// decision/{shareId} values are leaf JSON resources; follow fields only from SharingState.
+const SharingStateFieldFilter: Filter = treeFilter.resourceTypeEq(SharingStateResourceType.name);
+
+/** Creates the acceptor's SharingState synchronized tree (single explicit root). */
+export async function createSharingStateTree(
+  pl: PlClient,
+  stateRid: SignedResourceId,
+  env: MiddleLayerEnvironment,
+): Promise<SynchronizedTreeState> {
+  return await SynchronizedTreeState.init(
+    pl,
+    stateRid,
+    {
+      ...env.ops.defaultTreeOptions,
+      pruning: SharingStatePruningFunction,
+      fieldFilter: SharingStateFieldFilter,
+    },
+    env.logger,
+  );
+}
+
+/** Maps an envelope resource id (signed) to its string form, for failure reporting. */
+export function envelopeIdString(rid: SignedResourceId): string {
+  return resourceIdToString(rid);
+}

package/src/model/index.ts

@@ -12,3 +12,5 @@ export {
   BlockArgsAuthorKeyPrefix,
   ProjectStructureAuthorKey,
 } from "./project_model";
+
+export * from "./sharing_model";

package/src/model/sharing_model.ts

@@ -0,0 +1,150 @@
+import type { ResourceType, Role } from "@milaboratories/pl-client";
+import { Role as RoleEnum } from "@milaboratories/pl-client";
+import type { Branded, ProjectId } from "@milaboratories/pl-model-common";
+import { randomUUID } from "node:crypto";
+
+/**
+ * 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.
+ */
+export type ShareId = Branded<string, "ShareId">;
+
+/** Mints a fresh {@link ShareId}. The single place a share's logical identity is created. */
+export function newShareId(): ShareId {
+  return randomUUID() as 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. */
+export function asShareId(id: string): ShareId {
+  return id as ShareId;
+}
+
+//
+// Pl Model — Project Sharing
+//
+// All sharing structures are defined and managed by the middle layer; the
+// backend knows nothing about envelopes.
+//
+
+/** Field on the donor's clientRoot holding the {@link SharingOutboxResourceType} resource. */
+export const SharingOutboxField = "sharingOutbox";
+/** Field on the acceptor's clientRoot holding the {@link SharingStateResourceType} resource. */
+export const SharingStateField = "sharingState";
+
+export const SharingOutboxResourceType: ResourceType = { name: "SharingOutbox", version: "1" };
+export const SharedEnvelopeResourceType: ResourceType = { name: "SharedEnvelope", version: "1" };
+export const SharingStateResourceType: ResourceType = { name: "SharingState", version: "1" };
+
+export 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"). */
+export 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. */
+export 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.
+ */
+export function canGrantToEveryone(role: Role | null): boolean {
+  switch (role) {
+    case RoleEnum.CONTROLLER:
+    case RoleEnum.ADMIN:
+    case RoleEnum.USER:
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** One project's snapshot inside an envelope, keyed by {@link ProjectFieldUuid} in {@link EnvelopeData.projects}. */
+export interface EnvelopeProject {
+  label: string; // carried so the pending-share UI renders without traversing into the project
+  source: ProjectId; // donor's source projectId; supersedes a prior share and matches the snapshot to its live source on change
+  updatedAt: number; // ms epoch of the last (re)snapshot
+}
+
+/** Immutable `data` on a SharedEnvelope, set at createEphemeral, never mutated. */
+export interface EnvelopeData {
+  schemaVersion: 1;
+  shareId: ShareId; // donor-generated UUID; logical share identity, stable across changes
+  sharedAt: number; // ms epoch; this instance's creation time — distinguishes instances of one shareId
+  expiresAt: number | null; // ms epoch; sharedAt + ttl (default 14 days) for a targeted share; null for share-with-everybody (never expires)
+  mode: EnvelopeMode; // what the acceptor's app should do with the contents
+  sender: string; // donor login (informational; backend granted_by is authoritative)
+  title: string; // display name shown to recipients; defaults to the first project's name
+  projects: Record<ProjectFieldUuid, EnvelopeProject>; // contained projects, keyed by project field uuid
+}
+
+/** Dynamic field on SharingState, one per handled share, keyed by shareId. */
+export const decisionField = (shareId: ShareId) => `decision/${shareId}`;
+
+export interface SharingDecision {
+  decision: "accepted" | "rejected";
+  timestamp: number; // ms epoch — when the acceptor acted
+  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)
+  acceptedProjects: string[]; // ids of the projects created in the acceptor's list ([] for a rejected share)
+}
+
+/** 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. */
+export const AcceptanceFieldPrefix = "acceptance/";
+export const acceptanceField = (login: string) => `${AcceptanceFieldPrefix}${login}`;
+export const isAcceptanceField = (name: string) => name.startsWith(AcceptanceFieldPrefix);
+export const acceptanceFieldLogin = (name: string) => name.slice(AcceptanceFieldPrefix.length);
+
+export interface EnvelopeAcceptance {
+  action: "accepted" | "rejected";
+  timestamp: number; // ms since epoch
+}
+
+/**
+ * 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.
+ */
+export function decodeEnvelopeData(data: Uint8Array): EnvelopeData {
+  return JSON.parse(Buffer.from(data).toString("utf-8")) as 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.
+ */
+export type ShareProjectsOptions =
+  | {
+      recipients: string[]; // recipient logins
+      title: string; // display name shown to recipients; defaults to the first project's name
+      mode: EnvelopeMode; // v1 UI always sends "copy"
+    }
+  | {
+      everyone: true; // share with all users on the server
+      /**
+       * 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;
+    };