@voltro/plugin-storage 0.81.0 → 0.83.0

package/THIRD-PARTY-NOTICES.md

@@ -10789,7 +10789,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## undici@8.10.0
+## undici@8.11.2
 
 License: MIT
 

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { Effect } from 'effect';
 import { FieldDefinitions } from '@voltro/database';
 import { Layer } from 'effect';
 import { mixin } from '@voltro/database';
+import { PluginEgressDeclaration } from '@voltro/protocol';
 import { Readable } from 'node:stream';
 import { Schema } from 'effect';
 import { Stream } from 'effect';
@@ -285,6 +286,16 @@ export declare interface GrantTokenPayload {
 /** Hash a file password as `salt:scryptHash` (hex). */
 export declare const hashPassword: (password: string) => string;
 
+/** Where `ingestUrl` may fetch from — see `ssrfReason` in `@voltro/runtime`. */
+export declare interface IngestPolicy {
+    /** Hosts (or `host:port`, or `*.suffix`) reachable although internal — a
+     *  deliberate internal source, or a local test server. Everything else that
+     *  is loopback, private, link-local (cloud metadata) or `.internal` is refused. */
+    readonly allowHosts?: ReadonlyArray<string>;
+    /** Redirect hops followed, each checked again. Default 5. */
+    readonly maxRedirects?: number;
+}
+
 /**
  * Filter + page a `StorageService.listRefs` / media-library query. Every
  * filter is optional and ANDed; omit them all to page the whole (tenant-scoped)
@@ -365,7 +376,7 @@ export declare const makeStorageObjectMetadata: (store: DataStore) => {
             readonly id: string;
             readonly fingerprint: string;
             readonly generation: string;
-            readonly state: "ready" | "reserved" | "deleting" | "deleted";
+            readonly state: "ready" | "reserved" | "deleted" | "deleting";
             readonly refId: string;
             readonly objectId: string;
             readonly deleteKey: string | null;
@@ -574,6 +585,12 @@ export declare interface RefStore {
      *  newest-first, offset-paged. Backs `StorageService.listRefs`. Fetches
      *  `limit + 1` so the service can report whether another page follows. */
     readonly listRefs: (query: ResolvedListQuery) => Effect.Effect<ReadonlyArray<StorageRef>, StorageError>;
+    /** Change one ref's visibility; the updated ref, or null when there is none.
+     *  Optional: a store without it cannot back `StorageService.setVisibility`. */
+    readonly setVisibility?: ((id: string, visibility: StorageVisibility) => Effect.Effect<StorageRef | null, StorageError>) | undefined;
+    /** How many PUBLIC refs point at this provider key — whether the object must
+     *  stay publicly readable. */
+    readonly countPublicByKey?: ((bucket: string, key: string) => Effect.Effect<number, StorageError>) | undefined;
 }
 
 /** One derived output a `Transcoder` produces from a source asset. Each becomes
@@ -683,6 +700,13 @@ declare const StorageAccessDenied_base: Schema.TaggedErrorClass<StorageAccessDen
     reason: typeof Schema.String;
 }>;
 
+/**
+ * Where the bytes go, read from the same options and env `resolveProvider`
+ * reads: an object store is a destination outside the installation; the
+ * database, the filesystem and memory keep the bytes inside it.
+ */
+export declare const storageEgressOf: (options: StoragePluginOptions) => ReadonlyArray<PluginEgressDeclaration>;
+
 /**
  * Storage failure. `transient` drives retry — `true` for 429 / 5xx /
  * network blips, `false` for 4xx / config / not-found. Surfaced typed so
@@ -841,8 +865,23 @@ export declare interface StoragePluginOptions {
     readonly urlExpiresInSec?: number;
     /** Access engine config — a group resolver + named custom guards. */
     readonly access?: AccessOptions;
+    /**
+     * The access policy every PRIVATE client upload (an upload ticket) is
+     * stored with — declared by the app, never chosen by the client. Without
+     * it only the uploader (the implicit owner rule) can read a private upload;
+     * `[{ tenant: true }]` lets everyone in the uploader's tenant read it.
+     */
+    readonly uploadAccess?: AccessPolicy;
     /** Upload constraints — size cap, content-type allow-list, magic-byte sniff. */
     readonly limits?: UploadLimits;
