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

package/dist/cjs/storage/storage-config-update.js

@@ -0,0 +1,133 @@
+"use strict";
+// =============================================================================
+// PUT /api/admin/storage-config - request body (issue #375, epic #372; drivers: PP-14.7)
+// =============================================================================
+//
+// The active driver, its settings, its write-only secrets and the typed
+// confirmation. A save names the active driver (`provider`) and then supplies
+// settings in either of two spellings:
+//
+//   * `drivers`  - `{ <driverId>: { ...that driver's settings } }`. The shape
+//                  every driver, built-in or registered by an app, uses. Each
+//                  entry is merged over the driver's stored settings (a setting
+//                  it omits keeps its stored value), then validated by the
+//                  driver; `null` resets a driver to its defaults.
+//   * the flat fields (`bucket`, `region`, `endpoint`, `accountId`,
+//     `accessKeyId`, `forcePathStyle`) - the shape this route had before drivers
+//                  were pluggable. They are the settings of the built-in driver
+//                  named by `provider`, so a client written against the old
+//                  contract keeps working. A flat field present in the body
+//                  replaces that setting; one omitted keeps the stored value.
+//                  `drivers.<provider>` wins over a flat field for the same
+//                  setting.
+//
+// An empty string still CLEARS a text field (that is how an operator drops an
+// endpoint override, or un-configures storage by clearing `bucket`), and
+// `forcePathStyle` is still TRI-STATE (`null` is "use this vendor's
+// convention").
+//
+// -----------------------------------------------------------------------------
+// SECRETS ARE WRITE-ONLY, AND BLANK PRESERVES
+// -----------------------------------------------------------------------------
+//
+// `secretAccessKey` is the built-in drivers' secret. A driver an app registers
+// declares its own (`secrets: [{ name: 'connectionString' }]`) and the admin
+// form sends them in `secrets`, keyed by driver id and secret name. Omitted,
+// `null` or `''` means "the admin did not retype it" and the stored value stays.
+// There is deliberately no way to erase a stored secret through this endpoint;
+// an admin who wants storage off empties the driver's location (`bucket`).
+//
+// WHY THE SECRET IS ON THIS BODY AT ALL, rather than its own endpoint: the key
+// id and the secret are one credential, pasted from one screen at one moment.
+// Splitting them across two requests means every rotation has a window in which
+// the saved key id and the saved secret are from different key pairs.
+// `EmailSettingsController` makes the same call for `smtpPassword`.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateStorageConfigSchema = exports.STORAGE_SWITCH_CONFIRMATION = void 0;
+const zod_1 = require("zod");
+const settings_schemas_js_1 = require("./settings-schemas.js");
+/**
+ * The word `PUT /api/admin/storage-config` requires when the save would point
+ * a deployment that already holds objects at a different location.
+ *
+ * ⚠ EXPORTED, AND THE ONLY DEFINITION. The service raising the 409 and the DTO
+ * validating the body both read this constant, and #376's UI sends it back.
+ * A second string literal that differs by a character is a confirmation dialog
+ * whose "yes" the API rejects.
+ *
+ * Deliberately a different word from `RESTORE`, `ROLLBACK`, `ROTATE` and
+ * `REMOVE` for the reason those four differ from each other: a body copied from
+ * one confirming route to another must be refused, not silently accepted. The
+ * same argument against `{ "confirm": true }` applies here and is set out in
+ * full in `db-backup/dto/db-backup-restore.dto.ts` — in short, a boolean is
+ * reproduced by a replayed POST, a retried client and a double-clicked button,
+ * and this word is reproduced by none of them accidentally.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_SWITCH_CONFIRMATION = 'SWITCH';
+/**
+ * The `PUT /api/admin/storage-config` body: the active driver, its settings (`drivers`, or the legacy flat fields for the built-ins), the write-only secrets and the optional confirmation.
+ *
+ * @stability experimental
+ */
+exports.updateStorageConfigSchema = zod_1.z.object({
+    /** The id of the storage driver to make active (a built-in, or one an app registered). */
+    provider: settings_schemas_js_1.storageDriverIdSchema,
+    /**
+     * Driver settings, per driver id, merged over the stored ones and validated
+     * by each driver. `null` resets a driver to its defaults. See the header.
+     */
+    drivers: settings_schemas_js_1.storageDriversPatchSchema.optional(),
+    /**
+     * Alias of `drivers.<provider>.bucket` (built-in drivers). No `.min(1)`:
+     * `''` is the legal, persisted "not configured" state and is how an operator
+     * un-configures storage entirely. Completeness is decided by the driver.
+     */
+    bucket: zod_1.z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.region`. `''` is "not stated"; R2 wants the literal `auto`. */
+    region: zod_1.z.string().trim().max(255).optional(),
+    /** Alias of `drivers.<provider>.endpoint`. Explicit origin, or `''` to derive it (R2) or use the SDK's host (S3). */
+    endpoint: zod_1.z.string().trim().max(512).optional(),
+    /** Alias of `drivers.<provider>.accountId`. R2 account id, from which its endpoint is derived. */
+    accountId: zod_1.z.string().trim().max(255).optional(),
+    /**
+     * Alias of `drivers.<provider>.accessKeyId`. The identifier half of the
+     * credential: NOT A SECRET, in both the request and the response on purpose
+     * (it travels in the clear in every SigV4 `Authorization` header).
+     */
+    accessKeyId: zod_1.z.string().trim().max(255).optional(),
+    /**
+     * WRITE-ONLY, AND BLANK PRESERVES. The built-in drivers' secret access key.
+     * Omitted, `null` or `''` means "the admin did not retype the secret" and the
+     * stored one is left exactly as it is. NEVER ECHOED BACK: no response schema
+     * has a field capable of carrying it.
+     */
+    secretAccessKey: zod_1.z.string().max(512).nullish(),
+    /**
+     * WRITE-ONLY secrets of any driver: `{ <driverId>: { <secretName>: value } }`,
+     * the names the driver declares (`descriptors[].fields` of kind `secret`).
+     * A blank value keeps the stored one. Never echoed back.
+     */
+    secrets: zod_1.z.record(settings_schemas_js_1.storageDriverIdSchema, zod_1.z.record(zod_1.z.string(), zod_1.z.string().max(4096).nullish())).optional(),
+    /**
+     * Alias of `drivers.<provider>.forcePathStyle`: `https://host/bucket/key`
+     * (true) over `https://bucket.host/key` (false), or `null` for "use this
+     * vendor's convention".
+     */
+    forcePathStyle: zod_1.z.boolean().nullable().optional(),
+    /**
+     * The literal string `SWITCH`, required only when this save would repoint a
+     * deployment that still has objects at the old location.
+     *
+     * Optional because the ordinary save needs no acknowledgement at all. The
+     * service decides whether it was needed and answers `409` with the row counts
+     * when it was missing.
+     *
+     * IT ACKNOWLEDGES, IT DOES NOT MIGRATE. Saving a new location does not copy a
+     * single object.
+     */
+    confirmation: zod_1.z.literal(exports.STORAGE_SWITCH_CONFIRMATION).optional(),
+});
+//# sourceMappingURL=storage-config-update.js.map

