@milaboratories/pl-client 3.12.0 → 3.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-client",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "New TS/JS client for Platform API",
   "files": [
     "./dist/**/*",
@@ -30,7 +30,7 @@
     "undici": "~7.16.0",
     "utility-types": "^3.11.0",
     "yaml": "^2.8.0",
-    "@milaboratories/pl-model-common": "1.46.2",
+    "@milaboratories/pl-model-common": "1.46.3",
     "@milaboratories/pl-http": "1.2.4",
     "@milaboratories/ts-helpers": "1.8.3"
   },
@@ -41,9 +41,9 @@
     "openapi-typescript": "^7.10.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
-    "@milaboratories/build-configs": "2.0.0",
     "@milaboratories/ts-builder": "1.6.0",
-    "@milaboratories/ts-configs": "1.3.0"
+    "@milaboratories/ts-configs": "1.3.0",
+    "@milaboratories/build-configs": "2.0.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/core/capabilities.ts

@@ -5,8 +5,7 @@
  * to detect incompatibilities between blocks and backend via
  * via `TemplateDataV3.requiredCapabilities`.
  *
- * Mirror of `pl/platform/api/plapiserver/server_capabilities.go` — keep
- * tokens in sync with the backend's advertised list. Format is
+ * Keep tokens in sync with the backend's advertised list. Format is
  * `<feature>:<version>`; bump the version when wire semantics change.
  *
  * Shared across:
@@ -15,7 +14,15 @@
  *   - `@platforma-sdk/block-tools`       — copies it onto the published manifest
  *   - `@milaboratories/pl-middle-layer`  — checks it at install time
  */
