@nestm/storage 0.1.0-alpha.6 → 0.1.0-alpha.7

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @nestm/storage
 
+## 0.1.0-alpha.7
+
+### Minor Changes
+
+- 842ff34: Add a backend-neutral `StorageWorkspace` capability and optional AI SDK 7 tool
+  adapter. Workspaces expose only canonical mount-relative paths, enforce
+  permissions and resource limits, hide provider coordinates and cursors, and use
+  atomic create/ETag mutation preconditions. S3 now advertises and implements the
+  conditional mutation primitives used by writable workspaces.
+
+  Harden local filesystem workspace reads and conditional mutations against
+  symlink aliases. Moves retain their create-only destination whenever source
+  deletion cannot be confirmed, avoiding data loss after provider or
+  post-operation hook ambiguity.
+
+  Fix cross-store sync so `destinationPrefix` is applied to uploaded keys as well
+  as pruning, keeping every mutation inside the selected destination scope.
+
 ## 0.1.0-alpha.6
 
 ### Minor Changes

package/README.md

@@ -1,8 +1,8 @@
 # @nestm/storage
 
 Framework-neutral storage clients with NestJS 12 integration, named stores,
-explicit streaming I/O, cross-store workflows, and an optional guarded HTTP
-gateway.
+explicit streaming I/O, capability-scoped agent workspaces, cross-store
+workflows, and an optional guarded HTTP gateway.
 
 The package uses [`files-sdk`](https://github.com/haydenbleasel/files-sdk) as
 its provider engine, but owns the API injected into Nest applications. Provider
@@ -88,6 +88,186 @@ storage errors and operation types, and `StorageUploadControl`. It has no NestJS
 runtime or declaration imports. Provider adapters remain available through
 `@nestm/storage/files-sdk`.
 
+## Mounted agent workspaces
+
+`@nestm/storage/workspace` turns a `StorageClient` into a narrow capability for
+one logical directory. The mount is virtual: the same API works over S3, a
+filesystem driver, or another storage backend without exposing the provider,
+bucket, filesystem root, raw cursor, or internal prefix to its caller.
+
+```mermaid
+flowchart LR
+  A["Trusted application context"] -->|"store + opaque prefix + policy"| W["StorageWorkspace"]
+  W --> C["StorageClient"]
+  C --> D["S3 / filesystem / other driver"]
+  W --> T["AI SDK workspace tools"]
+  T --> G["ToolLoopAgent"]
+```
+
+Only trusted application code chooses the mount prefix. Every path accepted by
+the workspace is a canonical, relative POSIX path. Absolute paths, backslashes,
+control characters, repeated separators, and `.` or `..` segments are rejected
+rather than normalized. Keys and provider cursors returned by a driver are also
+checked before they are converted back to logical paths.
+
+```ts
+import { mountStorageWorkspace } from '@nestm/storage/workspace';
+
+const workspace = mountStorageWorkspace(agentFiles, {
+  // Use an opaque server-derived run id, never a value selected by the model.
+  prefix: `workspaces/${runId}`,
+  permissions: [
+    'list',
+    'read',
+    'search',
+    'create',
+    'replace',
+    'copy',
+    'move',
+    'delete',
+  ],
+  limits: {
+    maxReadBytes: 1024 * 1024,
+    maxWriteBytes: 1024 * 1024,
+    maxPageSize: 100,
+    maxSearchResults: 100,
+    maxSearchScan: 1000,
+  },
+});
+
+const created = await workspace.writeFile(
+  'src/main.ts',
+  'export const ready = true;\n',
+  { mode: 'create', contentType: 'text/typescript' },
+);
+
+if (created.etag === undefined) {
+  throw new Error('This backend cannot safely replace the object.');
+}
+
+await workspace.writeFile('src/main.ts', 'export const ready = false;\n', {
+  mode: 'replace',
+  etag: created.etag,
+  contentType: 'text/typescript',
+});
+```
+
+Create, replace, and delete are conditional operations. A driver that cannot
+enforce the requested not-exists or ETag precondition fails with
+`NOT_SUPPORTED`; the workspace never substitutes an `exists()`/`head()` check
+followed by an unconditional mutation. Reads enforce their byte ceiling while
+consuming the stream, and list/search results are bounded. Search supports
+exact, substring, and workspace-coordinate glob matching, but no caller-supplied
+regular expressions.
+
+Move is implemented as create-only copy followed by ETag-conditional source
+delete. If source deletion cannot be confirmed, the destination is retained and
+the call returns `CONFLICT`; inspect both logical paths before retrying. This
+preserves at least one copy across provider timeouts and post-operation hook
+failures, but does not pretend a multi-object move is transactionally atomic.
+
+A child mount may further restrict a directory, permissions, or limits, but it
+cannot widen any of them:
+
+```ts
+const readOnlySource = workspace.mount('src', {
+  permissions: ['list', 'read', 'search'],
+  limits: { maxReadBytes: 256 * 1024 },
+});
+```
+
+### AI SDK and NestJS composition
+
+Install AI SDK 7 and Zod only in applications that use the optional adapter:
+
+```sh
+pnpm add ai@^7 zod@^4
+```
+
+`files-sdk` 2.2.x still declares an optional `ai@^6` peer for its own adapter,
+so some package managers may print a peer warning when AI SDK 7 is installed.
+This package does not import that adapter; `@nestm/storage/ai-sdk` targets AI
+SDK 7 directly.
+
+`@nestm/storage/ai-sdk` converts an already-mounted workspace to an ordinary
+upstream `ToolSet`. It does not import NestJS or `@nestm/ai-sdk`; the application
+composes the tool set through the AI module's existing named-toolset factory.
+For a tenant or run selected per request, make both factories request-scoped and
+derive the mount coordinate from authenticated host context:
+
+```ts
+import { Module, Scope } from '@nestjs/common';
+import { AiSdkModule, AiSdkService, getAiToolsetToken } from '@nestm/ai-sdk';
+import { getStorageToken, type StorageClient } from '@nestm/storage';
+import { createAiSdkWorkspaceTools } from '@nestm/storage/ai-sdk';
+import { mountStorageWorkspace } from '@nestm/storage/workspace';
+import type { ToolSet } from 'ai';
+
+@Module({
+  imports: [
+    AppStorageModule,
+    WorkspaceContextModule,
+    AiSdkModule.forFeature({
+      imports: [AppStorageModule, WorkspaceContextModule],
+      toolsets: [
+        {
+          name: 'workspace',
+          scope: Scope.REQUEST,
+          inject: [getStorageToken('agent-files'), WorkspaceContext],
+          useFactory: (storage: StorageClient, context: WorkspaceContext) =>
+            createAiSdkWorkspaceTools({
+              workspace: mountStorageWorkspace(storage, {
+                // A validated, opaque coordinate from trusted auth/run state.
+                // It is never accepted from a prompt or tool input.
+                prefix: context.storagePrefix,
+                permissions: [
+                  'list',
+                  'read',
+                  'search',
+                  'create',
+                  'replace',
+                  'copy',
+                  'move',
+                  'delete',
+                ],
+              }),
+            }),
+        },
+      ],
+      agents: [
+        {
+          name: 'workspace-agent',
+          scope: Scope.REQUEST,
+          inject: [AiSdkService, getAiToolsetToken('workspace')],
+          useFactory: (ai: AiSdkService, tools: ToolSet) => ({
+            model: ai.languageModel(),
+            instructions:
+              'Use only the mounted workspace tools for file operations.',
+            tools,
+          }),
+        },
+      ],
+    }),
+  ],
+})
+export class WorkspaceAgentModule {}
+```
+
+The generated set contains only tools allowed by the workspace permissions:
+bounded list, stat, UTF-8 read, and search tools plus conditional create,
+replace, copy, move, and delete tools when granted. Mutation tools require AI
+SDK user approval by default; approval can be configured per tool, but the
+workspace capability remains the authorization boundary even when approval is
+disabled. The module's `AiSdkService.files()` API is the model provider's file
+upload facility and is unrelated to storage workspaces.
+
+This logical confinement is sufficient for a `ToolLoopAgent` whose only file
+capabilities are these tools. It cannot constrain a coding harness that already
+has shell, `node:fs`, or subprocess access. For Codex/Claude-style harnesses,
+materialize the workspace into a per-session container or VM, mount only that
+directory, run the harness there, and synchronize reviewed changes back through
+`StorageWorkspace`. A working directory alone is not a sandbox.
+
 ## Configure named stores
 
 Use the package-owned S3 factory when applicable. For other providers, create a

package/SECURITY.md

@@ -46,3 +46,43 @@ the validated `head` or with an immutable provider version. Ordinary `copy`
 does not protect against a staging-key replay between validation and copy.
 Conditional promotion keeps the staging source; delete it only after the
 application's metadata transaction commits.
+
+## Workspace security boundary
+
+`StorageWorkspace` is a narrowing capability for storage operations. Construct
+it from trusted application context, keep the underlying `StorageClient` and
+mount prefix private, and pass only the workspace or its AI tool set to
+untrusted agent code. A tenant id, run id, prefix, provider cursor, snapshot id,
+or fork id supplied by a model is not a safe mount coordinate.
+
+The workspace accepts only canonical mount-relative POSIX paths and rechecks
+every key returned by a driver before unscoping it. Its cursors are opaque and
+bound to the mount and query. Permissions, byte limits, result limits, and
+conditional mutation preconditions are enforced inside the capability; tool
+omission and user approval are additional workflow controls, not the
+authorization boundary.
+
+Conditional mutations can still have an ambiguous outcome when a remote
+provider commits and then loses or violates its response, or when a configured
+post-operation plugin fails after the driver has committed. The API fails
+closed in that case: inspect the logical destination and reconcile it before
+retrying. Create-only and ETag preconditions prevent a blind retry from
+silently overwriting a different object, but they cannot make a multi-object
+move transactionally atomic.
+
+This guarantee covers calls made through `StorageWorkspace`. It does not
+confine arbitrary `node:fs`, shell, subprocess, or native-code access in the
+same process. A coding harness with built-in shell or filesystem tools must run
+inside an OS sandbox (container, VM, or equivalent) that exposes only a
+materialized workspace. Setting `cwd` to a workspace directory is not
+isolation.
+
+For local filesystem storage, use a dedicated service-owned root and do not let
+another untrusted process mutate its directory tree concurrently. High-level
+Node filesystem checks reject symlinks and hard-linked object files in existing
+workspace read and mutation paths, including metadata sidecars, but cannot
+provide a race-proof boundary against an actor that can replace path components
+between validation and use. For that threat model, mount only the workspace
+into a separate UID/container/VM and synchronize approved results back through
+storage. The local adapter also commits the body and metadata sidecar as two
+files; a process crash between their atomic renames can require reconciliation.

package/dist/ai-sdk/ai-sdk-workspace-tools.d.ts

@@ -0,0 +1,63 @@
+import { type ToolSet } from 'ai';
+import { type StorageWorkspace } from '../workspace/index.js';
+import { type StorageErrorCode as StorageErrorCodeValue } from '../storage.error.js';
+export declare const AI_SDK_WORKSPACE_TOOL_NAMES: readonly ['workspace_list', 'workspace_stat', 'workspace_read_file', 'workspace_search', 'workspace_write_file', 'workspace_copy_file', 'workspace_move_file', 'workspace_delete_file'];
+export type AiSdkWorkspaceToolName = (typeof AI_SDK_WORKSPACE_TOOL_NAMES)[number];
+export type AiSdkWorkspaceMutationToolName = Extract<AiSdkWorkspaceToolName, 'workspace_write_file' | 'workspace_copy_file' | 'workspace_move_file' | 'workspace_delete_file'>;
+/**
+ * Approval policy for mutation tools. An omitted entry defaults to requiring
+ * approval, matching an omitted policy.
+ */
+export type AiSdkWorkspaceApprovalConfig = boolean | Partial<Record<AiSdkWorkspaceMutationToolName, boolean>>;
+export interface CreateAiSdkWorkspaceToolsOptions {
+    /** The already-mounted, policy-enforcing workspace exposed to the tools. */
+    workspace: StorageWorkspace;
+    /**
+     * Optional tighter read ceiling. Values above the workspace ceiling are
+     * clamped; the model cannot choose or raise this value.
+     */
+    maxReadBytes?: number;
+    /** Mutation tools require approval by default. */
+    requireApproval?: AiSdkWorkspaceApprovalConfig;
+}
+export type AiSdkWorkspaceToolErrorCode = StorageErrorCodeValue;
+/**
+ * Safe error exposed at the AI tool boundary. It deliberately carries no
+ * provider error, storage key, mount prefix, store name, or cause.
+ */
+export declare class AiSdkWorkspaceToolError extends Error {
+    readonly code: AiSdkWorkspaceToolErrorCode;
+    constructor(code: AiSdkWorkspaceToolErrorCode);
+}
+export interface AiSdkWorkspaceFileResult {
+    kind: 'file';
+    path: string;
+    name: string;
+    size: number;
+    contentType: string;
+    etag?: string;
+    lastModified?: string;
+}
+export interface AiSdkWorkspaceDirectoryResult {
+    kind: 'directory';
+    path: string;
+    name: string;
+}
+export type AiSdkWorkspaceEntryResult = AiSdkWorkspaceFileResult | AiSdkWorkspaceDirectoryResult;
+export interface AiSdkWorkspaceTextFileResult extends AiSdkWorkspaceFileResult {
+    text: string;
+}
+export interface AiSdkWorkspacePageResult {
+    entries: AiSdkWorkspaceEntryResult[];
+    cursor?: string;
+}
+/**
+ * Creates Vercel AI SDK tools backed only by a mounted StorageWorkspace.
+ *
+ * A tool is omitted unless the workspace grants its required permission.
+ * The workspace remains the enforcing boundary if a retained tool reference
+ * is invoked after further narrowing.
+ */
+export declare function createAiSdkWorkspaceTools({ workspace, maxReadBytes: requestedMaxReadBytes, requireApproval, }: CreateAiSdkWorkspaceToolsOptions): ToolSet;
+export declare function isAiSdkWorkspaceMutationToolName(value: string): value is AiSdkWorkspaceMutationToolName;
+//# sourceMappingURL=ai-sdk-workspace-tools.d.ts.map

package/dist/ai-sdk/ai-sdk-workspace-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk-workspace-tools.d.ts","sourceRoot":"","sources":["../../src/ai-sdk/ai-sdk-workspace-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAGxC,OAAO,EAEL,KAAK,gBAAgB,EAItB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,gBAAgB,IAAI,qBAAqB,EAC/C,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,2BAA2B,YACtC,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,CACf,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAClD,sBAAsB,EACpB,sBAAsB,GACtB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACtC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,8BAA8B,EAAE,OAAO,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,gCAAgC;IAC/C,4EAA4E;IAC5E,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,eAAe,CAAC,EAAE,4BAA4B,CAAC;CAChD;AAED,MAAM,MAAM,2BAA2B,GAAG,qBAAqB,CAAC;AAsBhE;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAE3C,YAAY,IAAI,EAAE,2BAA2B,EAI5C;CACF;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,yBAAyB,GACnC,wBAAwB,GAAG,6BAA6B,CAAC;AAE3D,MAAM,WAAW,4BAA6B,SAAQ,wBAAwB;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA2MD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,SAAS,EACT,YAAY,EAAE,qBAAqB,EACnC,eAAsB,GACvB,EAAE,gCAAgC,GAAG,OAAO,CA2R5C;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,8BAA8B,CAEzC"}