package/dist/cjs/storage/storage-config-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-config-update.js","sourceRoot":"","sources":["../../../src/storage/storage-config-update.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yFAAyF;AACzF,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,uCAAuC;AACvC,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,2EAA2E;AAC3E,mEAAmE;AACnE,oEAAoE;AACpE,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,4BAA4B;AAC5B,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,oEAAoE;AACpE,gBAAgB;AAChB,EAAE;AACF,gFAAgF;AAChF,8CAA8C;AAC9C,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,iFAAiF;AACjF,+EAA+E;AAC/E,2EAA2E;AAC3E,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAChF,sEAAsE;AACtE,oEAAoE;AACpE,gFAAgF;;;AAEhF,6BAAwB;AAExB,+DAAyF;AAEzF;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,2BAA2B,GAAG,QAAQ,CAAC;AAEpD;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,0FAA0F;IAC1F,QAAQ,EAAE,2CAAqB;IAE/B;;;OAGG;IACH,OAAO,EAAE,+CAAyB,CAAC,QAAQ,EAAE;IAE7C;;;;OAIG;IACH,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE7C,+FAA+F;IAC/F,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE7C,qHAAqH;IACrH,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE/C,kGAAkG;IAClG,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAEhD;;;;OAIG;IACH,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAElD;;;;;OAKG;IACH,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE;IAE9C;;;;OAIG;IACH,OAAO,EAAE,OAAC,CAAC,MAAM,CAAC,2CAAqB,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IAEzG;;;;OAIG;IACH,cAAc,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEjD;;;;;;;;;;OAUG;IACH,YAAY,EAAE,OAAC,CAAC,OAAO,CAAC,mCAA2B,CAAC,CAAC,QAAQ,EAAE;CAChE,CAAC,CAAC"}

