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

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # @nestm/storage
 
+## 0.1.0-alpha.9
+
+### Minor Changes
+
+- aec25d6: Add explicit last-write-wins workspace write, copy, and unconditional-delete
+  operations that traverse the ordinary Files SDK plugin, hook, and receipt
+  pipeline while retaining the existing native conditional create, replace,
+  copy, move, and delete variants. Unconditional delete requires both `write` and
+  `delete`; move remains conditional-only because a non-atomic
+  download/upload/delete sequence could delete a newer source generation. Add a
+  separate `write` permission and an AI tool factory mutation-mode switch whose
+  default remains conditional.
+
+  Add bounded binary workspace reads through `readBytes`, alongside the existing
+  UTF-8 `readText` API. `readBytes` is a required `StorageWorkspace` member, so
+  custom interface implementations and typed test doubles must add it when
+  upgrading; workspaces returned by `mountStorageWorkspace` need no changes.
+
+### Patch Changes
+
+- 37e0d8d: Fail conditional storage operations closed when caller-configured Files SDK
+  plugins, hooks, or receipts would be bypassed by native adapter extensions.
+  Ordinary operations continue through Files SDK while incompatible conditional
+  capabilities are hidden until Files SDK exposes one shared interception boundary.
+
+## 0.1.0-alpha.8
+
+### Minor Changes
+
+- d81c6f4: Add a typed `mapCreateConflict` hook to the AI SDK workspace adapter so
+  applications can represent atomic create collisions as domain results without
+  mutating generated tools. Keep replace/ETag conflicts fail-closed and sanitize
+  mapper failures at the tool boundary.
+
+  Mark workspace tools with optional inputs or a combined create/replace union as
+  non-strict for provider schema generation while retaining strict Zod runtime
+  validation.
+
+- a0ea392: Add injectable, replica-safe workspace pagination cursors. The workspace now
+  binds versioned cursor payloads to stable store, mount, tenant/workspace, prefix,
+  operation, query, limit, and expiry context; authorizes non-consuming replay
+  before that expiry; and rejects altered or cross-context continuations.
+  Successful continuation still depends on the embedded provider cursor remaining
+  valid and available.
+
+  Export an AES-256-GCM key-ring codec for stateless multi-replica deployments and
+  an asynchronous byte-payload codec contract for shared durable opaque-token
+  stores. Cursor payloads and tokens are bounded, provider continuations remain
+  opaque, and pagination fails closed when no cursor mechanism is configured.
+  Compatible replicas rely on the universal driver contract for non-consuming,
+  instance-portable provider cursors whose position is independent of page size
+  while the provider token remains valid. Cursor expiry is not a provider-token
+  retention, snapshot-isolation, or uptime promise; provider invalidation remains
+  an operational list failure.
+
+- d996b92: Split the aggregate S3 conditional-mutation and copy declarations into exact
+  create, replace, delete, read, source-copy, destination-copy, atomic-promotion,
+  and multipart-completion capabilities. Add independent AWS S3, Cloudflare R2,
+  and fail-closed custom-endpoint profiles that force unverified drivers
+  read-only; enforce complete physical-key byte budgets; normalize provider
+  errors without retaining raw provider payloads or causes; and publish a reusable
+  provider conformance contract with gated filesystem, AWS, R2, and custom suites.
+
+  Normalize every provider ETag to a canonical bare 1–1024-byte visible ASCII
+  token and serialize exactly one HTTP quote pair at S3 request boundaries.
+  Quoted, weak, wildcard, list-shaped, control-bearing, non-ASCII, and otherwise
+  unsafe values now fail closed instead of being accepted as arbitrary non-empty
+  strings. Applications that persisted quoted ETags must refresh them from
+  provider metadata before conditional mutation; this prevents wildcard/list and
+  header-ambiguity inputs from widening an exact-match precondition.
+
+  Specify and test provider list cursors as non-consuming replayable tokens for
+  unchanged provider state, so higher-level replayable pagination can fail closed
+  when a provider cannot meet that contract.
+
+  Exercise the complete advertised source-condition by destination-condition
+  promotion matrix, including stale-state preservation and competing stale/valid
+  requests. Provider documentation or audited implementation evidence remains
+  required for the internal one-linearization-point claim.
+
+  Ordinary and conditional provider failures now expose stable public messages
+  and preserve only normalized codes and retry flags; raw provider bodies,
+  request metadata, and nested causes are not retained in loggable error shapes.
+
+  Raise the `@aws-sdk/client-s3` peer floor to 3.919.0, the first release that
+  serializes destination conditions for `CopyObject`, and verify the real wire
+  headers in the packed minimum-peer consumer. Native AWS construction now
+  disables environment and shared-config endpoint URL overrides, while the public
+  capability helper derives custom-endpoint provenance from the actual SDK client
+  instead of a duplicated caller hint. Capability decoration is now single-use
+  per raw S3 adapter, preventing broader operations from surviving a later
+  narrower profile application.
+
+  Bind S3 provider authority to package-private raw-client and adapter-method
+  identity plus the exact surface snapshot installed by capability decoration.
+  Structurally S3-backed raw adapters are rejected until they pass through the
+  package helper, regardless of adapter name, proxying, or forged global symbols;
+  same-client aliases cannot replace their raw client, ordinary methods, policies,
+  or conditional operations. Unverified custom endpoints and noncanonical
+  S3-backed provider slugs are forced read-only, while an explicit branded profile
+  unlocks only its declared conditional operations. Endpoint and public-URL
+  provenance now follows the adapter actually produced by the provider loader,
+  including `configJson`.
+
+  Retain `publicBaseUrl` construction policy in the package-owned `s3()` helper
+  so omitted decorator hints cannot re-enable an expiring-download claim. Unknown
+  foreign S3 construction conservatively disables that claim. Validate the exact
+  physical adapter key without stripping leading slashes, and include configured
+  separators plus list/search-derived prefixes in the provider byte budget before
+  dispatch. Search uses files-sdk's own inferred glob-prefix and zero-result
+  semantics instead of duplicating its matcher logic. The innermost dispatch guard
+  repeats these checks after supported in-process plugins have transformed an
+  operation; adapters and plugins remain trusted code rather than a sandbox
+  boundary.
+
+  Derive signed-upload policy claims from the branded provider profile instead
+  of granting them to every S3-compatible endpoint. Native AWS proves content
+  type and POST size-range enforcement; Cloudflare R2 proves content type but not
+  POST form size ranges; omitted custom declarations normalize to false/false so
+  the gateway fails closed. Profile authority is backed by a package-private
+  WeakSet after deep freezing, so reflecting and copying the nominal brand symbol
+  cannot forge conformance evidence.
+
+  Treat the built-in AWS profile as an immutable ceiling for every SDK client
+  with native endpoint provenance, independent of mutable adapter display names.
+  Explicit profiles may narrow its operations, policy bits, and key limit but
+  cannot raise the 1,024-byte physical-key budget or add unsupported claims.
+
+  Enforce every requested signed-upload constraint at URL creation time.
+  Content-type-constrained PUT URLs now sign the `content-type` header; bounded
+  AWS uploads use exact POST MIME and byte-range conditions; unsupported profile
+  constraints and lower-only S3 ranges fail before signing. Bounded POST uploads
+  also reject physical keys ending in AWS's `${filename}` template so an exact
+  authorized key cannot be widened into a prefix policy.
+
 ## 0.1.0-alpha.7
 
 ### Minor Changes