+    /**
+     * Where `StorageService.ingestUrl` may fetch from. Every address — the URL
+     * and each redirect — is checked: loopback, private, link-local (cloud
+     * metadata), `localhost` and `.internal`/`.local` hosts are refused with
+     * `StorageRejected` (`blocked-source`). `allowHosts` names deliberate
+     * internal sources (or a local test server).
+     */
+    readonly ingest?: IngestPolicy;
     /**
      * Let a caller with NO identity mint an upload ticket. Default `false`.
      *
@@ -933,6 +972,10 @@ export declare interface StorageProvider {
      *  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>;
@@ -1099,6 +1142,8 @@ export declare interface StorageServiceOptions {
     readonly access?: AccessOptions;
     /** Upload constraints — size cap, content-type allow-list, magic-byte sniff. */
     readonly limits?: UploadLimits;
+    /** Where `ingestUrl` may fetch from (internal addresses are refused). */
+    readonly ingest?: IngestPolicy;
     /** Virus scanner run on `put` before the bytes are stored. */
     readonly scan?: StorageScanner;
     /** App-supplied probe for video/audio uploads (duration + poster frame).
@@ -1231,6 +1276,30 @@ export declare interface StorageServiceShape {
      *  caller's `tenantId` / `ownerId` for an end-user surface, and deliver any
      *  listed private object through `mintUrl`. */
     readonly listRefs: (input?: ListRefsInput) => Effect.Effect<ListRefsResult, StorageError>;
+    /**
+     * A short-lived URL that delivers the bytes WITHOUT an access check — for
+     * server code that has already decided the reader may see them (a shared
+     * preview whose link was verified). Public: its public URL. Private: a
+     * presigned GET (s3/minio) or the serve URL with a signed grant token. Never
+     * hand one to a caller whose access you have not checked.
+     */
+    readonly signedUrl: (id: string, opts?: {
+        readonly tenantId?: string | null;
+        readonly expiresInSec?: number;
+    }) => Effect.Effect<string, StorageError>;
+    /**
+     * Make a stored object public or private after the fact — an image that goes
+     * public when its page is published, and private again when it is taken
+     * down. Checks the tenant like `delete`. Where objects are served from a
+     * public base (`cdnBaseUrl`) a public object cannot be taken back: that is
+     * refused (`StorageRejected`, reason `visibility-unsupported`) rather than
+     * left public. On s3 with per-object ACLs the object follows its refs: it
+     * stays public while any ref to the same bytes is. A public object's earlier
+     * responses may remain in browser and CDN caches.
+     */
+    readonly setVisibility: (id: string, visibility: StorageVisibility, opts?: {
+        readonly tenantId?: string | null;
+    }) => Effect.Effect<StorageRef, StorageError | StorageRejected>;
     readonly grant: (input: GrantInput) => Effect.Effect<StorageGrant, StorageError>;
     readonly revoke: (grantId: string) => Effect.Effect<void, StorageError>;
     /** One grant by id, or null. Server-side read — the RPC layer uses it to
@@ -1269,6 +1338,8 @@ export declare interface StorageServiceShape {
         readonly operationId?: string;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        /** The access policy of a private object, as on `put`. */
+        readonly access?: AccessPolicy;
         readonly key?: string;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
@@ -1447,6 +1518,13 @@ export declare interface Transformed {
     readonly contentType: string;
 }
 
+/**
+ * Why a requested transform served the original instead — `null` when it did
+ * not fall back. The storage route sends it as `x-voltro-transform`, so a
+ * resize or format change that did not happen is never silent.
+ */
+export declare const transformFallbackReason: (contentType: string, transformed: boolean) => Promise<"not-an-image" | "no-sharp" | "failed" | null>;
+
 /**
  * Transform image bytes per `params`. Returns null (→ serve original) when
  * the content isn't a raster image, `sharp` isn't installed, or processing
@@ -1460,6 +1538,15 @@ export declare interface TransformParams {
     readonly format?: string;
     readonly q?: number;
     readonly fit?: string;
+    /**
+     * The focal point, `fp=x,y` as fractions of the width and height (0–1). With
+     * both `w` and `h` and `fit=cover` (the default), the crop keeps this point
+     * as central as the image allows instead of cutting around the middle.
+     */
+    readonly fp?: {
+        readonly x: number;
+        readonly y: number;
+    };
 }
 
 export declare interface UploadLimits {