MILAB-5815: resource signature support

.changeset/resource-signature-support.md

@@ -0,0 +1,11 @@
+---
+"@milaboratories/pl-client": minor
+"@milaboratories/pl-drivers": minor
+"@milaboratories/pl-tree": minor
+---
+
+Add resource signature propagation for server-side access control.
+
+- `pl-client`: cross-transaction `SignatureCache`, automatic signature tracking in `PlTransaction` (store/retrieve signatures for all resource and field operations), `setDefaultColor` for color proof on resource creation, `PermissionDeniedError` error type
+- `pl-drivers`: pass `resourceSignature` through proxied APIs (download, upload, logs, progress, ls), encode signatures in remote blob and log handles
+- `pl-tree`: propagate `resourceSignature` in `ResourceInfo`, `ResourceSnapshot`, and `PlTreeResource` state

lib/node/pl-client/src/core/client.ts

@@ -1,15 +1,16 @@
 import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol } from "./config";
 import type { PlCallOps } from "./ll_client";
 import { LLPlClient } from "./ll_client";
-import type { AnyResourceRef } from "./transaction";
+import type { AnyResourceRef, SignatureResolver } from "./transaction";
 import { PlTransaction, toGlobalResourceId, TxCommitConflict } from "./transaction";
 import { createHash } from "node:crypto";
-import type { OptionalResourceId, ResourceId } from "./types";
+import type { GlobalResourceId, OptionalResourceId, ResourceId } from "./types";
 import {
   bigintToResourceId,
   ensureResourceIdNotNull,
   isNullResourceId,
   NullResourceId,
+  toResourceSignature,
 } from "./types";
 import { ClientRoot } from "../helpers/pl";
 import { isUnimplementedError } from "./errors";
