[MILAB-6225]: Add federative envelope handling to Ls API

- Extend Ls API to carry additionalInfo envelope for federative storages
- Switch list results to a file-stats variant and propagate envelopes
- Pass envelope through to index handles when present
- Update REST/GRPC schemas to include additionalInfo
- Add tests to verify envelope threading and absence when empty

Author: popoffvg

.changeset/social-bars-beam.md

@@ -0,0 +1,6 @@
+---
+"@milaboratories/pl-middle-layer": minor
+"@milaboratories/pl-drivers": minor
+---
+
+support file link signing

lib/node/pl-drivers/proto/shared/lsapi/openapi.yaml

@@ -59,6 +59,14 @@ components:
         isDir:
           type: boolean
           description: is_dir is true for an item that can have subitems.
+        additionalInfo:
+          type: object
+          additionalProperties:
+            type: string
+          description: |-
+            additional_info carries the signed identity envelope for federative storages.
+             KV schema: v=1, path, uid, sid, role, exp, kid, signed, sig.
+             Empty for non-federative storages. Verifiers MUST ignore unknown keys.
         fullName:
           type: string
           description: |-

lib/node/pl-drivers/proto/shared/lsapi/protocol.proto

@@ -34,6 +34,13 @@ message LsAPI {
     // is_dir is true for an item that can have subitems.
     bool is_dir = 3;
 
+    // additional_info carries the signed identity envelope for federative storages.
+    // KV schema is authoritative in pl/util/storage/v4sign/envelope.go:
+    //   v=1, path, uid, sid (optional), role (optional), exp (unix-sec decimal), kid,
+    //   signed=path,uid,sid,role,exp,kid, sig (base64url HMAC-SHA256).
+    // Empty for non-federative storages. Verifiers MUST ignore unknown keys.
+    map<string, string> additional_info = 8;
+
     // full_name is the full name of the item, relative to the storage root.
     // It is <directory> + <name>.
     // The <delimiter>, used in names, is storage-specific and is NOT guaranteed to be '/'.
@@ -66,7 +73,7 @@ message LsAPI {
       // Location to list, relative to the storage root. Only items that have <full_name> starting
       // with <location> are included in the list response.
       string location = 2;
-      
+
       // // limit amount of items returned by server in single response.
       // // The default and maximum limit may differ for different storage types.
       // // If the storage has its own restrictions on <limit> value (<storage limit>),

lib/node/pl-drivers/src/clients/ls_api.ts

@@ -68,6 +68,7 @@ export class ClientLs {
         name: item.name,
         size: BigInt(item.size),
         isDir: item.isDir,
+        additionalInfo: item.additionalInfo ?? {},
         fullName: item.fullName,
         directory: item.directory,
         lastModified: parseTimestamp(item.lastModified),

lib/node/pl-drivers/src/drivers/helpers/ls_remote_import_handle.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "vitest";
+import { createIndexImportHandle, parseIndexHandle } from "./ls_remote_import_handle";
+
+// Golden URL for the no-envelope case — guards against accidental key injection or ordering drift.
+// Value: index://index/<url-encoded JSON of {storageId:"s3",path:"x/y"}>
+const GOLDEN_NO_ENVELOPE = `index://index/${encodeURIComponent(JSON.stringify({ storageId: "s3", path: "x/y" }))}`;
+
+describe("createIndexImportHandle", () => {
+  test("round-trips additionalInfo envelope", () => {
+    const envelope = { uid: "u", sid: "s", sig: "abc123", exp: "9999999999", kid: "k", v: "1" };
+    const handle = createIndexImportHandle("s3", "x/y", envelope);
+    const parsed = parseIndexHandle(handle);
+    expect(parsed.storageId).toBe("s3");
+    expect(parsed.path).toBe("x/y");
+    expect(parsed.additionalInfo).toEqual(envelope);
+  });
+
+  test("no-arg case is byte-identical to golden (regression guard)", () => {
+    const handle = createIndexImportHandle("s3", "x/y");
+    expect(handle).toBe(GOLDEN_NO_ENVELOPE);
+  });
+
+  test("empty map is pruned — byte-identical to no-arg golden", () => {
+    const handle = createIndexImportHandle("s3", "x/y", {});
+    expect(handle).toBe(GOLDEN_NO_ENVELOPE);
+  });
+
+  test("absent envelope: decoded handle has no additionalInfo key", () => {
+    const handle = createIndexImportHandle("s3", "x/y");
+    const parsed = parseIndexHandle(handle);
+    expect(parsed.additionalInfo).toBeUndefined();
+    // Confirm the key is truly absent from decoded JSON (not just undefined)
+    expect(Object.prototype.hasOwnProperty.call(parsed, "additionalInfo")).toBe(false);
+  });
+
+  test("parseIndexHandle accepts old handle without additionalInfo", () => {
+    // Simulate a handle that was created before this change (no additionalInfo key in JSON)
+    const oldJson = JSON.stringify({ storageId: "legacy", path: "a/b" });
+    const oldHandle = `index://index/${encodeURIComponent(oldJson)}` as import("@milaboratories/pl-model-common").ImportFileHandleIndex;
+    const parsed = parseIndexHandle(oldHandle);
+    expect(parsed.storageId).toBe("legacy");
+    expect(parsed.path).toBe("a/b");
+    expect(parsed.additionalInfo).toBeUndefined();
+  });
+});

lib/node/pl-drivers/src/drivers/helpers/ls_remote_import_handle.ts

@@ -5,12 +5,18 @@ import { ImportFileHandleIndexData, ImportFileHandleUploadData } from "../types"
 export function createIndexImportHandle(
   storageId: string,
   path: string,
+  additionalInfo?: Record<string, string>,
 ): sdk.ImportFileHandleIndex {
   const data: ImportFileHandleIndexData = {
     storageId: storageId,
     path: path,
   };
 
+  // Only embed the envelope when non-empty; preserves byte-identical URL for non-federative storages.
+  if (additionalInfo && Object.keys(additionalInfo).length > 0) {
+    data.additionalInfo = additionalInfo;
+  }
+
   return `index://index/${encodeURIComponent(JSON.stringify(data))}`;
 }
 

lib/node/pl-drivers/src/drivers/ls.test.ts

@@ -1,10 +1,13 @@
 import { ConsoleLoggerAdapter, HmacSha256Signer } from "@milaboratories/ts-helpers";
-import { LsDriver } from "./ls";
+import { LsDriver, type LsEntryWithFileStats } from "./ls";
 import { TestHelpers } from "@milaboratories/pl-client";
 import * as path from "node:path";
-import { test, expect } from "vitest";
+import { test, expect, describe } from "vitest";
 import { isImportFileHandleIndex, isImportFileHandleUpload } from "@milaboratories/pl-model-common";
+import type { StorageHandle } from "@milaboratories/pl-model-common";
 import * as env from "../test_env";
+import { parseIndexHandle } from "./helpers/ls_remote_import_handle";
+import { createRemoteStorageHandle } from "./helpers/ls_storage_entry";
 
 const assetsPath = path.resolve("../../../assets");
 
@@ -141,3 +144,135 @@ test("should ok when get file using local dialog, and read its content", async (
     expect(multiResult.files![0]).toStrictEqual(result.file);
   });
 });
+
+// Unit tests: verify that LsDriver.listFiles and listRemoteFilesWithFileStats correctly
+// thread additionalInfo from gRPC list items into the index:// handle.
+describe("LsDriver additionalInfo threading", () => {
+  const envelope = { uid: "u1", sid: "s1", sig: "sigval", exp: "9999999999", kid: "k1", v: "1" };
+
+  const storageInfo = {
+    storageId: "test-storage",
+    storageName: "Test Storage",
+    resourceId: "res-id" as any,
+    resourceType: { name: "LS/test-storage", version: "1" },
+  };
+
+  // Builds a minimal LsDriver instance with an injected mock lsClient via private-constructor bypass.
+  function makeMockDriver(listResponse: { items: any[]; delimiter: string }): LsDriver {
+    const mockLsClient = {
+      list: async () => listResponse,
+      close: () => {},
+    };
+    const mockUserResources = {
+      getDataLibraries: async () => new Map([[storageInfo.storageId, storageInfo]]),
+    };
+    const signer = new HmacSha256Signer("test");
+    // Bypass private constructor for unit testing only.
+    return new (LsDriver as any)(
+      new ConsoleLoggerAdapter(),
+      mockLsClient,
+      mockUserResources,
+      signer,
+      new Map(),
+      new Map(),
+      () => Promise.resolve(undefined),
+    ) as LsDriver;
+  }
+
+  function makeRemoteHandle(): StorageHandle {
+    return createRemoteStorageHandle(storageInfo) as StorageHandle;
+  }
+
+  test("listFiles: handle carries additionalInfo envelope from gRPC item", async () => {
+    const driver = makeMockDriver({
+      delimiter: "/",
+      items: [
+        {
+          name: "file.txt",
+          size: 100n,
+          isDir: false,
+          additionalInfo: envelope,
+          fullName: "dir/file.txt",
+          directory: "dir/",
+          version: "v1",
+        },
+      ],
+    });
+
+    const result = await driver.listFiles(makeRemoteHandle(), "dir/");
+    expect(result.entries).toHaveLength(1);
+
+    const parsed = parseIndexHandle(result.entries[0].handle as any);
+    expect(parsed.additionalInfo).toEqual(envelope);
+  });
+
+  test("listFiles: handle has no additionalInfo when item has empty envelope", async () => {
+    const driver = makeMockDriver({
+      delimiter: "/",
+      items: [
+        {
+          name: "plain.txt",
+          size: 50n,
+          isDir: false,
+          additionalInfo: {},
+          fullName: "plain.txt",
+          directory: "",
+          version: "v1",
+        },
+      ],
+    });
+
+    const result = await driver.listFiles(makeRemoteHandle(), "");
+    expect(result.entries).toHaveLength(1);
+
+    const parsed = parseIndexHandle(result.entries[0].handle as any);
+    expect(parsed.additionalInfo).toBeUndefined();
+  });
+
+  test("listRemoteFilesWithFileStats: handle carries additionalInfo envelope", async () => {
+    const driver = makeMockDriver({
+      delimiter: "/",
+      items: [
+        {
+          name: "data.csv",
+          size: 200n,
+          isDir: false,
+          additionalInfo: envelope,
+          fullName: "data.csv",
+          directory: "",
+          version: "v2",
+        },
+      ],
+    });
+
+    const result = await driver.listRemoteFilesWithFileStats(makeRemoteHandle(), "");
+    expect(result.entries).toHaveLength(1);
+    expect((result.entries[0] as LsEntryWithFileStats).size).toBe(200);
+
+    const parsed = parseIndexHandle(result.entries[0].handle as any);
+    expect(parsed.additionalInfo).toEqual(envelope);
+  });
+
+  test("listRemoteFilesWithFileStats: no additionalInfo when absent in item", async () => {
+    const driver = makeMockDriver({
+      delimiter: "/",
+      items: [
+        {
+          name: "plain.csv",
+          size: 10n,
+          isDir: false,
+          additionalInfo: {},
+          fullName: "plain.csv",
+          directory: "",
+          version: "v1",
+        },
+      ],
+    });
+
+    const result = await driver.listRemoteFilesWithFileStats(makeRemoteHandle(), "");
+    expect(result.entries).toHaveLength(1);
+
+    const parsed = parseIndexHandle(result.entries[0].handle as any);
+    expect(parsed.additionalInfo).toBeUndefined();
+  });
+});

lib/node/pl-drivers/src/drivers/ls.ts

@@ -34,18 +34,18 @@ export interface InternalLsDriver extends sdk.LsDriver {
    * */
   getLocalFileHandle(localPath: string): Promise<sdk.LocalImportFileHandle>;
 
-  listRemoteFilesWithAdditionalInfo(
+  listRemoteFilesWithFileStats(
     storage: sdk.StorageHandle,
     fullPath: string,
-  ): Promise<ListRemoteFilesResultWithAdditionalInfo>;
+  ): Promise<ListRemoteFilesResultWithFileStats>;
 }
 
-export type ListRemoteFilesResultWithAdditionalInfo = {
+export type ListRemoteFilesResultWithFileStats = {
   parent?: string;
-  entries: LsEntryWithAdditionalInfo[];
+  entries: LsEntryWithFileStats[];
 };
 
-export type LsEntryWithAdditionalInfo = sdk.LsEntry & {
+export type LsEntryWithFileStats = sdk.LsEntry & {
   size: number;
 };
 
@@ -217,7 +217,8 @@ export class LsDriver implements InternalLsDriver {
           type: e.isDir ? "dir" : "file",
           name: e.name,
           fullPath: e.fullName,
-          handle: createIndexImportHandle(storageData.storageId, e.fullName),
+          // e.additionalInfo: federative identity envelope from backend TODO-4 (map<string,string>).
+          handle: createIndexImportHandle(storageData.storageId, e.fullName, e.additionalInfo),
         })),
       };
     }
