@voltro/plugin-storage 0.86.0 → 0.88.0

package/dist/types.d.ts

@@ -1,9 +1,21 @@
+import { ByteStream } from '@voltro/kv/storage';
 import { Context } from 'effect';
 import { Effect } from 'effect';
+import { isStorageKey } from '@voltro/kv/storage';
+import { ObjectMeta } from '@voltro/kv/storage';
 import { Schema } from 'effect';
 import { StorageAccessPolicy } from '@voltro/protocol';
 import { StorageAccessRule } from '@voltro/protocol';
-import { Stream } from 'effect';
+import { StorageAddress } from '@voltro/kv/storage';
+import { storageAddressIdentity } from '@voltro/kv/storage';
+import { StorageDestination } from '@voltro/kv/storage';
+import { StorageDestinationRouter } from '@voltro/kv/storage';
+import { StorageError } from '@voltro/kv/storage';
+import { StorageObjectLocation } from '@voltro/kv/storage';
+import { StorageProvider } from '@voltro/kv/storage';
+import { StorageProviderName } from '@voltro/kv/storage';
+import { StoredObject } from '@voltro/kv/storage';
+import { StoredStream } from '@voltro/kv/storage';
 import { Subject } from '@voltro/protocol';
 import { YieldableError } from 'effect/Cause';
 
@@ -17,14 +29,7 @@ export declare type AccessPolicy = StorageAccessPolicy;
  */
 export declare type AccessRule = StorageAccessRule;
 
