@voltro/plugin-storage 0.85.0 → 0.87.0

package/dist/rpc.d.ts

@@ -3,6 +3,7 @@ import { MutationProcedureDescriptor } from '@voltro/protocol';
 import { PluginRpcClientDescriptor } from '@voltro/protocol';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
 import { Schema } from 'effect';
+import { StorageError } from '@voltro/kv/storage';
 import { YieldableError } from 'effect/Cause';
 
 export declare const abortMultipartUploadDescriptor: ActionProcedureDescriptor<"storage.abortMultipartUpload", Schema.Struct<{
@@ -178,6 +179,7 @@ export declare const mintPresignedUploadDescriptor: ActionProcedureDescriptor<"s
 }>, typeof StorageError>;
 
 export declare const mintUploadTicketDescriptor: ActionProcedureDescriptor<"storage.mintUploadTicket", Schema.Struct<{
+    readonly operationId: Schema.optional<Schema.String>;
     readonly contentType: Schema.String;
     readonly visibility: Schema.optional<Schema.Literals<readonly ["public", "private"]>>;
     readonly access: Schema.optional<Schema.$Array<Schema.Struct<{
@@ -199,6 +201,7 @@ export declare const mintUploadTicketDescriptor: ActionProcedureDescriptor<"stor
 }>, Schema.Struct<{
     readonly uploadUrl: Schema.String;
     readonly expiresInSec: Schema.Number;
+    readonly operationId: Schema.optional<Schema.String>;
 }>, typeof StorageError>;
 
 export declare const mintUploadUrlDescriptor: ActionProcedureDescriptor<"storage.mintUploadUrl", Schema.Struct<{
@@ -253,21 +256,6 @@ 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', …)`.
- */
-declare class StorageError extends StorageError_base {
-}
-
-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>;
-
 /** An upload was rejected by a constraint (size / content-type / magic-byte
  *  mismatch). `reason` is a stable code; `detail` is human-readable. */
 declare class StorageRejected extends StorageRejected_base {

package/dist/rpc.js

@@ -76,6 +76,7 @@ var l = i.Literals([
 }), g = o({
 	name: "storage.mintUploadTicket",
 	input: i.Struct({
+		operationId: i.optional(i.String.pipe(i.check(i.makeFilter((e) => e.trim().length > 0)), i.check(i.isMaxLength(200)))),
 		contentType: i.String,
 		visibility: i.optional(i.Literals(["public", "private"])),
 		access: i.optional(a),
@@ -88,7 +89,8 @@ var l = i.Literals([
 	}),
 	output: i.Struct({
 		uploadUrl: i.String,
-		expiresInSec: i.Number
+		expiresInSec: i.Number,
+		operationId: i.optional(i.String)
 	}),
 	error: t,
 	openAccess: "self-service upload: the ticket binds the calling subject + tenant, caps size, and the finalize path runs limits + scan; an unidentified caller is refused in-handler unless the app set `anonymousUploads`"

package/dist/scanners.js

@@ -0,0 +1,46 @@
+import { storageEnv as e } from "./env.js";
+//#region src/scanners.ts
+var t = (e, t = 65536) => {
+	let n = [Buffer.from("zINSTREAM\0", "utf8")];
+	for (let r = 0; r < e.length; r += t) {
+		let i = e.subarray(r, Math.min(r + t, e.length)), a = Buffer.alloc(4);
+		a.writeUInt32BE(i.length, 0), n.push(a, Buffer.from(i));
+	}
+	let r = Buffer.alloc(4);
+	return r.writeUInt32BE(0, 0), n.push(r), Buffer.concat(n);
+}, n = (e) => {
+	let t = e.replace(/\0+$/, "").trim();
+	if (/\bOK$/.test(t)) return { clean: !0 };
+	let n = /:\s*(.+?)\s+FOUND$/.exec(t);
+	if (n) return {
+		clean: !1,
+		threat: n[1] ?? "unknown"
+	};
+	throw Error(`clamav: unexpected response: ${t}`);
+}, r = async (r, i) => {
+	let a = await import("node:net"), o = e.read("CLAMAV_HOST", i.host) ?? "127.0.0.1", s = e.read("CLAMAV_PORT"), c = i.port ?? (s ? Number(s) : 3310), l = i.timeoutMs ?? 3e4;
+	return new Promise((e, s) => {
+		let u = a.createConnection({
+			host: o,
+			port: c
+		}), d = "", f = setTimeout(() => {
+			u.destroy(), s(/* @__PURE__ */ Error("clamav scan timed out"));
+		}, l);
+		u.on("error", (e) => {
+			clearTimeout(f), s(e);
+		}), u.on("connect", () => {
+			u.end(t(r, i.chunkSize));
+		}), u.on("data", (e) => {
+			d += e.toString("utf8");
+		}), u.on("close", () => {
+			clearTimeout(f);
+			try {
+				e(n(d));
+			} catch (e) {
+				s(e);
+			}
+		});
+	});
+}, i = (e = {}) => (t) => r(t.bytes, e);
+//#endregion
+export { i as clamavScanner, t as encodeInstream, n as parseClamavResponse };

package/dist/server.d.ts

@@ -0,0 +1,153 @@
+import { DataStore } from '@voltro/database';
+import { StorageAccessPolicy } from '@voltro/protocol';
+import { StorageConnectionConnector } from '@voltro/kv/storage';
+import { StorageProvider } from '@voltro/kv/storage';
+
+declare type AccessPolicy = StorageAccessPolicy;
+
+/** The CLI injects this server adapter into the leaf registry. No plugin imports enter KV. */
+export declare const connectStorage: StorageConnectionConnector;
+
+/** What a finalize token authorizes: promoting ONE temp-key blob into a real
+ *  ref under the bound identity, until `exp`. */
+export declare interface FinalizeTicketPayload extends Omit<UploadTicketPayload, 'key' | 'operationId'> {
+    /** The TEMP bucket key the client PUT its bytes to (required — finalize reads
+     *  exactly this key, so it can't be aimed at another object). */
+    readonly key: string;
+}
+
+/** What a grant token authorizes: read access to one ref at its storage HTTP mount until `exp`. */
+export declare interface GrantTokenPayload {
+    readonly refId: string;
+    /** Exact storage HTTP mount allowed to serve this reference. */
+    readonly audience: string;
+    /** Unix seconds when the token expires. */
+    readonly exp: number;
+}
+
+/** What a multipart ticket authorizes: one direct-to-bucket multipart session. */
+export declare interface MultipartTicketPayload extends Omit<UploadTicketPayload, 'key' | 'operationId'> {
+    /** The FINAL bucket key the parts assemble into. */
+    readonly key: string;
+    /** The provider's multipart upload id. */
+    readonly uploadId: string;
+    /** Total expected byte size. */
+    readonly size: number;
+}
+
+/** After a verified snapshot asset restore, with serving replicas stopped.
+ * The caller owns the transaction and explicitly identifies every old and new
+ * physical scope. This does no provider I/O and never changes plugin ownership.
+ * Ordinary namespace assignment continues to refuse moving assigned objects. */
+export declare const relocateRestoredStorageObjectNamespacesInTransaction: (store: DataStore, scopes: readonly StorageReferenceScope[], relocations: readonly StorageObjectNamespaceRelocation[]) => Promise<StorageObjectNamespaceMigrationResult>;
+
+/** The secret new storage tokens are signed with — the first of {@link resolveStorageSecrets}. */
+export declare const resolveStorageSecret: () => string;
+
+/** What a resumable ticket authorizes: one chunked upload session, until `exp`. */
+export declare interface ResumableTicketPayload extends Omit<UploadTicketPayload, 'key' | 'operationId'> {
+    /** Upload-session id (random) — namespaces this upload's chunk objects. */
+    readonly id: string;
+    /** Total expected byte size (validated at finalize; also the effective cap). */
+    readonly size: number;
+}
+
+/** Sign a finalize token valid for `ttlSeconds`. */
+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" | "version">, ttlSeconds: number, secret?: string) => string;
+
+/** Sign a resumable ticket valid for `ttlSeconds`. */
+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" | "version">, ttlSeconds: number, secret?: string) => string;
+
+declare interface StorageObjectNamespaceAssignment extends StorageReferenceScope {
+    readonly refId: string;
+}
+
+declare interface StorageObjectNamespaceMigrationResult {
+    readonly assigned: number;
+    readonly pendingDeletes: readonly StorageObjectNamespaceAssignment[];
+}
+
+export declare interface StorageObjectNamespaceRelocation extends StorageObjectNamespaceAssignment {
+    readonly from: StorageReferenceScope;
+}
+
+declare interface StorageReferenceScope {
+    readonly storageInstance: string;
+    readonly objectNamespace: string;
+}
+
+/** A secret, or the set a rotation keeps accepting (the signing one first). */
+declare type StorageSecrets = string | ReadonlyArray<string>;
+
+/** 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: 2;
+    /** Optional durable write identity, preserved across ticket renewal. */
+    readonly operationId?: string;
+    /** Exact reference catalogue and physical byte destination authorized by the issuer. */
+    readonly writeScope: string;
+    /** Optional signed routing hint for the binary relay; destination authorization still uses writeScope. */
+    readonly issuerReplicaId?: string;
+    /** Exact storage plugin instance authorized to accept the bytes. */
+    readonly instance: string;
+    /** Logical destination selected before issuing the upload/session. */
+    readonly destination: string;
+    /** ownerId (subject id) the stored object is attributed to. */
+    readonly sub: string | null;
+    /** tenantId that scopes the key prefix + ref row. */
+    readonly tenant: string | null;
+    /** 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). */
+    readonly max?: number;
+    /** App metadata carried onto the stored ref (so apps need no parallel table). */
+    readonly folder?: string;
+    readonly tags?: ReadonlyArray<string>;
+    readonly alt?: string;
+    readonly caption?: string;
+    /** Unix seconds when the ticket expires. */
+    readonly exp: number;
+}
+
+/** Verify a finalize token. Returns the payload on success, null on any failure
+ *  (malformed, bad signature, expired, missing temp key). Never throws. */
+export declare const verifyFinalizeTicket: (token: string, secret?: StorageSecrets) => FinalizeTicketPayload | null;
+
+/**
+ * Verify a grant token. Returns the payload on success, null on any
+ * failure (malformed, bad signature, expired). Never throws.
+ */
+export declare const verifyGrant: (token: string, secret?: StorageSecrets) => GrantTokenPayload | null;
+
+/** Verify a multipart ticket. Returns the payload on success, null on any
+ *  failure (malformed, bad signature, expired, missing key/uploadId). */
+export declare const verifyMultipartTicket: (token: string, secret?: StorageSecrets) => MultipartTicketPayload | null;
+
+/** Verify a resumable ticket. Returns the payload on success, null on any
+ *  failure (malformed, bad signature, expired, missing id/size). Never throws. */
+export declare const verifyResumableTicket: (token: string, secret?: StorageSecrets) => ResumableTicketPayload | null;
+
+/** Verify an upload ticket. Returns the payload on success, null on any
+ *  failure (malformed, bad signature, expired). Never throws. */
+export declare const verifyUploadTicket: (token: string, secret?: StorageSecrets) => UploadTicketPayload | null;
+
+/** All keyed operations share the same namespace, including presigned and multipart paths. */
+export declare const withStorageKeyPrefix: (provider: StorageProvider, prefix?: string) => StorageProvider;
+
+export { }

package/dist/server.js

@@ -0,0 +1,4 @@
+import { relocateRestoredStorageObjectNamespacesInTransaction as e } from "./storageObjectNamespaces.js";
+import { resolveStorageSecret as t, signFinalizeTicket as n, signGrant as r, signMultipartTicket as i, signResumableTicket as a, signUploadTicket as o, verifyFinalizeTicket as s, verifyGrant as c, verifyMultipartTicket as l, verifyResumableTicket as u, verifyUploadTicket as d } from "./grant.js";
+import { connectStorage as f, withStorageKeyPrefix as p } from "./connection.js";
+export { f as connectStorage, e as relocateRestoredStorageObjectNamespacesInTransaction, t as resolveStorageSecret, n as signFinalizeTicket, r as signGrant, i as signMultipartTicket, a as signResumableTicket, o as signUploadTicket, s as verifyFinalizeTicket, c as verifyGrant, l as verifyMultipartTicket, u as verifyResumableTicket, d as verifyUploadTicket, p as withStorageKeyPrefix };