@voltro/plugin-storage 0.83.1 → 0.85.0

package/dist/index.d.ts

@@ -9,11 +9,14 @@ import { mixin } from '@voltro/database';
 import { PluginEgressDeclaration } from '@voltro/protocol';
 import { Readable } from 'node:stream';
 import { Schema } from 'effect';
+import { StorageAccessPolicy } from '@voltro/protocol';
+import { StorageAccessRule } from '@voltro/protocol';
 import { Stream } from 'effect';
 import { Subject } from '@voltro/protocol';
 import { Table } from '@voltro/database';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
 
 export declare interface AccessOptions {
     /** Resolve a subject's group ids. Default: `subject.metadata.groups`. */
@@ -22,7 +25,7 @@ export declare interface AccessOptions {
     readonly guards?: Record<string, StorageGuard>;
 }
 
-export declare type AccessPolicy = ReadonlyArray<AccessRule>;
+export declare type AccessPolicy = StorageAccessPolicy;
 
 /**
  * One access rule. A rule GRANTS when EVERY present condition is satisfied
@@ -30,24 +33,7 @@ export declare type AccessPolicy = ReadonlyArray<AccessRule>;
  * grants (OR). An empty policy on a private object means owner-only (the
  * implicit owner check always applies).
  */
-export declare interface AccessRule {
-    /** `subject.id === ref.ownerId`. */
-    readonly owner?: boolean;
-    /** `subject.metadata.roles` intersects these. */
-    readonly roles?: ReadonlyArray<string>;
-    /** resolved groups (default `subject.metadata.groups`) intersect these. */
-    readonly groups?: ReadonlyArray<string>;
-    /** `subject.scopes` intersects these. */
-    readonly scopes?: ReadonlyArray<string>;
-    /** `subject.tenantId === ref.tenantId`. */
-    readonly tenant?: boolean;
-    /** subject is any authenticated api-key. */
-    readonly apiKey?: boolean;
-    /** a correct password was supplied (checked at mint, against passwordHash). */
-    readonly password?: boolean;
-    /** a named custom guard (`options.guards[name]`) returns true. */
-    readonly guard?: string;
-}
+export declare type AccessRule = StorageAccessRule;
 
 /**
  * The provider the APP configured, falling back to the env-derived default when no
@@ -193,6 +179,12 @@ export declare const decodeDataUri: (dataUri: string) => {
  */
 export declare const durabilityNotice: (path: string) => string | undefined;
 
+/**
+ * Apply a creative edit; null when the input is not an image, `sharp` is not
+ * installed, the edit is empty or fails. The format stays the input's.
+ */
+export declare const editImage: (bytes: Uint8Array, contentType: string, edit: ImageEdit) => Promise<Transformed | null>;
+
 /** Frame bytes for clamd `INSTREAM`: `zINSTREAM\0` then `<u32 len><data>`
  *  chunks, terminated by a zero-length chunk. Exposed for testing. */
 export declare const encodeInstream: (bytes: Uint8Array, chunkSize?: number) => Buffer;
@@ -286,6 +278,19 @@ export declare interface GrantTokenPayload {
 /** Hash a file password as `salt:scryptHash` (hex). */
 export declare const hashPassword: (password: string) => string;
 
+/** A creative edit: the result is new bytes, stored as a new version — unlike a delivery transform. */
+export declare interface ImageEdit {
+    /** Clockwise, in degrees. */
+    readonly rotate?: 90 | 180 | 270;
+    /** Mirror top to bottom. */
+    readonly flip?: boolean;
+    /** Mirror left to right. */
+    readonly flop?: boolean;
+    readonly grayscale?: boolean;
+    /** Cut this region out, in pixels of the original. */
+    readonly crop?: Region;
+}
+
 /** Where `ingestUrl` may fetch from — see `ssrfReason` in `@voltro/runtime`. */
 export declare interface IngestPolicy {
     /** Hosts (or `host:port`, or `*.suffix`) reachable although internal — a
@@ -339,9 +344,9 @@ export declare const makeStorageObjectMetadata: (store: DataStore) => {
         identity: {
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly operationId: string;
             readonly fingerprint: string;
             readonly checksum: string;
-            readonly operationId: string;
             readonly logicalKey: string;
         };
         ref: StorageRef;
@@ -363,30 +368,30 @@ export declare const makeStorageObjectMetadata: (store: DataStore) => {
         identity: {
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly operationId: string;
             readonly fingerprint: string;
             readonly checksum: string;
-            readonly operationId: string;
             readonly logicalKey: string;
         };
         operation?: never;
     } | {
         released: true;
         operation: {
-            readonly key: string;
             readonly id: string;
+            readonly objectId: string;
             readonly fingerprint: string;
             readonly generation: string;
-            readonly state: "ready" | "reserved" | "deleted" | "deleting";
+            readonly key: string;
             readonly refId: string;
-            readonly objectId: string;
+            readonly state: "ready" | "reserved" | "deleted" | "deleting";
             readonly deleteKey: string | null;
         };
         identity: {
             readonly tenantId: string | null;
             readonly bucket: string;
+            readonly operationId: string;
             readonly fingerprint: string;
             readonly checksum: string;
-            readonly operationId: string;
             readonly logicalKey: string;
         };
     }>;
@@ -593,6 +598,14 @@ export declare interface RefStore {
     readonly countPublicByKey?: ((bucket: string, key: string) => Effect.Effect<number, StorageError>) | undefined;
 }
 
+/** A region of an image in pixels. */
+declare interface Region {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+}
+
 /** 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 {
@@ -659,19 +672,19 @@ export declare interface S3ProviderOptions {
 export declare const setActiveStorageProvider: (provider: StorageProvider | undefined) => void;
 
 /** Sign a finalize token valid for `ttlSeconds`. */
-export declare const signFinalizeTicket: (fields: Omit<FinalizeTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signFinalizeTicket: (fields: Omit<FinalizeTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** Mint a token granting read access to `refId` for `ttlSeconds`. */
 export declare const signGrant: (refId: string, ttlSeconds: number, secret?: string, audience?: string) => string;
 
 /** Sign a multipart ticket valid for `ttlSeconds`. */
-export declare const signMultipartTicket: (fields: Omit<MultipartTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signMultipartTicket: (fields: Omit<MultipartTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** Sign a resumable ticket valid for `ttlSeconds`. */
-export declare const signResumableTicket: (fields: Omit<ResumableTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signResumableTicket: (fields: Omit<ResumableTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** Sign an upload ticket valid for `ttlSeconds`. */
-export declare const signUploadTicket: (fields: Omit<UploadTicketPayload, "exp">, ttlSeconds: number, secret?: string) => string;
+export declare const signUploadTicket: (fields: Omit<UploadTicketPayload, "exp" | "version">, ttlSeconds: number, secret?: string) => string;
 
 /** True if the bytes match the declared content type's magic number, OR we
  *  have no signature for that type (can't verify → don't block). */
@@ -693,12 +706,10 @@ export declare const STORAGE_USAGE_TABLE = "_voltro_storage_usage";
 export declare class StorageAccessDenied extends StorageAccessDenied_base {
 }
 
-declare const StorageAccessDenied_base: Schema.TaggedErrorClass<StorageAccessDenied, "StorageAccessDenied", {
-    readonly _tag: Schema.tag<"StorageAccessDenied">;
-} & {
-    refId: typeof Schema.String;
-    reason: typeof Schema.String;
-}>;
+declare const StorageAccessDenied_base: Schema.Class<StorageAccessDenied, Schema.TaggedStruct<"StorageAccessDenied", {
+    readonly refId: Schema.String;
+    readonly reason: Schema.String;
+}>, YieldableError>;
 
 /**
  * Where the bytes go, read from the same options and env `resolveProvider`
@@ -715,14 +726,12 @@ export declare const storageEgressOf: (options: StoragePluginOptions) => Readonl
 export declare class StorageError extends StorageError_base {
 }
 
-declare const StorageError_base: Schema.TaggedErrorClass<StorageError, "StorageError", {
-    readonly _tag: Schema.tag<"StorageError">;
-} & {
-    provider: typeof Schema.String;
-    message: typeof Schema.String;
-    transient: typeof Schema.Boolean;
-    status: Schema.optional<typeof Schema.Number>;
-}>;
+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>;
 
 /** A persisted, explicit share of one object with one principal. */
 export declare interface StorageGrant {
@@ -784,7 +793,7 @@ export declare const storageObjectLifecycleTables: ( Table<"_voltro_storage_oper
     readonly id: ColumnBuilder<string, "text", boolean>;
     readonly generation: ColumnBuilder<string, "text", boolean>;
     readonly key: ColumnBuilder<string, "text", boolean>;
-    readonly reservations: ColumnBuilder<number, "integer", boolean>;
+    readonly reservations: ColumnBuilder<string, "bigint", boolean>;
 }>, false, never> | Table<"_voltro_storage_operations", FieldDefinitions<{
     readonly id: ColumnBuilder<string, "text", boolean>;
     readonly objectId: ColumnBuilder<string, "text", boolean>;
@@ -866,12 +875,25 @@ export declare interface StoragePluginOptions {
     /** 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
+     * The default policy for PRIVATE client uploads, or an Effect function
+     * authorizing self-service upload visibility and requested policies before the server signs a ticket. 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;
+    readonly uploadAccess?: AccessPolicy | ((request: {
+        readonly subject: Subject;
+        readonly requested: AccessPolicy | undefined;
+        readonly visibility: 'public' | 'private';
+        readonly contentType: string;
+    }) => Effect.Effect<AccessPolicy, StorageError>);
+    /**
+     * How long a browser or shared cache may keep a PUBLIC object the serve
+     * route delivers itself (and each transform of it). Default: a year,
+     * `immutable`. An object can turn private later; a copy cached before then
+     * keeps opening until this runs out — set it to bound that window (the
+     * bucket's own caching, behind a direct URL, is the provider's).
+     */
+    readonly publicCacheSeconds?: number;
     /** Upload constraints — size cap, content-type allow-list, magic-byte sniff. */
     readonly limits?: UploadLimits;
     /**
@@ -1086,15 +1108,14 @@ export declare interface StorageRef {
 /** 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 {
+    get message(): string;
 }
 
-declare const StorageRejected_base: Schema.TaggedErrorClass<StorageRejected, "StorageRejected", {
-    readonly _tag: Schema.tag<"StorageRejected">;
-} & {
+declare const StorageRejected_base: Schema.Class<StorageRejected, Schema.TaggedStruct<"StorageRejected", {
     /** `'too-large' | 'content-type-not-allowed' | 'content-mismatch'` */
-    reason: typeof Schema.String;
-    detail: typeof Schema.String;
-}>;
+    readonly reason: Schema.String;
+    readonly detail: Schema.String;
+}>, YieldableError>;
 
 /** Scans bytes before they're stored. Return `{ clean:false, threat }` to
  *  reject the upload (fails with `StorageScanRejected`, nothing is stored). */
@@ -1108,11 +1129,9 @@ export declare type StorageScanner = (input: {
 export declare class StorageScanRejected extends StorageScanRejected_base {
 }
 
-declare const StorageScanRejected_base: Schema.TaggedErrorClass<StorageScanRejected, "StorageScanRejected", {
-    readonly _tag: Schema.tag<"StorageScanRejected">;
-} & {
-    threat: typeof Schema.String;
-}>;
+declare const StorageScanRejected_base: Schema.Class<StorageScanRejected, Schema.TaggedStruct<"StorageScanRejected", {
+    readonly threat: Schema.String;
+}>, YieldableError>;
 
 export declare interface StorageScanResult {
     readonly clean: boolean;
@@ -1123,7 +1142,7 @@ export declare interface StorageScanResult {
 export declare class StorageService extends StorageService_base {
 }
 
-declare const StorageService_base: Context.TagClass<StorageService, "@voltro/plugin-storage/StorageService", StorageServiceShape>;
+declare const StorageService_base: Context.ServiceClass<StorageService, "@voltro/plugin-storage/StorageService", StorageServiceShape>;
 
 export declare const storageServiceLayer: (options: StorageServiceOptions) => Layer.Layer<StorageService>;
 
@@ -1370,6 +1389,7 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        readonly access?: AccessPolicy;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
         readonly alt?: string;
@@ -1403,6 +1423,7 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        readonly access?: AccessPolicy;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
         readonly alt?: string;
@@ -1452,6 +1473,7 @@ export declare interface StorageServiceShape {
         readonly tenantId?: string | null;
         readonly ownerId?: string | null;
         readonly visibility?: StorageVisibility;
+        readonly access?: AccessPolicy;
         readonly folder?: string;
         readonly tags?: ReadonlyArray<string>;
         readonly alt?: string;
@@ -1564,6 +1586,8 @@ export declare interface UploadLimits {
 /** What an upload ticket authorizes: a single through-app upload bound to an
  *  owner/tenant/content-type/visibility, until `exp`. */
 export declare interface UploadTicketPayload {
+    /** Frozen-policy ticket contract. Previous tickets must be minted again. */
+    readonly version: 1;
     /** Optional durable write identity, preserved across ticket renewal. */
     readonly operationId?: string;
     /** Inspect uploads may be pinned to their issuing process. */
@@ -1577,6 +1601,8 @@ export declare interface UploadTicketPayload {
     /** Authorized content-type — the stored object uses this. */
     readonly ct: string;
     readonly vis: 'public' | 'private';
+    /** Server-authorized policy, frozen into the signed ticket. */
+    readonly access?: AccessPolicy;
     /** Optional fixed logical key (else content-addressed). */
     readonly key?: string;
     /** Max bytes the route will accept for this ticket (0/undefined = no cap). */