@milaboratories/pl-client 3.11.5 → 3.12.1

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/unauth_client.ts

@@ -29,6 +29,10 @@ export type SSOAuthMethod = {
   userIdClaim: string;
   groupsClaim: string;
   flowType: SSOFlowType;
+  /** OIDC `access_type` auth-request param ("online" | "offline"). Google-specific:
+   * "offline" makes Google issue a refresh token; other IdPs ignore it. Absent when
+   * the server does not set it — never send an empty string to the IdP. */
+  accessType?: string;
 };
 
 /** Server-issued material returned by {@link UnauthenticatedPlClient.beginSSOLogin}.
@@ -37,6 +41,11 @@ export type SSOLoginAttempt = {
   flow: "public_pkce";
   nonce: string;
   expiresAt: Date;
+  /** Confidential-client secret for the IdP token exchange; absent for public clients.
+   * Google's OIDC has no public-client mode — it requires a client_secret at the token
+   * endpoint even with PKCE — so for Google the backend forwards its secret here and the
+   * desktop exchanges the code as a confidential client. */
+  clientSecret?: string;
 };
 
 /** Primarily used for initial authentication (login) */
@@ -104,6 +113,7 @@ export class UnauthenticatedPlClient {
         subjectTokenSource: sso.subjectTokenSource,
         userIdClaim: sso.userIdClaim,
         groupsClaim: sso.groupsClaim,
+        accessType: sso.accessType || undefined,
         flowType: "public_pkce",
       };
     }
@@ -149,8 +159,13 @@ export class UnauthenticatedPlClient {
   /** Request fresh server-issued login material. v1 only emits the public-PKCE flow;
    * desktop MUST place the returned `nonce` verbatim into the OIDC auth-request. */
   public async beginSSOLogin(): Promise<SSOLoginAttempt> {
-    const { nonce, expiresAt } = await this.ll.beginSSOLogin();
-    return { flow: "public_pkce", nonce, expiresAt };
+    const attempt = await this.ll.beginSSOLogin();
+    return {
+      flow: "public_pkce",
+      nonce: attempt.nonce,
+      expiresAt: attempt.expiresAt,
+      clientSecret: attempt.clientSecret,
+    };
   }
 
   /** Forward the verbatim IdP `/token` response body and receive a Platforma JWT. */

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.client.ts

@@ -10,6 +10,8 @@ import type { MaintenanceAPI_Ping_Response } from "./api";
 import type { MaintenanceAPI_Ping_Request } from "./api";
 import type { MiscAPI_ListResourceTypes_Response } from "./api";
 import type { MiscAPI_ListResourceTypes_Request } from "./api";
+import type { AuthAPI_ListUsers_Response } from "./api";
+import type { AuthAPI_ListUsers_Request } from "./api";
 import type { AuthAPI_ListUserResources_Response } from "./api";
 import type { AuthAPI_ListUserResources_Request } from "./api";
 import type { AuthAPI_GetUserRoot_Response } from "./api";
@@ -284,6 +286,10 @@ export interface IPlatformClient {
      * @generated from protobuf rpc: ListUserResources
      */
     listUserResources(input: AuthAPI_ListUserResources_Request, options?: RpcOptions): ServerStreamingCall<AuthAPI_ListUserResources_Request, AuthAPI_ListUserResources_Response>;
+    /**
+     * @generated from protobuf rpc: ListUsers
+     */
+    listUsers(input: AuthAPI_ListUsers_Request, options?: RpcOptions): UnaryCall<AuthAPI_ListUsers_Request, AuthAPI_ListUsers_Response>;
     /**
      *
      * Other stuff
@@ -613,6 +619,13 @@ export class PlatformClient implements IPlatformClient, ServiceInfo {
         const method = this.methods[33], opt = this._transport.mergeOptions(options);
         return stackIntercept<AuthAPI_ListUserResources_Request, AuthAPI_ListUserResources_Response>("serverStreaming", this._transport, method, opt, input);
     }
+    /**
+     * @generated from protobuf rpc: ListUsers
+     */
+    listUsers(input: AuthAPI_ListUsers_Request, options?: RpcOptions): UnaryCall<AuthAPI_ListUsers_Request, AuthAPI_ListUsers_Response> {
+        const method = this.methods[34], opt = this._transport.mergeOptions(options);
+        return stackIntercept<AuthAPI_ListUsers_Request, AuthAPI_ListUsers_Response>("unary", this._transport, method, opt, input);
+    }
     /**
      *
      * Other stuff
@@ -621,7 +634,7 @@ export class PlatformClient implements IPlatformClient, ServiceInfo {
      * @generated from protobuf rpc: ListResourceTypes
      */
     listResourceTypes(input: MiscAPI_ListResourceTypes_Request, options?: RpcOptions): UnaryCall<MiscAPI_ListResourceTypes_Request, MiscAPI_ListResourceTypes_Response> {
-        const method = this.methods[34], opt = this._transport.mergeOptions(options);
+        const method = this.methods[35], opt = this._transport.mergeOptions(options);
         return stackIntercept<MiscAPI_ListResourceTypes_Request, MiscAPI_ListResourceTypes_Response>("unary", this._transport, method, opt, input);
     }
     /**
@@ -632,14 +645,14 @@ export class PlatformClient implements IPlatformClient, ServiceInfo {
      * @generated from protobuf rpc: Ping
      */
     ping(input: MaintenanceAPI_Ping_Request, options?: RpcOptions): UnaryCall<MaintenanceAPI_Ping_Request, MaintenanceAPI_Ping_Response> {
-        const method = this.methods[35], opt = this._transport.mergeOptions(options);
+        const method = this.methods[36], opt = this._transport.mergeOptions(options);
         return stackIntercept<MaintenanceAPI_Ping_Request, MaintenanceAPI_Ping_Response>("unary", this._transport, method, opt, input);
     }
     /**
      * @generated from protobuf rpc: License
      */
     license(input: MaintenanceAPI_License_Request, options?: RpcOptions): UnaryCall<MaintenanceAPI_License_Request, MaintenanceAPI_License_Response> {
-        const method = this.methods[36], opt = this._transport.mergeOptions(options);
+        const method = this.methods[37], opt = this._transport.mergeOptions(options);
         return stackIntercept<MaintenanceAPI_License_Request, MaintenanceAPI_License_Response>("unary", this._transport, method, opt, input);
     }
 }