@astram/guard 0.13.0 → 0.15.0

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"}

package/dist/storage/s3-object-store.js

@@ -0,0 +1,238 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3ObjectStore = void 0;
+/**
+ * `ObjectStore` over the S3 API (FILE_STORAGE SPEC §5 E) for MinIO and S3-compatible hosts.
+ *
+ * - Path-style addressing (`forcePathStyle`), region and credentials from {@link ObjectStorageConfig}.
+ * - `put`: SSE-S3 (`ServerSideEncryption: 'AES256'`) on every write, no overwrite
+ *   (`IfNoneMatch: '*'`), content type, and the sha256 both as `ChecksumSHA256` (the server
+ *   verifies the bytes) and as `x-amz-meta-sha256`.
+ * - `get`/`head`/`delete`: a missing key maps to `ObjectNotFoundError` / `null` / no-op. `get`
+ *   refuses an object whose `ContentLength` is missing or above the configured cap (at most the
+ *   50 MiB `FILE_MAX_BYTES_CEILING`) before reading any body byte.
+ * - Every other SDK failure becomes `ObjectStoreUnavailableError` with its fixed message and NO
+ *   `cause`: SDK errors can carry the endpoint, request id or credentials (Shield #10).
+ * - `ping`: `HeadBucket`, then put/get/delete of one probe object under `_probe/`, so a missing
+ *   write permission or a refused SSE header fails the boot check.
+ *
+ * `@aws-sdk/client-s3` is imported here as TYPES only. The runtime module is loaded on the first
+ * operation (one cached load per process), so `require('@astram/guard')` never loads the SDK.
+ */
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@astram/core");
+let sdkLoad;
+/** Load `@aws-sdk/client-s3` once, on first use (a failed load is retried next time). */
+function loadSdk() {
+    if (!sdkLoad) {
+        sdkLoad = Promise.resolve().then(() => __importStar(require('@aws-sdk/client-s3'))).catch((e) => {
+            sdkLoad = undefined;
+            throw e;
+        });
+    }
+    return sdkLoad;
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const PROBE_BYTES = new TextEncoder().encode('shield object store probe');
+const PROBE_CONTENT_TYPE = 'application/octet-stream';
+class S3ObjectStore {
+    config;
+    bucket;
+    sse;
+    noOverwrite;
+    maxGetBytes;
+    connection;
+    constructor(config, options = {}) {
+        const maxBytes = config.maxBytes ?? core_1.FILE_MAX_BYTES_CEILING;
+        if (!Number.isInteger(maxBytes) || maxBytes <= 0 || maxBytes > core_1.FILE_MAX_BYTES_CEILING) {
+            throw new Error(`S3ObjectStore: maxBytes must be a positive integer of at most ${core_1.FILE_MAX_BYTES_CEILING}`);
+        }
+        this.config = config;
+        this.bucket = config.bucket;
+        this.sse = config.sse;
+        this.noOverwrite = options.noOverwrite ?? 'if-none-match';
+        this.maxGetBytes = maxBytes;
+    }
+    /** The SDK and the client, built on first use. */
+    connect() {
+        if (!this.connection) {
+            const { endpoint, region, accessKeyId, secretAccessKey } = this.config;
+            this.connection = loadSdk().then((sdk) => ({
+                sdk,
+                client: new sdk.S3Client({
+                    endpoint,
+                    region,
+                    forcePathStyle: true,
+                    credentials: { accessKeyId, secretAccessKey },
+                }),
+            }));
+            this.connection.catch(() => {
+                this.connection = undefined;
+            });
+        }
+        return this.connection;
+    }
+    async put(key, bytes, meta) {
+        if (!SHA256_HEX.test(meta.sha256))
+            throw new core_1.ObjectStoreUnavailableError();
+        if (this.noOverwrite === 'head-first' && (await this.head(key)) !== null) {
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+        const { sdk, client } = await this.connect();
+        const input = {
+            Bucket: this.bucket,
+            Key: key,
+            Body: bytes,
+            ContentType: meta.contentType,
+            ContentLength: bytes.length,
+            ServerSideEncryption: this.sse,
+            ChecksumSHA256: Buffer.from(meta.sha256, 'hex').toString('base64'),
+            Metadata: { sha256: meta.sha256 },
+            ...(this.noOverwrite === 'if-none-match' ? { IfNoneMatch: '*' } : {}),
+        };
+        try {
+            await client.send(new sdk.PutObjectCommand(input));
+        }
+        catch {
+            // A 412 (key exists) is a refusal too: never overwrite. Fixed message, no cause.
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+    }
+    async get(key) {
+        const { sdk, client } = await this.connect();
+        let bytes;
+        let contentType;
+        try {
+            const out = await client.send(new sdk.GetObjectCommand({ Bucket: this.bucket, Key: key }));
+            if (!out.Body)
+                throw new core_1.ObjectStoreUnavailableError();
+            const length = out.ContentLength;
+            if (typeof length !== 'number' || length < 0 || length > this.maxGetBytes) {
+                // Unknown or over the cap: refuse before buffering, and release the socket.
+                discardBody(out.Body);
+                throw new core_1.ObjectStoreUnavailableError();
+            }
+            bytes = await out.Body.transformToByteArray();
+            if (bytes.length > this.maxGetBytes)
+                throw new core_1.ObjectStoreUnavailableError();
+            contentType = out.ContentType;
+        }
+        catch (e) {
+            if (isNotFound(e))
+                throw new core_1.ObjectNotFoundError();
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+        return {
+            bytes,
+            contentType: contentType ?? PROBE_CONTENT_TYPE,
+            sizeBytes: bytes.length,
+        };
+    }
+    async head(key) {
+        const { sdk, client } = await this.connect();
+        try {
+            const out = await client.send(new sdk.HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+            return {
+                sizeBytes: out.ContentLength ?? 0,
+                contentType: out.ContentType ?? PROBE_CONTENT_TYPE,
+            };
+        }
+        catch (e) {
+            if (isNotFound(e))
+                return null;
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+    }
+    async delete(key) {
+        const { sdk, client } = await this.connect();
+        try {
+            await client.send(new sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: key }));
+        }
+        catch (e) {
+            if (isNotFound(e))
+                return;
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+    }
+    async ping() {
+        const { sdk, client } = await this.connect();
+        try {
+            await client.send(new sdk.HeadBucketCommand({ Bucket: this.bucket }));
+        }
+        catch {
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+        const key = `_probe/${(0, node_crypto_1.randomUUID)()}`;
+        const sha256 = (0, node_crypto_1.createHash)('sha256').update(PROBE_BYTES).digest('hex');
+        await this.put(key, PROBE_BYTES, { contentType: PROBE_CONTENT_TYPE, sha256 });
+        try {
+            const got = await this.get(key);
+            if (!sameBytes(got.bytes, PROBE_BYTES))
+                throw new core_1.ObjectStoreUnavailableError();
+        }
+        catch {
+            throw new core_1.ObjectStoreUnavailableError();
+        }
+        finally {
+            await this.delete(key).catch(() => undefined);
+        }
+    }
+}
+exports.S3ObjectStore = S3ObjectStore;
+/** Best-effort release of an unread response body (a Node stream in the SDK's Node runtime). */
+function discardBody(body) {
+    const destroy = body.destroy;
+    if (typeof destroy === 'function') {
+        try {
+            destroy.call(body);
+        }
+        catch {
+            // Nothing to report: the request is refused either way.
+        }
+    }
+}
+/** S3 "no such key" (GET: `NoSuchKey`; HEAD: `NotFound`; or a bare 404 that is not a missing bucket). */
+function isNotFound(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const err = e;
+    if (err.name === 'NoSuchKey' || err.name === 'NotFound')
+        return true;
+    return err.$metadata?.httpStatusCode === 404 && err.name !== 'NoSuchBucket';
+}
+function sameBytes(a, b) {
+    return a.length === b.length && Buffer.from(a).equals(Buffer.from(b));
+}

package/dist/storage/storage.providers.d.ts

@@ -0,0 +1,10 @@
+import type { Provider } from '@nestjs/common';
+import { type ObjectStore } from '@astram/core';
+import { SHIELD_FILE_INGEST, SHIELD_OBJECT_STORE } from '../module/shield-tokens.js';
+/** The `storage` option on `ShieldModule.forRoot` / `forRootAsync`. */
+export type ShieldStorageOption = ObjectStore | 'env';
+/** The tokens `ShieldModule` exports app-wide for the storage option. */
+export declare const STORAGE_EXPORTS: readonly [typeof SHIELD_OBJECT_STORE, typeof SHIELD_FILE_INGEST];
+/** Build the storage providers for one `ShieldModule` registration (see the file header). */
+export declare function storageProviders(storage: ShieldStorageOption | undefined): Provider[];
+//# sourceMappingURL=storage.providers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.providers.d.ts","sourceRoot":"","sources":["../../src/storage/storage.providers.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAGjG,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAIrF,uEAAuE;AACvE,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,KAAK,CAAC;AAEtD,yEAAyE;AACzE,eAAO,MAAM,eAAe,kEAAqD,CAAC;AAIlF,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,QAAQ,EAAE,CA6CrF"}