@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.5

package/dist/storage/drivers/s3/s3-purge.js

@@ -0,0 +1,146 @@
+"use strict";
+// =============================================================================
+// The built-in S3 drivers' purge (issue #404; PP-14.7)
+// =============================================================================
+//
+// What `npm run storage:purge` does to an S3-family bucket: count (dry run) or
+// delete every object under the registered key prefixes, VERSION-AWARE. A
+// versioned bucket keeps every object version and a delete marker for each
+// deletion, so `DeleteObject` on a listing leaves the data behind while
+// reporting success; versions are enumerated and removed by id. When the
+// versioning status cannot be READ the bucket is treated as VERSIONED, because
+// assuming the cheaper answer produces silent retention, the one outcome a
+// purge must never produce. Moved here from `purge/run-storage-purge.ts` with
+// its comments when the S3 SDK became a concern of the drivers alone.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.purgeS3 = purgeS3;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_storage_provider_1 = require("../../providers/s3/s3-storage.provider");
+const s3_config_1 = require("./s3-config");
+/**
+ * Purges (or, with `dryRun`, counts) every object under `prefixes` in an
+ * S3-family bucket. Targets come ONLY from the list given, never from a
+ * filtered listing of the whole bucket.
+ *
+ * @param ctx - the driver context.
+ * @param flavour - the built-in flavour's rules.
+ * @param input - the prefixes, `dryRun`, and a pre-built client (tests).
+ * @throws Error when the configuration is incomplete and no client was given.
+ *
+ * @stability experimental
+ */
+async function purgeS3(ctx, flavour, input) {
+    let client = input.client;
+    if (client === undefined) {
+        // Reuses the driver's own client builder rather than re-deriving endpoint,
+        // region and forcePathStyle. A second construction here would be a second
+        // opinion about how to reach this bucket.
+        const resolution = (0, s3_config_1.resolveS3Config)(flavour, ctx.settings, await ctx.secret('secretAccessKey'));
+        if (!resolution.configured) {
+            throw new Error(`Cannot purge: the ${flavour.id} configuration is missing ${resolution.missing.join(', ')}.`);
+        }
+        client = new client_s3_1.S3Client((0, s3_storage_provider_1.buildS3ClientConfig)(resolution.config));
+    }
+    const bucket = ctx.settings.bucket;
+    const versioning = await readVersioning(client, bucket);
+    const prefixes = [];
+    let deleted = 0;
+    // ⚠ Targets come ONLY from the application's own list (every prefix in the
+    // storage key-prefix registry, platform and app), never from a listing of
+    // the whole bucket filtered afterwards. A filter can be inverted by a later
+    // edit; enumerating a fixed list cannot be. Root prefixes cover both key
+    // layouts (legacy `uploads/<timestamp>/` and `uploads/<orgId>/`).
+    for (const prefix of input.prefixes) {
+        const report = { prefix, objects: 0, bytes: 0 };
+        if (versioning === 'unversioned') {
+            deleted += await sweepObjects(client, bucket, prefix, report, input.dryRun);
+        }
+        else {
+            // Versioned, OR the status could not be read. Every version and delete
+            // marker goes by id: a plain DeleteObject on a versioned bucket adds a
+            // marker and leaves the data, while reporting success.
+            deleted += await sweepVersions(client, bucket, prefix, report, input.dryRun);
+        }
+        prefixes.push(report);
+    }
+    return { versioning, prefixes, deleted };
+}
+/**
+ * The bucket's versioning status.
+ *
+ * ⚠ AN UNREADABLE ANSWER IS TREATED AS VERSIONED. Assuming the cheaper answer
+ * is exactly what produces silent retention -- the purge would report complete
+ * having left every version in place -- and silent retention is the one outcome
+ * this must never produce. Reported as `unknown` so the operator sees which
+ * branch was taken.
+ */
+async function readVersioning(client, bucket) {
+    try {
+        const result = await client.send(new client_s3_1.GetBucketVersioningCommand({ Bucket: bucket }));
+        if (result.Status === 'Enabled')
+            return 'enabled';
+        if (result.Status === 'Suspended')
+            return 'suspended';
+        return 'unversioned';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Plain objects, for a bucket known not to be versioned. */
+async function sweepObjects(client, bucket, prefix, report, dryRun) {
+    let token;
+    let deleted = 0;
+    do {
+        const page = await client.send(new client_s3_1.ListObjectsV2Command({ Bucket: bucket, Prefix: prefix, ContinuationToken: token }));
+        const objects = page.Contents ?? [];
+        for (const object of objects) {
+            report.objects += 1;
+            report.bytes += object.Size ?? 0;
+        }
+        if (!dryRun && objects.length > 0) {
+            await client.send(new client_s3_1.DeleteObjectsCommand({
+                Bucket: bucket,
+                Delete: { Objects: objects.map((object) => ({ Key: object.Key })) },
+            }));
+            deleted += objects.length;
+        }
+        token = page.IsTruncated === true ? page.NextContinuationToken : undefined;
+    } while (token !== undefined);
+    return deleted;
+}
+/** Every version and delete marker, by id. */
+async function sweepVersions(client, bucket, prefix, report, dryRun) {
+    let keyMarker;
+    let versionMarker;
+    let deleted = 0;
+    do {
+        const page = await client.send(new client_s3_1.ListObjectVersionsCommand({
+            Bucket: bucket,
+            Prefix: prefix,
+            KeyMarker: keyMarker,
+            VersionIdMarker: versionMarker,
+        }));
+        const versions = page.Versions ?? [];
+        // Delete markers carry no bytes but MUST still be removed, or the bucket
+        // keeps a tombstone for every object the purge claimed to have deleted.
+        const markers = page.DeleteMarkers ?? [];
+        for (const version of versions) {
+            report.objects += 1;
+            report.bytes += version.Size ?? 0;
+        }
+        const targets = [...versions, ...markers].map((entry) => ({
+            Key: entry.Key,
+            VersionId: entry.VersionId,
+        }));
+        if (!dryRun && targets.length > 0) {
+            await client.send(new client_s3_1.DeleteObjectsCommand({ Bucket: bucket, Delete: { Objects: targets } }));
+            deleted += targets.length;
+        }
+        keyMarker = page.IsTruncated === true ? page.NextKeyMarker : undefined;
+        versionMarker = page.IsTruncated === true ? page.NextVersionIdMarker : undefined;
+    } while (keyMarker !== undefined || versionMarker !== undefined);
+    return deleted;
+}
+//# sourceMappingURL=s3-purge.js.map

package/dist/storage/drivers/s3/s3-purge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-purge.js","sourceRoot":"","sources":["../../../../src/storage/drivers/s3/s3-purge.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,uDAAuD;AACvD,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,2EAA2E;AAC3E,wEAAwE;AACxE,yEAAyE;AACzE,+EAA+E;AAC/E,2EAA2E;AAC3E,8EAA8E;AAC9E,sEAAsE;AACtE,gFAAgF;;AA6ChF,0BA4CC;AAvFD,kDAS4B;AAE5B,gFAA6E;AAM7E,2CAAyF;AAczF;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,OAAO,CAC3B,GAA2C,EAC3C,OAAsB,EACtB,KAAyE;IAEzE,IAAI,MAAM,GAAG,KAAK,CAAC,MAAwC,CAAC;IAC5D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,2EAA2E;QAC3E,0EAA0E;QAC1E,0CAA0C;QAC1C,MAAM,UAAU,GAAG,IAAA,2BAAe,EAAC,OAAO,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAC/F,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,qBAAqB,OAAO,CAAC,EAAE,6BAA6B,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChH,CAAC;QACD,MAAM,GAAG,IAAI,oBAAQ,CAAC,IAAA,yCAAmB,EAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;IACnC,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExD,MAAM,QAAQ,GAA+B,EAAE,CAAC;IAChD,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,yEAAyE;IACzE,kEAAkE;IAClE,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,MAAM,GAA6B,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAE1E,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;YACjC,OAAO,IAAI,MAAM,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9E,CAAC;aAAM,CAAC;YACN,uEAAuE;YACvE,uEAAuE;YACvE,uDAAuD;YACvD,OAAO,IAAI,MAAM,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/E,CAAC;QAED,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,cAAc,CAC3B,MAA0B,EAC1B,MAAc;IAEd,IAAI,CAAC;QACH,MAAM,MAAM,GAAqC,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,sCAA0B,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QACvH,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAClD,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW;YAAE,OAAO,WAAW,CAAC;QACtD,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,KAAK,UAAU,YAAY,CACzB,MAA0B,EAC1B,MAAc,EACd,MAAc,EACd,MAAgC,EAChC,MAAe;IAEf,IAAI,KAAyB,CAAC;IAC9B,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,GAAG,CAAC;QACF,MAAM,IAAI,GAA+B,MAAM,MAAM,CAAC,IAAI,CACxD,IAAI,gCAAoB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CACvF,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QACpC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,gCAAoB,CAAC;gBACvB,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAa,EAAE,CAAC,CAAC,EAAE;aAC9E,CAAC,CACH,CAAC;YACF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;QAC5B,CAAC;QAED,KAAK,GAAG,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,CAAC,QAAQ,KAAK,KAAK,SAAS,EAAE;IAE9B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8CAA8C;AAC9C,KAAK,UAAU,aAAa,CAC1B,MAA0B,EAC1B,MAAc,EACd,MAAc,EACd,MAAgC,EAChC,MAAe;IAEf,IAAI,SAA6B,CAAC;IAClC,IAAI,aAAiC,CAAC;IACtC,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,GAAG,CAAC;QACF,MAAM,IAAI,GAAoC,MAAM,MAAM,CAAC,IAAI,CAC7D,IAAI,qCAAyB,CAAC;YAC5B,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,SAAS;YACpB,eAAe,EAAE,aAAa;SAC/B,CAAC,CACH,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QACrC,yEAAyE;QACzE,wEAAwE;QACxE,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC;QAEzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACxD,GAAG,EAAE,KAAK,CAAC,GAAa;YACxB,SAAS,EAAE,KAAK,CAAC,SAAmB;SACrC,CAAC,CAAC,CAAC;QAEJ,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,gCAAoB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,CAC3E,CAAC;YACF,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;QAC5B,CAAC;QAED,SAAS,GAAG,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,aAAa,GAAG,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC;IACnF,CAAC,QAAQ,SAAS,KAAK,SAAS,IAAI,aAAa,KAAK,SAAS,EAAE;IAEjE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/storage/drivers/storage-driver.d.ts

@@ -0,0 +1,393 @@
+import type { Logger } from '@nestjs/common';
+import { type StorageBucketOutcome, type StorageBucketStep, type StorageBucketStepId, type StorageConnectionCheck } from '@marinoscar/platform-contract/storage';
+import type { PluggableDescriptor } from '@marinoscar/platform-contract/settings';
+import type { z } from 'zod';
+import { type PluggableBuildInput, type PluggableKind, type PluggableSecretPresence, type PluggableSecretSpec } from '../../core/index';
+import type { StorageProvider } from '../providers/storage-provider.interface';
+/**
+ * A driver's non-secret settings, as its `settingsSchema` parses them.
+ *
+ * @stability experimental
+ */
+export type StorageDriverSettings = Record<string, unknown>;
+/**
+ * What the slice passes to every driver call besides the driver's own
+ * settings and secrets.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverBuildContext {
+    /** A logger scoped to the storage slice. Never log a secret through it. */
+    logger: Logger;
+    /** The multipart part size in bytes the deployment is configured for (`storage.partSize`). */
+    partSize: number;
+    /**
+     * The deployment's own origin (`APP_URL`), for a driver that sets a CORS rule
+     * on the bucket it provisions. Absent when the deployment has none.
+     */
+    appOrigin?: string;
+}
+/**
+ * The argument of every driver operation: this driver's settings (parsed with
+ * its `settingsSchema`, defaults filled), a resolver for the secrets it
+ * declared, and the slice's context.
+ *
+ * `secret(name)` resolves one of the driver's DECLARED secrets for this call
+ * and returns `null` when none is stored. Hold the value only for the call.
+ *
+ * @typeParam S - the driver's parsed settings.
+ *
+ * @stability experimental
+ */
+export type StorageDriverContext<S extends StorageDriverSettings = StorageDriverSettings> = PluggableBuildInput<StorageDriverBuildContext, S>;
+/**
+ * The outcome of {@link StorageDriver.testConnection}.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverTestResult {
+    /** Whether the driver worked end to end. */
+    ok: boolean;
+    /**
+     * One sentence an operator can act on, authored by the driver: what worked,
+     * or what to change. NEVER carries secret material.
+     */
+    message: string;
+    /** Small non-secret facts worth showing (a directory, a container, a region). */
+    details?: Record<string, string | number | boolean>;
+    /**
+     * An optional per-step report. The S3 family reports four (`credentials`,
+     * `bucket`, `roundTrip`, `presignedUrl`); a driver with no steps omits it.
+     */
+    checks?: readonly StorageConnectionCheck[];
+}
+/**
+ * Where one of a driver's secrets lives in the credential store.
+ *
+ * @stability experimental
+ */
+export interface StorageSecretAddress {
+    /** The credential purpose (the cipher's sub-key domain; permanent once rows exist). */
+    purpose: string;
+    /** The name within the purpose. */
+    name: string;
+    /** The non-secret label stored beside the credential (default: the secret's declared label). */
+    label?: string;
+}
+/**
+ * Ready-to-paste instructions for a credential that may not create buckets.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverGuidance {
+    /** What sent the operator here, in one sentence. */
+    reason: string;
+    /** A complete command block with this deployment's real names substituted. */
+    commands: string;
+    /** Repository-relative path to the runbook that explains the block, or `null`. */
+    runbook: string | null;
+}
+/**
+ * The outcome of {@link StorageDriver.provision}.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverProvisionResult {
+    /** Whether this call created the bucket or container (`false`: it already existed). */
+    created: boolean;
+    /** One sentence for the whole run. */
+    message: string;
+    /** The overall outcome when the driver distinguishes more than created/existing (S3: `partial`, `guided`, `failed`). */
+    outcome?: StorageBucketOutcome;
+    /** Per-step report (S3: create, public access block, encryption, CORS). */
+    steps?: readonly StorageBucketStep[];
+    /** Ready-to-paste instructions for when the credential may not create buckets. */
+    guidance?: StorageDriverGuidance | null;
+    /** The CORS origin the driver allowed, when it set one. */
+    corsOrigin?: string | null;
+}
+/**
+ * Where a driver's objects live, for the admin view, the switch confirmation
+ * and the rows that record where bytes went.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverLocation {
+    /**
+     * The bucket, container or root directory name. Recorded on every object and
+     * backup row (`storage_objects.bucket`) and shown beside the driver. Empty
+     * means "not configured".
+     */
+    bucket: string;
+    /** The origin the driver talks to, or `null` for the SDK's own default host. */
+    endpoint?: string | null;
+    /** The region, when the backend has one. */
+    region?: string;
+}
+/**
+ * One prefix's tally from {@link StorageDriver.purge}.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverPurgePrefixReport {
+    /** The prefix. */
+    prefix: string;
+    /** Objects (or object versions) found under it. */
+    objects: number;
+    /** Their total size in bytes (0 when the backend does not say). */
+    bytes: number;
+}
+/**
+ * What {@link StorageDriver.purge} returns.
+ *
+ * @stability experimental
+ */
+export interface StorageDriverPurgeResult {
+    /** Bucket versioning, for backends that have it; `unversioned` otherwise. */
+    versioning: 'enabled' | 'suspended' | 'unversioned' | 'unknown';
+    /** One report per prefix, in the order given. */
+    prefixes: StorageDriverPurgePrefixReport[];
+    /** How many objects (or versions) were deleted; 0 on a dry run. */
+    deleted: number;
+}
+/**
+ * The operations of a storage driver. Every method receives the same
+ * {@link StorageDriverContext}, so a driver is a plain object with no state of
+ * its own.
+ *
+ * @typeParam S - the driver's parsed settings.
+ *
+ * @example
+ * ```ts
+ * const driver: StorageDriver<{ directory: string }> = {
+ *   build: ({ settings }) => new LocalFsProvider(settings.directory),
+ *   testConnection: async ({ settings }) => ({ ok: true, message: `Writable: ${settings.directory}` }),
+ * };
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export interface StorageDriver<S extends StorageDriverSettings = StorageDriverSettings> {
+    /**
+     * Builds the runtime provider the whole slice uses. Called when the
+     * configuration (settings or secrets) changes, not per request; the provider
+     * is reused until then, and `destroy()` is called on it when it is superseded
+     * (when it has one).
+     */
+    build(ctx: StorageDriverContext<S>): StorageProvider | Promise<StorageProvider>;
+    /**
+     * The admin page's "Test connection". NEVER THROWS: a refused request is a
+     * successful diagnosis, so every failure is `{ ok: false, message }`. Never
+     * returns secret material, not even inside `message` or `details`: redact
+     * anything an SDK error echoes back.
+     */
+    testConnection(ctx: StorageDriverContext<S>): Promise<StorageDriverTestResult>;
+    /**
+     * Creates the bucket or container (and anything the slice needs on it).
+     * Omit it for a backend with no such concept. Safe to repeat.
+     */
+    provision?(ctx: StorageDriverContext<S>): Promise<StorageDriverProvisionResult>;
+    /**
+     * Lists every object key under `prefix`, for `npm run storage:purge`. A driver
+     * that defines it can be purged generically (list, then `delete` each key).
+     */
+    listKeys?(ctx: StorageDriverContext<S>, prefix: string): AsyncIterable<string>;
+    /**
+     * A purge the driver does itself, for backends whose purge is not "list and
+     * delete" (S3 versioned buckets also need every version and delete marker
+     * removed). Takes precedence over `listKeys`. With `dryRun` it only counts.
+     * `client` is a pre-built client of the driver's own kind, for tests.
+     */
+    purge?(ctx: StorageDriverContext<S>, input: {
+        prefixes: readonly string[];
+        dryRun: boolean;
+        client?: unknown;
+    }): Promise<StorageDriverPurgeResult>;
+    /** The region used when the settings state none, if the backend has regions. */
+    defaultRegion?: string;
+    /**
+     * Where this configuration points. Default: `settings.bucket` when it is a
+     * string, else the driver id. Pure: reads nothing.
+     */
+    location?(settings: S): StorageDriverLocation;
+    /**
+     * The names of the settings and secrets this configuration still needs,
+     * `[]` when complete. `secrets` says which of the driver's declared secrets
+     * are stored. Default: every `required` declared secret that is absent.
+     * Pure: no I/O, and the names are shown to operators, never values.
+     */
+    missing?(settings: S, secrets: Readonly<Record<string, boolean>>): string[];
+}
+/**
+ * What an app or package registers with {@link registerStorageDriver}: the
+ * driver's definition (what an admin form needs) and its operations.
+ *
+ * @typeParam S - the driver's parsed settings.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export interface StorageDriverDefinition<S extends StorageDriverSettings = StorageDriverSettings> extends StorageDriver<S> {
+    /**
+     * The driver id, `^[a-z][a-z0-9-]{1,47}$`. Permanent once a setting, a secret
+     * or an object row exists under it: it is the key of `storage.drivers`, the
+     * value of `storage.provider`, `StorageProvider.kind` and the
+     * `storage_objects.storage_provider` of every object it stored.
+     */
+    id: string;
+    /** The human label the admin page shows (`Local filesystem`). */
+    label: string;
+    /** One sentence on what the driver is. */
+    description?: string;
+    /**
+     * The driver's own NON-SECRET settings (`z.object`). `.describe('help')`
+     * becomes a field's help text and `.meta({ label })` its label in the
+     * generated form. A field may not be named like a secret (`secretAccessKey`,
+     * `apiKey`, `token`, `password`, ...): declare it in {@link secrets}.
+     */
+    settingsSchema: z.ZodObject<z.ZodRawShape>;
+    /** The settings of a fresh install; must parse with `settingsSchema`. An unconfigured driver is complete only when `missing` says so. */
+    defaults: S;
+    /**
+     * The secrets the driver needs (an account key, a connection string, a service
+     * account), kept encrypted in the credential store, never in settings and
+     * never in an environment variable. By default each lives in the credential
+     * purpose `storage_<id>` under the secret's own name; the purpose is
+     * registered for you.
+     */
+    secrets?: readonly PluggableSecretSpec[];
+    /**
+     * Where the driver's secrets live when it must not use `storage_<id>` (the
+     * built-in S3 family keeps its secret access key at `(storage, default)`).
+     * The purpose is then the caller's to register. `label` is the non-secret
+     * label stored beside the credential (default: the secret's declared label).
+     */
+    credentialAddress?(secretName: string): StorageSecretAddress;
+    /** The hosts an instance with these settings calls, for the Doctor's network-egress view. Empty for a local backend. */
+    egressHosts?(settings: S): readonly string[];
+}
+/**
+ * The `storage-driver` pluggable kind. Its instances are the definitions
+ * themselves. Use {@link registerStorageDriver} and the helpers below rather
+ * than the kind directly.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const storageDriverKind: PluggableKind<StorageDriverDefinition<any>>;
+/**
+ * Human labels for the four bucket-provisioning steps, sent in the response so
+ * a client need not carry them.
+ *
+ * @stability experimental
+ */
+export declare const STORAGE_BUCKET_STEP_LABELS: Record<StorageBucketStepId, string>;
+/**
+ * The credential purpose a driver's secrets use by default (`storage_<id>`).
+ *
+ * @param id - the driver id.
+ * @stability experimental
+ */
+export declare function storageDriverCredentialPurpose(id: string): string;
+/**
+ * Registers a storage driver. Call it at import time, before the application
+ * bootstraps (the reference app does it from
+ * `apps/api/src/app-registrations/storage.ts`, which `platform/storage/storage.config.ts`
+ * imports first). The three built-in S3 drivers register through this same
+ * function.
+ *
+ * Registering is all it takes: the `storage` settings namespace gains a
+ * `drivers.<id>` record validated by the driver's `settingsSchema`,
+ * `GET /api/admin/storage-config` describes it (`descriptors`, and a generated
+ * form on the admin page), its secrets get a credential purpose
+ * (`storage_<id>`) unless `credentialAddress` names one, and once an
+ * administrator selects it, every consumer of `STORAGE_PROVIDER` (the objects
+ * API, profile images, exports, backups, the node object store) uses the
+ * provider it builds.
+ *
+ * @param def - the driver.
+ * @throws Error when the definition is malformed (an id that does not match the pattern, a secret-looking settings field, defaults that do not parse, a missing operation).
+ * @throws RegistryError `DUPLICATE_ID` when the id is registered, `FROZEN` after the application bootstrapped.
+ *
+ * @example
+ * ```ts
+ * registerStorageDriver({
+ *   id: 'local-fs',
+ *   label: 'Local filesystem',
+ *   settingsSchema: z.object({ directory: z.string().describe('Directory the objects are written under') }),
+ *   defaults: { directory: '' },
+ *   build: ({ settings }) => new LocalFsStorageProvider(settings.directory),
+ *   testConnection: async ({ settings }) => ({ ok: true, message: `Writable: ${settings.directory}` }),
+ * });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerStorageDriver<S extends StorageDriverSettings>(def: StorageDriverDefinition<S>): void;
+/**
+ * Every registered storage driver, in registration order (the built-ins first;
+ * the order the admin page lists them).
+ *
+ * @stability experimental
+ */
+export declare function storageDriverDefinitions(): readonly StorageDriverDefinition<any>[];
+/**
+ * The ids of every registered storage driver, in registration order.
+ *
+ * @stability experimental
+ */
+export declare function storageDriverIds(): string[];
+/**
+ * The driver registered under `id`, or `undefined`.
+ *
+ * @param id - the driver id.
+ * @stability experimental
+ */
+export declare function getStorageDriver(id: string): StorageDriverDefinition<any> | undefined;
+/**
+ * The driver registered under `id`.
+ *
+ * @param id - the driver id.
+ * @throws PluggableUnknownError when none is registered; the message names the registered ids.
+ * @stability experimental
+ */
+export declare function requireStorageDriver(id: string): StorageDriverDefinition<any>;
+/**
+ * Where `driver`'s secret `name` lives in the credential store.
+ *
+ * @param driver - a registered driver.
+ * @param name - one of the secrets it declares.
+ * @returns the `(purpose, name)` address.
+ * @stability experimental
+ */
+export declare function storageSecretAddress(driver: Pick<StorageDriverDefinition<any>, 'id' | 'credentialAddress'>, name: string): StorageSecretAddress;
+/**
+ * The descriptor of every registered driver for a generated form: its
+ * non-secret fields, then one write-only `secret` field per declared secret
+ * carrying only whether a value is stored.
+ *
+ * @param presence - which of a driver's secrets are stored.
+ * @stability experimental
+ */
+export declare function describeStorageDrivers(presence: (id: string) => PluggableSecretPresence): PluggableDescriptor[];
+/**
+ * The names of a driver's still-missing settings and secrets
+ * ({@link StorageDriver.missing}, or every required secret that is absent).
+ *
+ * @param driver - a registered driver.
+ * @param settings - its parsed settings.
+ * @param present - which of its declared secrets are stored.
+ * @stability experimental
+ */
+export declare function missingStorageFields(driver: StorageDriverDefinition<any>, settings: StorageDriverSettings, present: Readonly<Record<string, boolean>>): string[];
+/**
+ * Where `driver`'s objects live for these settings ({@link StorageDriver.location}, or the `bucket` setting).
+ *
+ * @param driver - a registered driver.
+ * @param settings - its parsed settings.
+ * @stability experimental
+ */
+export declare function storageLocationOf(driver: StorageDriverDefinition<any>, settings: StorageDriverSettings): StorageDriverLocation;
+//# sourceMappingURL=storage-driver.d.ts.map

package/dist/storage/drivers/storage-driver.d.ts.map

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