-/**
- * A lazy stream of bytes — the streaming counterpart to {@link StoredObject}'s
- * eager `bytes`. Backpressured: chunks are pulled on demand, so a multi-GB blob
- * never fully materialises in memory. The error channel is {@link StorageError}
- * so a stream handed to `putStream` carries the same typed failure the rest of
- * the transport does (callers map their source errors into it).
- */
-export declare type ByteStream = Stream.Stream<Uint8Array, StorageError>;
+export { ByteStream }
 
 /** Input to `StorageService.grant`. */
 export declare interface GrantInput {
@@ -40,6 +45,8 @@ export declare type GrantPermission = 'read' | 'write';
 
 export declare type GrantPrincipalType = 'user' | 'group' | 'apiKey';
 
+export { isStorageKey }
+
 /**
  * Filter + page a `StorageService.listRefs` / media-library query. Every
  * filter is optional and ANDed; omit them all to page the whole (tenant-scoped)
@@ -75,17 +82,15 @@ export declare interface ListRefsResult {
     readonly nextOffset: number | null;
 }
 
-/** Result of a provider `put` / `head`. */
-export declare interface ObjectMeta {
-    readonly size: number;
-    readonly etag?: string;
-}
+export { ObjectMeta }
 
 /** A ref with the server-only `passwordHash` removed — safe to serialize. */
 export declare type PublicStorageRef = Omit<StorageRef, 'passwordHash'>;
 
 /** Input to `StorageService.put`. */
 export declare interface PutInput {
+    /** Server-owned logical destination; omitted new writes use this plugin's selection. */
+    readonly destination?: string;
     readonly bytes: Uint8Array;
     readonly contentType: string;
     /** Active org id — scopes the key prefix + the ref row. */
@@ -148,6 +153,8 @@ export declare type PutOutcome = 'created' | 'resumed' | 'joined';
 /** One derived output a `Transcoder` produces from a source asset. Each becomes
  *  a normal storage ref linked back to the original via `derivedFrom`. */
 export declare interface Rendition {
+    /** Optional structured producer attestation; unproven outputs keep it absent. */
+    readonly derivation?: RenditionDerivation;
     readonly bytes: Uint8Array;
     readonly contentType: string;
     /** Derivative class — e.g. `'rendition'` (a playable variant) or `'poster'`. */
@@ -156,6 +163,39 @@ export declare interface Rendition {
     readonly label?: string;
 }
 
+/** Producer attestation. Digests bind a normalized recipe and the observed
+ * engine build; the consumer still admits allowed recipes, engines and rights. */
+export declare interface RenditionDerivation {
+    readonly recipe: {
+        readonly format: string;
+        readonly digest: string;
+    };
+    readonly engine: {
+        readonly name: string;
+        readonly version: string;
+        readonly digest: string;
+    };
+}
+
+/** Storage-verified input/output identity around a producer attestation.
+ * Not an approval, rights grant or proof of complete external dependencies. */
+export declare interface RenditionProof extends RenditionDerivation {
+    readonly version: 1;
+    readonly source: {
+        readonly id: string;
+        readonly metadataDigest: string;
+        readonly checksum: string;
+        readonly size: number;
+        readonly contentType: string;
+    };
+    readonly output: {
+        readonly checksum: string;
+        readonly size: number;
+        readonly contentType: string;
+    };
+    readonly digest: string;
+}
+
 /**
  * Access to a private object was refused. Distinct from `StorageError` so
  * handlers can tell "not allowed" (403) from "backend blew up" (5xx) and
@@ -169,20 +209,15 @@ declare const StorageAccessDenied_base: Schema.Class<StorageAccessDenied, Schema
     readonly reason: Schema.String;
 }>, YieldableError>;
 
-/**
- * Storage failure. `transient` drives retry — `true` for 429 / 5xx /
- * network blips, `false` for 4xx / config / not-found. Surfaced typed so
- * handlers can `Effect.catchTag('StorageError', …)`.
- */
-export declare class StorageError extends StorageError_base {
-}
+export { StorageAddress }
 
-declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
-    readonly provider: Schema.String;
-    readonly message: Schema.String;
-    readonly transient: Schema.Boolean;
-    readonly status: Schema.optional<Schema.Number>;
-}>, YieldableError>;
+export { storageAddressIdentity }
+
+export { StorageDestination }
+
+export { StorageDestinationRouter }
+
+export { StorageError }
 
 /** A persisted, explicit share of one object with one principal. */
 export declare interface StorageGrant {
@@ -202,100 +237,27 @@ export declare type StorageGuard = (ctx: {
     readonly ref: StorageRef;
 }) => boolean | Promise<boolean> | Effect.Effect<boolean>;
 
-/**
- * A backend transport. Keyed by an opaque object key (the service owns key
- * derivation + tenant prefixing); knows nothing about refs, tenants, or
- * access policy.
- */
-export declare interface StorageProvider {
-    /** Stable physical object-key namespace; exclude credentials and plugin aliases. */
-    readonly objectNamespace: Effect.Effect<string, StorageError>;
-    /**
-     * Where a FILESYSTEM provider writes. Absent for every other provider.
-     *
-     * It exists so a caller can ask a question this interface otherwise cannot
-     * answer: does what I write here survive the process? A rollback capture
-     * written for a pod that then dies is worthless, and `filesystem` is the one
-     * provider that can be either — a mounted volume or an ephemeral container
-     * directory. A deployment pointed this out: their check for "storage is
-     * configured" passed on a `/tmp` path with no volume behind it.
-     */
-    readonly root?: string;
-    readonly name: string;
-    /** True when `getUrl` returns a real presigned URL (s3/minio). When
-     *  false the service serves bytes via the `/_voltro/storage/:id`
-     *  endpoint instead (filesystem/memory). */
-    readonly presigns: boolean;
-    readonly put: (key: string, bytes: Uint8Array, meta: {
-        readonly contentType: string;
-        readonly public?: boolean;
-    }) => Effect.Effect<ObjectMeta, StorageError>;
-    readonly get: (key: string) => Effect.Effect<StoredObject, StorageError>;
-    readonly delete: (key: string) => Effect.Effect<void, StorageError>;
-    /** Presigned GET (s3/minio) for private reads. */
-    readonly getUrl: (key: string, expiresInSec: number) => Effect.Effect<string, StorageError>;
-    /** A direct, cacheable URL for a PUBLIC object — virtual-hosted bucket
-     *  URL or a configured CDN base. `null` when the provider can't serve
-     *  publicly without the app (filesystem/memory) → the service falls
-     *  back to the `/_voltro/storage/:id` route. */
-    readonly publicUrl?: (key: string) => string | null;
-    /** Make an object publicly readable at the provider, or not (s3/minio with
-     *  per-object ACLs). Absent where the app decides per request (database,
-     *  filesystem, memory) — there a ref's visibility is the whole answer. */
-    readonly setObjectPublic?: (key: string, isPublic: boolean) => Effect.Effect<void, StorageError>;
-    /** Presigned PUT for direct-to-bucket uploads (s3/minio). Absent on
-     *  providers that can't presign uploads. */
-    readonly getUploadUrl?: (key: string, expiresInSec: number, contentType: string) => Effect.Effect<string, StorageError>;
-    readonly createMultipartUpload?: (key: string, contentType: string, opts?: {
-        readonly public?: boolean;
-    }) => Effect.Effect<{
-        readonly uploadId: string;
-    }, StorageError>;
-    readonly presignUploadPart?: (key: string, uploadId: string, partNumber: number, expiresInSec: number) => Effect.Effect<string, StorageError>;
-    readonly completeMultipartUpload?: (key: string, uploadId: string, parts: ReadonlyArray<{
-        readonly partNumber: number;
-        readonly etag: string;
-    }>) => Effect.Effect<{
-        readonly etag?: string;
-    }, StorageError>;
-    readonly abortMultipartUpload?: (key: string, uploadId: string) => Effect.Effect<void, StorageError>;
-    readonly head: (key: string) => Effect.Effect<ObjectMeta | null, StorageError>;
-    /**
-     * Stream an object's bytes in chunks instead of buffering the whole blob
-     * ({@link get}). Present on backends with a real streaming read (filesystem,
-     * s3, azure). OPTIONAL: when a provider omits it, {@link getObjectStream}
-     * transparently falls back to `get` + a chunked in-memory stream — correct
-     * for the small-blob backends (memory / database) that have nothing to
-     * stream from.
-     */
-    readonly getStream?: (key: string) => Effect.Effect<StoredStream, StorageError>;
-    /**
-     * Consume a {@link ByteStream} and store it via the backend's chunked /
-     * multipart upload, so a large upload never fully materialises in memory.
-     * Present on filesystem (streamed atomic write), s3 (multipart via
-     * `@aws-sdk/lib-storage`), azure (`uploadStream`). OPTIONAL: when absent,
-     * {@link putObjectStream} buffers the stream and calls `put`. `totalSize`,
-     * when the caller knows it (e.g. from an export manifest), lets the backend
-     * report an accurate size without a follow-up HEAD.
-     */
-    readonly putStream?: (key: string, stream: ByteStream, meta: {
-        readonly contentType: string;
-        readonly public?: boolean;
-        readonly totalSize?: number;
-    }) => Effect.Effect<ObjectMeta, StorageError>;
-    /**
-     * Read a byte range `[start, endInclusive]` (HTTP Range / fd offset). Enables
-     * seekable + resumable reads. OPTIONAL and best-effort: whole-object resume
-     * already works via content-addressing (skip an asset whose hash is present
-     * at the target), so this is an optimisation, not a correctness requirement.
-     */
-    readonly getRange?: (key: string, start: number, endInclusive: number) => Effect.Effect<Uint8Array, StorageError>;
-    /** Providers that store bytes via the app's DataStore (e.g. `database`)
-     *  receive it here once it exists — bound by the plugin at boot. */
-    readonly bindDataStore?: (store: unknown) => void;
-}
+export { StorageObjectLocation }
+
+/** A durable metadata observation, not a claim on the object or a provider HEAD. */
+export declare type StorageOperationState = {
+    readonly state: 'absent' | 'reserved' | 'deleting' | 'deleted';
+} | {
+    readonly state: 'ready';
+    readonly ref: StorageRef;
+};
+
+/** Metadata state qualified by the actual selected storage destination. */
+export declare type StorageOperationStatus = StorageOperationState & {
+    /** Configured instance, actual catalogue, physical namespace and logical bucket. */
+    readonly scope: string;
+    /** Selected logical destination; retain it with the scope before minting a ticket. */
+    readonly destination: string;
+};
 
-export declare type StorageProviderName = 's3' | 'minio' | 'azure' | 'filesystem' | 'memory' | 'database';
+export { StorageProvider }
+
+export { StorageProviderName }
 
 /**
  * Metadata row for a stored blob — the bytes live in object storage; this
@@ -335,8 +297,13 @@ export declare interface StorageRef {
     readonly derivedFrom?: string | null;
     /** Derivative label — e.g. `'rendition'` / `'poster'`; null on an original. */
     readonly kind?: string | null;
+    /** Immutable provenance for an attested transcode; absent on older/unproven refs. */
+    readonly renditionProof?: RenditionProof | null;
 }
 
+/** Persisted destination ownership is independent of the current write selection. */
+export declare const storageRefAddress: (ref: Pick<StorageRef, "bucket" | "tenantId" | "key">) => StorageAddress;
+
 /** An upload was rejected by a constraint (size / content-type / magic-byte
  *  mismatch). `reason` is a stable code; `detail` is human-readable. */
 export declare class StorageRejected extends StorageRejected_base {
@@ -378,8 +345,20 @@ declare const StorageService_base: Context.ServiceClass<StorageService, "@voltro
 
 /** The service handlers consume: `const storage = yield* StorageService`. */
 export declare interface StorageServiceShape {
+    /** Trusted server read of one raw durable put identity in this configured
+     * instance/physical namespace/bucket and the explicitly supplied tenant.
+     * No access-policy check, claim, byte read, retry write or provider HEAD.
+     * Unbound/unsupported/corrupt metadata refuses; it never becomes absence. */
+    readonly operationStatus: (input: {
+        readonly operationId: string;
+        readonly tenantId: string | null;
+        readonly destination?: string;
+    }) => Effect.Effect<StorageOperationStatus, StorageError>;
     /** Opaque destination binding for manually signed upload-family credentials. */
-    readonly uploadTicketScope: () => Effect.Effect<string, StorageError>;
+    readonly uploadTicketScope: (input?: {
+        readonly tenantId?: string | null;
+        readonly destination?: string;
+    }) => Effect.Effect<string, StorageError>;
     /** Store bytes. The result is the ref plus this call's `outcome`. */
     readonly put: (input: PutInput) => Effect.Effect<StoredRef, StorageError | StorageRejected | StorageScanRejected>;
     /** Fetch an object's bytes by id. Enforces the tenant guard ONLY — it does
@@ -550,9 +529,9 @@ export declare interface StorageServiceShape {
         readonly contentType: string;
         readonly tenantId?: string | null;
         readonly expiresInSec?: number;
-    }) => Effect.Effect<{
+    }) => Effect.Effect<StorageAddress & {
+        readonly writeScope: string;
         readonly uploadUrl: string;
-        readonly key: string;
         readonly expiresInSec: number;
     }, StorageError>;
     /** Promote a blob the client PUT directly to a TEMP `key` into a real ref:
@@ -561,6 +540,7 @@ export declare interface StorageServiceShape {
      *  scanned + a non-degraded ref — out of band from the direct PUT. On a scan
      *  reject the temp bytes are deleted (fail-closed, nothing promoted). */
     readonly finalizeUpload: (input: {
+        readonly destination: string;
         readonly key: string;
         readonly contentType: string;
         readonly tenantId?: string | null;
@@ -575,6 +555,7 @@ export declare interface StorageServiceShape {
     /** Store one chunk of a resumable upload as its own durable `_incoming/<id>/
      *  <index>` object. Idempotent — re-PUTting the same index overwrites it. */
     readonly putResumableChunk: (input: {
+        readonly destination: string;
         readonly uploadId: string;
         readonly index: number;
         readonly bytes: Uint8Array;
@@ -584,6 +565,7 @@ export declare interface StorageServiceShape {
      *  0 and returns the received byte `offset` + the `nextIndex` to send. Lets a
      *  reconnecting client resume instead of restarting. */
     readonly resumableStatus: (input: {
+        readonly destination: string;
         readonly uploadId: string;
         readonly tenantId?: string | null;
     }) => Effect.Effect<{
@@ -594,6 +576,7 @@ export declare interface StorageServiceShape {
      *  concatenate, run the FULL `put()` pipeline, then delete the chunk objects
      *  (on success AND on reject — fail-closed). */
     readonly finalizeResumable: (input: {
+        readonly destination: string;
         readonly uploadId: string;
         readonly count: number;
         readonly contentType: string;
@@ -625,12 +608,14 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly visibility?: StorageVisibility;
         readonly expiresInSec?: number;
-    }) => Effect.Effect<{
+    }) => Effect.Effect<StorageAddress & {
+        readonly writeScope: string;
         readonly uploadId: string;
-        readonly key: string;
     }, StorageError>;
     /** Presign a PUT for one part (1-based `partNumber`). */
     readonly signMultipartPart: (input: {
+        readonly destination: string;
+        readonly tenantId: string | null;
         readonly key: string;
         readonly uploadId: string;
         readonly partNumber: number;
@@ -640,6 +625,7 @@ export declare interface StorageServiceShape {
      *  registered straight from it (size via HEAD, etag as checksum). No fetch-back,
      *  so NO scan/derivatives — scan multi-GB out of band. */
     readonly completeMultipart: (input: {
+        readonly destination: string;
         readonly key: string;
         readonly uploadId: string;
         readonly parts: ReadonlyArray<{
@@ -658,6 +644,8 @@ export declare interface StorageServiceShape {
     }) => Effect.Effect<StorageRef, StorageError | StorageRejected>;
     /** Abort a multipart session (client cancelled) — frees the bucket's parts. */
     readonly abortMultipart: (input: {
+        readonly destination: string;
+        readonly tenantId: string | null;
         readonly key: string;
         readonly uploadId: string;
     }) => Effect.Effect<void, StorageError>;
@@ -667,11 +655,7 @@ export declare interface StorageServiceShape {
  *  the ref's access policy + grants. Default for a new put is `private`. */
 export declare type StorageVisibility = 'public' | 'private';
 
-/** Bytes + content type as returned by a provider `get`. */
-export declare interface StoredObject {
-    readonly bytes: Uint8Array;
-    readonly contentType: string;
-}
+export { StoredObject }
 
 /** What `put` returns: the stored ref, plus what this call did to it. The
  *  `outcome` is a fact about the CALL, not the row — it is never persisted and
@@ -680,13 +664,7 @@ export declare type StoredRef = StorageRef & {
     readonly outcome: PutOutcome;
 };
 
-/** A streamed read from a provider — the object as a {@link ByteStream} plus
- *  its content type and, when the backend reports it up front, its size. */
-export declare interface StoredStream {
-    readonly stream: ByteStream;
-    readonly contentType: string;
-    readonly size?: number;
-}
+export { StoredStream }
 
 /**
  * App-supplied (or first-party `ffmpegTranscoder`) transcode step. Given a

package/dist/types.js

@@ -1,20 +1,19 @@
-import { Context as e, Schema as t } from "effect";
-//#region src/types.ts
-var n = class extends t.TaggedError()("StorageError", {
-	provider: t.String,
-	message: t.String,
-	transient: t.Boolean,
-	status: t.optional(t.Number)
-}) {}, r = class extends t.TaggedError()("StorageAccessDenied", {
-	refId: t.String,
-	reason: t.String
-}) {}, i = class extends t.TaggedError()("StorageRejected", {
-	reason: t.String,
-	detail: t.String
+import { StorageAddress as e, StorageError as t, isStorageKey as n, storageAddressIdentity as r } from "@voltro/kv/storage";
+import { Context as i, Schema as a } from "effect";
+// src/types.ts
+var o = class extends a.TaggedError()("StorageAccessDenied", {
+	refId: a.String,
+	reason: a.String
+}) {}, s = class extends a.TaggedError()("StorageRejected", {
+	reason: a.String,
+	detail: a.String
 }) {
 	get message() {
 		return this.detail;
 	}
-}, a = class extends t.TaggedError()("StorageScanRejected", { threat: t.String }) {}, o = class extends e.Service()("@voltro/plugin-storage/StorageService") {};
-//#endregion
-export { r as StorageAccessDenied, n as StorageError, i as StorageRejected, a as StorageScanRejected, o as StorageService };
+}, c = class extends a.TaggedError()("StorageScanRejected", { threat: a.String }) {}, l = class extends i.Service()("@voltro/plugin-storage/StorageService") {}, u = (e) => ({
+	destination: e.bucket,
+	tenantId: e.tenantId,
+	key: e.key
+});
+export { o as StorageAccessDenied, e as StorageAddress, t as StorageError, s as StorageRejected, c as StorageScanRejected, l as StorageService, n as isStorageKey, r as storageAddressIdentity, u as storageRefAddress };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-storage",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "description": "File-storage plugin — one StorageProvider contract, switchable backends (S3 / MinIO / Azure / filesystem / memory / database). Public (CDN-direct) + private (access policy + per-object grants) objects, upload constraints, virus-scan hook, on-the-fly image transforms.",
   "keywords": [
     "voltro",
@@ -33,7 +33,17 @@
       "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./byte-security": {
+      "types": "./dist/byteSecurity.d.ts",
+      "import": "./dist/byteSecurity.js",
+      "default": "./dist/byteSecurity.js"
+    }
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -43,20 +53,21 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.86.0",
-    "@voltro/env": "0.86.0",
-    "@voltro/protocol": "0.86.0",
-    "@voltro/runtime": "0.86.0"
+    "@voltro/database": "0.88.0",
+    "@voltro/env": "0.88.0",
+    "@voltro/kv": "0.88.0",
+    "@voltro/protocol": "0.88.0",
+    "@voltro/runtime": "0.88.0"
   },
   "optionalDependencies": {
-    "@aws-sdk/client-s3": "^3.1134.0",
-    "@aws-sdk/lib-storage": "^3.1134.0",
-    "@aws-sdk/s3-request-presigner": "^3.1134.0",
-    "@azure/storage-blob": "^12.33.0",
+    "@aws-sdk/client-s3": "^3.1159.0",
+    "@aws-sdk/lib-storage": "^3.1159.0",
+    "@aws-sdk/s3-request-presigner": "^3.1159.0",
+    "@azure/storage-blob": "^12.34.0",
     "sharp": "^0.35.5"
   },
   "peerDependencies": {
-    "effect": "4.0.1"
+    "effect": "4.1.0"
   },
   "publishConfig": {
     "access": "public"