matchlock-sdk 0.2.10 → 0.2.11

package/README.md

@@ -85,6 +85,31 @@ const sandbox = new Sandbox("alpine:latest").withNetworkInterception({
 - Port forwarding API parity (`portForward`, `portForwardWithAddresses`)
 - Lifecycle control (`close`, `remove`, `vmId`)
 
+## Mounts
+
+Mount host directories or use in-memory/snapshot filesystems:
+
+```ts
+import { Client, Sandbox, MountConfig } from "matchlock-sdk";
+
+const sandbox = new Sandbox("alpine:latest")
+  .mountHostDir("/workspace/src", "/home/user/project/src")
+  .mountHostDirReadonly("/workspace/config", "/home/user/project/config")
+  .mountMemory("/workspace/tmp")
+  .mountOverlay("/workspace/data", "/home/user/project/data")
+  // Or use the generic mount() method:
+  .mount("/workspace/custom", { type: "host_fs", hostPath: "/tmp/custom" });
+```
+
+Pass `ownerUID` and/or `ownerGID` to have all files in the mount appear owned by a specific user inside the VM. This is useful when the sandbox runs as a non-root user (via `.withUser()`):
+
+```ts
+const sandbox = new Sandbox("alpine:latest")
+  .withUser("1000:1000")
+  .mountHostDir("/workspace/src", "/home/user/project/src", { ownerUID: 1000, ownerGID: 1000 })
+  .mountHostDirReadonly("/workspace/config", "/home/user/project/config", { ownerUID: 1000 });
+```
+
 ## Development
 
 ```bash

package/dist/builder.d.ts

@@ -1,4 +1,4 @@
-import type { CreateOptions, ImageConfig, MountConfig, NetworkInterceptionConfig, VFSInterceptionConfig } from "./types";
+import type { CreateOptions, ImageConfig, MountConfig, MountOwnerOptions, NetworkInterceptionConfig, VFSInterceptionConfig } from "./types";
 export declare function cloneCreateOptions(opts: CreateOptions): CreateOptions;
 export declare class Sandbox {
     private readonly opts;
@@ -29,8 +29,8 @@ export declare class Sandbox {
     withPortForward(localPort: number, remotePort: number): Sandbox;
     withPortForwardAddresses(...addresses: string[]): Sandbox;
     mount(guestPath: string, config: MountConfig): Sandbox;
-    mountHostDir(guestPath: string, hostPath: string): Sandbox;
-    mountHostDirReadonly(guestPath: string, hostPath: string): Sandbox;
+    mountHostDir(guestPath: string, hostPath: string, opts?: MountOwnerOptions): Sandbox;
+    mountHostDirReadonly(guestPath: string, hostPath: string, opts?: MountOwnerOptions): Sandbox;
     mountMemory(guestPath: string): Sandbox;
     mountOverlay(guestPath: string, hostPath: string): Sandbox;
     withUser(user: string): Sandbox;

package/dist/builder.js

@@ -188,11 +188,13 @@ class Sandbox {
         this.opts.mounts[guestPath] = { ...config };
         return this;
     }
-    mountHostDir(guestPath, hostPath) {
-        return this.mount(guestPath, { type: "host_fs", hostPath });
+    mountHostDir(guestPath, hostPath, opts) {
+        const { ownerUID, ownerGID } = validatedMountOwnerOptions(opts);
+        return this.mount(guestPath, { type: "host_fs", hostPath, ownerUID, ownerGID });
     }
-    mountHostDirReadonly(guestPath, hostPath) {
-        return this.mount(guestPath, { type: "host_fs", hostPath, readonly: true });
+    mountHostDirReadonly(guestPath, hostPath, opts) {
+        const { ownerUID, ownerGID } = validatedMountOwnerOptions(opts);
+        return this.mount(guestPath, { type: "host_fs", hostPath, readonly: true, ownerUID, ownerGID });
     }
     mountMemory(guestPath) {
         return this.mount(guestPath, { type: "memory" });
@@ -240,3 +242,16 @@ exports.Sandbox = Sandbox;
 function createSandbox(image) {
     return new Sandbox(image);
 }
+function validatedMountOwnerOptions(opts) {
+    if (!opts) {
+        return {};
+    }
+    validateID("ownerUID", opts.ownerUID);
+    validateID("ownerGID", opts.ownerGID);
+    return opts;
+}
+function validateID(name, id) {
+    if (id !== undefined && (!Number.isInteger(id) || id < 0 || id > 0xffffffff)) {
+        throw new RangeError(`${name} must be an integer in [0, 4294967295], got ${id}`);
+    }
+}

package/dist/client/create.js

@@ -56,6 +56,12 @@ function buildCreateParams(options, wireVFS, wireNetworkInterception) {
                 if (config.readonly) {
                     mount.readonly = true;
                 }
+                if (config.ownerUID !== undefined) {
+                    mount.owner_uid = config.ownerUID;
+                }
+                if (config.ownerGID !== undefined) {
+                    mount.owner_gid = config.ownerGID;
+                }
                 mounts[guestPath] = mount;
             }
             vfs.mounts = mounts;

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { Client, defaultConfig } from "./client";
 export { Sandbox, createSandbox } from "./builder";
 export { MatchlockError, RPCError } from "./errors";
 export { NETWORK_HOOK_ACTION_ALLOW, NETWORK_HOOK_ACTION_BLOCK, NETWORK_HOOK_ACTION_MUTATE, NETWORK_HOOK_PHASE_AFTER, NETWORK_HOOK_PHASE_BEFORE, VFS_HOOK_ACTION_ALLOW, VFS_HOOK_ACTION_BLOCK, VFS_HOOK_OP_STAT, VFS_HOOK_OP_READDIR, VFS_HOOK_OP_OPEN, VFS_HOOK_OP_CREATE, VFS_HOOK_OP_MKDIR, VFS_HOOK_OP_CHMOD, VFS_HOOK_OP_REMOVE, VFS_HOOK_OP_REMOVE_ALL, VFS_HOOK_OP_RENAME, VFS_HOOK_OP_SYMLINK, VFS_HOOK_OP_READLINK, VFS_HOOK_OP_READ, VFS_HOOK_OP_WRITE, VFS_HOOK_OP_CLOSE, VFS_HOOK_OP_SYNC, VFS_HOOK_OP_TRUNCATE, VFS_HOOK_PHASE_BEFORE, VFS_HOOK_PHASE_AFTER, } from "./types";
-export type { BinaryLike, Config, CreateOptions, ExecInteractiveOptions, ExecInteractiveResult, ExecOptions, ExecPipeOptions, ExecPipeResult, ExecResult, ExecStreamOptions, ExecStreamResult, FileInfo, VolumeInfo, HostIPMapping, ImageConfig, LogStreamOptions, MountConfig, NetworkBodyTransform, NetworkHookFunc, NetworkHookRequest, NetworkHookRequestMutation, NetworkHookResponseMutation, NetworkHookResult, NetworkHookAction, NetworkHookPhase, NetworkHookRule, NetworkInterceptionConfig, PortForward, PortForwardBinding, RequestOptions, Secret, TTYSize, StreamWriter, StreamReader, VFSActionHookFunc, VFSActionRequest, VFSDangerousHookFunc, VFSHookAction, VFSHookEvent, VFSHookFunc, VFSHookOp, VFSHookPhase, VFSHookRule, VFSInterceptionConfig, VFSMutateHookFunc, VFSMutateRequest, } from "./types";
+export type { BinaryLike, Config, CreateOptions, ExecInteractiveOptions, ExecInteractiveResult, ExecOptions, ExecPipeOptions, ExecPipeResult, ExecResult, ExecStreamOptions, ExecStreamResult, FileInfo, VolumeInfo, HostIPMapping, ImageConfig, LogStreamOptions, MountConfig, MountOwnerOptions, NetworkBodyTransform, NetworkHookFunc, NetworkHookRequest, NetworkHookRequestMutation, NetworkHookResponseMutation, NetworkHookResult, NetworkHookAction, NetworkHookPhase, NetworkHookRule, NetworkInterceptionConfig, PortForward, PortForwardBinding, RequestOptions, Secret, TTYSize, StreamWriter, StreamReader, VFSActionHookFunc, VFSActionRequest, VFSDangerousHookFunc, VFSHookAction, VFSHookEvent, VFSHookFunc, VFSHookOp, VFSHookPhase, VFSHookRule, VFSInterceptionConfig, VFSMutateHookFunc, VFSMutateRequest, } from "./types";

package/dist/types.d.ts

@@ -41,6 +41,15 @@ export interface MountConfig {
     type?: string;
     hostPath?: string;
     readonly?: boolean;
+    ownerUID?: number;
+    ownerGID?: number;
+}
+/** Options accepted by {@link Sandbox.mountHostDir} and {@link Sandbox.mountHostDirReadonly}. */
+export interface MountOwnerOptions {
+    /** UID reported for all files in this mount inside the VM. Must be in [0, 4294967295]. */
+    ownerUID?: number;
+    /** GID reported for all files in this mount inside the VM. Must be in [0, 4294967295]. */
+    ownerGID?: number;
 }
 export interface Secret {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matchlock-sdk",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "TypeScript SDK for Matchlock sandboxes",
   "license": "MIT",
   "repository": {