package/README.md

@@ -36,6 +36,14 @@ such as `files-sdk/gcs`:
 pnpm add files-sdk@2.2.3
 ```
 
+Pass AWS-SDK-backed S3 adapters through the package-owned `s3()` and
+`withS3Capabilities()` helpers (or use `createS3StorageDriver()`).
+`createFilesSdkDriver()` rejects a structurally S3-backed raw adapter that has
+not crossed this provenance boundary, even when a wrapper renames or proxies
+the adapter. This prevents callers from bypassing endpoint and provider-profile
+checks by omitting the capability decorator or replacing the public `raw`
+property while retaining methods closed over the original client.
+
 Install only the native SDKs required by the chosen provider. For example:
 
 ```sh
@@ -50,6 +58,11 @@ pnpm add @google-cloud/storage google-auth-library
 pnpm add @azure/storage-blob @azure/core-auth @azure/identity
 ```
 
+`@aws-sdk/client-s3` 3.919.0 or newer is required. Earlier releases omit
+destination `If-Match` and `If-None-Match` from the serialized `CopyObject`
+request even when those fields appear in a newer compile-time command shape;
+the package peer range and packed minimum-peer smoke test enforce this floor.
+
 `files-sdk` currently declares its optional Nest peer for Nest 10 and 11. This
 library does not import `files-sdk/nestjs`; the Nest 12 integration is entirely
 owned here. A package manager may nevertheless report that temporary optional
@@ -110,16 +123,51 @@ 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.
 
+Pagination requires a server-owned cursor configuration. The built-in
+`Aes256GcmStorageWorkspaceCursorCodec` produces versioned, authenticated,
+encrypted tokens that can resume on another request, process, or replica when
+every replica constructs an equivalent codec from the same key ring and uses
+the same stable store identity, physical prefix, mount ID, trusted scope, and
+effective limits. Use one codec instance per process, use a dedicated 32-byte
+key, retain rotated decryption keys for at least one cursor TTL, and derive
+`mountId` and `scope` only from authenticated server context.
+
+The underlying driver must also implement the universal replayable list-cursor
+contract against the same logical backend namespace: its cursor cannot be
+consumed or tied to one driver instance. While the provider cursor remains
+valid and available, an outer cursor can be retried until its authenticated
+expiry. That expiry is only an authorization ceiling: it does not extend a
+provider token's lifetime or promise snapshot isolation, provider availability,
+network access, or valid credentials. Provider invalidation is an operational
+list failure, and concurrent object changes remain subject to provider
+continuation semantics. Without a codec, single-page operations still work but
+a continuation fails closed.
+
 ```ts