@@ -38,6 +39,7 @@ export type TxOps = PlCallOps & {
   retryOptions?: RetryOptions;
   name?: string;
   lockId?: string;
+  signatureResolver?: SignatureResolver;
 };
 
 const defaultTxOps = {
@@ -94,7 +96,7 @@ export class PlClient {
   public readonly finalPredicate: FinalResourceDataPredicate;
 
   /** Resource data cache, to minimize redundant data rereading from remote db */
-  private readonly resourceDataCache: LRUCache<ResourceId, ResourceDataCacheRecord>;
+  private readonly resourceDataCache: LRUCache<GlobalResourceId, ResourceDataCacheRecord>;
 
   private constructor(
     configOrAddress: PlClientConfig | string,
@@ -236,7 +238,10 @@ export class PlClient {
       const responses = await this._ll.listUserResources({ limit: 1 });
       for (const msg of responses) {
         if (msg.entry.oneofKind === "userRoot") {
-          rootFromServer = bigintToResourceId(msg.entry.userRoot.resourceId);
+          rootFromServer = bigintToResourceId(
+            msg.entry.userRoot.resourceId,
+            toResourceSignature(msg.entry.userRoot.resourceSignature),
+          );
           break;
         }
       }
@@ -268,6 +273,9 @@ export class PlClient {
 
             return await altRoot.globalId;
           },
+          rootFromServer.signature !== undefined
+            ? { signatureResolver: (id) => (id.id === rootFromServer!.id ? rootFromServer!.signature : undefined) }
+            : undefined,
         );
       }
     } else {
@@ -341,14 +349,17 @@ export class PlClient {
         // opening low-level tx
         const llTx = this.ll.createTx(writable, ops);
         // wrapping it into high-level tx (this also asynchronously sends initialization message)
-        const tx = new PlTransaction(
-          llTx,
-          name,
-          writable,
-          clientRoot,
-          this.finalPredicate,
-          this.resourceDataCache,
-        );
+        const tx = new PlTransaction(llTx, name, writable, clientRoot, {
+          finalPredicate: this.finalPredicate,
+          resourceDataCache: this.resourceDataCache,
+          signatureResolver: ops?.signatureResolver,
+        });
+
+        // Auto-set default color proof so that resource creation (write TXs)
+        // and name lookups (read TXs) carry the correct access color.
+        if (!isNullResourceId(clientRoot) && clientRoot.signature && writable) {
+          tx.setDefaultColor(clientRoot.signature);
+        }
 
         let ok = false;
         let result: T | undefined = undefined;

lib/node/pl-client/src/core/errors.ts

@@ -25,6 +25,18 @@ export function isUnauthenticated(err: unknown, nested: boolean = false): boolea
   return false;
 }
 
+export function isPermissionDenied(err: unknown, nested: boolean = false): boolean {
+  if (err === undefined || err === null) return false;
+
+  if (err instanceof PermissionDeniedError) return true;
+  if ((err as any).name === "RpcError" && (err as any).code === "PERMISSION_DENIED") return true;
+  if ((err as any).name === "RESTError" && (err as any).status.code === Code.PERMISSION_DENIED)
+    return true;
+  if ((err as any).cause !== undefined && !nested)
+    return isPermissionDenied((err as any).cause, true);
+  return false;
+}
+
 export function isTimeoutError(err: unknown, nested: boolean = false): boolean {
   if (err === undefined || err === null) return false;
 
@@ -125,6 +137,13 @@ export class UnauthenticatedError extends Error {
   }
 }
 
+export class PermissionDeniedError extends Error {
+  name = "PermissionDeniedError";
+  constructor(message: string) {
+    super("PermissionDenied: " + message);
+  }
+}
+
 export class DisconnectedError extends Error {
   name = "DisconnectedError";
   constructor(message: string) {
@@ -144,6 +163,10 @@ export function rethrowMeaningfulError(error: any, wrapIfUnknown: boolean = fals
     if (error instanceof UnauthenticatedError) throw error;
     throw new UnauthenticatedError(error.message);
   }
+  if (isPermissionDenied(error)) {
+    if (error instanceof PermissionDeniedError) throw error;
+    throw new PermissionDeniedError(error.message);
+  }
   if (isConnectionProblem(error)) {
     if (error instanceof DisconnectedError) throw error;
     throw new DisconnectedError(error.message);

lib/node/pl-client/src/core/ll_client.test.ts

@@ -146,7 +146,6 @@ test("test https call via proxy", async () => {
 test("list user resources returns user root", async () => {
   const client = await getTestLLClient();
   const responses = await client.listUserResources({ limit: 1 });
-  expect(responses.length).toBe(1);
-  const msg = responses[0];
-  expect(msg.entry.oneofKind).toBe("userRoot");
+  const userRoots = responses.filter((r) => r.entry.oneofKind === "userRoot");
+  expect(userRoots.length).toBe(1);
 });

lib/node/pl-client/src/core/ll_transaction.test.ts

@@ -5,6 +5,18 @@ import { test, expect } from "vitest";
 
 import { isTimeoutOrCancelError } from "./errors";
 import { Aborted } from "@milaboratories/ts-helpers";
+import type { LLPlClient } from "./ll_client";
+
+/** Get root resource signature from ListUserResources for use as color proof in tests. */
+async function getRootSignature(client: LLPlClient): Promise<Uint8Array> {
+  const responses = await client.listUserResources({ limit: 1 });
+  for (const msg of responses) {
+    if (msg.entry.oneofKind === "userRoot" && msg.entry.userRoot.resourceSignature) {
+      return msg.entry.userRoot.resourceSignature;
+    }
+  }
+  return new Uint8Array(0);
+}
 
 test("check successful transaction", async () => {
   const client = await getTestLLClient();
@@ -80,6 +92,7 @@ test("check timeout error type (passive)", async () => {
 
 test("check timeout error type (active)", async () => {
   const client = await getTestLLClient();
+  const rootSig = await getRootSignature(client);
   const tx = client.createTx(true, { timeout: 500 });
 
   try {
@@ -96,6 +109,12 @@ test("check timeout error type (active)", async () => {
     );
     expect(openResponse.txOpen.tx?.isValid).toBeTruthy();
 
+    // Set default color so resource creation succeeds in strict mode
+    await tx.send(
+      { oneofKind: "setDefaultColor", setDefaultColor: { colorProof: rootSig } },
+      false,
+    );
+
     const rData = Uint8Array.from([
       (Math.random() * 256) & 0xff,
       (Math.random() * 256) & 0xff,
@@ -115,12 +134,13 @@ test("check timeout error type (active)", async () => {
           type: { name: "TestValue", version: "1" },
           data: rData,
           errorIfExists: false,
-          colorProof: new Uint8Array(0),
         },
       },
       false,
     );
-    const id = (await createResponse).resourceCreateValue.resourceId;
+    const createResp = (await createResponse).resourceCreateValue;
+    const id = createResp.resourceId;
+    const resourceSignature = createResp.resourceSignature ?? new Uint8Array(0);
 
     while (true) {
       const vr = await tx.send(
@@ -129,7 +149,7 @@ test("check timeout error type (active)", async () => {
           resourceGet: {
             resourceId: id,
             loadFields: false,
-            resourceSignature: new Uint8Array(0),
+            resourceSignature,
           },
         },
         false,
@@ -144,6 +164,7 @@ test("check timeout error type (active)", async () => {
 
 test("check is abort error (active)", async () => {
   const client = await getTestLLClient();
+  const rootSig = await getRootSignature(client);
   const tx = client.createTx(true, { abortSignal: AbortSignal.timeout(100) });
 
   try {
@@ -160,6 +181,12 @@ test("check is abort error (active)", async () => {
     );
     expect(openResponse.txOpen.tx?.isValid).toBeTruthy();
 
+    // Set default color so resource creation succeeds in strict mode
+    await tx.send(
+      { oneofKind: "setDefaultColor", setDefaultColor: { colorProof: rootSig } },
+      false,
+    );
+
     const rData = Uint8Array.from([
       Math.random() & 0xff,
       Math.random() & 0xff,
@@ -179,12 +206,13 @@ test("check is abort error (active)", async () => {
           type: { name: "TestValue", version: "1" },
           data: rData,
           errorIfExists: false,
-          colorProof: new Uint8Array(0),
         },
       },
       false,
     );
-    const id = (await createResponse).resourceCreateValue.resourceId;
+    const createResp = (await createResponse).resourceCreateValue;
+    const id = createResp.resourceId;
+    const resourceSignature = createResp.resourceSignature ?? new Uint8Array(0);
 
     while (true) {
       const vr = await tx.send(
@@ -193,7 +221,7 @@ test("check is abort error (active)", async () => {
           resourceGet: {
             resourceId: id,
             loadFields: false,
-            resourceSignature: new Uint8Array(0),
+            resourceSignature,
           },
         },
         false,