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

@@ -4,15 +4,16 @@ import { LLPlClient } from "./ll_client";
 import type { AnyResourceRef } from "./transaction";
 import { PlTransaction, toGlobalResourceId, TxCommitConflict } from "./transaction";
 import { createHash } from "node:crypto";
-import type { OptionalResourceId, ResourceId } from "./types";
+import type { OptionalResourceId, ResourceId, ResourceSignature } from "./types";
 import {
   bigintToResourceId,
   ensureResourceIdNotNull,
   isNullResourceId,
   NullResourceId,
+  toResourceSignature,
 } from "./types";
 import { ClientRoot } from "../helpers/pl";
-import { isUnimplementedError } from "./errors";
+import { isPermissionDenied, isUnimplementedError } from "./errors";
 import type { MiLogger, RetryOptions } from "@milaboratories/ts-helpers";
 import { assertNever, createRetryState, nextRetryStateOrError } from "@milaboratories/ts-helpers";
 import type { PlDriver, PlDriverDefinition } from "./driver";
@@ -32,6 +33,7 @@ import { addStat, initialTxStat } from "./stat";
 import type { WireConnection } from "./wire";
 import { advisoryLock } from "./advisory_locks";
 import { plAddressToConfig } from "./config";
+import { SignatureCache } from "./signature_cache";
 
 export type TxOps = PlCallOps & {
   sync?: boolean;
@@ -96,6 +98,9 @@ export class PlClient {
   /** Resource data cache, to minimize redundant data rereading from remote db */
   private readonly resourceDataCache: LRUCache<ResourceId, ResourceDataCacheRecord>;
 
+  /** Cross-transaction signature cache */
+  private readonly _signatureCache = new SignatureCache();
+
   private constructor(
     configOrAddress: PlClientConfig | string,
     auth: AuthOps,
@@ -209,6 +214,12 @@ export class PlClient {
     return this._serverInfo!;
   }
 
+  /** Shared signature cache, persists across transactions.
+   * Call clear() on auth errors to invalidate stale signatures. */
+  public get signatureCache(): SignatureCache {
+    return this._signatureCache;
+  }
+
   /** Discovers or creates the user's root resource.
    *  Tries ListUserResources RPC first (new backend), falls back to
    *  legacy named-resource lookup for older backends. */
@@ -232,11 +243,13 @@ export class PlClient {
 
     // Try ListUserResources first (new backend, gRPC only)
     let rootFromServer: ResourceId | undefined;
+    let rootSignature: ResourceSignature | undefined;
     try {
       const responses = await this._ll.listUserResources({ limit: 1 });
       for (const msg of responses) {
         if (msg.entry.oneofKind === "userRoot") {
           rootFromServer = bigintToResourceId(msg.entry.userRoot.resourceId);
+          rootSignature = toResourceSignature(msg.entry.userRoot.resourceSignature);
           break;
         }
       }
@@ -246,6 +259,12 @@ export class PlClient {
     }
 
     if (rootFromServer !== undefined) {
+      // Store root signature in cross-transaction cache so subsequent
+      // transactions can attach it to requests and use it as color proof.
+      if (rootSignature && rootSignature.length > 0) {
+        this._signatureCache.set(rootFromServer, rootSignature);
+      }
+
       // New path: server created/returned the root
       if (this.conf.alternativeRoot === undefined) {
         this._clientRoot = rootFromServer;
@@ -341,14 +360,20 @@ 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,
+          signatureCache: this._signatureCache,
+        });
+
+        // Auto-set default color proof so that resource creation (write TXs)
+        // and name lookups (read TXs) carry the correct access color.
+        if (!isNullResourceId(clientRoot)) {
+          const rootSig = this._signatureCache.get(clientRoot);
+          if (rootSig) {
+            tx.setDefaultColor(rootSig);
+          }
+        }
 
         let ok = false;
         let result: T | undefined = undefined;
@@ -369,6 +394,14 @@ export class PlClient {
           } else {
             // collecting stat
             this._txErrorStat = addStat(this._txErrorStat, tx.stat);
+            // Invalidate all cached signatures on permission denied.
+            // Targeted invalidation is impractical here because the failing
+            // resource id is not reliably available from the error.  A full
+            // clear is safe: signatures are re-populated lazily from server
+            // responses in subsequent transactions.
+            if (isPermissionDenied(e)) {
+              this._signatureCache.clear();
+            }
             throw e;
           }
         } finally {

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_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,

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

@@ -0,0 +1,44 @@
+import { LRUCache } from "lru-cache";
+import type { ResourceId, ResourceSignature, SignedResourceId } from "./types";
+
+const DEFAULT_MAX_ENTRIES = 100_000;
+
+/** Cross-transaction cache for resource signatures.
+ * Keyed by ResourceId, stores opaque ResourceSignature bytes.
+ * Uses LRU eviction to prevent unbounded memory growth in long-running clients. */
+export class SignatureCache {
+  private readonly store: LRUCache<ResourceId, ResourceSignature>;
+
+  constructor(maxEntries: number = DEFAULT_MAX_ENTRIES) {
+    this.store = new LRUCache({ max: maxEntries });
+  }
+
+  set(id: ResourceId, sig: ResourceSignature): void {
+    this.store.set(id, sig);
+  }
+
+  get(id: ResourceId): ResourceSignature | undefined {
+    return this.store.get(id);
+  }
+
+  /** Return a SignedResourceId by looking up the cached signature. */
+  sign(id: ResourceId): SignedResourceId {
+    return { resourceId: id, resourceSignature: this.get(id) };
+  }
+
+  delete(id: ResourceId): boolean {
+    return this.store.delete(id);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  has(id: ResourceId): boolean {
+    return this.store.has(id);
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+}