@nestm/storage 0.1.0-alpha.0 → 0.1.0-alpha.10

package/SECURITY.md

@@ -23,3 +23,104 @@ cross-store pruning, or dependency compromise are especially useful.
 For a vulnerability originating in NestJS, `files-sdk`, or a provider SDK,
 follow that project's security policy as well. You may still report it here
 privately when this integration needs a mitigation.
+
+## Gateway security boundary
+
+Mounting the optional HTTP gateway requires both authentication guards and a
+`StorageGatewayKeyPolicy`. The policy receives parsed paths and must derive the
+provider key space from trusted request context. Do not treat a client prefix
+or object key as a tenant identifier. `unsafeAllowUnscopedKeys` exists only to
+migrate trusted single-tenant deployments and is unsafe on an exposed gateway.
+
+Signed URL expiry, signed-upload byte size, and signed-upload MIME are bounded
+by module configuration and cannot be increased by a request. Only `inline`
+and `attachment` content dispositions are accepted. File type still must be
+verified from magic bytes after upload; a signed MIME condition proves only
+what header the uploader supplied. The gateway rejects signed-upload drivers
+that do not advertise provider-enforced content-type and size-range policies.
+It also rejects download adapters that cannot guarantee the requested expiry;
+in particular, the S3 bridge does not treat `publicBaseUrl` links as expiring.
+
+For staged uploads on S3, use `promote`/`promoteTo` with the ETag returned by
+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. Pagination cursors are bound
+to the store, normalized physical prefix, stable mount identity, trusted
+tenant/workspace scope, operation, complete effective limits, normalized query,
+and expiry. Provider continuations and prefixes stay inside the encrypted or
+server-side payload. Both layers are non-consuming: a durable opaque token
+store must read rather than consume a record, and an embedded provider cursor
+must remain replayable through a fresh compatible driver against the same
+backend namespace while that provider cursor remains valid and available.
+Provider cursors cannot depend on process-local state; an adapter for a
+consuming or instance-bound backend token must materialize a stable continuation
+before exposing paginated `StorageDriver.list` results.
+
+Under unchanged provider-visible state, cursors are reusable while their
+provider continuation remains valid and available. The authenticated expiry is
+an authorization ceiling, not a guarantee of provider-token lifetime, snapshot
+isolation, provider/network availability, or valid credentials. Provider
+invalidation remains an operational failure, and concurrent mutations remain
+subject to provider ordering, duplicate, and omission semantics.
+
+Production pagination must configure either the built-in AES-256-GCM codec with
+a dedicated shared 32-byte key ring or an authenticated shared durable token
+store. Do not reuse an authentication, session, storage-provider, or encryption
+key from another purpose. All replicas must use the same stable identities and
+key ring, compatible driver configuration, and logical backend namespace. New
+cursors use the active key id; retain prior keys for at least the maximum cursor
+TTL during rotation. Dropping a key, changing a binding field, or restarting
+with a different ephemeral key intentionally invalidates outstanding cursors.
+Tokens and decoded payloads are bounded, and malformed, altered, expired,
+cross-query, cross-operation, cross-workspace, and cross-store cursors fail
+closed.
+
+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. Known post-commit
+failures report `StorageError.applied === true`; a conditional upload also
+carries `appliedEtag` when its committed generation is known. This is positive
+evidence, not a complete remote-commit oracle: a timeout, connection loss, or
+exhausted retry can lose a provider success response and still leave
+`applied === false`. Do not reissue an ambiguous predicate blindly. Reconcile
+the logical destination first, using an exact ETag read when `appliedEtag` is
+available and inspecting the relevant source/destination state for copy or
+delete. 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 route all
+in-process mutations through the package-decorated adapter; its ordinary and
+conditional mutation paths share one lock domain. A separate process,
+unwrapped adapter, or direct filesystem writer can bypass that coordination and
+must not mutate the 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,91 @@
+import { type JSONValue, 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 type AiSdkWorkspaceMutationMode = 'conditional' | 'last-write-wins';
+export interface AiSdkWorkspaceCreateConflict {
+    /** The logical destination inside the mounted workspace. */
+    readonly path: string;
+}
+export type AiSdkWorkspaceCreateConflictMapper<Result extends JSONValue> = (conflict: AiSdkWorkspaceCreateConflict) => PromiseLike<Result> | Result;
+export interface CreateAiSdkWorkspaceToolsOptions<CreateConflictResult extends JSONValue = never> {
+    /** 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;
+    /**
+     * Selects the mutation contract exposed to the model. Conditional mode is
+     * the default; last-write-wins uses the workspace's ordinary Files path.
+     */
+    mutationMode?: AiSdkWorkspaceMutationMode;
+    /**
+     * Maps an atomic create collision to an application result. When omitted,
+     * the collision remains an AiSdkWorkspaceToolError like every other storage
+     * failure. Replace conflicts are never mapped by this hook. This option is
+     * valid only when mutationMode is conditional.
+     */
+    mapCreateConflict?: AiSdkWorkspaceCreateConflictMapper<CreateConflictResult>;
+}
+export type AiSdkWorkspaceToolErrorCode = StorageErrorCodeValue;
+export interface AiSdkWorkspaceToolErrorOptions {
+    /** True when the failed operation may already have committed. */
+    readonly applied?: boolean;
+    /** Canonical ETag of the committed object, when the provider returned one. */
+    readonly appliedEtag?: string;
+}
+/**
+ * Safe error exposed at the AI tool boundary. It deliberately carries no
+ * provider error, storage key, mount prefix, store name, or cause. Applied
+ * reconciliation metadata is retained so callers do not blindly retry a
+ * mutation that may already have committed.
+ */
+export declare class AiSdkWorkspaceToolError extends Error {
+    readonly code: AiSdkWorkspaceToolErrorCode;
+    readonly applied?: true;
+    readonly appliedEtag?: string;
+    constructor(code: AiSdkWorkspaceToolErrorCode, options?: AiSdkWorkspaceToolErrorOptions);
+}
+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<CreateConflictResult extends JSONValue = never>({ workspace, maxReadBytes: requestedMaxReadBytes, mutationMode, requireApproval, mapCreateConflict, }: CreateAiSdkWorkspaceToolsOptions<CreateConflictResult>): 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":"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"}