-import { mountStorageWorkspace } from '@nestm/storage/workspace';
+import {
+  Aes256GcmStorageWorkspaceCursorCodec,
+  mountStorageWorkspace,
+} from '@nestm/storage/workspace';
+
+// cursorKey is a separately validated 32-byte secret from deployment config.
+const cursorCodec = new Aes256GcmStorageWorkspaceCursorCodec({
+  activeKeyId: 'v1',
+  keys: { v1: cursorKey },
+});
 
 const workspace = mountStorageWorkspace(agentFiles, {
   // Use an opaque server-derived run id, never a value selected by the model.
   prefix: `workspaces/${runId}`,
+  cursor: {
+    codec: cursorCodec,
+    mountId: `agent-workspace:${runId}`,
+    scope: `organization:${organizationId}/workspace:${workspaceId}`,
+  },
   permissions: [
     'list',
     'read',
     'search',
+    'write',
     'create',
     'replace',
     'copy',
@@ -127,6 +175,8 @@ const workspace = mountStorageWorkspace(agentFiles, {
     'delete',
   ],
   limits: {
+    cursorTtlMs: 5 * 60 * 1000,
+    maxCursorBytes: 4096,
     maxReadBytes: 1024 * 1024,
     maxWriteBytes: 1024 * 1024,
     maxPageSize: 100,
@@ -150,8 +200,16 @@ await workspace.writeFile('src/main.ts', 'export const ready = false;\n', {
   etag: created.etag,
   contentType: 'text/typescript',
 });
+
+const image = await workspace.readBytes('assets/logo.png');
+console.log(image.bytes.byteLength);
 ```
 
+`readBytes` is now a required member of the exported `StorageWorkspace`
+interface. Workspaces returned by `mountStorageWorkspace` provide it
+automatically; custom implementations and typed test doubles must add the
+method when adopting this alpha minor.
+
 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
@@ -166,6 +224,32 @@ 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.
 
+Callers that prefer the ordinary Files pipeline can opt into explicit
+last-write-wins variants. The `write` permission is separate from conditional
+`create` and `replace` authority:
+
+```ts
+await workspace.writeFile('notes.txt', 'latest contents', {
+  mode: 'overwrite',
+});
+await workspace.copyFile('notes.txt', 'backup.txt', { mode: 'overwrite' });
+await workspace.deleteFile('backup.txt', { mode: 'unconditional' });
+```
+
+Overwrite copy reads the latest source through the ordinary download pipeline,
+enforces `maxWriteBytes` while collecting it, and uploads it through the
+ordinary upload pipeline. It never substitutes the provider's server-side
+copy. These paths compose with Files SDK plugins, hooks, and receipts, including
+the built-in `encryption()` plugin. That plugin is useful compatibility
+evidence, not an Artifact-specific security policy: strict encrypted-only
+reads, tenant/path-bound AAD, key custody and rotation, and copy/move rules
+remain application-owned.
+
+Move remains conditional-only. A last-write-wins download/upload/delete
+sequence could copy one source generation and then delete a newer generation
+written during the transfer. Use the ETag-conditional `moveFile` variant when a
+move is required.
+
 A child mount may further restrict a directory, permissions, or limits, but it
 cannot widen any of them:
 
@@ -220,10 +304,13 @@ import type { ToolSet } from 'ai';
                 // A validated, opaque coordinate from trusted auth/run state.
                 // It is never accepted from a prompt or tool input.
                 prefix: context.storagePrefix,
+                // Includes the singleton codec plus stable mountId and scope.
+                cursor: context.cursorConfiguration,
                 permissions: [
                   'list',
                   'read',
                   'search',
+                  'write',
                   'create',
                   'replace',
                   'copy',
@@ -261,6 +348,32 @@ 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.
 
+`mutationMode` defaults to `'conditional'`. A trusted composition can instead
+select `{ mutationMode: 'last-write-wins' }`; generated mutation schemas then
+omit ETags and modes, hardcode the explicit overwrite/unconditional workspace
+variants, and require `write` permission for destination mutations.
+Unconditional delete requires both `write` and `delete`. The move tool is
+omitted in last-write-wins mode because Workspace move remains conditional-only.
+
+Atomic create collisions remain sanitized tool errors by default. Applications
+that model an existing destination as a normal tool result can map that one
+case while preserving replace/ETag conflicts as failures:
+
+```ts
+const tools = createAiSdkWorkspaceTools({
+  workspace,
+  mapCreateConflict: ({ path }) => ({
+    kind: 'artifact-conflict' as const,
+    path,
+    status: 'already-exists' as const,
+  }),
+});
+```
+
+The mapper receives only the logical workspace path; provider errors, object
+keys, and mount coordinates are never exposed. `mapCreateConflict` is valid
+only in conditional mode and is rejected with last-write-wins mode.
+
 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,
@@ -463,19 +576,77 @@ listStorageProviderSecretEnvVars('s3').map((variable) => variable.key);
 The catalog is pure data and pulls in no adapter, so it is safe in config UIs,
 health checks, and startup validation.
 
-The `s3` slug additionally carries the conditional-promotion and signed-policy
-capabilities described under
-[Race-free staged-object promotion](#race-free-staged-object-promotion); every
-other provider exposes exactly what its adapter declares. When the provider _is_
-known at build time, import `@nestm/storage/files-sdk/s3` or
-`@nestm/storage/files-sdk/fs` directly and skip the indirection.
+The `s3` slug additionally carries the verified per-operation profile and
+signed-policy capabilities described under
+[Exact provider conditions and staged-object promotion](#exact-provider-conditions-and-staged-object-promotion);
+every provider not backed by the AWS S3 SDK exposes what its adapter declares.
+When the provider _is_ known at build time, import
+`@nestm/storage/files-sdk/s3` or `@nestm/storage/files-sdk/fs` directly and skip
+the indirection.
+
+S3 endpoint and public-URL provenance is resolved from the adapter that
+`files-sdk` actually constructs, including values merged from `configJson`.
+An unaudited endpoint forces the driver read-only, and a `publicBaseUrl` removes
+the signed-download TTL guarantee because the resulting public URL does not
+expire. AWS-SDK-backed noncanonical provider slugs (for example an S3-compatible
+provider wrapper) also default to unverified/read-only; only the canonical
+`s3` provider may infer the native AWS profile, and a custom endpoint becomes
+writable only with an explicit branded `S3ProviderProfile`.
+
+Before enabling conditional operations for a custom S3-compatible endpoint,
+run the reusable
+[provider conformance contract](https://github.com/nestm-dev/storage/blob/main/docs/provider-conformance.md)
+against dedicated test credentials. Unknown endpoints are forced read-only and
+receive no inferred conditional capabilities.
+
+## Files SDK responsibility boundary
+
+Files SDK is the upstream authority for the generic storage data plane:
+provider adapters, generic CRUD, bulk and list operations, retries, transfers
+and sync, its plugin pipeline, and framework-neutral gateway mechanics.
+`@nestm/storage` retains the guarantees that Files SDK does not currently
+provide: NestJS 12 named stores, exact native conditional/CAS capabilities,
+`StorageWorkspace` permissions and limits, bounded storage errors, and
+capability-scoped AI tools.
+
+On the alpha.8 base, ordinary `FilesSdkStorageDriver` operations already
+delegate to the Files SDK pipeline. The exception is the native conditional
+adapter extensions: the current Files SDK operation union does not include
+them, so they cannot run through caller-configured Files plugins, hooks, or
+receipts. Until Files SDK provides one interception boundary for ordinary and
+conditional operations, the driver applies this interim fail-closed
+compatibility rule:
+
+| Caller Files configuration                        | Ordinary operations                  | Conditional operations                                   |
+| ------------------------------------------------- | ------------------------------------ | -------------------------------------------------------- |
+| No plugins, active hooks, or receipts             | Files pipeline                       | Advertised when the adapter supports the exact primitive |
+| One or more plugins                               | Files pipeline, including transforms | Hidden; direct invocation returns `NOT_SUPPORTED`        |
+| Any active hook                                   | Files pipeline and hook callbacks    | Hidden; direct invocation returns `NOT_SUPPORTED`        |
+| Receipts enabled with `true` or an options object | Files pipeline and receipts          | Hidden; direct invocation returns `NOT_SUPPORTED`        |
+
+An empty plugin list, an empty hooks object, and `receipts: false` do not trigger
+the gate. NestM's internal physical-key guard does not trigger it either. When
+available, direct conditional paths independently apply prefixing, the
+physical-key budget, mutation read-only restrictions, default
+retry/signal/timeout options, and bounded error mapping. `StoragePlugin` remains
+a separate veto/observation boundary; it is not a substitute for Files body or
+result transforms. This compatibility gate is intended to be removed once
+native CAS can traverse the upstream operation and plugin pipeline rather than
+becoming a second generic CRUD facade here.
+
+`StorageWorkspace` therefore exposes both contracts without weakening either:
+its existing create/replace, exact-read copy/move, and conditional-delete paths
+retain native CAS and this fail-closed gate, while explicit overwrite and
+unconditional-delete variants use the ordinary Files pipeline. Lower-level
+conditional client and driver APIs remain available to callers that need them.
 
 ## Storage API
 
 `StorageClient` exposes:
 
 - `upload`, `downloadStream`, `head`, `exists`, `delete`, `copy`, and `move`;
-- conditional staged-object `promote` when the driver advertises it;
+- exact `uploadConditional`, `downloadConditional`, `deleteConditional`, and
+  staged-object `promote` operations when the driver advertises each primitive;
 - `list`, cursor-aware `listAll`, and lazy `search`;
 - `signDownload` and discriminated PUT/POST `signUpload`;
 - `uploadMany`, `downloadMany`, `headMany`, `existsMany`, and `deleteMany`;
@@ -483,6 +654,24 @@ known at build time, import `@nestm/storage/files-sdk/s3` or
 - provider capability inspection; and
 - pause/resume/abort through `StorageUploadControl`.
 
+Provider list cursors are opaque, non-consuming continuation tokens. Replaying
+the same cursor and page limit against unchanged provider-visible state must
+return an equivalent page and continuation position, even after a descendant
+cursor has been used. A cursor is bound to the logical store, `prefix`, and
+`delimiter`, but not to `limit`, retries, timeout, or abort signal; callers may
+change those transport/page-size options while resuming the same position.
+
+The cursor must work through a newly constructed compatible driver targeting
+the same backend namespace while the provider token remains valid and
+available; it cannot depend on process-, client-, or session-local state. An
+adapter for a consuming or instance-bound provider token must materialize a
+stable continuation before it can provide conforming paginated
+`StorageDriver.list` results. This contract lets a caller safely retry, replay,
+or resume pagination on another replica. It does not promise a provider-token
+lifetime, snapshot isolation across concurrent mutations, or provider,
+network, credential, or authorization availability. Provider invalidation is
+an ordinary list-operation failure.
+
 Downloads are streaming by default:
 
 ```ts
@@ -505,11 +694,54 @@ Node `Readable` uploads are accepted and converted to Web streams without
 buffering. Provider capability gaps fail closed with `StorageError` rather than
 silently discarding a range, metadata, or cache-control request.
 
-### Race-free staged-object promotion
-
-The S3 bridge advertises ETag- and version-conditional server-side copy. This
-lets an application validate a staged object and copy that exact source to its
-final key instead of re-reading whichever bytes occupy the staging key later:
+### Exact provider conditions and staged-object promotion
+
+Capabilities distinguish conditional create, replace, delete, read, source
+copy, destination copy, atomic source-and-destination promotion, and multipart
+completion. They also declare the complete physical-key byte budget. Callers
+must check the exact primitive they need; a missing field is unsupported and is
+never widened from another operation.
+
+The physical-key budget applies to the exact key sent to the adapter. It
+therefore counts leading slashes for unprefixed drivers, the separator added to
+a configured driver prefix, and provider prefixes derived for `list` or
+`search`. Over-budget object keys and explicit list/search prefixes fail before
+provider dispatch rather than being normalized into a shorter key. A glob's
+provider prefix is the exact prefix inferred by files-sdk itself, and that
+derived list operation passes through the same final guard. A non-positive
+`maxResults` performs no provider walk and therefore dispatches no prefix.
+
+Adapters and plugins execute as trusted in-process code; this package does not
+attempt to sandbox a plugin that performs its own network or filesystem I/O.
+For supported plugin pipelines that forward operations through `next`, the
+physical-key guard is the innermost wrapper, after caller plugins and before
+the adapter call. A plugin therefore cannot widen an upload key or list/search
+prefix past the declared byte ceiling while still using the normal dispatch
+pipeline.
+
+Storage-facing ETags have one canonical representation: a bare, case-sensitive
+opaque token with no HTTP quotes. Canonical values contain 1–1024 visible
+ASCII bytes and exclude commas, backslashes, whitespace, control characters,
+`DEL`, non-ASCII text, the `*` wildcard, and case-insensitive `W/` weak-tag
+prefixes. Treat the value as opaque: preserve the exact string returned by
+`head`, reads, or writes and pass it back unchanged to a conditional operation.
+Do not add or remove quotes in application code. S3-compatible drivers remove
+exactly one valid provider-owned quote pair on ingress and add exactly one pair
+when serializing the HTTP header.
+
+This tightens the precondition boundary. Quoted or otherwise non-canonical
+ETags that older versions happened to accept now fail with `INVALID_ARGUMENT`,
+and an unsafe provider result fails with a sanitized `PROVIDER` error instead
+of being exposed as a usable validator. Applications that persisted quoted
+ETags must refresh them with `head` rather than trimming them heuristically.
+Strict normalization prevents a caller-controlled wildcard, entity-tag list,
+weak validator, or malformed header value from widening an operation that
+promises one exact strong match.
+
+The native AWS S3 profile advertises ETag- and version-conditioned server-side
+copy. This lets an application validate a staged object and copy that exact
+source to its final key instead of re-reading whichever bytes occupy the
+staging key later:
 
 ```ts
 import { StorageError, StorageErrorCode } from '@nestm/storage';
@@ -532,9 +764,58 @@ await media.delete(stagingKey);
 ```
 
 `sourceVersion` can select an immutable S3 version and may be combined with
-`sourceEtag`. A promotion without either identity is rejected. Drivers that do
-not publish `capabilities.conditionalCopy` fail with `NOT_SUPPORTED` rather
-than falling back to an unsafe ordinary copy.
+`sourceEtag`. A destination condition can independently require create-only or
+replacement of an exact ETag. Combining source and destination predicates also
+requires `capabilities.conditionalCopyDestination.atomicWithSource`; otherwise
+the request fails with `NOT_SUPPORTED`. A promotion must contain at least one
+source or destination predicate.
+
+Cloudflare R2 has a separate stable profile: create, replace, ETag-conditioned
+read, and ETag-conditioned source copy are enabled, while conditional delete,
+destination copy, atomic promotion, version predicates, and conditional
+multipart completion remain absent. R2 proves content-type binding for
+presigned PUT requests but not POST-form size ranges, so its signed-upload
+policy is `{ contentType: true, sizeRange: false }` and the gateway refuses to
+mint its POST upload form. Cloudflare documents that presigned `POST` form
+uploads are not supported in its
+[presigned URL contract](https://developers.cloudflare.com/r2/api/s3/presigned-urls/).
+Direct R2 signed-upload calls that request a size bound likewise fail with
+`NOT_SUPPORTED` before signing.
+Custom S3-compatible endpoints start with no conditional operations and the
+entire driver is forced read-only until an explicit conformance-verified
+`S3ProviderProfile` is supplied. Omitting `signedUploadPolicy` while defining a
+custom profile normalizes both policy claims to `false`; providers may opt in
+only to constraints their conformance evidence proves.
+
+Successful S3 signed uploads enforce every requested constraint. A request
+with `contentType` and no `maxSize` uses a presigned PUT whose signature
+includes the `content-type` header. A request with `maxSize` uses a POST policy
+with `content-length-range` and, when present, an exact `Content-Type`
+condition. S3 cannot express a lower-only `minSize` through this contract, so
+that shape fails with `NOT_SUPPORTED`; an unclaimed profile constraint also
+fails before credentials are resolved or a URL is minted. Literal physical
+keys ending in AWS's `${filename}` POST template are rejected for bounded
+uploads because the SDK otherwise widens the exact key condition to a prefix.
+
+`withS3Capabilities()` decorates a raw S3 adapter in place and may be applied
+only once. Construct a fresh raw adapter when selecting a different profile;
+reapplying the helper is rejected so a previous broader profile cannot survive
+a later narrower declaration. The selected profile is bound to the exact
+reserved capability and operation members installed by that decoration;
+same-client aliases may change display metadata but cannot add or replace those
+members to widen the profile.
+
+An explicit profile applied to a native AWS SDK endpoint may only narrow the
+immutable `AWS_S3_PROVIDER_PROFILE`. It cannot raise the complete-key budget
+above 1,024 bytes or claim an operation/policy bit absent from the built-in
+profile. This containment follows actual SDK endpoint provenance even when an
+adapter alias changes its display name.
+
+The package-owned `s3()` factory also retains whether `publicBaseUrl` was
+configured even when the second `withS3Capabilities()` options object is
+omitted. In that case `signedDownloadPolicy.expiresIn` is false. Foreign S3
+adapters whose construction metadata is unavailable receive the same
+conservative false value instead of claiming an enforceable TTL.
 
 ### Resumable uploads
 
@@ -676,8 +957,11 @@ by `maxSignedUploadBytes`, and require an exact lowercase MIME type from
 `attachment` or `inline` response disposition; arbitrary response-header text
 and filenames are rejected. A driver must also advertise
 `signedUploadPolicy.contentType` and `signedUploadPolicy.sizeRange`; otherwise
-the gateway refuses to mint the URL. `createS3StorageDriver()` advertises both
-and uses S3 POST policy conditions. Signed downloads similarly require
+the gateway refuses to mint the URL. Native AWS advertises both and uses S3
+POST policy conditions. R2 advertises content-type enforcement but not a POST
+size range, while omitted custom declarations normalize both claims to false;
+the gateway therefore fails closed for those profiles. Signed downloads
+similarly require
 `signedDownloadPolicy.expiresIn`. The S3 factory advertises it only when no
 permanent `publicBaseUrl` was configured, preventing a configured TTL from
 silently returning a non-expiring public link.

package/SECURITY.md

@@ -56,11 +56,40 @@ 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.
+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