@astram/guard 0.12.1 → 0.14.0

package/dist/storage/file-intake.interceptor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `FileIntake(options)` (FILE_STORAGE SPEC §5 G, §13): one multipart file, checked, then handed
+ * to the route handler.
+ *
+ *   @Classified({ typeKey: 'stored_file', action: 'create' })
+ *   @UseInterceptors(FileIntake({ field: 'file', profile: 'xlsx' }))
+ *
+ * - Interceptors run after guards, so the global guard has decided (and a denied caller is
+ *   refused) before any multipart byte is read (Shield #1, #3). A request with no principal is
+ *   refused here too, before parsing.
+ * - Parsing wraps `@nestjs/platform-express` `FileInterceptor` with multer's memory storage
+ *   (no module-level `MulterModule` options apply: no disk storage, no consumer file filter) and
+ *   limits `{ files: 1, fileSize: maxBytes + 1, fields: 0, parts: 2 }` and `defParamCharset:
+ *   'utf8'`. `maxBytes` defaults to the bound profile's configured cap (`OBJECT_STORAGE_MAX_BYTES`
+ *   under `storage: 'env'`); an explicit smaller `maxBytes` wins; never above 50 MiB.
+ * - Then `SHIELD_FILE_INGEST` checks the bytes (size, extension, declared type, magic) with the
+ *   tenant from the session (`req.principal.tenantId`, never the request body).
+ * - Errors are mapped here, at the source: 400 / 413 / 415 `HttpException`s carrying a fixed
+ *   reason code. The file name, field name and bytes are never echoed (Shield #10).
+ * - On success the request carries `req[FILE_INTAKE_REQUEST_KEY] = { file, bytes }` for
+ *   `FilesService.store`; multer's raw `req.file` (unsanitised name) is removed.
+ */
+import { type NestInterceptor, type Type } from '@nestjs/common';
+import { type FileRejectionReason, type IngestedFile } from '@astram/core';
+/** The HTTP reason codes `FileIntake` answers with: the core reasons plus `bad_request`. */
+export type FileIntakeRejectionReason = FileRejectionReason | 'bad_request';
+/** Options for {@link FileIntake}. */
+export interface FileIntakeOptions {
+    /** The multipart field that carries the file. */
+    readonly field: string;
+    /** A profile name known to `SHIELD_FILE_INGEST` (e.g. `'xlsx'`). */
+    readonly profile: string;
+    /**
+     * Lower multipart byte cap for this route (at most 50 MiB). Default: the profile's configured
+     * cap on `SHIELD_FILE_INGEST` (`OBJECT_STORAGE_MAX_BYTES` under `storage: 'env'`, else 10 MiB);
+     * a larger value than the profile cap is lowered to it. The parser stops at `maxBytes + 1`;
+     * the profile's own cap still applies in the ingest check.
+     */
+    readonly maxBytes?: number;
+}
+/** What {@link FileIntake} attaches to the request for `FilesService.store`. */
+export interface FileIntakeResult {
+    /** Server-built metadata (storage key, sha256, canonical type, size, sanitised name). */
+    readonly file: IngestedFile;
+    /** The exact bytes that were checked. */
+    readonly bytes: Uint8Array;
+}
+/** The request property {@link FileIntake} sets to a {@link FileIntakeResult}. */
+export declare const FILE_INTAKE_REQUEST_KEY = "shieldFileIntake";
+/** Fallback multipart cap (10 MiB, SPEC §10) when the bound ingest cannot report a profile cap. */
+export declare const FILE_INTAKE_DEFAULT_MAX_BYTES: number;
+/** Build the intake interceptor for one route (see the file header). Throws at boot on bad options. */
+export declare function FileIntake(options: FileIntakeOptions): Type<NestInterceptor>;
+//# sourceMappingURL=file-intake.interceptor.d.ts.map

package/dist/storage/file-intake.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-intake.interceptor.d.ts","sourceRoot":"","sources":["../../src/storage/file-intake.interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAWL,KAAK,eAAe,EACpB,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAMtB,4FAA4F;AAC5F,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,GAAG,aAAa,CAAC;AAE5E,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D,mGAAmG;AACnG,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAuH9D,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC,eAAe,CAAC,CAkF5E"}

package/dist/storage/file-intake.interceptor.js

@@ -0,0 +1,223 @@
+"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 __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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_INTAKE_DEFAULT_MAX_BYTES = exports.FILE_INTAKE_REQUEST_KEY = void 0;
+exports.FileIntake = FileIntake;
+/**
+ * `FileIntake(options)` (FILE_STORAGE SPEC §5 G, §13): one multipart file, checked, then handed
+ * to the route handler.
+ *
+ *   @Classified({ typeKey: 'stored_file', action: 'create' })
+ *   @UseInterceptors(FileIntake({ field: 'file', profile: 'xlsx' }))
+ *
+ * - Interceptors run after guards, so the global guard has decided (and a denied caller is
+ *   refused) before any multipart byte is read (Shield #1, #3). A request with no principal is
+ *   refused here too, before parsing.
+ * - Parsing wraps `@nestjs/platform-express` `FileInterceptor` with multer's memory storage
+ *   (no module-level `MulterModule` options apply: no disk storage, no consumer file filter) and
+ *   limits `{ files: 1, fileSize: maxBytes + 1, fields: 0, parts: 2 }` and `defParamCharset:
+ *   'utf8'`. `maxBytes` defaults to the bound profile's configured cap (`OBJECT_STORAGE_MAX_BYTES`
+ *   under `storage: 'env'`); an explicit smaller `maxBytes` wins; never above 50 MiB.
+ * - Then `SHIELD_FILE_INGEST` checks the bytes (size, extension, declared type, magic) with the
+ *   tenant from the session (`req.principal.tenantId`, never the request body).
+ * - Errors are mapped here, at the source: 400 / 413 / 415 `HttpException`s carrying a fixed
+ *   reason code. The file name, field name and bytes are never echoed (Shield #10).
+ * - On success the request carries `req[FILE_INTAKE_REQUEST_KEY] = { file, bytes }` for
+ *   `FilesService.store`; multer's raw `req.file` (unsanitised name) is removed.
+ */
+const common_1 = require("@nestjs/common");
+const rxjs_1 = require("rxjs");
+const core_1 = require("@astram/core");
+const shield_tokens_js_1 = require("../module/shield-tokens.js");
+const optional_peer_js_1 = require("./optional-peer.js");
+/** The request property {@link FileIntake} sets to a {@link FileIntakeResult}. */
+exports.FILE_INTAKE_REQUEST_KEY = 'shieldFileIntake';
+/** Fallback multipart cap (10 MiB, SPEC §10) when the bound ingest cannot report a profile cap. */
+exports.FILE_INTAKE_DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+const STATUS_BY_REASON = {
+    empty: 400,
+    too_large: 413,
+    type_not_allowed: 415,
+    content_mismatch: 415,
+    too_many_files: 400,
+    missing_file: 400,
+    bad_request: 400,
+};
+/** The core reasons `createFileIngest` may throw (`bad_request` is intake-only). */
+const CORE_REASONS = new Set([
+    'empty',
+    'too_large',
+    'type_not_allowed',
+    'content_mismatch',
+    'too_many_files',
+    'missing_file',
+]);
+/**
+ * Nest's messages for the multer limits that mean "more than one file, or extra fields" (SPEC
+ * §13 -> `too_many_files`): `LIMIT_FILE_COUNT`, `LIMIT_FIELD_COUNT`, `LIMIT_PART_COUNT` and
+ * `LIMIT_UNEXPECTED_FILE` (a file part under another field, or a second file in this one).
+ * Nest may append ` - <field>`, so the message is matched by prefix and never passed on.
+ */
+const TOO_MANY_PREFIXES = [
+    'Too many files',
+    'Too many fields',
+    'Too many parts',
+    'Unexpected file',
+];
+/** The fixed-body exception for a refused file (status per SPEC §13). */
+function fileRejection(reason) {
+    const status = STATUS_BY_REASON[reason];
+    const body = { statusCode: status, message: `file rejected: ${reason}`, reason };
+    if (status === 413)
+        return new common_1.PayloadTooLargeException(body);
+    if (status === 415)
+        return new common_1.UnsupportedMediaTypeException(body);
+    return new common_1.BadRequestException(body);
+}
+/**
+ * Map a parser failure to a fixed reason, by status first. `FileInterceptor` has already turned
+ * multer/busboy errors into `PayloadTooLargeException` (`LIMIT_FILE_SIZE`) or
+ * `BadRequestException`:
+ * - 413 -> `too_large`;
+ * - 400 whose message is one of the count / unexpected-file limits -> `too_many_files`;
+ * - any other 4xx/5xx `HttpException` (malformed multipart, missing boundary, unexpected end of
+ *   form, field name too long, ...) -> 400 `bad_request`: the request is broken, not missing a
+ *   file.
+ * The parser's message may name the field, so it is only matched, never passed on.
+ */
+function parserRejection(err) {
+    if (!(err instanceof common_1.HttpException))
+        return err;
+    const status = err.getStatus();
+    if (status === 413)
+        return fileRejection('too_large');
+    if (status === 400) {
+        const res = err.getResponse();
+        const message = typeof res === 'string'
+            ? res
+            : typeof res?.message === 'string'
+                ? res.message
+                : '';
+        if (TOO_MANY_PREFIXES.some((p) => message.startsWith(p))) {
+            return fileRejection('too_many_files');
+        }
+    }
+    return fileRejection('bad_request');
+}
+function isFileRejection(e) {
+    if (e instanceof core_1.FileRejectedError)
+        return true;
+    // Duck-typed too: a dual-package (ESM/CJS) copy of core is a different class.
+    return (typeof e === 'object' &&
+        e !== null &&
+        e.name === 'FileRejectedError' &&
+        CORE_REASONS.has(String(e.reason)));
+}
+/**
+ * The multipart cap for one route: the bound profile's configured cap (`OBJECT_STORAGE_MAX_BYTES`
+ * under `storage: 'env'`), lowered by an explicit `maxBytes`, never above the 50 MiB ceiling. An
+ * ingest that cannot report caps (a hand-written `FileIngest`) falls back to the explicit value or
+ * {@link FILE_INTAKE_DEFAULT_MAX_BYTES}. A profile the bound ingest does not know aborts boot.
+ */
+function routeMaxBytes(ingest, profile, explicit) {
+    if (typeof ingest?.maxBytesFor !== 'function') {
+        return Math.min(explicit ?? exports.FILE_INTAKE_DEFAULT_MAX_BYTES, core_1.FILE_MAX_BYTES_CEILING);
+    }
+    const profileCap = ingest.maxBytesFor(profile);
+    if (typeof profileCap !== 'number' ||
+        !Number.isInteger(profileCap) ||
+        profileCap <= 0 ||
+        profileCap > core_1.FILE_MAX_BYTES_CEILING) {
+        throw new Error(`FileIntake: profile '${profile}' is not registered on SHIELD_FILE_INGEST`);
+    }
+    return Math.min(explicit ?? profileCap, profileCap);
+}
+/** Build the intake interceptor for one route (see the file header). Throws at boot on bad options. */
+function FileIntake(options) {
+    const { field, profile } = options;
+    if (typeof field !== 'string' || field.trim() === '') {
+        throw new Error('FileIntake: `field` must be a non-empty string');
+    }
+    if (typeof profile !== 'string' || profile.trim() === '') {
+        throw new Error('FileIntake: `profile` must be a non-empty string');
+    }
+    const explicitMax = options.maxBytes;
+    if (explicitMax !== undefined &&
+        (!Number.isInteger(explicitMax) || explicitMax <= 0 || explicitMax > core_1.FILE_MAX_BYTES_CEILING)) {
+        throw new Error(`FileIntake: maxBytes must be a positive integer of at most ${core_1.FILE_MAX_BYTES_CEILING}`);
+    }
+    // Loaded here, not at module top, so `require('@astram/guard')` does not need the optional
+    // peer `@nestjs/platform-express`; a missing package is a clear error at controller load.
+    const { FileInterceptor } = (0, optional_peer_js_1.requireOptionalPeer)('@nestjs/platform-express', 'FileIntake');
+    let FileIntakeInterceptor = class FileIntakeInterceptor {
+        ingest;
+        multipart;
+        constructor(ingest) {
+            this.ingest = ingest;
+            const maxBytes = routeMaxBytes(ingest, profile, explicitMax);
+            // No `storage`/`dest`: multer keeps the file in memory. Instantiated with empty module
+            // options, so an app-level MulterModule configuration cannot switch this route to disk.
+            // `defParamCharset: 'utf8'`: a raw UTF-8 `filename="..."` is decoded as UTF-8 (busboy's
+            // default is latin1), so it sanitises to the same name as the RFC 5987 `filename*` form.
+            const Multipart = FileInterceptor(field, {
+                limits: { files: 1, fileSize: maxBytes + 1, fields: 0, parts: 2 },
+                defParamCharset: 'utf8',
+            });
+            this.multipart = new Multipart({});
+        }
+        async intercept(context, next) {
+            const req = context.switchToHttp().getRequest();
+            const tenantId = req.principal?.tenantId;
+            if (typeof tenantId !== 'string' || tenantId === '') {
+                // No session principal (e.g. a misclassified public route): refuse before parsing.
+                throw new common_1.ForbiddenException();
+            }
+            try {
+                // Resolves once multer has parsed the body; the inner `next` is a no-op.
+                await this.multipart.intercept(context, { handle: () => rxjs_1.EMPTY });
+            }
+            catch (e) {
+                throw parserRejection(e);
+            }
+            const part = req.file;
+            delete req.file;
+            if (!part || !Buffer.isBuffer(part.buffer))
+                throw fileRejection('missing_file');
+            const bytes = new Uint8Array(part.buffer.buffer, part.buffer.byteOffset, part.buffer.length);
+            let file;
+            try {
+                file = await this.ingest.ingest({
+                    tenantId,
+                    profile,
+                    bytes,
+                    declaredContentType: part.mimetype ?? '',
+                    originalName: part.originalname ?? '',
+                });
+            }
+            catch (e) {
+                if (isFileRejection(e))
+                    throw fileRejection(e.reason);
+                throw e;
+            }
+            req[exports.FILE_INTAKE_REQUEST_KEY] = { file, bytes };
+            return next.handle();
+        }
+    };
+    FileIntakeInterceptor = __decorate([
+        (0, common_1.Injectable)(),
+        __param(0, (0, common_1.Inject)(shield_tokens_js_1.SHIELD_FILE_INGEST)),
+        __metadata("design:paramtypes", [Object])
+    ], FileIntakeInterceptor);
+    return (0, common_1.mixin)(FileIntakeInterceptor);
+}

package/dist/storage/node-sha256-digest.d.ts

@@ -0,0 +1,6 @@
+import type { ByteDigest } from '@astram/core';
+export declare class NodeSha256Digest implements ByteDigest {
+    /** Lower-case hex sha256 of the raw bytes. */
+    sha256(bytes: Uint8Array): Promise<string>;
+}
+//# sourceMappingURL=node-sha256-digest.d.ts.map

package/dist/storage/node-sha256-digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sha256-digest.d.ts","sourceRoot":"","sources":["../../src/storage/node-sha256-digest.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,qBAAa,gBAAiB,YAAW,UAAU;IACjD,8CAA8C;IACxC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;CAGjD"}

package/dist/storage/node-sha256-digest.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeSha256Digest = void 0;
+/**
+ * `ByteDigest` adapter over `node:crypto` (FILE_STORAGE SPEC §5 B, E). Core is zero-dependency,
+ * so the hash is injected into `createFileIngest`.
+ */
+const node_crypto_1 = require("node:crypto");
+class NodeSha256Digest {
+    /** Lower-case hex sha256 of the raw bytes. */
+    async sha256(bytes) {
+        return (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    }
+}
+exports.NodeSha256Digest = NodeSha256Digest;

package/dist/storage/object-store-boot-check.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Boot check for the bound `ObjectStore` (FILE_STORAGE SPEC §5 H, §12). Registered by
+ * `ShieldModule` only when a `storage` option is given; pings once at bootstrap and aborts the
+ * boot (Shield #1) when the bucket is unreachable, not writable, or refuses SSE.
+ *
+ * The message names the bucket (`OBJECT_STORAGE_BUCKET`) and the variables to check, never a
+ * credential, the endpoint or the underlying error text (Shield #10).
+ */
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import type { ObjectStore } from '@astram/core';
+export declare class ObjectStoreBootCheck implements OnApplicationBootstrap {
+    private readonly store;
+    constructor(store: ObjectStore | null);
+    onApplicationBootstrap(): Promise<void>;
+}
+//# sourceMappingURL=object-store-boot-check.d.ts.map

package/dist/storage/object-store-boot-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-store-boot-check.d.ts","sourceRoot":"","sources":["../../src/storage/object-store-boot-check.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAgC,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,qBACa,oBAAqB,YAAW,sBAAsB;IAEtB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW,GAAG,IAAI;IAG/E,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CAc9C"}

package/dist/storage/object-store-boot-check.js

@@ -0,0 +1,52 @@
+"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 __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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectStoreBootCheck = void 0;
+/**
+ * Boot check for the bound `ObjectStore` (FILE_STORAGE SPEC §5 H, §12). Registered by
+ * `ShieldModule` only when a `storage` option is given; pings once at bootstrap and aborts the
+ * boot (Shield #1) when the bucket is unreachable, not writable, or refuses SSE.
+ *
+ * The message names the bucket (`OBJECT_STORAGE_BUCKET`) and the variables to check, never a
+ * credential, the endpoint or the underlying error text (Shield #10).
+ */
+const common_1 = require("@nestjs/common");
+const shield_tokens_js_1 = require("../module/shield-tokens.js");
+let ObjectStoreBootCheck = class ObjectStoreBootCheck {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async onApplicationBootstrap() {
+        if (!this.store)
+            return;
+        try {
+            await this.store.ping();
+        }
+        catch {
+            const bucket = process.env.OBJECT_STORAGE_BUCKET?.trim();
+            const named = bucket ? `bucket '${bucket}' (OBJECT_STORAGE_BUCKET)` : 'the configured bucket';
+            throw new Error(`Object storage boot check failed: ${named} is not reachable, not writable or refused ` +
+                'server-side encryption with the configured key. Check OBJECT_STORAGE_ENDPOINT, ' +
+                'OBJECT_STORAGE_ACCESS_KEY_ID, OBJECT_STORAGE_SECRET_ACCESS_KEY and the bucket policy.');
+        }
+    }
+};
+exports.ObjectStoreBootCheck = ObjectStoreBootCheck;
+exports.ObjectStoreBootCheck = ObjectStoreBootCheck = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(shield_tokens_js_1.SHIELD_OBJECT_STORE)),
+    __metadata("design:paramtypes", [Object])
+], ObjectStoreBootCheck);

package/dist/storage/optional-peer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Synchronous load of an OPTIONAL peer dependency at the point a feature is used, so that
+ * `require('@astram/guard')` itself never loads it (review P1-2: `@nestjs/platform-express` is
+ * only needed by apps that use `FileIntake`). Guard is CommonJS, so `require` is the loader.
+ *
+ * A missing package becomes one clear error naming the package and the feature; any other load
+ * failure (the package is installed but throws) is rethrown unchanged.
+ */
+export declare function requireOptionalPeer<T>(name: string, feature: string, load?: (id: string) => unknown): T;
+//# sourceMappingURL=optional-peer.d.ts.map

package/dist/storage/optional-peer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-peer.d.ts","sourceRoot":"","sources":["../../src/storage/optional-peer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAiB,GACtC,CAAC,CAeH"}

package/dist/storage/optional-peer.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireOptionalPeer = requireOptionalPeer;
+/**
+ * Synchronous load of an OPTIONAL peer dependency at the point a feature is used, so that
+ * `require('@astram/guard')` itself never loads it (review P1-2: `@nestjs/platform-express` is
+ * only needed by apps that use `FileIntake`). Guard is CommonJS, so `require` is the loader.
+ *
+ * A missing package becomes one clear error naming the package and the feature; any other load
+ * failure (the package is installed but throws) is rethrown unchanged.
+ */
+function requireOptionalPeer(name, feature, load = require) {
+    try {
+        return load(name);
+    }
+    catch (e) {
+        const err = e;
+        const missing = err?.code === 'MODULE_NOT_FOUND' &&
+            typeof err.message === 'string' &&
+            err.message.includes(`'${name}'`);
+        if (!missing)
+            throw e;
+        throw new Error(`${feature} requires the optional peer dependency ${name}; install it in the app ` +
+            `(e.g. \`pnpm add ${name}\`)`);
+    }
+}

package/dist/storage/s3-object-store.d.ts

@@ -0,0 +1,35 @@
+import { type ObjectPutMeta, type ObjectStore, type StoredObject, type StoredObjectHead } from '@astram/core';
+import type { ObjectStorageConfig } from '../config/app-config.js';
+/**
+ * The connection fields `S3ObjectStore` needs (the {@link ObjectStorageConfig} result).
+ * `maxBytes` caps what `get` will buffer (default and maximum: `FILE_MAX_BYTES_CEILING`).
+ */
+export type S3ObjectStoreConfig = Pick<ObjectStorageConfig, 'endpoint' | 'bucket' | 'region' | 'accessKeyId' | 'secretAccessKey' | 'sse'> & {
+    readonly maxBytes?: number;
+};
+export interface S3ObjectStoreOptions {
+    /**
+     * How `put` refuses to overwrite. `'if-none-match'` (default): a conditional PUT
+     * (`If-None-Match: *`), atomic on the server. `'head-first'`: for a backend that does not
+     * support conditional PUT (SPEC §5 E assumption) — `head` first, refuse when the key exists,
+     * then a plain PUT; not atomic, so it relies on the server-built uuid key for uniqueness.
+     */
+    readonly noOverwrite?: 'if-none-match' | 'head-first';
+}
+export declare class S3ObjectStore implements ObjectStore {
+    private readonly config;
+    private readonly bucket;
+    private readonly sse;
+    private readonly noOverwrite;
+    private readonly maxGetBytes;
+    private connection;
+    constructor(config: S3ObjectStoreConfig, options?: S3ObjectStoreOptions);
+    /** The SDK and the client, built on first use. */
+    private connect;
+    put(key: string, bytes: Uint8Array, meta: ObjectPutMeta): Promise<void>;
+    get(key: string): Promise<StoredObject>;
+    head(key: string): Promise<StoredObjectHead | null>;
+    delete(key: string): Promise<void>;
+    ping(): Promise<void>;
+}
+//# sourceMappingURL=s3-object-store.d.ts.map

package/dist/storage/s3-object-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-object-store.d.ts","sourceRoot":"","sources":["../../src/storage/s3-object-store.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAiBnE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,mBAAmB,EACnB,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,iBAAiB,GAAG,KAAK,CAC7E,GAAG;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,GAAG,YAAY,CAAC;CACvD;AAWD,qBAAa,aAAc,YAAW,WAAW;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,UAAU,CAAkC;gBAExC,MAAM,EAAE,mBAAmB,EAAE,OAAO,GAAE,oBAAyB;IAc3E,kDAAkD;IAClD,OAAO,CAAC,OAAO;IAmBT,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA2BvC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAcnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB5B"}