package/dist/cjs/storage/storage-connection-test.d.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { type StorageEnum } from './constants.js';
+/**
+ * The configuration to test: the SUBMITTED, UNSAVED one.
+ *
+ * ⚠ IT TESTS THE BODY, NOT THE STORED ROW, AND THAT IS THE POINT. An operator
+ * changing buckets should 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. Nothing here writes: no settings row, no credential, no audit of a
+ * configuration change (the attempt itself is audited).
+ *
+ * Structurally identical to the `PUT` body minus `confirmation`, and derived
+ * from it with `.omit()` rather than restated: a field added to the save form
+ * is then testable without a second edit, and the two can never disagree about
+ * what a configuration is. `confirmation` is absent because nothing is being
+ * switched — there is no old location to strand.
+ *
+ * `secretAccessKey` keeps the same blank-preserves meaning it has on `PUT`:
+ * empty means "test with the secret already stored", which is what makes
+ * "I changed only the region, does it still work?" a single click rather than a
+ * re-paste of a credential the admin may not have to hand.
+ *
+ * @stability experimental
+ */
+export declare const testStorageConfigSchema: z.ZodObject<{
+    secretAccessKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider: z.ZodString;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNullable<z.ZodString>>>>>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    drivers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+}, z.core.$strip>;
+/**
+ * The connection-test body, parsed.
+ *
+ * @stability experimental
+ */
+export type TestStorageConfigInput = z.output<typeof testStorageConfigSchema>;
+/**
+ * The four checks, in the order they are attempted. See this file's header.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_TEST_CHECK_IDS: readonly ["credentials", "bucket", "roundTrip", "presignedUrl"];
+/**
+ * One connection-test check id.
+ *
+ * @stability experimental
+ */
+export type StorageTestCheckId = (typeof STORAGE_TEST_CHECK_IDS)[number];
+/**
+ * `skipped` is NOT a failure and NOT a pass: the check could not be attempted
+ * because an earlier one failed, so this run knows nothing about it either way.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_TEST_CHECK_STATUSES: readonly ["passed", "failed", "skipped"];
+/**
+ * Machine-readable causes, so a UI can offer the RIGHT next action rather than
+ * a generic error toast.
+ *
+ * ⚠ `bucket_missing` AND `bucket_forbidden` ARE THE REASON THIS ENUM EXISTS.
+ * `HeadBucket` answers `404` when there is no such bucket at this endpoint and
+ * `403` when there is one and this key may not inspect it. The two need
+ * OPPOSITE fixes — create the bucket (which `POST /bucket` will do) versus
+ * widen the key's policy, and creating a bucket that already exists under
+ * somebody else's account is not a recoverable mistake — so collapsing them
+ * into "bucket check failed" sends half of all operators to the wrong remedy.
+ * S3 is explicit that `HeadBucket` returns `403` for a bucket that exists and
+ * is not yours, which is exactly the case a name typo lands in.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_TEST_CHECK_CODES: readonly ["ok", "not_configured", "credentials_rejected", "endpoint_unreachable", "bucket_missing", "bucket_forbidden", "bucket_region_mismatch", "write_denied", "read_denied", "read_mismatch", "delete_denied", "presign_unreachable", "presign_rejected", "presign_mismatch", "not_attempted", "unknown_error"];
+/**
+ * One connection-test check: id, label, status, code, detail and the redacted provider error.
+ *
+ * @stability experimental
+ */
+export declare const storageConnectionCheckSchema: z.ZodObject<{
+    id: z.ZodEnum<StorageEnum<readonly ["credentials", "bucket", "roundTrip", "presignedUrl"]>>;
+    label: z.ZodString;
+    status: z.ZodEnum<StorageEnum<readonly ["passed", "failed", "skipped"]>>;
+    code: z.ZodEnum<StorageEnum<readonly ["ok", "not_configured", "credentials_rejected", "endpoint_unreachable", "bucket_missing", "bucket_forbidden", "bucket_region_mismatch", "write_denied", "read_denied", "read_mismatch", "delete_denied", "presign_unreachable", "presign_rejected", "presign_mismatch", "not_attempted", "unknown_error"]>>;
+    detail: z.ZodString;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The `POST /api/admin/storage-config/test` payload, always HTTP 200: read `success`.
+ *
+ * @stability experimental
+ */
+export declare const storageConnectionTestResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    provider: z.ZodString;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    effectiveEndpoint: z.ZodNullable<z.ZodString>;
+    usedStoredSecret: z.ZodBoolean;
+    checks: z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<StorageEnum<readonly ["credentials", "bucket", "roundTrip", "presignedUrl"]>>;
+        label: z.ZodString;
+        status: z.ZodEnum<StorageEnum<readonly ["passed", "failed", "skipped"]>>;
+        code: z.ZodEnum<StorageEnum<readonly ["ok", "not_configured", "credentials_rejected", "endpoint_unreachable", "bucket_missing", "bucket_forbidden", "bucket_region_mismatch", "write_denied", "read_denied", "read_mismatch", "delete_denied", "presign_unreachable", "presign_rejected", "presign_mismatch", "not_attempted", "unknown_error"]>>;
+        detail: z.ZodString;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    message: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    attemptedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+/**
+ * One connection-test check, inferred.
+ *
+ * @stability experimental
+ */
+export type StorageConnectionCheck = z.infer<typeof storageConnectionCheckSchema>;
+/**
+ * The connection-test payload, inferred.
+ *
+ * @stability experimental
+ */
+export type StorageConnectionTestResult = z.infer<typeof storageConnectionTestResultSchema>;
+//# sourceMappingURL=storage-connection-test.d.ts.map

package/dist/cjs/storage/storage-connection-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-connection-test.d.ts","sourceRoot":"","sources":["../../../src/storage/storage-connection-test.ts"],"names":[],"mappings":"AAyDA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAQlD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;iBAElC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAM9E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,iEAKzB,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,0CAA2C,CAAC;AAEpF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,qTAiC3B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,4BAA4B;;;;;;;iBAmCvC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;iBAgD5C,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC"}

package/dist/cjs/storage/storage-connection-test.js

@@ -0,0 +1,244 @@
+"use strict";
+// =============================================================================
+// POST /api/admin/storage-config/test — request and response (issue #375)
+// =============================================================================
+//
+// ⚠ THIS ENDPOINT ANSWERS 200 EVEN WHEN THE CONFIGURATION IS BROKEN. That is
+// the design, and it is the single most important thing in this file.
+//
+// It is the same contract `POST /api/email-settings/test` states, in the same
+// words, for the same reason: diagnosing a misconfiguration is this page's
+// entire job, so a refused request is a SUCCESSFUL DIAGNOSIS. Returning 4xx/5xx
+// for that answer loses it — this app's error envelope is `{ code, message,
+// details }` produced by `HttpExceptionFilter`, which suppresses detail in
+// production and which the web client funnels into generic failure handling, so
+// "the bucket exists but this key may not see it" would arrive as "Request
+// failed". The outcome therefore travels as a normal payload.
+//
+// A real 4xx/5xx still means what it always means: not authenticated, not
+// permitted, a malformed body, or a bug in this API. Those are transport
+// failures of the endpoint. A refused `HeadBucket` is a result.
+//
+// `success` IS THE ONLY SUCCESS SIGNAL, and it is true only when EVERY check
+// passed.
+//
+// -----------------------------------------------------------------------------
+// FOUR CHECKS, REPORTED SEPARATELY, NEVER COLLAPSED INTO ONE BOOLEAN
+// -----------------------------------------------------------------------------
+//
+// "Storage does not work" is not an actionable sentence, and the four ways it
+// can be untrue need four different fixes:
+//
+//   1. `credentials`   — was the signature accepted at all? A rejected key is
+//                        fixed in the credential fields; nothing else can help.
+//   2. `bucket`        — does the bucket exist, and may this key see it?
+//                        ⚠ 404 AND 403 ARE NOT THE SAME ANSWER — see
+//                        {@link STORAGE_TEST_CHECK_CODES}.
+//   3. `roundTrip`     — write, read back, delete, on a throwaway key. This is
+//                        the only check that proves the key has the PERMISSIONS
+//                        an upload needs; `HeadBucket` passing proves nothing
+//                        about `s3:PutObject`.
+//   4. `presignedUrl`  — is the signed URL this API hands to a browser valid,
+//                        and does the object store actually serve it?
+//                        ⚠ IT IS FETCHED FROM THIS PROCESS, so it cannot and
+//                        does not prove the host is reachable from a user's
+//                        BROWSER — no server-side check can, and claiming
+//                        otherwise would be worse than not checking. What it
+//                        does catch is the class of failure the three checks
+//                        above hide by construction: presigning is a different
+//                        code path from a signed API call, so a wrong region or
+//                        a wrong path-style setting can be tolerated on the
+//                        direct call and produce a `SignatureDoesNotMatch` or a
+//                        404 on the URL every download in the product uses.
+//
+// A check that could not be attempted because an earlier one failed is
+// `skipped`, not `failed`: reporting four failures for one cause sends an
+// operator looking for four problems.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageConnectionTestResultSchema = exports.storageConnectionCheckSchema = exports.STORAGE_TEST_CHECK_CODES = exports.STORAGE_TEST_CHECK_STATUSES = exports.STORAGE_TEST_CHECK_IDS = exports.testStorageConfigSchema = void 0;
+const zod_1 = require("zod");
+const settings_schemas_js_1 = require("./settings-schemas.js");
+const storage_config_update_js_1 = require("./storage-config-update.js");
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+/**
+ * The configuration to test: the SUBMITTED, UNSAVED one.
+ *
+ * ⚠ IT TESTS THE BODY, NOT THE STORED ROW, AND THAT IS THE POINT. An operator
+ * changing buckets should 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. Nothing here writes: no settings row, no credential, no audit of a
+ * configuration change (the attempt itself is audited).
+ *
+ * Structurally identical to the `PUT` body minus `confirmation`, and derived
+ * from it with `.omit()` rather than restated: a field added to the save form
+ * is then testable without a second edit, and the two can never disagree about
+ * what a configuration is. `confirmation` is absent because nothing is being
+ * switched — there is no old location to strand.
+ *
+ * `secretAccessKey` keeps the same blank-preserves meaning it has on `PUT`:
+ * empty means "test with the secret already stored", which is what makes
+ * "I changed only the region, does it still work?" a single click rather than a
+ * re-paste of a credential the admin may not have to hand.
+ *
+ * @stability experimental
+ */
+exports.testStorageConfigSchema = storage_config_update_js_1.updateStorageConfigSchema.omit({
+    confirmation: true,
+});
+// ---------------------------------------------------------------------------
+// Response
+// ---------------------------------------------------------------------------
+/**
+ * The four checks, in the order they are attempted. See this file's header.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_TEST_CHECK_IDS = [
+    'credentials',
+    'bucket',
+    'roundTrip',
+    'presignedUrl',
+];
+/**
+ * `skipped` is NOT a failure and NOT a pass: the check could not be attempted
+ * because an earlier one failed, so this run knows nothing about it either way.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_TEST_CHECK_STATUSES = ['passed', 'failed', 'skipped'];
+/**
+ * Machine-readable causes, so a UI can offer the RIGHT next action rather than
+ * a generic error toast.
+ *
+ * ⚠ `bucket_missing` AND `bucket_forbidden` ARE THE REASON THIS ENUM EXISTS.
+ * `HeadBucket` answers `404` when there is no such bucket at this endpoint and
+ * `403` when there is one and this key may not inspect it. The two need
+ * OPPOSITE fixes — create the bucket (which `POST /bucket` will do) versus
+ * widen the key's policy, and creating a bucket that already exists under
+ * somebody else's account is not a recoverable mistake — so collapsing them
+ * into "bucket check failed" sends half of all operators to the wrong remedy.
+ * S3 is explicit that `HeadBucket` returns `403` for a bucket that exists and
+ * is not yours, which is exactly the case a name typo lands in.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_TEST_CHECK_CODES = [
+    /** The check passed. */
+    'ok',
+    /** Nothing was attempted: the configuration is incomplete. */
+    'not_configured',
+    /** The signature itself was refused — a wrong key id or secret. */
+    'credentials_rejected',
+    /** No response at all: DNS, TLS, a refused connection, a timeout. */
+    'endpoint_unreachable',
+    /** `HeadBucket` 404 — no bucket by that name at this endpoint. */
+    'bucket_missing',
+    /** `HeadBucket` 403 — it exists (possibly not yours); the key cannot see it. */
+    'bucket_forbidden',
+    /** The bucket lives in a different region from the one configured. */
+    'bucket_region_mismatch',
+    /** `PutObject` refused. */
+    'write_denied',
+    /** `GetObject` refused. */
+    'read_denied',
+    /** The object read back did not match the bytes written. */
+    'read_mismatch',
+    /** `DeleteObject` refused — the probe object may have been left behind. */
+    'delete_denied',
+    /** The presigned URL could not be fetched from this process at all. */
+    'presign_unreachable',
+    /** The presigned URL answered, but not with a success status. */
+    'presign_rejected',
+    /** It answered 200 with bytes that are not the ones that were written. */
+    'presign_mismatch',
+    /** An earlier check failed, so this one was not attempted. */
+    'not_attempted',
+    /** Something else. `error` carries the provider's own words. */
+    'unknown_error',
+];
+/**
+ * One connection-test check: id, label, status, code, detail and the redacted provider error.
+ *
+ * @stability experimental
+ */
+exports.storageConnectionCheckSchema = zod_1.z.object({
+    /** The id. */
+    id: zod_1.z.enum(exports.STORAGE_TEST_CHECK_IDS),
+    /** Short human label, so a client need not carry its own copy of the four. */
+    label: zod_1.z.string(),
+    /** The status. */
+    status: zod_1.z.enum(exports.STORAGE_TEST_CHECK_STATUSES),
+    /** The machine-readable cause. See {@link STORAGE_TEST_CHECK_CODES}. */
+    code: zod_1.z.enum(exports.STORAGE_TEST_CHECK_CODES),
+    /**
+     * One or two sentences an operator can act on, authored here — never the
+     * provider's raw text. It says what to change, not only what went wrong.
+     */
+    detail: zod_1.z.string(),
+    /**
+     * THE PROVIDER'S OWN MESSAGE, verbatim, or null.
+     *
+     * `NoSuchBucket`, `SignatureDoesNotMatch`, `ECONNREFUSED 10.0.0.4:9000`,
+     * `PermanentRedirect: the bucket is in a different region`. Not a category and
+     * not a rewritten sentence — each of those discards the one thing the
+     * operator came here for, and a wrong region, a bad secret and a firewalled
+     * port all collapse into the same useless toast.
+     *
+     * SAFE TO SURFACE: the reader already holds `storage_config:write`, so every
+     * value this text could reveal about the storage configuration is one they can
+     * read and change on the same page. The SECRET is a different matter, and the
+     * service redacts it out of this string before it is ever set — see
+     * `StorageConnectionTestService.describeError`.
+     */
+    error: zod_1.z.string().nullable(),
+});
+/**
+ * The `POST /api/admin/storage-config/test` payload, always HTTP 200: read `success`.
+ *
+ * @stability experimental
+ */
+exports.storageConnectionTestResultSchema = zod_1.z.object({
+    /**
+     * True only when all four checks passed.
+     *
+     * ⚠ A CALLER THAT TREATS HTTP 200 AS "STORAGE WORKS" REPORTS SUCCESS FOR
+     * EVERY MISCONFIGURATION THERE IS. Read this field.
+     */
+    success: zod_1.z.boolean(),
+    /** Which driver was tested - the SUBMITTED one, not necessarily the saved one. */
+    provider: settings_schemas_js_1.storageDriverIdSchema,
+    /** The bucket that was tested. */
+    bucket: zod_1.z.string(),
+    /** The signing region that was used. */
+    region: zod_1.z.string(),
+    /** The origin actually talked to, or null for the SDK's own AWS host. */
+    effectiveEndpoint: zod_1.z.string().nullable(),
+    /**
+     * Whether the stored secret was used because the body left it blank.
+     *
+     * Worth echoing: "I pasted a new key and it still fails" and "I left the key
+     * alone and it still fails" are different situations, and an admin cannot tell
+     * which one they are in from the result alone.
+     */
+    usedStoredSecret: zod_1.z.boolean(),
+    /**
+     * The checks, in attempt order. The built-in (S3 family) drivers report all
+     * four; a driver an app registers reports whatever it can, possibly none
+     * (read `message` then).
+     */
+    checks: zod_1.z.array(exports.storageConnectionCheckSchema),
+    /**
+     * One sentence for the whole run, authored by the driver: what worked or what
+     * to fix. Present for every driver; the built-ins summarise their checks.
+     */
+    message: zod_1.z.string().optional(),
+    /** Small non-secret facts the driver wants shown (a directory, a container). Never a secret. */
+    details: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()])).optional(),
+    /** When it ran (ISO). */
+    attemptedAt: zod_1.z.iso.datetime(),
+});
+//# sourceMappingURL=storage-connection-test.js.map

