@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/storage/storage.module.js

@@ -0,0 +1,99 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var StorageModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageModule = void 0;
+const common_1 = require("@nestjs/common");
+const storage_cleanup_handler_1 = require("./handlers/storage-cleanup.handler");
+const storage_object_process_handler_1 = require("./handlers/storage-object-process.handler");
+const objects_controller_1 = require("./objects/objects.controller");
+const objects_service_1 = require("./objects/objects.service");
+const object_processing_module_1 = require("./processing/object-processing.module");
+const storage_provider_binding_1 = require("./providers/storage-provider.binding");
+const storage_providers_module_1 = require("./providers/storage-providers.module");
+const storage_status_controller_1 = require("./status/storage-status.controller");
+const storage_key_prefixes_1 = require("./storage-key-prefixes");
+const storage_options_1 = require("./storage.options");
+const storage_cleanup_task_1 = require("./tasks/storage-cleanup.task");
+// =============================================================================
+// StorageModule (issue #736, PP-8.3; objects API #150, cleanup job #353,
+// processing job #520)
+// =============================================================================
+//
+// The objects API (`/api/storage/objects`, `storage:read|write`,
+// `storage:delete_any`), `GET /api/storage/status`, the two queue job types
+// (`storage.cleanup.stale-uploads`, `storage.object.process`, both
+// server-only, both PERMANENT strings) and the daily cleanup cron, which only
+// enqueues (`enqueueHousekeepingJob`).
+//
+// `JobsModule.forRoot()` (`@marinoscar/platform-api/jobs`) is GLOBAL, so
+// `JobsService` and `JobHandlerRegistry` need no import here; nothing in the
+// jobs slice imports storage. The processor registry and runner come from
+// `ObjectProcessingModule`; `ObjectsService` asks it whether an upload needs
+// processing at all, and `StorageObjectProcessHandler` runs it.
+// =============================================================================
+/**
+ * The storage slice's objects API, its status route, the stale-upload sweep
+ * and the post-upload processing job.
+ *
+ * Needs, from the app: `JobsModule.forRoot()` (global), `SettingsModule.forRoot()`
+ * (global), the core `PlatformHostModule` (`PLATFORM_PRISMA`), the
+ * `STORAGE_SYSTEM_DATA` port, the credential store's encryption key and the
+ * `@fastify/multipart` plugin registered on the Fastify instance (the simple
+ * upload route; `simpleUploadFileSizeLimit` gives its limit).
+ *
+ * @stability experimental
+ */
+let StorageModule = StorageModule_1 = class StorageModule {
+    /**
+     * The slice for one app. Call once. Registers the slice's own object-key
+     * prefixes (`uploads`, `avatars`, `node-outputs`, `storage-config-test`;
+     * idempotent).
+     *
+     * @param options - deployment tuning, and the `provider` binding that replaces the default object store; see {@link StorageModuleOptions}.
+     * @returns the dynamic module. It exports `ObjectsService` and `STORAGE_OPTIONS`.
+     * @throws Error when an option is invalid.
+     *
+     * @example
+     * ```ts
+     * export const StorageModule = PlatformStorageModule.forRoot({});
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const resolved = (0, storage_options_1.resolveStorageModuleOptions)(options);
+        (0, storage_key_prefixes_1.registerStorageSliceKeyPrefixes)();
+        return {
+            module: StorageModule_1,
+            imports: [
+                ...resolved.imports,
+                // The app's object store, visible to every package consumer of
+                // STORAGE_PROVIDER (global; see `storage-provider.binding.ts`).
+                ...(resolved.provider ? [storage_provider_binding_1.StorageProviderBindingModule.forBinding(resolved.provider, resolved.imports)] : []),
+                storage_providers_module_1.StorageProvidersModule,
+                object_processing_module_1.ObjectProcessingModule,
+            ],
+            controllers: [objects_controller_1.ObjectsController, storage_status_controller_1.StorageStatusController],
+            providers: [
+                { provide: storage_options_1.STORAGE_OPTIONS, useValue: resolved },
+                objects_service_1.ObjectsService,
+                storage_cleanup_task_1.StorageCleanupTask,
+                storage_cleanup_handler_1.StorageCleanupHandler,
+                storage_object_process_handler_1.StorageObjectProcessHandler,
+            ],
+            exports: [storage_options_1.STORAGE_OPTIONS, objects_service_1.ObjectsService],
+        };
+    }
+};
+exports.StorageModule = StorageModule;
+exports.StorageModule = StorageModule = StorageModule_1 = __decorate([
+    (0, common_1.Module)({})
+], StorageModule);
+//# sourceMappingURL=storage.module.js.map

package/dist/storage/storage.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.module.js","sourceRoot":"","sources":["../../src/storage/storage.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AAEvD,gFAA2E;AAC3E,8FAAwF;AACxF,qEAAiE;AACjE,+DAA2D;AAC3D,oFAA+E;AAC/E,mFAAoF;AACpF,mFAA8E;AAC9E,kFAA6E;AAC7E,iEAAyE;AACzE,uDAA4G;AAC5G,uEAAkE;AAElE,gFAAgF;AAChF,yEAAyE;AACzE,uBAAuB;AACvB,gFAAgF;AAChF,EAAE;AACF,iEAAiE;AACjE,4EAA4E;AAC5E,mEAAmE;AACnE,8EAA8E;AAC9E,uCAAuC;AACvC,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,0EAA0E;AAC1E,6EAA6E;AAC7E,gEAAgE;AAChE,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AAEI,IAAM,aAAa,qBAAnB,MAAM,aAAa;IACxB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,OAAO,CAAC,UAAgC,EAAE;QAC/C,MAAM,QAAQ,GAAG,IAAA,6CAA2B,EAAC,OAAO,CAAC,CAAC;QACtD,IAAA,sDAA+B,GAAE,CAAC;QAElC,OAAO;YACL,MAAM,EAAE,eAAa;YACrB,OAAO,EAAE;gBACP,GAAG,QAAQ,CAAC,OAAO;gBACnB,+DAA+D;gBAC/D,gEAAgE;gBAChE,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,uDAA4B,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5G,iDAAsB;gBACtB,iDAAsB;aACvB;YACD,WAAW,EAAE,CAAC,sCAAiB,EAAE,mDAAuB,CAAC;YACzD,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,iCAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE;gBAChD,gCAAc;gBACd,yCAAkB;gBAClB,+CAAqB;gBACrB,4DAA2B;aAC5B;YACD,OAAO,EAAE,CAAC,iCAAe,EAAE,gCAAc,CAAC;SAC3C,CAAC;IACJ,CAAC;CACF,CAAA;AA3CY,sCAAa;wBAAb,aAAa;IADzB,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,aAAa,CA2CzB"}

package/dist/storage/storage.options.d.ts

@@ -0,0 +1,116 @@
+import type { ModuleMetadata } from '@nestjs/common';
+import type { PortBinding } from '../core/index';
+import type { StorageProvider } from './providers/storage-provider.interface';
+/**
+ * Injection token of the resolved {@link StorageModuleOptions}. Optional to
+ * every consumer: without it the shipped defaults apply.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_OPTIONS: unique symbol;
+/**
+ * The simple-upload ceiling (`POST /api/storage/objects`): 100 MiB. The app's
+ * multipart plugin caps the route at `min(this, storage.maxFileSize)`.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_MAX_SIMPLE_UPLOAD_BYTES: number;
+/**
+ * The multipart part size used when neither the option nor the deployment's
+ * `storage.partSize` (`STORAGE_PART_SIZE`) says otherwise: 10 MiB.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_STORAGE_PART_SIZE_BYTES: number;
+/**
+ * How long an unfinished upload is left alone before the stale-upload sweep
+ * reclaims it: 24 hours.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_STALE_UPLOAD_HOURS = 24;
+/**
+ * Options of `StorageModule.forRoot()`. Every field is optional.
+ *
+ * @stability experimental
+ */
+export interface StorageModuleOptions {
+    /** Max simple-upload size in bytes. Default {@link DEFAULT_MAX_SIMPLE_UPLOAD_BYTES}. */
+    maxSimpleUploadBytes?: number;
+    /**
+     * Multipart part size in bytes (at least 5 MiB, the S3 minimum). Default:
+     * the deployment's `storage.partSize` (`STORAGE_PART_SIZE`), else
+     * {@link DEFAULT_STORAGE_PART_SIZE_BYTES}.
+     */
+    partSizeBytes?: number;
+    /** Stale-upload cleanup threshold in hours. Default {@link DEFAULT_STALE_UPLOAD_HOURS}. */
+    staleUploadHours?: number;
+    /**
+     * Modules to import next to the slice: typically the app's `@Global()` host
+     * module binding `STORAGE_SYSTEM_DATA`.
+     */
+    imports?: ModuleMetadata['imports'];
+    /**
+     * Replaces the default object store (`ResolvingStorageProvider`: S3, R2 or an
+     * S3-compatible service from the `storage` settings) for EVERY package
+     * consumer: the objects API, profile images, data exports, database backups,
+     * user-data purges, the AI output writer and the nodes data plane. Give the
+     * binding of an app backend (Azure Blob, a local disk): `{ useClass }`,
+     * `{ useExisting }` or `{ useFactory, inject }`. Its dependencies come from
+     * `imports` and from global modules.
+     *
+     * The provider's `kind` is what rows record as the storage provider.
+     * Without this option nothing changes. Providing `STORAGE_PROVIDER` in an
+     * app module instead does not work (see `STORAGE_PROVIDER`).
+     *
+     * @example
+     * ```ts
+     * StorageModule.forRoot({ imports: [StorageHostModule], provider: { useClass: AzureBlobStorageProvider } });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    provider?: PortBinding<StorageProvider>;
+}
+/**
+ * {@link StorageModuleOptions} with every default applied (`partSizeBytes`
+ * stays optional: absent means "the deployment's `storage.partSize`").
+ *
+ * @stability experimental
+ */
+export interface ResolvedStorageModuleOptions {
+    /** The simple-upload ceiling in bytes. */
+    readonly maxSimpleUploadBytes: number;
+    /** The part size override, when set. */
+    readonly partSizeBytes?: number;
+    /** The stale-upload threshold in hours. */
+    readonly staleUploadHours: number;
+    /** The modules imported next to the slice. */
+    readonly imports: NonNullable<ModuleMetadata['imports']>;
+    /** The app's provider binding, when one was given. */
+    readonly provider?: PortBinding<StorageProvider>;
+}
+/**
+ * Validates `options` and applies the defaults.
+ *
+ * @param options - what the app passed.
+ * @returns the resolved options (frozen).
+ * @throws Error when a value is not a positive finite number, `partSizeBytes` is below 5 MiB, or `provider` does not have exactly one of `useExisting`, `useClass` or `useFactory`.
+ *
+ * @stability experimental
+ */
+export declare function resolveStorageModuleOptions(options?: StorageModuleOptions): ResolvedStorageModuleOptions;
+/**
+ * The `fileSize` limit the app's multipart plugin registers for the simple
+ * upload route: `min(maxSimpleUploadBytes, maxFileSize)`, or the ceiling
+ * alone when the deployment's `storage.maxFileSize` is unusable.
+ *
+ * @param maxFileSize - the deployment's `storage.maxFileSize`.
+ * @param ceiling - `maxSimpleUploadBytes`.
+ * @returns the byte limit.
+ *
+ * @stability experimental
+ */
+export declare function simpleUploadFileSizeLimit(maxFileSize: unknown, ceiling?: number): number;
+//# sourceMappingURL=storage.options.d.ts.map

package/dist/storage/storage.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.options.d.ts","sourceRoot":"","sources":["../../src/storage/storage.options.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,MAA2D,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,QAAoB,CAAC;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,QAAmB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,wCAAwC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;IACzD,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC;CAClD;AASD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,oBAAyB,GAAG,4BAA4B,CAmB5G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,GAAE,MAAwC,GAAG,MAAM,CAIzH"}

package/dist/storage/storage.options.js

@@ -0,0 +1,97 @@
+"use strict";
+// =============================================================================
+// StorageModule.forRoot() options (issue #736, PP-8.3)
+// =============================================================================
+//
+// DEPLOYMENT TUNING ONLY. Which provider, bucket, region, endpoint and
+// credential are the `storage` system-settings namespace plus the credential
+// store, edited at `/admin/settings/storage` with no restart; none of them is
+// an option here and none ever may be (CLAUDE.md: never `STORAGE_PROVIDER`,
+// `S3_BUCKET`, `S3_REGION`, `S3_ENDPOINT`). The defaults are today's values.
+// The one exception is `provider`: not a configuration value but the CODE of an
+// app's own backend (a class binding), replacing the S3 driver wholesale.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALE_UPLOAD_HOURS = exports.DEFAULT_STORAGE_PART_SIZE_BYTES = exports.DEFAULT_MAX_SIMPLE_UPLOAD_BYTES = exports.STORAGE_OPTIONS = void 0;
+exports.resolveStorageModuleOptions = resolveStorageModuleOptions;
+exports.simpleUploadFileSizeLimit = simpleUploadFileSizeLimit;
+/**
+ * Injection token of the resolved {@link StorageModuleOptions}. Optional to
+ * every consumer: without it the shipped defaults apply.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_OPTIONS = Symbol.for('@marinoscar/platform/storage/OPTIONS');
+/**
+ * The simple-upload ceiling (`POST /api/storage/objects`): 100 MiB. The app's
+ * multipart plugin caps the route at `min(this, storage.maxFileSize)`.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_MAX_SIMPLE_UPLOAD_BYTES = 100 * 1024 * 1024;
+/**
+ * The multipart part size used when neither the option nor the deployment's
+ * `storage.partSize` (`STORAGE_PART_SIZE`) says otherwise: 10 MiB.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_STORAGE_PART_SIZE_BYTES = 10 * 1024 * 1024;
+/**
+ * How long an unfinished upload is left alone before the stale-upload sweep
+ * reclaims it: 24 hours.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_STALE_UPLOAD_HOURS = 24;
+function positive(name, value, min = 1) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < min) {
+        throw new Error(`StorageModule.forRoot(): ${name} must be a finite number >= ${min} (got ${String(value)})`);
+    }
+}
+/**
+ * Validates `options` and applies the defaults.
+ *
+ * @param options - what the app passed.
+ * @returns the resolved options (frozen).
+ * @throws Error when a value is not a positive finite number, `partSizeBytes` is below 5 MiB, or `provider` does not have exactly one of `useExisting`, `useClass` or `useFactory`.
+ *
+ * @stability experimental
+ */
+function resolveStorageModuleOptions(options = {}) {
+    positive('maxSimpleUploadBytes', options.maxSimpleUploadBytes);
+    positive('partSizeBytes', options.partSizeBytes, 5 * 1024 * 1024);
+    positive('staleUploadHours', options.staleUploadHours);
+    if (options.provider !== undefined) {
+        const shape = options.provider;
+        const kinds = shape && typeof shape === 'object' ? ['useExisting', 'useClass', 'useFactory'].filter((k) => k in shape) : [];
+        if (kinds.length !== 1) {
+            throw new Error('StorageModule.forRoot(): `provider` needs exactly one of useExisting, useClass or useFactory');
+        }
+    }
+    return Object.freeze({
+        maxSimpleUploadBytes: options.maxSimpleUploadBytes ?? exports.DEFAULT_MAX_SIMPLE_UPLOAD_BYTES,
+        ...(options.partSizeBytes !== undefined ? { partSizeBytes: options.partSizeBytes } : {}),
+        staleUploadHours: options.staleUploadHours ?? exports.DEFAULT_STALE_UPLOAD_HOURS,
+        imports: [...(options.imports ?? [])],
+        ...(options.provider !== undefined ? { provider: options.provider } : {}),
+    });
+}
+/**
+ * The `fileSize` limit the app's multipart plugin registers for the simple
+ * upload route: `min(maxSimpleUploadBytes, maxFileSize)`, or the ceiling
+ * alone when the deployment's `storage.maxFileSize` is unusable.
+ *
+ * @param maxFileSize - the deployment's `storage.maxFileSize`.
+ * @param ceiling - `maxSimpleUploadBytes`.
+ * @returns the byte limit.
+ *
+ * @stability experimental
+ */
+function simpleUploadFileSizeLimit(maxFileSize, ceiling = exports.DEFAULT_MAX_SIMPLE_UPLOAD_BYTES) {
+    return typeof maxFileSize === 'number' && Number.isFinite(maxFileSize) && maxFileSize > 0
+        ? Math.min(ceiling, maxFileSize)
+        : ceiling;
+}
+//# sourceMappingURL=storage.options.js.map

package/dist/storage/storage.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.options.js","sourceRoot":"","sources":["../../src/storage/storage.options.ts"],"names":[],"mappings":"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"}

package/dist/storage/storage.permissions.d.ts

@@ -0,0 +1,33 @@
+import type { PermissionDeclaration } from '../core/index';
+/**
+ * One permission this slice declares: core's `PermissionDeclaration`, the
+ * entry type of the permission registry (`registerPermissions`).
+ *
+ * @typeParam Id - the permission string.
+ *
+ * @stability stable
+ */
+export type StoragePermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The storage slice's object-access permissions, keyed by the `PERMISSIONS`
+ * constant name the reference app derives from them: `storage:read` and
+ * `storage:write` (org scope, held through the membership role) and
+ * `storage:delete_any` (system scope, `admin`). Register them with the app's
+ * permission registry.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(STORAGE_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const STORAGE_PERMISSIONS: {
+    /** `storage:read`: read object metadata and get download URLs (org scope). */
+    readonly STORAGE_READ: StoragePermissionDeclaration<'storage:read'>;
+    /** `storage:write`: upload and update metadata (org scope). */
+    readonly STORAGE_WRITE: StoragePermissionDeclaration<'storage:write'>;
+    /** `storage:delete_any`: delete any user's object, never another user's avatar (system scope). */
+    readonly STORAGE_DELETE_ANY: StoragePermissionDeclaration<'storage:delete_any'>;
+};
+//# sourceMappingURL=storage.permissions.d.ts.map

package/dist/storage/storage.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.permissions.d.ts","sourceRoot":"","sources":["../../src/storage/storage.permissions.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAOjG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,4BAA4B,CAAC,cAAc,CAAC,CAAC;IACpE,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,4BAA4B,CAAC,eAAe,CAAC,CAAC;IACtE,kGAAkG;IAClG,QAAQ,CAAC,kBAAkB,EAAE,4BAA4B,CAAC,oBAAoB,CAAC,CAAC;CAqBjF,CAAC"}

package/dist/storage/storage.permissions.js

@@ -0,0 +1,55 @@
+"use strict";
+// =============================================================================
+// Object-storage access permissions (issue #676, PP-1.4)
+// =============================================================================
+//
+// Pure data: this module's permissions and their default role grants. Imports
+// only types and has no side effect; the manifest slice (`registerPlatformPermissions()`)
+// registers it, and `common/constants/roles.constants.ts` derives `PERMISSIONS`
+// from it. After a change, run `npm run catalog:permissions --workspace=api` and
+// commit the regenerated `prisma/catalog/permissions.json`.
+// Recipe: common/permissions/README.md.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORAGE_PERMISSIONS = void 0;
+// Object ACCESS. `storage:read` and `storage:write` are ORG scope (issue #723):
+// a member's own objects, held through the membership role. `storage:delete_any`
+// stays SYSTEM scope: deleting anybody's object is an operator's act, held by
+// the system `admin` role only. The storage CONFIGURATION pair (`storage_config:*`) is a
+// separate, Admin-only declaration in `config/storage-config.permissions.ts`.
+/**
+ * The storage slice's object-access permissions, keyed by the `PERMISSIONS`
+ * constant name the reference app derives from them: `storage:read` and
+ * `storage:write` (org scope, held through the membership role) and
+ * `storage:delete_any` (system scope, `admin`). Register them with the app's
+ * permission registry.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(STORAGE_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+exports.STORAGE_PERMISSIONS = {
+    // Storage
+    STORAGE_READ: {
+        id: 'storage:read',
+        description: 'Read object metadata, get download URLs',
+        scope: 'org',
+        defaultGrants: ['org_admin', 'contributor', 'viewer'],
+    },
+    STORAGE_WRITE: {
+        id: 'storage:write',
+        description: 'Upload, update metadata',
+        scope: 'org',
+        defaultGrants: ['org_admin', 'contributor'],
+    },
+    STORAGE_DELETE_ANY: {
+        id: 'storage:delete_any',
+        description: 'Admin: delete any object',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+//# sourceMappingURL=storage.permissions.js.map

package/dist/storage/storage.permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.permissions.js","sourceRoot":"","sources":["../../src/storage/storage.permissions.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yDAAyD;AACzD,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,0FAA0F;AAC1F,gFAAgF;AAChF,iFAAiF;AACjF,4DAA4D;AAC5D,wCAAwC;AACxC,gFAAgF;;;AAchF,gFAAgF;AAChF,iFAAiF;AACjF,8EAA8E;AAC9E,yFAAyF;AACzF,8EAA8E;AAC9E;;;;;;;;;;;;;GAaG;AACU,QAAA,mBAAmB,GAO5B;IACF,UAAU;IACV,YAAY,EAAE;QACZ,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE,yCAAyC;QACtD,KAAK,EAAE,KAAK;QACZ,aAAa,EAAE,CAAC,WAAW,EAAE,aAAa,EAAE,QAAQ,CAAC;KACtD;IACD,aAAa,EAAE;QACb,EAAE,EAAE,eAAe;QACnB,WAAW,EAAE,yBAAyB;QACtC,KAAK,EAAE,KAAK;QACZ,aAAa,EAAE,CAAC,WAAW,EAAE,aAAa,CAAC;KAC5C;IACD,kBAAkB,EAAE;QAClB,EAAE,EAAE,oBAAoB;QACxB,WAAW,EAAE,0BAA0B;QACvC,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC"}

package/dist/storage/tasks/index.d.ts

@@ -0,0 +1,2 @@
+export * from './storage-cleanup.task';
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/tasks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/tasks/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/storage/tasks/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./storage-cleanup.task"), exports);
+//# sourceMappingURL=index.js.map

package/dist/storage/tasks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/tasks/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC"}

package/dist/storage/tasks/storage-cleanup.task.d.ts

@@ -0,0 +1,17 @@
+import { type JobsPrisma } from '../../jobs/index';
+import { JobsService } from '../../jobs/index';
+/**
+ * The daily `@Cron` that enqueues the `storage.cleanup.stale-uploads` job (enqueue only).
+ *
+ * @internal
+ *
+ * @stability experimental
+ */
+export declare class StorageCleanupTask {
+    private readonly jobs;
+    private readonly prisma;
+    private readonly logger;
+    constructor(jobs: JobsService, prisma: JobsPrisma);
+    handleCleanup(): Promise<void>;
+}
+//# sourceMappingURL=storage-cleanup.task.d.ts.map

package/dist/storage/tasks/storage-cleanup.task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-cleanup.task.d.ts","sourceRoot":"","sources":["../../../src/storage/tasks/storage-cleanup.task.ts"],"names":[],"mappings":"AAeA,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI/C;;;;;;GAMG;AACH,qBACa,kBAAkB;IAI3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACI,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJlD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAG3C,IAAI,EAAE,WAAW,EACQ,MAAM,EAAE,UAAU;IAIxD,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CASrC"}

package/dist/storage/tasks/storage-cleanup.task.js

@@ -0,0 +1,71 @@
+"use strict";
+// =============================================================================
+// The nightly stale-upload scheduler (issue #353, epic #345)
+// =============================================================================
+//
+// ⚠ THIS TASK ABORTS AND DELETES NOTHING. It enqueues a job, and
+// `storage/handlers/storage-cleanup.handler.ts` does the work on a worker slot.
+// See that handler's header for why the loop moved, and
+// `jobs/housekeeping.enqueue.ts` for the two guards in front of the enqueue.
+//
+// 4am, unchanged from before the conversion.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var StorageCleanupTask_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageCleanupTask = void 0;
+const common_1 = require("@nestjs/common");
+const schedule_1 = require("@nestjs/schedule");
+const index_1 = require("../../jobs/index");
+const index_2 = require("../../jobs/index");
+const storage_cleanup_handler_1 = require("../handlers/storage-cleanup.handler");
+const index_3 = require("../../core/index");
+/**
+ * The daily `@Cron` that enqueues the `storage.cleanup.stale-uploads` job (enqueue only).
+ *
+ * @internal
+ *
+ * @stability experimental
+ */
+let StorageCleanupTask = StorageCleanupTask_1 = class StorageCleanupTask {
+    jobs;
+    prisma;
+    logger = new common_1.Logger(StorageCleanupTask_1.name);
+    constructor(jobs, prisma) {
+        this.jobs = jobs;
+        this.prisma = prisma;
+    }
+    async handleCleanup() {
+        await (0, index_1.enqueueHousekeepingJob)({
+            jobs: this.jobs,
+            prisma: this.prisma,
+            logger: this.logger,
+            type: storage_cleanup_handler_1.STORAGE_CLEANUP_TYPE,
+            what: 'stale upload cleanup',
+        });
+    }
+};
+exports.StorageCleanupTask = StorageCleanupTask;
+__decorate([
+    (0, schedule_1.Cron)(schedule_1.CronExpression.EVERY_DAY_AT_4AM),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], StorageCleanupTask.prototype, "handleCleanup", null);
+exports.StorageCleanupTask = StorageCleanupTask = StorageCleanupTask_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(index_3.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [index_2.JobsService, Object])
+], StorageCleanupTask);
+//# sourceMappingURL=storage-cleanup.task.js.map

package/dist/storage/tasks/storage-cleanup.task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-cleanup.task.js","sourceRoot":"","sources":["../../../src/storage/tasks/storage-cleanup.task.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,6DAA6D;AAC7D,gFAAgF;AAChF,EAAE;AACF,iEAAiE;AACjE,gFAAgF;AAChF,wDAAwD;AACxD,6EAA6E;AAC7E,EAAE;AACF,6CAA6C;AAC7C,gFAAgF;;;;;;;;;;;;;;;;AAEhF,2CAA4D;AAC5D,+CAAwD;AAExD,4CAA2E;AAC3E,4CAA+C;AAC/C,iFAA2E;AAC3E,4CAAmD;AAEnD;;;;;;GAMG;AAEI,IAAM,kBAAkB,0BAAxB,MAAM,kBAAkB;IAIV;IACyB;IAJ3B,MAAM,GAAG,IAAI,eAAM,CAAC,oBAAkB,CAAC,IAAI,CAAC,CAAC;IAE9D,YACmB,IAAiB,EACQ,MAAkB;QAD3C,SAAI,GAAJ,IAAI,CAAa;QACQ,WAAM,GAAN,MAAM,CAAY;IAC3D,CAAC;IAGE,AAAN,KAAK,CAAC,aAAa;QACjB,MAAM,IAAA,8BAAsB,EAAC;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,8CAAoB;YAC1B,IAAI,EAAE,sBAAsB;SAC7B,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAlBY,gDAAkB;AASvB;IADL,IAAA,eAAI,EAAC,yBAAc,CAAC,gBAAgB,CAAC;;;;uDASrC;6BAjBU,kBAAkB;IAD9B,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;qCADD,mBAAW;GAJzB,kBAAkB,CAkB9B"}

package/dist/storage/testing/conformance.d.ts

@@ -0,0 +1,61 @@
+import type { ConformanceFinding, ConformanceSuite } from '../../testing/index';
+import { type StorageKeyPrefixDef } from '../storage-key-prefix.registry';
+declare module '../../testing/index' {
+    interface PlatformConformanceSuiteOptions {
+        /** The storage slice's suite: its options, or `false` to opt out. Registered by importing `@marinoscar/platform-api/storage/testing`. */
+        storage?: StorageConformanceOptions | false;
+    }
+}
+/**
+ * Options of the `storage` suite.
+ *
+ * @stability experimental
+ */
+export interface StorageConformanceOptions {
+    /** Prefix ids the app must have registered on top of the slice's own (its writers' prefixes). */
+    readonly requiredPrefixIds?: readonly string[];
+}
+/**
+ * Check 1: the registered prefixes are well-formed, disjoint and complete.
+ *
+ * @param defs - the registered prefixes.
+ * @param requiredIds - ids that must be among them.
+ * @returns one finding per problem.
+ *
+ * @stability experimental
+ */
+export declare function checkStorageKeyPrefixes(defs: readonly StorageKeyPrefixDef[], requiredIds: readonly string[]): ConformanceFinding[];
+/**
+ * Check 2: org-scoped prefixes build org-segmented keys and refuse a key
+ * without an organization (outside single-organization mode).
+ *
+ * @param defs - the registered prefixes.
+ * @returns one finding per problem.
+ *
+ * @stability experimental
+ */
+export declare function checkOrgScopedKeys(defs: readonly StorageKeyPrefixDef[]): ConformanceFinding[];
+/**
+ * Check 3: neither the stored `storage` namespace, its response branch nor
+ * the admin view declares a secret-named field.
+ *
+ * @returns one finding per offending field.
+ *
+ * @stability experimental
+ */
+export declare function checkStorageSettingsSchemas(): ConformanceFinding[];
+/**
+ * The `storage` conformance suite. Registered when
+ * `@marinoscar/platform-api/storage/testing` is imported.
+ *
+ * @example
+ * ```ts
+ * import '@marinoscar/platform-api/storage/testing';
+ * runPlatformConformance({ sourceRoots: [API_SOURCE_ROOT], suites: { storage: { requiredPrefixIds: ['exports'] } } });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const storageConformanceSuite: ConformanceSuite<StorageConformanceOptions>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/storage/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../src/storage/testing/conformance.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAmB,kBAAkB,EAAqB,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACpH,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,+BAA+B;QACvC,yIAAyI;QACzI,OAAO,CAAC,EAAE,yBAAyB,GAAG,KAAK,CAAC;KAC7C;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,iGAAiG;IACjG,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AASD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,mBAAmB,EAAE,EACpC,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,kBAAkB,EAAE,CAiBtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,mBAAmB,EAAE,GAAG,kBAAkB,EAAE,CAe7F;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,IAAI,kBAAkB,EAAE,CAWlE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,CAAC,yBAAyB,CA2C/E,CAAC"}