-export type BackendCapability = "auth:v2" | "treeFilter:v2" | "wasm:v1";
+export type BackendCapability =
+  | "auth:v2"
+  | "treeFilter:v2"
+  | "wasm:v1"
+  // Project-sharing capability tokens.
+  | "crossTreeRefs:v1" // cross-color field attach (accept a foreign-colored shared envelope)
+  | "userListing:v1" // list users for the recipient picker
+  | "publicGrants:v1" // public (everyone) grants allowed for any role
+  | "txListGrants:v1"; // list grants inside a transaction (batched recipient reads)
 
 /** True iff `capabilities` advertises the requested token. */
 export function hasCapability(

package/src/core/client.ts

@@ -2,6 +2,7 @@ import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol
 import type { PlCallOps } from "./ll_client";
 import { LLPlClient } from "./ll_client";
 import { PlTransaction, TxCommitConflict } from "./transaction";
+import type { Role } from "./transaction";
 import type { OptionalSignedResourceId, SignedResourceId } from "./types";
 import {
   ensureSignedResourceIdNotNull,
@@ -80,6 +81,11 @@ export class PlClient {
 
   private _userResources?: UserResources;
 
+  /** Cached effective role of the authenticated session, fetched once during
+   *  init via the GetSessionInfo RPC. `null` for an anonymous (no-auth)
+   *  connection — mirrors {@link authUser}. Read through {@link currentUserRole}. */
+  private _currentUserRole: Role | null = null;
+
   private _txCommittedStat: TxStat = initialTxStat();
   private _txConflictStat: TxStat = initialTxStat();
   private _txErrorStat: TxStat = initialTxStat();
@@ -106,6 +112,15 @@ export class PlClient {
     const conf =
       typeof configOrAddress === "string" ? plAddressToConfig(configOrAddress) : configOrAddress;
 
+    // An empty or whitespace-only asUser means "no impersonation"; normalize to undefined so a
+    // directly-constructed { asUser: "" } does not slip through as an empty login.
+    if (conf.asUser !== undefined && conf.asUser.trim() === "") conf.asUser = undefined;
+
+    // asUser (impersonation) and alternativeRoot both repoint the client root, so they cannot be
+    // combined. Validate here, before init() touches the network, so a misconfiguration fails fast.
+    if (conf.asUser !== undefined && conf.alternativeRoot !== undefined)
+      throw new Error("PlClient: asUser and alternativeRoot cannot be combined.");
+
     this.buildLLPlClient = async (
       shouldUseGzip: boolean,
       wireProtocol?: wireProtocol,
@@ -232,10 +247,24 @@ export class PlClient {
     return this._ll!.hasCapability(capability);
   }
 
+  /** Effective role of the authenticated session, resolved once during init via
+   *  the GetSessionInfo RPC and cached. `null` for an anonymous (no-auth)
+   *  connection, or when the backend predates GetSessionInfo. Mirrors
+   *  {@link authUser}'s null contract. */
+  public get currentUserRole(): Role | null {
+    this.checkInitialized();
+    return this._currentUserRole;
+  }
+
+  /** Login of the authenticated user, or `null` for an anonymous connection. */
+  public get authUser(): string | null {
+    this.checkInitialized();
+    return this.userResources.authUser;
+  }
+
   /**
-   * True if the backend honors per-file `permissions` on workdir fill rules
-   * (PR #1830 in milaboratory/pl). See `LLPlClient.supportsWritableWorkdirFiles`
-   * for the full definition.
+   * True if the backend honors per-file `permissions` on workdir fill rules.
+   * See {@link LLPlClient.supportsWritableWorkdirFiles} for the full definition.
    */
   public get supportsWritableWorkdirFiles(): boolean {
     this.checkInitialized();
@@ -274,7 +303,27 @@ export class PlClient {
       this._ll = await this.buildLLPlClient(true, wireProtocol);
     }
 
-    const userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });
+    // Resolve the client root. Normally the caller's own root; when `asUser` is set (admin impersonation),
+    // the target user's root instead. The backend authorizes impersonation by role and silently returns the
+    // caller's own root for non-admins, so no client-side role gate is needed here.
+    let userRoot: SignedResourceId;
+    if (this.conf.asUser === undefined) {
+      userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });
+    } else {
+      const impersonatedRoot = await this.userResources.getUserRoot({ login: this.conf.asUser });
+      if (impersonatedRoot === undefined)
+        throw new Error(
+          `PlClient: cannot open root of user '${this.conf.asUser}': no root found (the user may have never logged in).`,
+        );
+      userRoot = impersonatedRoot;
+    }
+
+    // Resolve the caller's role once; only the publicGrants-gated share-with-everybody check uses it,
+    // so skip it for anonymous connections or when publicGrants:v1 is absent. Use _ll.hasCapability,
+    // not this.hasCapability: we are mid-init, so this.checkInitialized() would throw.
+    if (this.userResources.authUser !== null && this._ll.hasCapability("publicGrants:v1")) {
+      this._currentUserRole = (await this._ll.getSessionInfo()).role;
+    }
 
     if (this.conf.alternativeRoot === undefined) {
       this._clientRoot = userRoot;
@@ -421,6 +470,22 @@ export class PlClient {
     return await this.withTx(name, true, body, { ...ops, ...defaultTxOps });
   }
 
+  /**
+   * Runs a write transaction whose default color is `root`'s signature instead of the client
+   * root's, and whose `tx.clientRoot` is `root`. For admin cross-root operations (e.g. copying a
+   * project into another user's root so the copy is minted in that user's color). The backend
+   * still authorizes the write by role.
+   */
+  public async withWriteTxOnRoot<T>(
+    root: SignedResourceId,
+    name: string,
+    body: (tx: PlTransaction) => Promise<T>,
+    ops: Partial<TxOps> = {},
+  ): Promise<T> {
+    this.checkInitialized();
+    return await this._withTx(name, true, root, body, { ...ops, ...defaultTxOps });
+  }
+
   public async withReadTx<T>(
     name: string,
     body: (tx: PlTransaction) => Promise<T>,

package/src/core/config.test.ts

@@ -73,6 +73,21 @@ test("should retain non-default port for https URL", () => {
   expect(config.ssl).toBe(true);
 });
 
+test("asUser is undefined when as-user param is absent", () => {
+  const conf = plAddressToConfig("http://127.0.0.1:6345");
+  expect(conf.asUser).toBeUndefined();
+});
+
+test("asUser is undefined when as-user param is empty", () => {
+  const conf = plAddressToConfig("http://127.0.0.1:6345/?as-user=");
+  expect(conf.asUser).toBeUndefined();
+});
+
+test("asUser is parsed from the as-user url param", () => {
+  const conf = plAddressToConfig("http://127.0.0.1:6345/?as-user=alice");
+  expect(conf.asUser).toEqual("alice");
+});
+
 test("should throw an error for grpc URL without an explicit port", () => {
   expect(() => plAddressToConfig("grpc://example.com")).toThrow(
     "Port must be specified explicitly for grpc: protocol.",

package/src/core/config.ts

@@ -16,6 +16,11 @@ export interface PlClientConfig {
    * client root. */
   alternativeRoot?: string;
 
+  /** Admin-only impersonation: if set, the client opens the root of the user with this login instead of the
+   * caller's own root. The backend authorizes this by role and silently falls back to the caller's own root for
+   * regular users, so it is safe without a client-side gate. Mutually exclusive with {@link alternativeRoot}. */
+  asUser?: string;
+
   /** If true, client will establish tls connection to the server, using default
    * CA of node instance. */
   // Not implementing custom ssl validation logic for now.
@@ -190,6 +195,7 @@ export function plAddressToConfig(
   return {
     hostAndPort: `${url.hostname}:${port}`,
     alternativeRoot: url.searchParams.get("alternative-root") ?? undefined,
+    asUser: url.searchParams.get("as-user") || undefined,
     ssl: url.protocol === "https:" || url.protocol === "tls:",
 
     wireProtocol: (url.searchParams.get("wire-protocol") as wireProtocol) ?? undefined,

package/src/core/errors.ts

@@ -20,6 +20,8 @@ export function isUnauthenticated(err: unknown, nested: boolean = false): boolea
   if ((err as any).name == "RpcError" && (err as any).code == "UNAUTHENTICATED") return true;
   if ((err as any).name == "RESTError" && (err as any).status.code == Code.UNAUTHENTICATED)
     return true;
+  // PlError (e.g. UnrecoverablePlError from a failed streaming tx) carries the status code numerically.
+  if (err instanceof PlError && err.status?.code === Code.UNAUTHENTICATED) return true;
   if ((err as any).cause !== undefined && !nested)
     return isUnauthenticated((err as any).cause, true);
   return false;

package/src/core/final.ts

@@ -87,6 +87,10 @@ export const DefaultFinalResourceDataPredicate: FinalResourceDataPredicate = (r)
     case ResourceTypeName.UserProject:
     case ResourceTypeName.Projects:
     case ResourceTypeName.ClientRoot:
+    // Never final — these sharing resources gain and lose dynamic child fields over their lifetime.
+    case ResourceTypeName.SharingOutbox:
+    case ResourceTypeName.SharingState:
+    case ResourceTypeName.SharedEnvelope:
       return false;
     default:
       if (

package/src/core/ll_client.test.ts

@@ -50,7 +50,15 @@ test("unauthenticated status change", async () => {
     return;
   }
 
-  const client = await LLPlClient.build(plAddressToTestConfig(cfg.address));
+  // The flip to Unauthenticated is async, so await it via the status listener.
+  let onUnauthenticated!: () => void;
+  const unauthenticated = new Promise<void>((resolve) => (onUnauthenticated = resolve));
+
+  const client = await LLPlClient.build(plAddressToTestConfig(cfg.address), {
+    statusListener: (s) => {
+      if (s === "Unauthenticated") onUnauthenticated();
+    },
+  });
   expect(client.status).toBe("OK");
 
   const tx = client.createTx(true);
@@ -73,7 +81,12 @@ test("unauthenticated status change", async () => {
     await tx.await();
   }).rejects.toThrow(UnauthenticatedError);
 
-  await tp.setImmediate();
+  await Promise.race([
+    unauthenticated,
+    tp
+      .setTimeout(5000)
+      .then(() => Promise.reject(new Error("status never became Unauthenticated"))),
+  ]);
 
   expect(client.status).toEqual("Unauthenticated");
 });

package/src/core/ll_client.ts

@@ -42,7 +42,7 @@ import {
   TxAPI_ServerMessage,
 } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
 import type { MiLogger } from "@milaboratories/ts-helpers";
-import { isAbortedError } from "./errors";
+import { isAbortedError, isUnauthenticated } from "./errors";
 import { Timestamp } from "../proto-grpc/google/protobuf/timestamp";
 
 export interface PlCallOps {
@@ -122,6 +122,7 @@ export class LLPlClient implements WireClientProviderFactory {
   private _authMethodsSync?: grpcTypes.AuthAPI_ListMethods_Response;
 
   private _status: PlConnectionStatus = "OK";
+  private authProbeInFlight = false;
   private readonly statusListener?: PlConnectionStatusListener;
 
   private _wireProto: wireProtocol = "grpc";
@@ -393,6 +394,25 @@ export class LLPlClient implements WireClientProviderFactory {
     });
   }
 
+  /**
+   * UNAUTHENTICATED covers both a dead session (must reset) and a per-request authorization failure
+   * such as a revoked resource signature (must not). Disambiguate by probing getSessionInfo — an
+   * authenticated call with no resource signature: success means the session is alive and the failure
+   * was resource-level; a probe that is itself Unauthenticated means real auth loss. Coalesced via
+   * authProbeInFlight so a burst of failures costs one probe.
+   */
+  private async verifyThenMaybeEscalateUnauthenticated(): Promise<void> {
+    if (this._status !== "OK" || this.authProbeInFlight) return;
+    this.authProbeInFlight = true;
+    try {
+      await this.getSessionInfo();
+    } catch (e) {
+      if (isUnauthenticated(e)) this.updateStatus("Unauthenticated");
+    } finally {
+      this.authProbeInFlight = false;
+    }
+  }
+
   public get status(): PlConnectionStatus {
     return this._status;
   }
@@ -458,7 +478,7 @@ export class LLPlClient implements WireClientProviderFactory {
         }
 
         if (respErr.error.code === Code.UNAUTHENTICATED) {
-          this.updateStatus("Unauthenticated");
+          void this.verifyThenMaybeEscalateUnauthenticated();
         }
 
         // Let later middleware to deal with standard gRPC error.
@@ -476,7 +496,7 @@ export class LLPlClient implements WireClientProviderFactory {
             onReceiveStatus: (status, next) => {
               if (status.code == GrpcStatus.UNAUTHENTICATED)
                 // (!!!) don't change to "==="
-                this.updateStatus("Unauthenticated");
+                void this.verifyThenMaybeEscalateUnauthenticated();
               if (status.code == GrpcStatus.UNAVAILABLE)
                 // (!!!) don't change to "==="
                 this.updateStatus("Disconnected");
@@ -742,13 +762,12 @@ export class LLPlClient implements WireClientProviderFactory {
   }
 
   /**
-   * True if the backend honors per-file `permissions` on workdir fill rules
-   * (PR #1830 in milaboratory/pl). Backends before this change ignore the
-   * requested mode and always land files at the canonical archive perm,
-   * making `exec.builder().writeFile/addFile({ writable: true })` a no-op.
+   * True if the backend honors per-file `permissions` on workdir fill rules, so
+   * `exec.builder().writeFile/addFile({ writable: true })` takes effect. When false
+   * the requested mode is ignored and files land at the canonical archive perm.
    *
-   * Tagged at 3.5.0 cut without the change, so [3, 5, 0] excludes the tagged
-   * release but includes dev builds past the tag (e.g. "3.5.0-224-g0ca182").
+   * [3, 5, 0] excludes the tagged 3.5.0 release but includes dev builds past the
+   * tag (e.g. "3.5.0-224-g0ca182"), which is where the support lands.
    */
   public get supportsWritableWorkdirFiles(): boolean {
     return isAfterVersion(this.serverInfo.coreVersion, [3, 5, 0]);
@@ -931,6 +950,37 @@ export class LLPlClient implements WireClientProviderFactory {
     return responses;
   }
 
+  /** Returns the authenticated caller's session id and effective role.
+   *  Models the {@link getUserRoot} wrapper: gRPC unary with a REST fallback. */
+  public async getSessionInfo(): Promise<grpcTypes.AuthAPI_GetSessionInfo_Response> {
+    const cl = this.clientProvider.get();
+    if (cl instanceof GrpcPlApiClient) {
+      return (await cl.getSessionInfo({})).response;
+    } else {
+      const resp = notEmpty(
+        (await cl.POST("/v1/auth/session-info", { body: {} })).data,
+        "REST: empty response for getSessionInfo request",
+      );
+      return {
+        sessionId: Uint8Array.from(Buffer.from(resp.sessionId, "base64")),
+        role: resp.role as AuthAPI_Role,
+      };
+    }
+  }
+
+  /** Lists the users known to the server — the recipient picker's source. A user
+   *  becomes known on first login; provisioned users who have never logged in do not
+   *  appear. gRPC-only (unary, no REST binding). */
+  public async listUsers(): Promise<grpcTypes.AuthAPI_User[]> {
+    const cl = this.clientProvider.get();
+
+    if (!(cl instanceof GrpcPlApiClient)) {
+      throw new Error("ListUsers requires gRPC wire protocol; REST is not supported");
+    }
+
+    return (await cl.listUsers({})).response.users;
+  }
+
   public async txSync(txId: bigint): Promise<void> {
     const cl = this.clientProvider.get();
     if (cl instanceof GrpcPlApiClient) {

package/src/core/transaction.ts

@@ -1,5 +1,3 @@
-// TODO: fix this
-/* eslint-disable no-prototype-builtins */
 import type {
   ColorProof,
   LocalResourceId,
@@ -31,10 +29,15 @@ import type {
   ServerMessageResponse,
 } from "./ll_transaction";
 import type {
+  AuthAPI_Grant,
   ResourceAPI_Tree_Filter,
   ResourceAPI_Tree_SeedResource,
 } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
-import { TxAPI_Open_Request_WritableTx } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
+import {
+  TxAPI_Open_Request_WritableTx,
+  AuthAPI_GrantAccess_GrantType,
+  AuthAPI_Role,
+} from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
 import type { NonUndefined } from "utility-types";
 import { toBytes } from "../util/util";
 import {
@@ -155,6 +158,42 @@ export interface ResourceIdWithSignature {
   resourceSignature: ResourceSignature;
 }
 
+/** Access level handed to a grant recipient (see {@link PlTransaction.grantAccess}). */
+export interface GrantPermissions {
+  /** Write access = ability to modify the resource subtree + re-share it. */
+  writable: boolean;
+}
+
+/**
+ * Distinguishes a regular user-to-user grant from a system-level public grant.
+ * Re-export of the wire enum so callers need not reach into the generated proto.
+ */
+export const GrantType = AuthAPI_GrantAccess_GrantType;
+export type GrantType = AuthAPI_GrantAccess_GrantType;
+
+/**
+ * Effective role of an authenticated session (controller / workflow / user / admin).
+ * Re-export of the wire enum so callers need not reach into the generated proto.
+ * Returned by {@link LLPlClient.getSessionInfo} and surfaced as
+ * {@link PlClient.currentUserRole}.
+ */
+export const Role = AuthAPI_Role;
+export type Role = AuthAPI_Role;
+
+/**
+ * Recognises the "all users on the server" sentinel login. A public
+ * ({@link GrantType.ANY_AUTHORISED}) grant is recorded against a reserved login, and
+ * recipients of an everyone-grant surface in `ListGrants` with that value — callers
+ * detect it here and map it to "*".
+ *
+ * Matched by exact token equality. The long random token guarantees no real user login
+ * collides with it.
+ */
+const EveryoneUser = "everyone-Po9ahwahxai7Aejingaiyiequuecu3ei4moaNge4xahTh0Co7XeeLeiph6ahy3As";
+export function isEveryoneUserLogin(login: string): boolean {
+  return login === EveryoneUser;
+}
+
 const emptySignature = toResourceSignature(new Uint8Array(0));
 
 function toResourceIdAndSignature(ref: AnyResourceRef): ResourceIdWithSignature {
@@ -817,6 +856,67 @@ export class PlTransaction {
     });
   }
 
+  /**
+   * Grant another user access to a resource (and its subtree). Used by the
+   * project-sharing donor flow to hand a recipient the shared envelope.
+   *
+   * `grantType` defaults to a regular user-to-user grant
+   * ({@link GrantType.SINGLE_USER}); pass {@link GrantType.ANY_AUTHORISED}
+   * to make the resource public to everyone (requires backend `publicGrants:v1`
+   * and a role allowed to grant to everyone — `target` is ignored / rewritten
+   * to the everyone-user by the backend).
+   */
+  public grantAccess(
+    rId: AnyResourceRef,
+    target: string,
+    permissions: GrantPermissions,
+    grantType: GrantType = AuthAPI_GrantAccess_GrantType.SINGLE_USER,
+  ): void {
+    this.sendVoidAsync({
+      oneofKind: "grantAccess",
+      grantAccess: {
+        ...this.toSignedResourceId(rId),
+        targetUser: target,
+        permissions,
+        grantType,
+      },
+    });
+  }
+
+  /**
+   * Revoke a single user's grant on a resource — the inverse of {@link grantAccess}.
+   * Used by the sharing donor flow to pull one recipient out of a multi-recipient
+   * envelope without tearing the whole share down. A no-op on the backend if the user
+   * has no grant.
+   */
+  public revokeAccess(rId: AnyResourceRef, target: string): void {
+    this.sendVoidAsync({
+      oneofKind: "revokeAccess",
+      revokeAccess: {
+        ...this.toSignedResourceId(rId),
+        targetUser: target,
+      },
+    });
+  }
+
+  /**
+   * Enumerate the grants of a resource — the donor-side "who did I share with" view.
+   * The backend gates this on the signed, writable resource handle, so only the
+   * resource's owner can read its grants. Recipients of a public
+   * ({@link GrantType.ANY_AUTHORISED}) grant surface with `user` matching the
+   * everyone-sentinel — test with {@link isEveryoneUserLogin}.
+   *
+   * Transactional unary op (single response with all grants), so it rides the tx
+   * channel and works on every wire protocol — unlike the standalone server-streaming
+   * `ListGrants` RPC, which has no REST binding.
+   */
+  public listGrants(rId: AnyResourceRef): Promise<AuthAPI_Grant[]> {
+    return this.sendSingleAndParse(
+      { oneofKind: "listGrants", listGrants: this.toSignedResourceId(rId) },
+      (r) => r.listGrants.grants,
+    );
+  }
+
   //
   // Fields
   //

package/src/core/user_resources.ts

@@ -16,6 +16,26 @@ const AnonymousClientRoot = "AnonymousRoot";
 const LsStorageTypePrefix = "LS/"; // implements ls API in particular storage
 const LsProviderFieldPrefix = "storage/"; // provides access to storages list
 
+/** One recipient of a resource, as returned by {@link UserResources.listGrants}. */
+export interface GrantEntry {
+  /** Login the grant targets. An everyone-grant surfaces here as the backend's
+   *  everyone-sentinel — test with {@link isEveryoneUserLogin} (from "./transaction"); callers
+   *  map it to "*". */
+  readonly user: string;
+  /** True for a writable grant (copy / collaboration), false for read-only. */
+  readonly writable: boolean;
+  /** Login of the user who created the grant. */
+  readonly grantedBy: string;
+  /** When the grant was created (ms epoch). */
+  readonly grantedAt: number;
+}
+
+/** One user known to the server, as returned by {@link UserResources.listUsers}. */
+export interface UserEntry {
+  /** Stable identifier of the user; the grant target and `GetUserRoot` key. */
+  readonly login: string;
+}
+
 /** Information about a single data library (LS storage). */
 export interface StorageInfo {
   /** Machine-stable identifier, e.g. "library". Used for filtering and map keys. */
@@ -172,6 +192,71 @@ export class UserResources {
     return await this.getDataLibrariesViaLegacy();
   }
 
+  /**
+   * Discovers shared resources of a given type granted to the user, as signed resource ids.
+   *
+   * The public, type-filtered form of {@link getDataLibrariesViaList}: it polls the
+   * `ListUserResources` gRPC stream and returns every `sharedResource` entry whose
+   * `resourceType.name` matches `resourceTypeName`. Matching is by name only — the
+   * version is ignored (permissive, survives schema bumps).
+   *
+   * gRPC-only: `ListUserResources` throws on a REST-connected client
+   * ({@link LLPlClient.listUserResources}), so callers on REST get a thrown error.
+   */
+  async listSharedResourcesByType(
+    resourceTypeName: string,
+    opts: { login?: string } = {},
+  ): Promise<SignedResourceId[]> {
+    const responses = await this.ll.listUserResources({ login: opts.login });
+
+    const result: SignedResourceId[] = [];
+    for (const msg of responses) {
+      if (msg.entry.oneofKind !== "sharedResource") continue;
+      const sr = msg.entry.sharedResource;
+      if (!sr.resourceType) continue;
+      if (sr.resourceType.name !== resourceTypeName) continue;
+      result.push(createSignedResourceId(sr.resourceId, toResourceSignature(sr.resourceSignature)));
+    }
+    return result;
+  }
+
+  /**
+   * Enumerates the recipients of a single resource — the donor-side "who did I
+   * share with" view.
+   *
+   * Takes a signed, writable resource handle: the backend gates grant listing on a
+   * signed resource id with writable permission, so only the resource's owner can
+   * call it. An everyone-grant surfaces with `user` matching the backend's
+   * everyone-sentinel — test with {@link isEveryoneUserLogin} (from "./transaction");
+   * the caller maps that to "*".
+   *
+   * Runs over a read transaction ({@link PlTransaction.listGrants}), so it works on
+   * every wire protocol — including REST, where the standalone server-streaming
+   * `ListGrants` RPC has no binding.
+   */
+  async listGrants(resourceId: SignedResourceId): Promise<GrantEntry[]> {
+    const grants = await this.runTx("ListGrants", false, NullSignedResourceId, (tx) =>
+      tx.listGrants(resourceId),
+    );
+    return grants.map((grant) => ({
+      user: grant.user,
+      writable: grant.permissions?.writable ?? false,
+      grantedBy: grant.grantedBy,
+      grantedAt: Number(grant.grantedAt),
+    }));
+  }
+
+  /**
+   * Lists the logins of users known to the server, for the recipient picker. A user becomes
+   * known on first login; provisioned users who have never logged in do not appear. gRPC-only
+   * (the underlying {@link LLPlClient.listUsers} has no REST binding) — throws on a
+   * REST-connected client, so callers gate on the `userListing:v1` capability.
+   */
+  async listUsers(): Promise<UserEntry[]> {
+    const users = await this.ll.listUsers();
+    return users.map((user) => ({ login: user.login }));
+  }
+
   private async getUserRootViaRpc(opts: {
     login?: string;
     createIfNotExists: true;

package/src/proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api.ts

@@ -3938,7 +3938,7 @@ export interface AuthAPI_GrantAccess_Request {
     /**
      * @generated from protobuf field: MiLaboratories.PL.API.AuthAPI.GrantAccess.GrantType grant_type = 5
      */
-    grantType: AuthAPI_GrantAccess_GrantType; // default: GENERAL
+    grantType: AuthAPI_GrantAccess_GrantType; // default: SINGLE_USER
 }
 /**
  * @generated from protobuf message MiLaboratories.PL.API.AuthAPI.GrantAccess.Response
@@ -3952,17 +3952,17 @@ export interface AuthAPI_GrantAccess_Response {
  */
 export enum AuthAPI_GrantAccess_GrantType {
     /**
-     * regular user-to-user grant (default)
+     * grants access for single user (default).
      *
-     * @generated from protobuf enum value: GENERAL = 0;
+     * @generated from protobuf enum value: SINGLE_USER = 0;
      */
-    GENERAL = 0,
+    SINGLE_USER = 0,
     /**
-     * make resource publically-accessible, showing it in ListUserResources for all users. Requires controller role.
+     * makes resource publically-accessible, showing it in ListUserResources for all authorised clients.
      *
-     * @generated from protobuf enum value: MAKE_RESOURCE_PUBLIC = 1;
+     * @generated from protobuf enum value: ANY_AUTHORISED = 1;
      */
-    MAKE_RESOURCE_PUBLIC = 1
+    ANY_AUTHORISED = 1
 }
 /**
  * @generated from protobuf message MiLaboratories.PL.API.AuthAPI.RevokeAccess
@@ -4034,11 +4034,11 @@ export interface AuthAPI_Grant {
     /**
      * @generated from protobuf field: string user = 1
      */
-    user: string;
+    user: string; // grantee
     /**
      * @generated from protobuf field: uint64 resource_id = 2
      */
-    resourceId: bigint;
+    resourceId: bigint; // target resource of a grant (what grantee can access)
     /**
      * @generated from protobuf field: MiLaboratories.PL.API.AuthAPI.Grant.Permissions permissions = 3
      */