package/dist/cjs/storage/storage-connection-test.js.map

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

package/dist/cjs/storage/storage-status.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/**
+ * The `GET /api/storage/status` payload: whether object storage is configured.
+ *
+ * @stability experimental
+ */
+export declare const storageStatusResponseSchema: z.ZodObject<{
+    configured: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * The status payload, inferred.
+ *
+ * @stability experimental
+ */
+export type StorageStatusResponse = z.infer<typeof storageStatusResponseSchema>;
+//# sourceMappingURL=storage-status.d.ts.map

package/dist/cjs/storage/storage-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-status.d.ts","sourceRoot":"","sources":["../../../src/storage/storage-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;iBAGtC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/cjs/storage/storage-status.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageStatusResponseSchema = void 0;
+const zod_1 = require("zod");
+// =============================================================================
+// GET /api/storage/status — response
+// =============================================================================
+//
+// One boolean and nothing else. The provider, bucket, region and credentials
+// are an administrator's business (`storage_config:read`); this answer goes to
+// every `storage:read` holder so the web app can show "not enabled yet"
+// instead of an upload control that would fail.
+// =============================================================================
+/**
+ * The `GET /api/storage/status` payload: whether object storage is configured.
+ *
+ * @stability experimental
+ */
+exports.storageStatusResponseSchema = zod_1.z.object({
+    /** The object-storage configuration is complete (the Doctor's `storage.config` would pass). */
+    configured: zod_1.z.boolean(),
+});
+//# sourceMappingURL=storage-status.js.map

package/dist/cjs/storage/storage-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-status.js","sourceRoot":"","sources":["../../../src/storage/storage-status.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,gFAAgF;AAChF,qCAAqC;AACrC,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,wEAAwE;AACxE,gDAAgD;AAChD,gFAAgF;AAEhF;;;;GAIG;AACU,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAClD,+FAA+F;IAC/F,UAAU,EAAE,OAAC,CAAC,OAAO,EAAE;CACxB,CAAC,CAAC"}