@astram/guard 0.12.1 → 0.14.0

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

package/dist/storage/storage.providers.js

@@ -0,0 +1,104 @@
+"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.STORAGE_EXPORTS = void 0;
+exports.storageProviders = storageProviders;
+/**
+ * `ShieldModule` providers for the `storage` option (FILE_STORAGE SPEC §6):
+ * - `SHIELD_OBJECT_STORE`: the given `ObjectStore`, an `S3ObjectStore` built from
+ *   `OBJECT_STORAGE_*` (`'env'`; `null` when `OBJECT_STORAGE_BUCKET` is unset), or `null` when
+ *   the option is absent (the `makeAuditSinkProvider` null-binding pattern; callers answer 501).
+ * - `SHIELD_FILE_INGEST`: core `createFileIngest` over `NodeSha256Digest`, with the `xlsx`
+ *   profile (its cap set from `OBJECT_STORAGE_MAX_BYTES` under `'env'`). Always bound.
+ * - `ObjectStoreBootCheck`: registered only when the option is given (fail-closed ping at boot).
+ *
+ * `S3ObjectStore` (and so `@aws-sdk/client-s3`) is loaded lazily, only for `'env'` with a bucket.
+ */
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@astram/core");
+const app_config_js_1 = require("../config/app-config.js");
+const boot_secrets_js_1 = require("../secrets/boot-secrets.js");
+const shield_tokens_js_1 = require("../module/shield-tokens.js");
+const node_sha256_digest_js_1 = require("./node-sha256-digest.js");
+const object_store_boot_check_js_1 = require("./object-store-boot-check.js");
+/** The tokens `ShieldModule` exports app-wide for the storage option. */
+exports.STORAGE_EXPORTS = [shield_tokens_js_1.SHIELD_OBJECT_STORE, shield_tokens_js_1.SHIELD_FILE_INGEST];
+const STORE_METHODS = ['put', 'get', 'head', 'delete', 'ping'];
+/** Build the storage providers for one `ShieldModule` registration (see the file header). */
+function storageProviders(storage) {
+    if (storage !== undefined && storage !== 'env') {
+        const s = storage;
+        if (STORE_METHODS.some((m) => typeof s?.[m] !== 'function')) {
+            throw new Error("ShieldModule: `storage` must be an ObjectStore (put/get/head/delete/ping) or 'env'");
+        }
+    }
+    const configToken = Symbol('SHIELD_OBJECT_STORAGE_CONFIG');
+    return [
+        {
+            provide: configToken,
+            useFactory: () => storage === 'env'
+                ? ((0, app_config_js_1.loadObjectStorageConfig)(process.env, {
+                    resolvedFromSecretRef: boot_secrets_js_1.wasResolvedFromSecretRef,
+                }) ?? null)
+                : null,
+        },
+        {
+            provide: shield_tokens_js_1.SHIELD_OBJECT_STORE,
+            useFactory: async (config) => {
+                if (storage === undefined)
+                    return null;
+                if (storage !== 'env')
+                    return storage;
+                if (config === null)
+                    return null;
+                const { S3ObjectStore } = await Promise.resolve().then(() => __importStar(require('./s3-object-store.js')));
+                return new S3ObjectStore(config);
+            },
+            inject: [configToken],
+        },
+        {
+            provide: shield_tokens_js_1.SHIELD_FILE_INGEST,
+            useFactory: (config) => (0, core_1.createFileIngest)({
+                digest: new node_sha256_digest_js_1.NodeSha256Digest(),
+                newId: node_crypto_1.randomUUID,
+                profiles: {
+                    xlsx: config ? { ...core_1.XLSX_PROFILE, maxBytes: config.maxBytes } : core_1.XLSX_PROFILE,
+                },
+            }),
+            inject: [configToken],
+        },
+        ...(storage !== undefined ? [object_store_boot_check_js_1.ObjectStoreBootCheck] : []),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "license": "MIT",
   "description": "Astram framework — the enforcement guard + real-world adapters (the 'hands'). One global deny-by-default gate every request passes through (ADR-0002), classification decorators, boot-pool assertion (ADR-0018), the forRoot() registration seam, and the DB/Redis/crypto adapters that connect the sealed core to a real backend. Depends on @astram/core (ADR-0003, ADR-0023).",
   "type": "commonjs",
@@ -32,21 +32,29 @@
     "access": "public"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "3.1142.0",
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.5.4",
-    "@astram/core": "1.5.0",
-    "@astram/engine": "0.5.3"
+    "@astram/core": "1.6.0",
+    "@astram/engine": "0.7.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",
     "@nestjs/core": "^11",
+    "@nestjs/platform-express": "^11",
     "reflect-metadata": "^0.2",
     "rxjs": "^7"
   },
+  "peerDependenciesMeta": {
+    "@nestjs/platform-express": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
     "@nestjs/testing": "^11.0.0",
     "@types/node": "^22.0.0",
     "@types/supertest": "^6.0.2",