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

package/dist/storage/config/storage-config.service.js

@@ -0,0 +1,431 @@
+"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 StorageConfigService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageConfigService = exports.STORAGE_POLICY_CACHE_MS = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../credentials/index");
+const index_2 = require("../../settings/index");
+const storage_driver_1 = require("../drivers/storage-driver");
+// The built-in drivers register on import: whatever resolves a driver by id finds them.
+require("../drivers/builtin-storage-drivers");
+// =============================================================================
+// StorageConfigService — the live storage configuration (issue #373, epic #372)
+// =============================================================================
+//
+// Joins the two halves of a storage configuration, per call:
+//
+//     system_settings.storage        (provider + drivers.<provider>: the active
+//                                     driver's non-secret settings)
+//   + credentials(<driver's purpose>) (the driver's secrets, decrypted; the
+//                                     built-ins' secret access key lives at
+//                                     (storage, default))
+//   → ResolvedStorageConfig | "not configured, here is what is missing"
+//
+// -----------------------------------------------------------------------------
+// WHY THIS RESOLVES PER CALL AND NOT AT BOOT
+// -----------------------------------------------------------------------------
+//
+// Because the configuration is now something an administrator edits in a
+// running application, and "no restart" is the entire feature. A value captured
+// in a constructor is a value that is wrong from the moment the settings page
+// is saved until somebody remembers to redeploy — and the two occasions this
+// matters most are exactly the two where a redeploy is least welcome: an
+// operator repairing a broken bucket during an incident, and a CREDENTIAL
+// ROTATION, where the old key stops working the instant the new one is issued.
+//
+// It also removes a failure mode the environment-variable version had by
+// construction: reading configuration in a constructor means an unreadable
+// database (or an unconfigured deployment) can prevent the API from STARTING.
+// Nothing in this file is touched at construction; a fresh install with no
+// storage at all boots normally, serves every non-storage route, and answers
+// storage calls with a 503 that says which field to fill in.
+//
+// -----------------------------------------------------------------------------
+// WHY THE SECRET IS FETCHED HERE AND NEVER STORED ON THE INSTANCE
+// -----------------------------------------------------------------------------
+//
+// `CredentialsService.getSecret` is the one method in the credential store that
+// yields plaintext, and its contract is explicit: use it at the moment of use
+// and let it go out of scope — "do not cache it on an instance field". This
+// service holds to that literally. The CACHE BELOW HOLDS THE SETTINGS HALF
+// ONLY; the secret is re-read from the store on every single resolve and is
+// handed straight to the caller that needs it.
+//
+// That is a deliberate trade, and it is worth naming both sides:
+//
+//   * COST — one indexed `credentials` lookup and one AES-GCM decrypt per
+//     storage operation. A batch of ten presigned part URLs is ten of them.
+//     Both are microseconds against an operation that is about to talk to an
+//     object store over the network.
+//   * BENEFIT — no long-lived plaintext copy of the deployment's storage
+//     credential sitting on a singleton where a heap dump, a `JSON.stringify`
+//     in a debug log or a future `describe()`-style method would find it; and a
+//     rotated key takes effect on the NEXT CALL rather than up to a TTL later.
+//     A five-second window in which a revoked key is still being used is a
+//     five-second window nobody would be able to explain afterwards.
+//
+// The settings half is cached because it is not secret, it is read on paths
+// with no administrator anywhere near them (an avatar download, a job's
+// presigned URL), and it changes only when somebody saves a form.
+//
+// REJECTED: caching the RESOLVED config, secret and all, for the same five
+// seconds. It reads as the obvious optimisation and it quietly undoes both
+// benefits above at once.
+//
+// -----------------------------------------------------------------------------
+// NOTHING HERE READS `process.env`
+// -----------------------------------------------------------------------------
+//
+// The saved settings namespace and the encrypted credential store are the only
+// two sources of a storage configuration, and this service reads exactly those
+// two. There is no environment variable that names a bucket, a region, an
+// endpoint or a key — epic #372 removed the last of them — so there is no
+// second place for an operator to have configured storage, and no precedence
+// rule for anybody to have to remember.
+// =============================================================================
+/**
+ * How long a settings read is reused before the row is consulted again.
+ *
+ * Deliberately the same five seconds as `MAINTENANCE_PERSISTED_CACHE_MS`, and
+ * for the same reasons: short enough that an edit on one instance takes effect
+ * across a fleet within a poll or two, long enough that a burst of storage
+ * calls (an upload's ten presigned parts, a retention sweep's hundred deletes)
+ * costs one `system_settings` read rather than a hundred. The instance that
+ * HANDLED the write does not wait at all — see {@link
+ * StorageConfigService.invalidateCache}.
+ *
+ * ⚠ THIS BOUNDS THE SETTINGS HALF ONLY. The secret access key is never cached,
+ * so a rotation is never delayed by this constant. See the file header.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_POLICY_CACHE_MS = 5_000;
+/**
+ * Where the active storage configuration comes from: the `storage` settings namespace and the credential store, read per call (settings cached `STORAGE_POLICY_CACHE_MS`). `resolveActiveConfig` for a client, `activeProvider` for the provider a row records.
+ *
+ * @stability experimental
+ */
+let StorageConfigService = StorageConfigService_1 = class StorageConfigService {
+    systemSettings;
+    credentials;
+    logger = new common_1.Logger(StorageConfigService_1.name);
+    /**
+     * Last successful settings read, with the time it was taken.
+     *
+     * Same shape as `MaintenanceModeService.cache`, deliberately: `{ value, readAt }`
+     * with a module-level TTL is the pattern this repository already
+     * uses for "a settings namespace read on a hot path", and a second shape for
+     * the same job is a second thing to reason about at 3am.
+     *
+     * CARRIES NO SECRET — `SystemStorageValue` has no field capable of holding
+     * one, and there is a compile-time proof of that in `settings.schema.ts`.
+     */
+    cache = null;
+    /**
+     * The configured bucket from the most recent successful settings read, or
+     * `null` when there has not been one (or it was empty).
+     *
+     * Exists for exactly one caller: `StorageProvider.getBucket()`, which is
+     * synchronous by interface and cannot await a settings read. See the long
+     * comment on that method in `ResolvingStorageProvider` for why answering from
+     * a snapshot is the honest option and what the alternatives cost.
+     *
+     * SET FROM THE SETTINGS HALF ALONE — it does not wait for a COMPLETE
+     * resolution, and deliberately so. A deployment whose bucket is typed but
+     * whose secret access key is not yet saved still has exactly one answer to
+     * "which bucket is this?", and withholding it would strand the one caller
+     * that cannot recover: `DatabaseBackupRunnerService.queueBackup` calls
+     * `getBucket()` with no async storage call anywhere in its path, so a refusal
+     * there would repeat forever rather than resolving on a retry. Nothing is
+     * risked by answering: every path that actually MOVES BYTES goes through one
+     * of the twelve async methods first, and those refuse an incomplete
+     * configuration outright, so a bucket name recorded from here can never
+     * describe an object that was written somewhere else.
+     *
+     * DELIBERATELY NOT CLEARED when a later read comes back empty. The rows this
+     * answers for are records of where bytes went, and the last bucket this
+     * process knew about remains the truthful answer for work already in flight.
+     */
+    lastPolicyBucket = null;
+    /**
+     * The provider kind named by the last successful settings read, for the
+     * synchronous {@link lastKnownProvider} (`StorageProvider.kind`). Unlike the
+     * bucket it always has an answer: the namespace always names a provider, and
+     * until the first read it is the schema default (`'s3'`). Refreshed on every
+     * settings read, next to {@link lastPolicyBucket}, so a row naming a bucket
+     * and a row naming its provider describe one configuration.
+     */
+    lastPolicyProvider = 's3';
+    constructor(systemSettings, credentials) {
+        this.systemSettings = systemSettings;
+        this.credentials = credentials;
+    }
+    /**
+     * Take one best-effort SETTINGS read at startup, so the synchronous
+     * `getBucket()` has an answer before the first storage call rather than after
+     * it.
+     *
+     * WHY THIS IS NEEDED AT ALL: `DatabaseBackupRunnerService.queueBackup` calls
+     * `getBucket()` with no preceding async storage operation anywhere in its
+     * path. Without a warm read, the first backup queued after a restart would be
+     * refused on a correctly configured deployment — and, because nothing in that
+     * path ever resolves asynchronously, refused again on every retry. A dead end
+     * that only some unrelated avatar download can clear is not a failure an
+     * operator can be expected to diagnose.
+     *
+     * ⚠ IT READS THE SETTINGS HALF ONLY, NEVER THE CREDENTIAL. Boot is not a
+     * moment of use: the secret would be decrypted, not cached (this service
+     * never caches it), and immediately discarded — a plaintext read with no
+     * consumer, on a path with no storage operation behind it. That is precisely
+     * what `CredentialsService.getSecret`'s contract rules out, and
+     * `test/settings/email-settings.integration.spec.ts` asserts the equivalent
+     * property for SMTP. The bucket is in the settings half, so nothing is lost.
+     *
+     * DETACHED AND SWALLOWED, ON PURPOSE. It is one indexed read; it must not
+     * delay boot, and it must never prevent it. A database that is not up yet
+     * simply leaves the snapshot empty and the next storage call reads properly.
+     * This is emphatically not "work outside the queue" in the sense of the
+     * job-queue rule — it is a single SELECT, not an activity with a duration
+     * worth accounting for.
+     */
+    onModuleInit() {
+        void this.readPolicy({ fresh: true })
+            .then((policy) => {
+            // Asked of the snapshot `readPolicy` has just filled rather than of
+            // `policy.bucket` directly, so this line and `getBucket()` can never
+            // disagree about whether this process knows a bucket.
+            const bucket = this.lastKnownBucket();
+            if (!bucket) {
+                this.logger.warn('No object storage bucket is configured. Storage operations will be ' +
+                    'refused with 503 until one is saved.');
+                return;
+            }
+            // The non-secret half only — this line cannot say whether the
+            // credential exists, and must not pretend to. `describeStorageConfig`
+            // is used on the first real resolve instead (see
+            // `ResolvingStorageProvider.delegateFor`).
+            this.logger.log(`Object storage settings loaded: ${policy.provider} bucket=${bucket}`);
+        })
+            .catch((error) => {
+            this.logger.warn(`Could not read the storage settings at startup; they will be read ` +
+                `again on the first storage operation: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    }
+    /**
+     * Drop the cached settings read, so the next resolve consults the row.
+     *
+     * CALL THIS SYNCHRONOUSLY, BEFORE THE AUDIT WRITE, from any path that changes
+     * the storage settings — exactly as `MaintenanceModeService.setMaintenance`
+     * does with its own cache. The ordering is the whole point: between the
+     * settings write committing and this call, this instance would still answer
+     * storage questions from the value it read up to five seconds ago, and an
+     * administrator who saved a corrected bucket and immediately retried an
+     * upload would watch it fail against the old one. Anything that awaits in
+     * between — an audit row, a notification, a log flush — widens that window
+     * for no benefit; the admin write path in a later part of #373 is the caller
+     * this exists for.
+     *
+     * It does NOT need to be called after a credential write: the secret is never
+     * cached, so a rotation is already live on the next call.
+     */
+    invalidateCache() {
+        this.cache = null;
+    }
+    /**
+     * The active configuration, or `null` when this deployment has none.
+     *
+     * The narrow form, for the callers that only need "can I use storage": it
+     * throws away the reason. Anything that has to EXPLAIN the answer — a 503
+     * body, part 3's connection test, an admin page's readiness badge — should
+     * call {@link resolve} and keep the missing-field list, which is the one
+     * thing a person needs and the one thing `null` cannot carry.
+     *
+     * ⚠ The returned object holds a plaintext secret access key. See
+     * `ResolvedStorageConfig`.
+     */
+    async resolveActiveConfig(options = {}) {
+        const resolution = await this.resolve(options);
+        return resolution.configured ? resolution.config : null;
+    }
+    /**
+     * The active configuration, or the list of fields that are missing.
+     *
+     * `fresh: true` bypasses the settings cache, and is for the caller that is
+     * SHOWING the configuration to a person or TESTING it — an operator looking
+     * at a settings page, or clicking "test connection", must never be answered
+     * from a value up to five seconds stale, however cheap that would be. It is
+     * the same option, with the same meaning, as `MaintenanceModeService.resolve`.
+     *
+     * Never returns a partially-built config: the completeness rules are the
+     * ACTIVE DRIVER's (`StorageDriver.missing`; for the built-ins,
+     * `drivers/s3/s3-config.ts`), in one place per driver, and this method's only
+     * job is to gather the inputs they judge. A provider id no driver is
+     * registered for (a package that was removed) is "not configured", missing
+     * `driver`, never a crash.
+     */
+    async resolve(options = {}) {
+        const policy = await this.readPolicy(options);
+        const driver = (0, storage_driver_1.getStorageDriver)(policy.provider);
+        if (!driver) {
+            return { configured: false, provider: policy.provider, missing: ['driver'] };
+        }
+        const settings = policy.drivers[policy.provider] ?? {};
+        // Read on EVERY resolve, cached nowhere. See the file header — this is the
+        // line that makes a key rotation take effect on the next call.
+        const secrets = await this.readSecrets(driver);
+        const present = Object.fromEntries((driver.secrets ?? []).map((secret) => [secret.name, secrets[secret.name] !== undefined]));
+        const missing = (0, storage_driver_1.missingStorageFields)(driver, settings, present);
+        if (missing.length > 0) {
+            return { configured: false, provider: policy.provider, missing };
+        }
+        const location = (0, storage_driver_1.storageLocationOf)(driver, settings);
+        return {
+            configured: true,
+            config: {
+                provider: policy.provider,
+                bucket: location.bucket,
+                region: location.region ?? '',
+                // Absent, not empty: see `ResolvedStorageConfig.endpoint`.
+                ...(location.endpoint ? { endpoint: location.endpoint } : {}),
+                settings,
+                secrets,
+            },
+        };
+    }
+    /** The active driver's location, or `undefined` when no driver is registered for the provider. */
+    locationOf(policy) {
+        const driver = (0, storage_driver_1.getStorageDriver)(policy.provider);
+        return driver ? (0, storage_driver_1.storageLocationOf)(driver, policy.drivers[policy.provider] ?? {}) : undefined;
+    }
+    /**
+     * The driver's declared secrets, decrypted, by name. A secret with no stored
+     * value is absent from the result (a blank is never a value).
+     */
+    async readSecrets(driver) {
+        const secrets = {};
+        for (const spec of driver.secrets ?? []) {
+            const address = (0, storage_driver_1.storageSecretAddress)(driver, spec.name);
+            const value = await this.credentials.getSecret(address.purpose, address.name);
+            if (value)
+                secrets[spec.name] = value;
+        }
+        return secrets;
+    }
+    /**
+     * Which vendor's flavour of the S3 protocol this deployment is pointed at,
+     * right now.
+     *
+     * ── WHAT IT IS FOR ──────────────────────────────────────────────────────────
+     *
+     * The rows that RECORD WHERE BYTES WENT — `storage_objects.storage_provider`
+     * and `database_backup_runs.storage_provider` — plus the one rule that
+     * compares `databaseBackup.storageProvider` against the provider actually in
+     * force (`assertUsableStorageProvider`). Before #373 all four of those read a
+     * hard-coded `'s3'`, which stopped being true the moment an operator could
+     * select `r2`.
+     *
+     * ── WHY ASYNC, WHEN `getBucket()` IS NOT ────────────────────────────────────
+     *
+     * Because nothing forces this one to be synchronous, and `getBucket()`'s own
+     * comment says plainly that async "is the genuinely correct shape" — it stays
+     * synchronous only because `StorageProvider.getBucket(): string` is fixed by
+     * an interface. There is no interface method returning a provider kind, and
+     * all four recording sites above are already `async`, so the honest read is
+     * available to every one of them and {@link lastKnownBucket}'s snapshot
+     * machinery is not needed a second time.
+     *
+     * It goes through the SAME cached `readPolicy` the snapshot is filled
+     * from, deliberately: a row whose `bucket` came from `getBucket()` and whose
+     * provider came from here then names one configuration rather than two, and a
+     * change an administrator saves reaches both within the same five seconds.
+     *
+     * ── WHY THERE IS NO "DON'T KNOW" ANSWER ─────────────────────────────────────
+     *
+     * Unlike the bucket, which genuinely may not have been configured yet (and
+     * whose absence `getBucket()` must raise a 503 for rather than invent), this
+     * namespace ALWAYS names a provider: `provider` is a closed enum with a
+     * schema default, and a damaged row degrades to that default field by field.
+     * "No storage configured" is `bucket === ''`, never a missing provider — so
+     * there is nothing here for a caller to handle and no fallback for one to get
+     * wrong.
+     */
+    async activeProvider(options = {}) {
+        return (await this.readPolicy(options)).provider;
+    }
+    /**
+     * The provider kind as of the last successful settings read (`'s3'` before
+     * any). Synchronous, for `ResolvingStorageProvider.kind`; callers that can
+     * await and need the current value use {@link activeProvider}.
+     */
+    lastKnownProvider() {
+        return this.lastPolicyProvider;
+    }
+    /**
+     * The configured bucket as of the last successful settings read, or `null`.
+     *
+     * SYNCHRONOUS, and that is its entire reason for existing:
+     * `StorageProvider.getBucket()` is synchronous by interface. This method reads nothing, waits
+     * for nothing, falls back to no default and guesses at nothing — `null` means
+     * "this process does not know", which the caller must surface rather than
+     * paper over with an empty string.
+     */
+    lastKnownBucket() {
+        return this.lastPolicyBucket;
+    }
+    /**
+     * Read the `storage` settings namespace, through the cache.
+     *
+     * Goes through `SystemSettingsService.getStoragePolicy`, which is narrow by
+     * design: it does not create the settings row as a side effect of serving a
+     * file, and it projects the stored value through `readKnownSettings`, so a
+     * damaged row degrades field by field to `DEFAULT_SYSTEM_SETTINGS.storage` —
+     * the UNCONFIGURED state — rather than to a half-built client pointed
+     * somewhere nobody chose.
+     *
+     * UNLIKE `MaintenanceModeService.readPersisted`, A FAILED READ IS NOT
+     * SWALLOWED HERE. That service degrades to its last known value because a
+     * global guard runs on every request and an unreadable database must not turn
+     * every call into a 500. This one is different in the way that matters: a
+     * storage call that cannot read its configuration has nothing useful to do
+     * with a stale one — it would build a client, talk to an object store and
+     * possibly WRITE BYTES using a configuration this process can no longer
+     * confirm. Letting the error surface (as the 500 it is) is the honest
+     * outcome, and the cache above still absorbs the ordinary case.
+     */
+    async readPolicy(options = {}) {
+        const now = Date.now();
+        if (!options.fresh &&
+            this.cache &&
+            now - this.cache.readAt < exports.STORAGE_POLICY_CACHE_MS) {
+            return this.cache.value;
+        }
+        const value = await this.systemSettings.getStoragePolicy();
+        this.cache = { value, readAt: now };
+        this.lastPolicyProvider = value.provider;
+        // The synchronous snapshot is refreshed HERE — on every settings read,
+        // whether it came from a resolve, the startup warm or a `fresh` admin read
+        // — rather than at the end of a complete resolution. See
+        // `lastPolicyBucket` for why the credential's presence is not a condition.
+        const bucket = this.locationOf(value)?.bucket;
+        if (bucket) {
+            this.lastPolicyBucket = bucket;
+        }
+        return value;
+    }
+};
+exports.StorageConfigService = StorageConfigService;
+exports.StorageConfigService = StorageConfigService = StorageConfigService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [index_2.SystemSettingsService,
+        index_1.CredentialsService])
+], StorageConfigService);
+//# sourceMappingURL=storage-config.service.js.map

package/dist/storage/config/storage-config.service.js.map

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

package/dist/storage/config/storage-connection-test.service.d.ts

@@ -0,0 +1,30 @@
+import type { StoragePrisma } from '../data/storage-db';
+import { STORAGE_PROBE_KEY_PREFIX } from '../drivers/s3/s3-connection-test';
+import type { StorageConnectionTestResult, TestStorageConfigInput } from './dto/storage-connection-test.dto';
+import { StorageSubmissionService } from './storage-submission.service';
+export { STORAGE_PROBE_KEY_PREFIX };
+/**
+ * The connection test of a configuration, saved or not, run by the DRIVER it names (the built-ins report four checks: credentials, bucket, round trip, presigned URL); never throws on a bad answer.
+ *
+ * @stability experimental
+ */
+export declare class StorageConnectionTestService {
+    private readonly prisma;
+    private readonly submission;
+    private readonly logger;
+    constructor(prisma: StoragePrisma, submission: StorageSubmissionService);
+    /**
+     * Run the driver's connection test against `input` and report it.
+     *
+     * NEVER THROWS for a configuration or connectivity problem: every such
+     * outcome is `success: false` with a `message` (and, for the S3 family, a
+     * check with `status: 'failed'`). A driver that throws anyway is turned into
+     * `success: false` with the secret redacted out of its message. It can still
+     * reject for a genuine fault (the database being down while writing the audit
+     * row), which is a 500 and correctly so, and for a body naming a driver nobody
+     * registered or settings it refuses, which is a 400.
+     */
+    test(input: TestStorageConfigInput, actorUserId: string): Promise<StorageConnectionTestResult>;
+    private assemble;
+}
+//# sourceMappingURL=storage-connection-test.service.d.ts.map

package/dist/storage/config/storage-connection-test.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-connection-test.service.d.ts","sourceRoot":"","sources":["../../../src/storage/config/storage-connection-test.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAyB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAEV,2BAA2B,EAC3B,sBAAsB,EACvB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAkC,MAAM,8BAA8B,CAAC;AAExG,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAiDpC;;;;GAIG;AACH,qBACa,4BAA4B;IAIZ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJ7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiD;gBAG5B,MAAM,EAAE,aAAa,EAC9C,UAAU,EAAE,wBAAwB;IAGvD;;;;;;;;;;OAUG;IACG,IAAI,CACR,KAAK,EAAE,sBAAsB,EAC7B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,2BAA2B,CAAC;YAqBzB,QAAQ;CAqEvB"}

package/dist/storage/config/storage-connection-test.service.js

@@ -0,0 +1,174 @@
+"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); }
+};
+var StorageConnectionTestService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageConnectionTestService = exports.STORAGE_PROBE_KEY_PREFIX = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const s3_connection_test_1 = require("../drivers/s3/s3-connection-test");
+Object.defineProperty(exports, "STORAGE_PROBE_KEY_PREFIX", { enumerable: true, get: function () { return s3_connection_test_1.STORAGE_PROBE_KEY_PREFIX; } });
+const storage_submission_service_1 = require("./storage-submission.service");
+// =============================================================================
+// StorageConnectionTestService — "does this configuration actually work?" (#375)
+// =============================================================================
+//
+// THIS IS A DIAGNOSTIC, AND EVERY DECISION BELOW FOLLOWS FROM THAT. It is the
+// storage counterpart of `EmailTestSendService`, deliberately built to the same
+// contract, and that file's header is worth reading first: it returns a RESULT
+// rather than throwing, because a refused request is a successful diagnosis and
+// this app's error envelope would discard the one fact worth having.
+//
+// -----------------------------------------------------------------------------
+// IT TESTS THE SUBMITTED BODY, NOT THE SAVED ROW
+// -----------------------------------------------------------------------------
+//
+// An operator moving to a new bucket must be able to prove a configuration
+// BEFORE committing the deployment to it. A test that could only exercise what
+// had already been saved would mean the only way to try a new bucket is to break
+// the running one first — and then discover, with uploads already failing, that
+// the new key lacks `s3:PutObject`.
+//
+// Nothing here writes a settings row or a credential. The ONE thing it writes is
+// a throwaway object in the target bucket, which it then deletes; that is not a
+// side effect to be avoided, it is the only way to learn whether the credential
+// has the permissions an upload needs.
+//
+// -----------------------------------------------------------------------------
+// WHY `:write` AND NOT `:read`
+// -----------------------------------------------------------------------------
+//
+// Because it is side-effecting: it puts an object into a bucket and asks a
+// third-party endpoint to do work at the caller's request. `:read` is held by
+// anyone who may LOOK at the configuration, and looking is not writing —
+// the identical argument `EmailSettingsController` makes for its test send.
+//
+// -----------------------------------------------------------------------------
+// ⚠ THE SECRET, AND WHERE IT IS ALLOWED TO GO
+// -----------------------------------------------------------------------------
+//
+// The driver legitimately holds the plaintext secret (an S3 client cannot sign
+// without it); THIS service resolves it only when the driver asks, and obeys
+// `CredentialsService.getSecret`'s contract literally — read at the moment of
+// use, held in a local, never stored on an instance field, never logged, and
+// never returned. Every string that leaves here goes through `redact` first, at
+// a single exit point, because most of these messages are authored by an SDK
+// rather than by this repository (the S3 driver also scrubs its own).
+// =============================================================================
+/**
+ * The connection test of a configuration, saved or not, run by the DRIVER it names (the built-ins report four checks: credentials, bucket, round trip, presigned URL); never throws on a bad answer.
+ *
+ * @stability experimental
+ */
+let StorageConnectionTestService = StorageConnectionTestService_1 = class StorageConnectionTestService {
+    prisma;
+    submission;
+    logger = new common_1.Logger(StorageConnectionTestService_1.name);
+    constructor(prisma, submission) {
+        this.prisma = prisma;
+        this.submission = submission;
+    }
+    /**
+     * Run the driver's connection test against `input` and report it.
+     *
+     * NEVER THROWS for a configuration or connectivity problem: every such
+     * outcome is `success: false` with a `message` (and, for the S3 family, a
+     * check with `status: 'failed'`). A driver that throws anyway is turned into
+     * `success: false` with the secret redacted out of its message. It can still
+     * reject for a genuine fault (the database being down while writing the audit
+     * row), which is a 500 and correctly so, and for a body naming a driver nobody
+     * registered or settings it refuses, which is a 400.
+     */
+    async test(input, actorUserId) {
+        const attemptedAt = new Date();
+        const prepared = await this.submission.prepare(input);
+        let outcome;
+        try {
+            outcome = await prepared.driver.testConnection(prepared.ctx);
+        }
+        catch (error) {
+            // The contract says a driver never throws. A driver that does is a bug
+            // worth a log line, and the administrator still gets an answer.
+            outcome = {
+                ok: false,
+                message: `The ${prepared.driver.label} driver failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`,
+            };
+            this.logger.warn(`Storage driver "${prepared.driver.id}" threw from testConnection: ${prepared.redact(outcome.message)}`);
+        }
+        return this.assemble(prepared, outcome, attemptedAt, actorUserId);
+    }
+    async assemble(prepared, outcome, attemptedAt, actorUserId) {
+        const { redact, location } = prepared;
+        const checks = (outcome.checks ?? []).map((entry) => ({
+            ...entry,
+            detail: redact(entry.detail),
+            error: entry.error === null ? null : redact(entry.error),
+        }));
+        const details = outcome.details
+            ? Object.fromEntries(Object.entries(outcome.details).map(([key, value]) => [key, typeof value === 'string' ? redact(value) : value]))
+            : undefined;
+        const success = outcome.ok && checks.every((entry) => entry.status === 'passed');
+        const region = typeof details?.region === 'string' ? details.region : (location.region ?? '');
+        const endpoint = typeof details?.effectiveEndpoint === 'string' ? details.effectiveEndpoint : (location.endpoint ?? null);
+        const result = {
+            success,
+            provider: prepared.driver.id,
+            bucket: location.bucket,
+            region,
+            effectiveEndpoint: endpoint,
+            usedStoredSecret: prepared.usedStoredSecret,
+            checks,
+            message: redact(outcome.message),
+            ...(details ? { details } : {}),
+            attemptedAt: attemptedAt.toISOString(),
+        };
+        await this.prisma.auditEvent.create({
+            data: {
+                actorUserId,
+                action: 'storage_config:test',
+                targetType: 'system_settings',
+                targetId: 'storage',
+                // The verdict only: never a detail, never a message that could echo a value.
+                meta: {
+                    provider: result.provider,
+                    bucket: result.bucket,
+                    success,
+                    usedStoredSecret: result.usedStoredSecret,
+                    checks: checks.map((entry) => ({
+                        id: entry.id,
+                        status: entry.status,
+                        code: entry.code,
+                    })),
+                },
+            },
+        });
+        if (!success) {
+            this.logger.warn(`Storage connection test failed for user ${actorUserId} ` +
+                `(provider=${result.provider} bucket=${result.bucket || '(none)'}): ` +
+                (checks.some((entry) => entry.status !== 'passed')
+                    ? checks
+                        .filter((entry) => entry.status !== 'passed')
+                        .map((entry) => `${entry.id}=${entry.code}`)
+                        .join(' ')
+                    : result.message));
+        }
+        return result;
+    }
+};
+exports.StorageConnectionTestService = StorageConnectionTestService;
+exports.StorageConnectionTestService = StorageConnectionTestService = StorageConnectionTestService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [Object, storage_submission_service_1.StorageSubmissionService])
+], StorageConnectionTestService);
+//# sourceMappingURL=storage-connection-test.service.js.map