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

package/dist/cjs/storage/storage-bucket-provision.js

@@ -0,0 +1,216 @@
+"use strict";
+// =============================================================================
+// POST /api/admin/storage-config/bucket — request and response (issue #375)
+// =============================================================================
+//
+// Creates the bucket the submitted configuration names, and applies the four
+// settings this application actually needs it to have. It is the remedy the
+// connection test's `bucket_missing` code points at.
+//
+// -----------------------------------------------------------------------------
+// ⚠ `guided` IS A 200, AND INVENTING A STATUS CODE FOR IT WOULD BE THE BUG
+// -----------------------------------------------------------------------------
+//
+// This is the same argument `db-backup/dto/db-backup-node-credential.dto.ts`
+// and `restore-preflight.service.ts` make for `CREATEROLE` and `CREATEDB`, and
+// it holds here for the same reason: AN APPLICATION CREDENTIAL WITHOUT
+// `s3:CreateBucket` IS THE ORDINARY CONFIGURATION, NOT A FAULT. A
+// least-privilege IAM policy scoped to one bucket's objects is what a
+// well-run deployment issues, and Cloudflare R2 API tokens are routinely minted
+// object-read-write with no bucket-admin scope at all.
+//
+// A `4xx` would tell an administrator their setup is unsupported when it is
+// exactly right. A `5xx` would tell them something is broken when nothing is.
+// What is true is smaller and more useful: this key cannot make buckets, here
+// are the three commands that make one with a key that can, and once it exists
+// everything else works untouched. So the STATUS is 200 and the ANSWER is
+// `outcome`, with real names already substituted into `guidance.commands` — a
+// block with a placeholder in it is not a deliverable, it is homework.
+//
+// -----------------------------------------------------------------------------
+// PER-STEP OUTCOMES, BECAUSE PARTIAL SUCCESS IS THE COMMON CASE
+// -----------------------------------------------------------------------------
+//
+// Creating a bucket and hardening it are four API calls against four different
+// IAM actions, and a key permitted the first is frequently not permitted the
+// rest. Reporting one boolean would mean an operator whose bucket was created
+// but left publicly listable is told either "failed" (and creates a second
+// bucket) or "created" (and never learns). Every step reports its own status,
+// and `outcome: 'partial'` exists precisely so the answer can be "the bucket is
+// there, and here is the one thing you must still do yourself".
+//
+// ⚠ CORS `ExposeHeaders: ['ETag']` IS NOT OPTIONAL POLISH. The browser
+// multipart path reads the `ETag` off each `UploadPart` response and sends the
+// list back to `POST /storage/objects/:id/upload/complete` (see
+// `objects.service.ts`). A cross-origin `XMLHttpRequest`/`fetch` cannot read a
+// response header that is not in `Access-Control-Expose-Headers`, so a bucket
+// whose CORS rule omits it produces uploads that transfer every byte
+// successfully and then fail to complete, with a browser-side error that names
+// neither CORS nor the bucket. See {@link STORAGE_BUCKET_STEP_IDS}.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageBucketProvisionResultSchema = exports.guidedBucketInstructionsSchema = exports.storageBucketStepSchema = exports.STORAGE_BUCKET_OUTCOMES = exports.STORAGE_BUCKET_STEP_STATUSES = exports.STORAGE_BUCKET_STEP_IDS = exports.provisionStorageBucketSchema = void 0;
+const zod_1 = require("zod");
+const settings_schemas_js_1 = require("./settings-schemas.js");
+const storage_connection_test_js_1 = require("./storage-connection-test.js");
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+/**
+ * The configuration whose bucket to create — the SUBMITTED, UNSAVED one, for
+ * the same reason the connection test takes one: an operator provisions the new
+ * bucket before pointing the deployment at it, not after.
+ *
+ * Reuses the test request's schema rather than restating it. No `confirmation`:
+ * creating a bucket strands nothing, and a bucket that already exists is
+ * reported as `already_exists` rather than touched.
+ *
+ * @stability experimental
+ */
+exports.provisionStorageBucketSchema = storage_connection_test_js_1.testStorageConfigSchema;
+// ---------------------------------------------------------------------------
+// Response
+// ---------------------------------------------------------------------------
+/**
+ * The four steps, in the order they are attempted.
+ *
+ * `publicAccessBlock` and `encryption` are **AWS S3 only** and are reported as
+ * `skipped` for `r2` and `s3compatible`. That is not laziness: R2 buckets are
+ * private by default and encrypted at rest by default, and `PutPublicAccessBlock`
+ * /`PutBucketEncryption` are AWS-specific APIs that an S3-compatible server is
+ * free not to implement. Calling them anyway would turn "this vendor does not
+ * have that API" into a failed step on a bucket that is already in the state the
+ * step wanted.
+ *
+ * `cors` runs for every provider: it is the one step whose absence breaks the
+ * product rather than loosening it, and every S3-compatible implementation this
+ * application supports has `PutBucketCors`.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_BUCKET_STEP_IDS = [
+    'create',
+    'publicAccessBlock',
+    'encryption',
+    'cors',
+];
+/**
+ * `skipped` covers two different, both-honest cases, and the step's `detail`
+ * says which: the step does not apply to this provider, or an earlier step
+ * failed so hard that attempting it would be meaningless.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_BUCKET_STEP_STATUSES = ['passed', 'failed', 'skipped'];
+/**
+ * Five outcomes, and none of them is an HTTP error. See this file's header.
+ *
+ * `created`        every applicable step succeeded, and the bucket is new.
+ * `already_exists` the bucket was already there and owned by this key; the
+ *                  hardening steps still ran, and every applicable one passed.
+ * `partial`        the bucket exists now, but at least one hardening step
+ *                  failed. `steps` says which, and it is the operator's to
+ *                  finish.
+ * `guided`         the credential may not create buckets. `guidance` carries
+ *                  the commands that do it elsewhere. ⚠ NOT AN ERROR.
+ * `failed`         the bucket does not exist and this is not a permissions
+ *                  question — the name is taken by another account, the
+ *                  endpoint is unreachable, the credential is wrong.
+ *
+ * @stability experimental
+ */
+exports.STORAGE_BUCKET_OUTCOMES = [
+    'created',
+    'already_exists',
+    'partial',
+    'guided',
+    'failed',
+];
+/**
+ * One step of bucket provisioning and how it went.
+ *
+ * @stability experimental
+ */
+exports.storageBucketStepSchema = zod_1.z.object({
+    /** The id. */
+    id: zod_1.z.enum(exports.STORAGE_BUCKET_STEP_IDS),
+    /** A human label. */
+    label: zod_1.z.string(),
+    /** The status. */
+    status: zod_1.z.enum(exports.STORAGE_BUCKET_STEP_STATUSES),
+    /** Authored here: what this step did, or why it did not. */
+    detail: zod_1.z.string(),
+    /** The provider's own message, verbatim, with any secret redacted. Null on success. */
+    error: zod_1.z.string().nullable(),
+});
+/**
+ * The ready-to-paste answer the `guided` outcome exists to deliver. Same three
+ * fields, same meanings, as `guidedJobRoleInstructionsSchema` in
+ * `db-backup/dto/db-backup-node-credential.dto.ts` — a second shape for
+ * "here is what to run instead" would be a second thing to render.
+ *
+ * @stability experimental
+ */
+exports.guidedBucketInstructionsSchema = zod_1.z.object({
+    /** What sent the operator here, in one sentence. */
+    reason: zod_1.z.string(),
+    /**
+     * A complete command block with this deployment's REAL bucket, region and
+     * endpoint already substituted — `aws s3api` for `s3` and `s3compatible`,
+     * `wrangler` for `r2`.
+     */
+    commands: zod_1.z.string(),
+    /**
+     * Repository-relative path to the runbook that explains the block.
+     *
+     * NULLABLE — kept that way even now that issue #378 has written
+     * `docs/runbooks/storage-configuration.md` and
+     * `StorageBucketProvisionService` fills this in (`STORAGE_RUNBOOK_PATH`).
+     * The nullability is what let #375 ship the endpoint before the runbook
+     * existed without ever pointing at a file that was not there — the same
+     * shape `guidedJobRoleInstructionsSchema` uses non-nullably only because its
+     * runbook already existed the day that schema was written. Leaving this
+     * field nullable rather than tightening it to `z.string()` costs nothing and
+     * keeps the type honest for a fork that removes the runbook or ships this
+     * response before writing one of its own.
+     */
+    runbook: zod_1.z.string().nullable(),
+});
+/**
+ * The `POST /api/admin/storage-config/bucket` payload, always HTTP 200: read `outcome`.
+ *
+ * @stability experimental
+ */
+exports.storageBucketProvisionResultSchema = zod_1.z.object({
+    /** ⚠ THE ANSWER. Never inferred from the status code, which is always 200. */
+    outcome: zod_1.z.enum(exports.STORAGE_BUCKET_OUTCOMES),
+    /** Which driver. */
+    provider: settings_schemas_js_1.storageDriverIdSchema,
+    /** The bucket (or container, or directory) name; empty means not configured. */
+    bucket: zod_1.z.string(),
+    /** The region (`auto` for R2); empty means not configured. */
+    region: zod_1.z.string(),
+    /** The endpoint the client actually uses, or `null` for the SDK default. */
+    effectiveEndpoint: zod_1.z.string().nullable(),
+    /** Always all four, in attempt order, whatever the outcome. */
+    steps: zod_1.z.array(exports.storageBucketStepSchema),
+    /**
+     * One sentence for the whole run, authored by the driver. Present for every
+     * driver; a driver without a bucket concept says so here.
+     */
+    message: zod_1.z.string().optional(),
+    /** Present exactly when `outcome` is `guided`. */
+    guidance: exports.guidedBucketInstructionsSchema.nullable(),
+    /**
+     * The CORS origin the `cors` step allowed, echoed so an operator can see it
+     * without reading the bucket back.
+     *
+     * It is `APP_URL`, taken from this deployment's own configuration and never
+     * from the request: a caller-supplied origin would make this endpoint a
+     * "grant any website write access to our bucket" button.
+     */
+    corsOrigin: zod_1.z.string().nullable(),
+    /** When it ran (ISO). */
+    attemptedAt: zod_1.z.iso.datetime(),
+});
+//# sourceMappingURL=storage-bucket-provision.js.map