@@ -249,10 +250,10 @@ export class LsDriver implements InternalLsDriver {
     return { entries };
   }
 
-  public async listRemoteFilesWithAdditionalInfo(
+  public async listRemoteFilesWithFileStats(
     storageHandle: sdk.StorageHandle,
     fullPath: string,
-  ): Promise<ListRemoteFilesResultWithAdditionalInfo> {
+  ): Promise<ListRemoteFilesResultWithFileStats> {
     const storageData = parseStorageHandle(storageHandle);
     if (!storageData.isRemote) {
       throw new Error(`Storage ${storageData.name} is not remote`);
@@ -266,7 +267,8 @@ export class LsDriver implements InternalLsDriver {
         type: e.isDir ? "dir" : "file",
         name: e.name,
         fullPath: e.fullName,
-        handle: createIndexImportHandle(storageData.storageId, e.fullName),
+        // e.additionalInfo: federative identity envelope from backend TODO-4 (map<string,string>).
+        handle: createIndexImportHandle(storageData.storageId, e.fullName, e.additionalInfo),
         size: Number(e.size),
       })),
     };

lib/node/pl-drivers/src/drivers/types.ts

@@ -54,6 +54,11 @@ export const ImportFileHandleIndexData = z.object({
   storageId: z.string(),
   /** Path inside storage */
   path: z.string(),
+  /**
+   * Federative identity envelope from LsAPI.List.Response.ListItem.additional_info.
+   * Absent for non-federative storages (backwards compatible: old handles parse unchanged).
+   */
+  additionalInfo: z.record(z.string(), z.string()).optional(),
 });
 export type ImportFileHandleIndexData = z.infer<typeof ImportFileHandleIndexData>;