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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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
+
+- 5bb646e: Remove the product-specific artifact protocol, encryption codec, and Nest composition entry
+  points. `@nestm/storage` remains a generic storage library; applications should compose domain
+  protocols over its clients and provider drivers in their own packages.
+
 ## 0.1.0-alpha.5
 
 ### 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
@@ -43,9 +43,6 @@ Install only the native SDKs required by the chosen provider. For example:
 pnpm add @aws-sdk/client-s3 @aws-sdk/s3-presigned-post \
   @aws-sdk/s3-request-presigner @aws-sdk/lib-storage
 
-# Encrypted artifact storage with AWS KMS
-pnpm add @aws-sdk/client-kms
-
 # Google Cloud Storage
 pnpm add @google-cloud/storage google-auth-library
 
@@ -91,116 +88,185 @@ storage errors and operation types, and `StorageUploadControl`. It has no NestJS
 runtime or declaration imports. Provider adapters remain available through
 `@nestm/storage/files-sdk`.
 
-## Encrypted artifact storage
+## Mounted agent workspaces
 
-The optional `@nestm/storage/artifacts` entry point adds a framework-neutral
-artifact facade over the same provider drivers. Every write is a self-contained
-CAE1 AES-256-GCM envelope; plaintext mode does not exist. The authenticated
-context binds each object to its tenant scope, artifact id, version, path, and
-content type so moving ciphertext to another address fails closed.
+`@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.
 
-Install `@aws-sdk/client-kms` in every artifact-storage consumer. It is an
-optional peer so core-only applications do not download AWS KMS, while artifact
-applications can choose either the local key provider or KMS at runtime.
+```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"]
+```
 
-Set `ARTIFACT_KEY_PROVIDER=local` with a base64-encoded 32-byte `ARTIFACT_KEK`
-(`ARTIFACT_KEK_NAME` is optional), or set `ARTIFACT_KEY_PROVIDER=kms` with
-`ARTIFACT_KMS_KEY_ID` (`ARTIFACT_KMS_REGION` is optional). Invalid or missing
-key configuration aborts startup. `ARTIFACT_ENCRYPTION_READ_LEGACY=true` is a
-temporary, explicit plaintext-read migration flag and never enables plaintext
-writes.
+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 {
-  artifactScope,
-  artifactStorageConfigFromEnv,
-  createArtifactStorage,
-  storageCryptoFromEnv,
-} from '@nestm/storage/artifacts';
-
-const storage = await createArtifactStorage(
-  artifactStorageConfigFromEnv(process.env),
-  storageCryptoFromEnv(process.env),
+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' },
 );
 
-const ref = artifactScope({
-  organizationId: 'org-1',
-  ownerUserId: 'user-1',
-});
+if (created.etag === undefined) {
+  throw new Error('This backend cannot safely replace the object.');
+}
 
-await storage.writeHtml('artifact-1', Buffer.from('<h1>Encrypted</h1>'), {
-  scope: ref,
+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:
 
-const html = await storage.read('artifact-1', 'index.html', {
-  scope: ref,
+```ts
+const readOnlySource = workspace.mount('src', {
+  permissions: ['list', 'read', 'search'],
+  limits: { maxReadBytes: 256 * 1024 },
 });
 ```
 
-`writeBundle()` expands a zip into separately authenticated objects, skips
-traversal and reserved-namespace entries, and rejects case-folded duplicate
-paths, more than 1,000 entries, entries larger than 64 MiB, or more than 256 MiB
-total expanded data. Callers may lower those limits per write. `read()` and
-`readWithInfo()` support directory-to-`index.html` resolution, optional
-plaintext-size limits, and version-bound paths.
-
-`ObjectStore` exposes the same encryption guarantees for non-artifact objects
-such as upload staging and organization media. Keys must begin with a configured
-top-level namespace; the defaults are `_staging` and `org-logos`. Those names
-are reserved as artifact ids, case-insensitively, so artifact and object
-operations cannot address one another even when an object-store provider uses a
-shared bucket root. Override the top-level
-`ArtifactStorageConfig.objectNamespaces` field when an application owns
-different object families.
-
-Keep `objectNamespaces` identical across every reader and writer for a deployed
-store; changing the set is a storage-protocol migration, not a per-process
-preference. On case-insensitive filesystems, use case-stable artifact ids,
-version ids, and object keys (Concepta's lowercase UUID ids satisfy this).
-
-The CAE1 framing and its `{ scope, artifactId, version, path }` context are a
-compatibility contract. Existing envelopes remain readable. Filesystems retain
-the layouts `<root>/<artifactId>/<path>` and `<root>/_objects/<key>`; S3 and
-other object-store providers retain their deployed unprefixed object keys, so a
-rolling upgrade does not split old and new writers across keyspaces. Artifact
-and version ids must each be one safe storage segment. Legacy plaintext reads
-are available only through the explicit
-`ARTIFACT_ENCRYPTION_READ_LEGACY=true` migration flag; writes are always
-encrypted.
-
-The convenience `createArtifactStorage()` and `createObjectStore()` factories
-are ideal for scripts. Long-running framework-neutral processes that need an
-explicit shutdown path should create the raw clients with
-`createArtifactStorageClient()` / `createObjectStorageClient()`, compose them
-with the corresponding `create*WithClient()` function, call each client's
-`onApplicationShutdown()`, and finally call `crypto.keyProvider.clear()`. The
-Nest module owns that lifecycle automatically.
-
-Nest applications can register both adapters with one dynamic module:
+### 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 } from '@nestjs/common';
-import {
-  artifactStorageConfigFromEnv,
-  storageCryptoFromEnv,
-} from '@nestm/storage/artifacts';
-import { ArtifactStorageModule } from '@nestm/storage/artifacts/nest';
+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: [
-    ArtifactStorageModule.forRoot({
-      config: artifactStorageConfigFromEnv(process.env),
-      crypto: storageCryptoFromEnv(process.env),
+    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 AppModule {}
+export class WorkspaceAgentModule {}
 ```
 
-Inject `ArtifactStorage` with `@InjectArtifactStorage()` and `ObjectStore` with
-`@InjectObjectStore()`. The module owns named raw clients (`artifacts` and
-`objects`) and clears cached data keys during application shutdown. Set
-`isGlobal: true` only when both adapters are intentionally application-wide.
+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
 

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"}