package/dist/cjs/storage/storage-bucket-provision.js.map

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

package/dist/cjs/storage/storage-config-response.d.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+/**
+ * The masked view of the stored secret access key.
+ *
+ * Deliberately the same four fields as `PrivateKeyStatus` and
+ * `SmtpPasswordStatus`, in the same order, with the same meanings — a fourth
+ * shape for the same job is a fourth thing to reason about when a credential
+ * page misbehaves.
+ *
+ * @stability experimental
+ */
+export declare const storageSecretStatusSchema: z.ZodObject<{
+    configured: z.ZodBoolean;
+    hint: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    updatedByUserId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The `GET` / `PUT /api/admin/storage-config` view: the active driver, every
+ * driver's settings and descriptor, the resolution verdict, the masked secret status and provenance.
+ *
+ * @stability experimental
+ */
+export declare const storageConfigResponseSchema: z.ZodObject<{
+    provider: z.ZodString;
+    drivers: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    endpoint: z.ZodString;
+    accountId: z.ZodString;
+    accessKeyId: z.ZodString;
+    forcePathStyle: z.ZodNullable<z.ZodBoolean>;
+    descriptors: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"boolean">;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"enum">;
+            options: z.ZodArray<z.ZodString>;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"number">;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            integer: z.ZodOptional<z.ZodBoolean>;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"string">;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"other">;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"secret">;
+            hasValue: z.ZodBoolean;
+            required: z.ZodBoolean;
+            name: z.ZodString;
+            label: z.ZodString;
+            help: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>>;
+    effectiveEndpoint: z.ZodNullable<z.ZodString>;
+    configured: z.ZodBoolean;
+    missing: z.ZodArray<z.ZodString>;
+    secretStatus: z.ZodObject<{
+        configured: z.ZodBoolean;
+        hint: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodISODateTime>;
+        updatedByUserId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    version: z.ZodNumber;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+    updatedBy: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The admin view, inferred.
+ *
+ * @stability experimental
+ */
+export type StorageConfigResponse = z.infer<typeof storageConfigResponseSchema>;
+//# sourceMappingURL=storage-config-response.d.ts.map

package/dist/cjs/storage/storage-config-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-config-response.d.ts","sourceRoot":"","sources":["../../../src/storage/storage-config-response.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB;;;;;iBA2BpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+GtC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

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

@@ -0,0 +1,173 @@
+"use strict";
+// =============================================================================
+// GET / PUT /api/admin/storage-config — response body (issue #375, epic #372)
+// =============================================================================
+//
+// ⚠ THE INVARIANT THIS FILE EXISTS TO HOLD: THERE IS NO FIELD HERE CAPABLE OF
+// CARRYING THE SECRET ACCESS KEY, AND THERE MUST NEVER BE ONE.
+//
+// The secret lives at `(purpose 'storage', name 'default')` in the encrypted
+// credential store and is readable only through `CredentialsService.getSecret`,
+// which no controller may call. What an administrator gets instead is
+// {@link storageSecretStatusSchema} — `configured`, a mask, and who wrote it
+// last — which is exactly the information needed to tell "a key is stored" from
+// "a key is stored and it is the one I just rotated to", and carries none of
+// the material. `PrivateKeyStatus` in `notifications/push-config.service.ts` and
+// `SmtpPasswordStatus` in `email/email-settings.service.ts` are the same shape
+// for the same reason; this is the third and it does not invent a fourth.
+//
+// Everything else in the `storage` namespace IS returned in full, including
+// `accessKeyId`. That is not an oversight: a key id is an identifier, it travels
+// in the clear in every SigV4 `Authorization` header, and an administrator who
+// cannot see which key id is configured cannot tell a rotated key from a
+// mistyped one. `common/schemas/settings.schema.ts` carries a compile-time proof
+// that the settings half never acquires the secret.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageConfigResponseSchema = exports.storageSecretStatusSchema = void 0;
+const zod_1 = require("zod");
+const index_js_1 = require("../settings/index.js");
+const settings_schemas_js_1 = require("./settings-schemas.js");
+/**
+ * The masked view of the stored secret access key.
+ *
+ * Deliberately the same four fields as `PrivateKeyStatus` and
+ * `SmtpPasswordStatus`, in the same order, with the same meanings — a fourth
+ * shape for the same job is a fourth thing to reason about when a credential
+ * page misbehaves.
+ *
+ * @stability experimental
+ */
+exports.storageSecretStatusSchema = zod_1.z.object({
+    /** Is a secret stored at `(purpose 'storage', name 'default')`? */
+    configured: zod_1.z.boolean(),
+    /**
+     * The credential store's own mask, e.g. `••••x9fQ`. Null when nothing is
+     * stored.
+     *
+     * Derived by `CredentialsService` from the plaintext at write time and held
+     * in a non-secret column; this endpoint never sees the value it masks.
+     */
+    hint: zod_1.z.string().nullable(),
+    /**
+     * When the stored secret was last written, as an ISO 8601 string. Null when
+     * nothing is stored.
+     *
+     * ⚠ A STRING, NOT `z.date()`. A `Date` has no JSON Schema representation, and
+     * `nestjs-zod` throws while building the OpenAPI document rather than
+     * degrading — which takes `/api/docs` down for the whole API, not just this
+     * route. Every dated field in this repository's response DTOs is
+     * `z.iso.datetime()` for that reason; see `push-config-response.dto.ts`.
+     */
+    updatedAt: zod_1.z.iso.datetime().nullable(),
+    /** Who last wrote it. Null when nothing is stored, or that user was deleted. */
+    updatedByUserId: zod_1.z.string().nullable(),
+});
+/**
+ * The `GET` / `PUT /api/admin/storage-config` view: the active driver, every
+ * driver's settings and descriptor, the resolution verdict, the masked secret status and provenance.
+ *
+ * @stability experimental
+ */
+exports.storageConfigResponseSchema = zod_1.z.object({
+    // ---------------------------------------------------------------------------
+    // The `storage` settings namespace, verbatim
+    // ---------------------------------------------------------------------------
+    /** The id of the active storage driver: a built-in (`s3`, `r2`, `s3compatible`) or one an app registered. */
+    provider: settings_schemas_js_1.storageDriverIdSchema,
+    /**
+     * Every registered driver's own non-secret settings, keyed by driver id, with
+     * its defaults filled. The shape drivers an app registers are configured in.
+     */
+    drivers: settings_schemas_js_1.storageDriversSchema,
+    /** @deprecated The active built-in driver's `bucket`; empty means not configured (or the active driver is not a built-in). */
+    bucket: zod_1.z.string(),
+    /** @deprecated The active built-in driver's `region` (`auto` for R2). */
+    region: zod_1.z.string(),
+    /** @deprecated The active built-in driver's `endpoint` override; empty means derive it (R2) or use the SDK's host. */
+    endpoint: zod_1.z.string(),
+    /** @deprecated The active built-in driver's Cloudflare account id (R2 only). */
+    accountId: zod_1.z.string(),
+    /** @deprecated The active built-in driver's access key id. An identifier, not a credential. See this file's header. */
+    accessKeyId: zod_1.z.string(),
+    /** @deprecated The active built-in driver's tri-state `forcePathStyle`: `true`/`false`, or `null` for "use this vendor's convention". */
+    forcePathStyle: zod_1.z.boolean().nullable(),
+    /**
+     * One descriptor per REGISTERED storage driver, in registration order: its
+     * id and label, its non-secret settings fields and one `secret` field per
+     * declared secret carrying only whether a value is stored (`hasValue`),
+     * never the value. The admin page renders any driver without hard-coded
+     * knowledge of it.
+     */
+    descriptors: zod_1.z.array(index_js_1.pluggableDescriptorSchema),
+    // ---------------------------------------------------------------------------
+    // Derived, read-only
+    // ---------------------------------------------------------------------------
+    /**
+     * The origin an S3 client would actually be pointed at, or `null` for "the
+     * SDK's own regional AWS host".
+     *
+     * EXISTS SO THE UI CAN SHOW R2's ENDPOINT WITHOUT DERIVING IT. An R2
+     * deployment stores an `accountId` and an empty `endpoint`; the host is
+     * `<accountId>.r2.cloudflarestorage.com`, built by `deriveR2Endpoint`. A
+     * settings page that computed that itself would be a second copy of the rule
+     * in a language that cannot be unit-tested against the server's — and the
+     * failure mode of the second copy is a page that displays one host while the
+     * client talks to another. It is READ-ONLY: `endpoint` above is the field a
+     * `PUT` writes, and typing one there always wins.
+     */
+    effectiveEndpoint: zod_1.z.string().nullable(),
+    /**
+     * Whether this configuration is complete enough to use, RIGHT NOW.
+     *
+     * Answered by `resolveStorageConfig` — the single definition of "configured"
+     * — and never re-derived here. A page that decides for itself that six
+     * non-empty fields means "ready" is a page that reports ready about a
+     * configuration the upload path refuses.
+     */
+    configured: zod_1.z.boolean(),
+    /**
+     * Every field the configuration needs and does not have. Empty when
+     * `configured` is true.
+     *
+     * The built-in drivers name `bucket`, `region`, `endpoint`, `accountId`,
+     * `accessKeyId` and `secretAccessKey` (`MISSING_STORAGE_CONFIG_FIELDS`); a
+     * driver an app registers names its own settings and secrets.
+     *
+     * INCLUDES `secretAccessKey`, which is not a settings field: from the point
+     * of view of "can this deployment store a file?", a missing credential row and
+     * an empty bucket are the same kind of problem. It names the field, never its
+     * value.
+     */
+    missing: zod_1.z.array(zod_1.z.string()),
+    /**
+     * The masked status of the ACTIVE driver's primary secret (the first one it
+     * declares: the secret access key for the built-ins). Every driver's secret
+     * presence is in `descriptors`. See the header.
+     */
+    secretStatus: exports.storageSecretStatusSchema,
+    // ---------------------------------------------------------------------------
+    // Provenance of the settings row
+    // ---------------------------------------------------------------------------
+    /**
+     * The `system_settings` row version, bumped on every write.
+     *
+     * The optimistic-concurrency token: send it back as `If-Match` on `PUT`.
+     * It is the version of the WHOLE `global` row, not of the `storage` namespace
+     * alone — see `StorageConfigAdminService` for why that is the honest token
+     * and not an over-broad one.
+     */
+    version: zod_1.z.number().int(),
+    /** ISO 8601. See the note on `secretStatus.updatedAt` for why not `z.date()`. */
+    updatedAt: zod_1.z.iso.datetime().nullable(),
+    /** Who last saved the settings row, or `null`. */
+    updatedBy: zod_1.z
+        .object({
+        /** Their user id. */
+        id: zod_1.z.string(),
+        /** Their address. */
+        email: zod_1.z.string(),
+    })
+        .nullable(),
+});
+//# sourceMappingURL=storage-config-response.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage-config-response.js","sourceRoot":"","sources":["../../../src/storage/storage-config-response.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,+DAA+D;AAC/D,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,sEAAsE;AACtE,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,iFAAiF;AACjF,+EAA+E;AAC/E,0EAA0E;AAC1E,EAAE;AACF,4EAA4E;AAC5E,iFAAiF;AACjF,+EAA+E;AAC/E,yEAAyE;AACzE,iFAAiF;AACjF,oDAAoD;AACpD,gFAAgF;;;AAEhF,6BAAwB;AAExB,mDAAiE;AACjE,+DAAoF;AAEpF;;;;;;;;;GASG;AACU,QAAA,yBAAyB,GAAG,OAAC,CAAC,MAAM,CAAC;IAChD,mEAAmE;IACnE,UAAU,EAAE,OAAC,CAAC,OAAO,EAAE;IAEvB;;;;;;OAMG;IACH,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE3B;;;;;;;;;OASG;IACH,SAAS,EAAE,OAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEtC,gFAAgF;IAChF,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAEH;;;;;GAKG;AACU,QAAA,2BAA2B,GAAG,OAAC,CAAC,MAAM,CAAC;IAClD,8EAA8E;IAC9E,6CAA6C;IAC7C,8EAA8E;IAE9E,6GAA6G;IAC7G,QAAQ,EAAE,2CAAqB;IAC/B;;;OAGG;IACH,OAAO,EAAE,0CAAoB;IAC7B,8HAA8H;IAC9H,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,yEAAyE;IACzE,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,sHAAsH;IACtH,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE;IACpB,gFAAgF;IAChF,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,uHAAuH;IACvH,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE;IACvB,yIAAyI;IACzI,cAAc,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAEtC;;;;;;OAMG;IACH,WAAW,EAAE,OAAC,CAAC,KAAK,CAAC,oCAAyB,CAAC;IAE/C,8EAA8E;IAC9E,qBAAqB;IACrB,8EAA8E;IAE9E;;;;;;;;;;;;OAYG;IACH,iBAAiB,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAExC;;;;;;;OAOG;IACH,UAAU,EAAE,OAAC,CAAC,OAAO,EAAE;IAEvB;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IAE5B;;;;OAIG;IACH,YAAY,EAAE,iCAAyB;IAEvC,8EAA8E;IAC9E,iCAAiC;IACjC,8EAA8E;IAE9E;;;;;;;OAOG;IACH,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAEzB,iFAAiF;IACjF,SAAS,EAAE,OAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEtC,kDAAkD;IAClD,SAAS,EAAE,OAAC;SACT,MAAM,CAAC;QACN,qBAAqB;QACrB,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;QACd,qBAAqB;QACrB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;KAClB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC"}

package/dist/cjs/storage/storage-config-update.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+/**
+ * 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
+ */
+export declare const 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
+ */
+export declare const updateStorageConfigSchema: z.ZodObject<{
+    provider: z.ZodString;
+    drivers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+    bucket: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    accountId: z.ZodOptional<z.ZodString>;
+    accessKeyId: z.ZodOptional<z.ZodString>;
+    secretAccessKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNullable<z.ZodString>>>>>;
+    forcePathStyle: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    confirmation: z.ZodOptional<z.ZodLiteral<"SWITCH">>;
+}, z.core.$strip>;
+/**
+ * The parsed body.
+ *
+ * @stability experimental
+ */
+export type UpdateStorageConfigInput = z.output<typeof updateStorageConfigSchema>;
+//# sourceMappingURL=storage-config-update.d.ts.map

package/dist/cjs/storage/storage-config-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-config-update.d.ts","sourceRoot":"","sources":["../../../src/storage/storage-config-update.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,WAAW,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;iBAmEpC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC"}