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

package/dist/doctor/support-bundle/sections/meta.section.js

@@ -0,0 +1,89 @@
+"use strict";
+// The `meta` support-bundle section (issue #772): which platform packages are
+// installed, at which versions, and which sections the bundle holds. Built in;
+// registered by `DoctorModule.forRoot()`.
+//
+// NO ACTOR: the caller's id and email are audited, never written into the
+// bundle.
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaSupportBundleSection = exports.PLATFORM_PACKAGE_NAMES = void 0;
+const common_1 = require("@nestjs/common");
+const zod_1 = require("zod");
+const support_bundle_registry_1 = require("../support-bundle.registry");
+/**
+ * The platform packages whose versions the `meta` section reports, when installed.
+ *
+ * @stability experimental
+ */
+exports.PLATFORM_PACKAGE_NAMES = Object.freeze([
+    '@marinoscar/platform-contract',
+    '@marinoscar/platform-api',
+    '@marinoscar/platform-web',
+    '@marinoscar/platform-db',
+    '@marinoscar/platform-cli',
+    '@marinoscar/platform-infra',
+]);
+const metaSectionSchema = zod_1.z
+    .object({
+    platformPackages: zod_1.z
+        .record(zod_1.z.string().regex(/^@marinoscar\/platform-[a-z]+$/), zod_1.z.string().max(64))
+        .describe('Installed platform packages and their versions; a package that is not installed is absent.'),
+    sections: zod_1.z.array(zod_1.z.string()).describe('The section ids this bundle holds, in registration order.'),
+})
+    .strict();
+/** Reads `<name>/package.json`'s version, or `null` when the package is not installed. */
+function installedVersion(name) {
+    try {
+        // Every platform package exports `./package.json`.
+        const manifest = require(`${name}/package.json`);
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The built-in `meta` section: platform package versions and section ids.
+ *
+ * @stability experimental
+ */
+let MetaSupportBundleSection = class MetaSupportBundleSection {
+    registry;
+    id = 'meta';
+    label = 'Bundle metadata';
+    schema = metaSectionSchema;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    onModuleInit() {
+        this.registry.register(this);
+    }
+    async collect() {
+        const platformPackages = {};
+        for (const name of exports.PLATFORM_PACKAGE_NAMES) {
+            const version = installedVersion(name);
+            if (version !== null)
+                platformPackages[name] = version;
+        }
+        return { platformPackages, sections: this.registry.list().map((section) => section.id) };
+    }
+};
+exports.MetaSupportBundleSection = MetaSupportBundleSection;
+exports.MetaSupportBundleSection = MetaSupportBundleSection = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(support_bundle_registry_1.SupportBundleRegistry)),
+    __metadata("design:paramtypes", [support_bundle_registry_1.SupportBundleRegistry])
+], MetaSupportBundleSection);
+//# sourceMappingURL=meta.section.js.map

package/dist/doctor/support-bundle/sections/meta.section.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.section.js","sourceRoot":"","sources":["../../../../src/doctor/support-bundle/sections/meta.section.ts"],"names":[],"mappings":";AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,0CAA0C;AAC1C,EAAE;AACF,0EAA0E;AAC1E,UAAU;;;;;;;;;;;;;;;AAEV,2CAAkE;AAClE,6BAAwB;AAGxB,wEAAmE;AAEnE;;;;GAIG;AACU,QAAA,sBAAsB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACrE,+BAA+B;IAC/B,0BAA0B;IAC1B,0BAA0B;IAC1B,yBAAyB;IACzB,0BAA0B;IAC1B,4BAA4B;CAC7B,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,OAAC;KACxB,MAAM,CAAC;IACN,gBAAgB,EAAE,OAAC;SAChB,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gCAAgC,CAAC,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;SAC9E,QAAQ,CAAC,4FAA4F,CAAC;IACzG,QAAQ,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,2DAA2D,CAAC;CACpG,CAAC;KACD,MAAM,EAAE,CAAC;AASZ,0FAA0F;AAC1F,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,mDAAmD;QACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,IAAI,eAAe,CAA0B,CAAC;QAC1E,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AAEI,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;IAKyB;IAJnD,EAAE,GAAG,MAAM,CAAC;IACZ,KAAK,GAAG,iBAAiB,CAAC;IAC1B,MAAM,GAAG,iBAAiB,CAAC;IAEpC,YAA4D,QAA+B;QAA/B,aAAQ,GAAR,QAAQ,CAAuB;IAAG,CAAC;IAE/F,YAAY;QACV,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,gBAAgB,GAA2B,EAAE,CAAC;QACpD,KAAK,MAAM,IAAI,IAAI,8BAAsB,EAAE,CAAC;YAC1C,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,OAAO,KAAK,IAAI;gBAAE,gBAAgB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;QACzD,CAAC;QACD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;IAC3F,CAAC;CACF,CAAA;AAnBY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,mBAAU,GAAE;IAME,WAAA,IAAA,eAAM,EAAC,+CAAqB,CAAC,CAAA;qCAA4B,+CAAqB;GALhF,wBAAwB,CAmBpC"}

package/dist/doctor/support-bundle/support-bundle-section.interface.d.ts

@@ -0,0 +1,100 @@
+import type { ZodType } from 'zod';
+/**
+ * What a section's `collect()` receives.
+ *
+ * @stability experimental
+ */
+export interface SupportBundleSectionContext {
+    /** Who is downloading the bundle. For an audited read the section performs on their behalf; never copy it into the data. */
+    readonly actorUserId: string;
+    /** Every permission the caller holds. */
+    readonly permissions: ReadonlySet<string>;
+    /** When the bundle build started. Use it instead of `new Date()` so every section agrees. */
+    readonly now: Date;
+    /** Aborted when the section's timeout elapses. Pass it on to any I/O that accepts one. */
+    readonly signal: AbortSignal;
+}
+/**
+ * One section of the support bundle. Implement it in the module that owns the
+ * capability, inject `SupportBundleRegistry` and call
+ * `registry.register(this)` from `onModuleInit`.
+ *
+ * @typeParam T - the data the section returns, as its `schema` describes it.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export interface SupportBundleSection<T = unknown> {
+    /** Unique across the application; the key of the section in the bundle (`'doctor'`, `'versions'`, `'telemetry'`). Lowercase letters, digits, `.`, `_` and `-`. */
+    readonly id: string;
+    /** Human label, for logs and docs. */
+    readonly label: string;
+    /**
+     * A permission needed IN ADDITION to the route's own (`system_settings:read`
+     * by default). A caller without it gets `{ status: 'omitted' }` for this
+     * section.
+     */
+    readonly permission?: string;
+    /** Strict schema (`.strict()` objects): an unexpected field fails the section closed. */
+    readonly schema: ZodType<T>;
+    /** Ceiling for `collect()`, in milliseconds. Default 10_000. */
+    readonly timeoutMs?: number;
+    /**
+     * Gathers the section's data. READ-ONLY, like a doctor check: no writes, no
+     * jobs, no model calls, no "test" services. Return
+     * {@link SupportBundleOmission} (`omitSupportBundleSection(reason)`) when the
+     * capability is off and there is nothing to collect.
+     *
+     * @param ctx - the caller, the build instant and the timeout signal.
+     */
+    collect(ctx: SupportBundleSectionContext): Promise<T | SupportBundleOmission>;
+}
+declare const OMISSION: unique symbol;
+/**
+ * What `collect()` returns to say "nothing to collect" (the capability is
+ * switched off or not configured). Build it with {@link omitSupportBundleSection}.
+ *
+ * @stability experimental
+ */
+export interface SupportBundleOmission {
+    /** Brand; do not construct by hand. */
+    readonly [OMISSION]: true;
+    /** One line saying why, shown as the section's `reason`. */
+    readonly reason: string;
+}
+/**
+ * Marks a section as `omitted` from inside `collect()`.
+ *
+ * @param reason - one line saying why (`'telemetry is switched off'`).
+ * @returns the omission marker to return from `collect()`.
+ *
+ * @example
+ * ```ts
+ * if (!policy.enabled) return omitSupportBundleSection('telemetry is switched off');
+ * ```
+ *
+ * @stability experimental
+ */
+export declare function omitSupportBundleSection(reason: string): SupportBundleOmission;
+/**
+ * Whether `value` is the marker {@link omitSupportBundleSection} returns.
+ *
+ * @param value - what a section's `collect()` resolved with.
+ * @returns `true` for an omission.
+ *
+ * @stability experimental
+ */
+export declare function isSupportBundleOmission(value: unknown): value is SupportBundleOmission;
+/**
+ * Who is downloading the bundle, as the route resolves them from the request.
+ *
+ * @stability experimental
+ */
+export interface SupportBundlePrincipal {
+    /** The caller's user id. Audited; never written into the bundle. */
+    readonly userId: string;
+    /** Every permission the caller holds. */
+    readonly permissions: readonly string[];
+}
+export {};
+//# sourceMappingURL=support-bundle-section.interface.d.ts.map

package/dist/doctor/support-bundle/support-bundle-section.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-bundle-section.interface.d.ts","sourceRoot":"","sources":["../../../src/doctor/support-bundle/support-bundle-section.interface.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,4HAA4H;IAC5H,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,6FAA6F;IAC7F,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,kKAAkK;IAClK,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,OAAO,CAAC,GAAG,EAAE,2BAA2B,GAAG,OAAO,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC;CAC/E;AAED,QAAA,MAAM,QAAQ,eAAkE,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,qBAAqB,CAEtF;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC"}

package/dist/doctor/support-bundle/support-bundle-section.interface.js

@@ -0,0 +1,59 @@
+"use strict";
+// =============================================================================
+// The support-bundle section contract (issue #772, PP-13.1)
+// =============================================================================
+//
+// A SECTION is one capability's contribution to the support bundle
+// (`GET /api/admin/doctor/support-bundle`): the Doctor report, the versions,
+// a telemetry summary, an app's own facts. It mirrors a doctor check:
+//
+//   1. READ-ONLY, like a doctor check (rule 3 of `doctor-check.interface.ts`):
+//      no writes, no jobs, no model calls, no "test" services. An audited
+//      read the capability already performs (the telemetry dashboard's
+//      `telemetry:dashboard` row) is fine; a new write is not.
+//   2. ALLOWLIST, NEVER DENYLIST. `collect()` copies the fields it means to
+//      send into a new object; it never spreads a service's response. The
+//      section's `schema` is STRICT (`.strict()` objects), so a field nobody
+//      chose fails the section closed (status `error`, data dropped) instead
+//      of leaking.
+//   3. NO SECRET MATERIAL, no personal data beyond counts. A central redaction
+//      pass (`redact.ts`) runs over the whole bundle afterwards, but it is the
+//      second line of defence, not the first.
+//   4. BOUNDED. Each section runs under `timeoutMs` (default 10 s) and its
+//      serialized data is capped at 512 KiB.
+//
+// Sections self-register with `SupportBundleRegistry` from `onModuleInit`,
+// exactly as checks register with `DoctorCheckRegistry`.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.omitSupportBundleSection = omitSupportBundleSection;
+exports.isSupportBundleOmission = isSupportBundleOmission;
+const OMISSION = Symbol.for('@marinoscar/platform/doctor/SupportBundleOmission');
+/**
+ * Marks a section as `omitted` from inside `collect()`.
+ *
+ * @param reason - one line saying why (`'telemetry is switched off'`).
+ * @returns the omission marker to return from `collect()`.
+ *
+ * @example
+ * ```ts
+ * if (!policy.enabled) return omitSupportBundleSection('telemetry is switched off');
+ * ```
+ *
+ * @stability experimental
+ */
+function omitSupportBundleSection(reason) {
+    return Object.freeze({ [OMISSION]: true, reason });
+}
+/**
+ * Whether `value` is the marker {@link omitSupportBundleSection} returns.
+ *
+ * @param value - what a section's `collect()` resolved with.
+ * @returns `true` for an omission.
+ *
+ * @stability experimental
+ */
+function isSupportBundleOmission(value) {
+    return typeof value === 'object' && value !== null && value[OMISSION] === true;
+}
+//# sourceMappingURL=support-bundle-section.interface.js.map

package/dist/doctor/support-bundle/support-bundle-section.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-bundle-section.interface.js","sourceRoot":"","sources":["../../../src/doctor/support-bundle/support-bundle-section.interface.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,4DAA4D;AAC5D,gFAAgF;AAChF,EAAE;AACF,mEAAmE;AACnE,6EAA6E;AAC7E,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,uEAAuE;AACvE,+DAA+D;AAC/D,4EAA4E;AAC5E,0EAA0E;AAC1E,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AACnB,+EAA+E;AAC/E,+EAA+E;AAC/E,8CAA8C;AAC9C,2EAA2E;AAC3E,6CAA6C;AAC7C,EAAE;AACF,2EAA2E;AAC3E,yDAAyD;AACzD,gFAAgF;;AAoFhF,4DAEC;AAUD,0DAEC;AA1CD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;AAejF;;;;;;;;;;;;GAYG;AACH,SAAgB,wBAAwB,CAAC,MAAc;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAa,EAAE,MAAM,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,uBAAuB,CAAC,KAAc;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;AAC9G,CAAC"}

package/dist/doctor/support-bundle/support-bundle.controller.d.ts

@@ -0,0 +1,57 @@
+import { Type } from '@nestjs/common';
+import type { FastifyReply } from 'fastify';
+import type { ResolvedDoctorModuleOptions } from '../doctor.options';
+declare const SupportBundleDto_base: import("nestjs-zod").ZodDto<import("zod").ZodObject<{
+    bundleVersion: import("zod").ZodLiteral<1>;
+    generatedAt: import("zod").ZodString;
+    redaction: import("zod").ZodObject<{
+        rules: import("zod").ZodLiteral<"v1">;
+        replacements: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    sections: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        status: import("zod").ZodLiteral<"ok">;
+        data: import("zod").ZodUnknown;
+        truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        status: import("zod").ZodLiteral<"omitted">;
+        reason: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        status: import("zod").ZodLiteral<"error">;
+        error: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>], "status">>;
+}, import("zod/v4/core").$strip>, false>;
+/**
+ * The bundle's OpenAPI schema (from `@marinoscar/platform-contract/doctor`).
+ *
+ * @stability experimental
+ */
+export declare class SupportBundleDto extends SupportBundleDto_base {
+}
+/**
+ * The shape of the controller class {@link createSupportBundleController} returns.
+ *
+ * @stability experimental
+ */
+export interface SupportBundleControllerInstance {
+    /**
+     * `GET <path>/support-bundle`: builds the bundle and sends it as a JSON attachment.
+     *
+     * @param request - the framework request (the caller is resolved from it).
+     * @param reply - the Fastify reply the file is written to.
+     */
+    download(request: unknown, reply: FastifyReply): Promise<FastifyReply>;
+}
+/**
+ * Creates the support bundle's controller class for one set of options: the
+ * route at `<options.path>/support-bundle`, guarded by
+ * `options.host.access.requirePermissions([options.permission])`.
+ * `DoctorModule.forRoot()` calls it; an app never needs to.
+ *
+ * @param options - the resolved Doctor module options.
+ * @returns a controller class named `SupportBundleController` with a `download` handler.
+ *
+ * @stability experimental
+ */
+export declare function createSupportBundleController(options: ResolvedDoctorModuleOptions): Type<SupportBundleControllerInstance>;
+export {};
+//# sourceMappingURL=support-bundle.controller.d.ts.map

package/dist/doctor/support-bundle/support-bundle.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-bundle.controller.d.ts","sourceRoot":"","sources":["../../../src/doctor/support-bundle/support-bundle.controller.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAyD,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;;;;;;;;;;;;;;;;;;;;AAIrE;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,qBAAiC;CAAG;AAE1E;;;;GAIG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACxE;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,2BAA2B,GAAG,IAAI,CAAC,+BAA+B,CAAC,CA+CzH"}

package/dist/doctor/support-bundle/support-bundle.controller.js

@@ -0,0 +1,141 @@
+"use strict";
+// =============================================================================
+// GET /api/admin/doctor/support-bundle, created per app (issue #772, PP-13.1)
+// =============================================================================
+//
+// The controller-factory recipe (core README, "Host ports"), as the Doctor's
+// own controller: the class is defined inside a function
+// `DoctorModule.forRoot()` calls, with the access decorator the app's host
+// supplies, so the route gets exactly the app's `@Auth()`.
+//
+// A SIBLING of `DoctorController`, not a new handler on it, so the Doctor's
+// own OpenAPI operation (`doctor_getReport`) stays word for word what it was.
+// Same path prefix, same permission (`system_settings:read` by default): the
+// bundle describes the deployment's configuration and health, exactly what
+// that permission covers, and no new permission is invented. A section that
+// needs more (telemetry needs `telemetry:query`) declares it and is `omitted`
+// for a caller without it.
+//
+// The body is the FILE, not the `{ data, meta }` envelope: the handler writes
+// the reply itself (`@Res()`), like the telemetry export.
+//
+// Not `@AllowDuringMaintenance()`, the same as the Doctor route: the doctor
+// section performs network I/O through the checks.
+// =============================================================================
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupportBundleDto = void 0;
+exports.createSupportBundleController = createSupportBundleController;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const nestjs_zod_1 = require("nestjs-zod");
+const doctor_1 = require("@marinoscar/platform-contract/doctor");
+const support_bundle_options_1 = require("./support-bundle.options");
+const support_bundle_service_1 = require("./support-bundle.service");
+/**
+ * The bundle's OpenAPI schema (from `@marinoscar/platform-contract/doctor`).
+ *
+ * @stability experimental
+ */
+class SupportBundleDto extends (0, nestjs_zod_1.createZodDto)(doctor_1.supportBundleSchema) {
+}
+exports.SupportBundleDto = SupportBundleDto;
+function describeOperation(options) {
+    return ('Builds one JSON file for a support ticket: the doctor report, the deployment versions, ' +
+        'a 24-hour telemetry summary and every section the application registers, each validated ' +
+        'by its own strict schema and then passed through a central redaction pass that removes ' +
+        'secrets and personal data (rules `v1`; `redaction.replacements` counts what it replaced). ' +
+        'Raw logs, traces and query results are never included.\n\n' +
+        '**Returned as an attachment** (`Content-Disposition: attachment; filename="support-bundle-' +
+        `${options.supportBundle.appSlug}-<yyyyMMdd'T'HHmmss'Z'>.json"\`), not in the \`{ data }\` envelope.\n\n` +
+        '**Per-section outcome.** `ok` (collected), `omitted` (a section-specific permission is missing — ' +
+        'the telemetry section needs `telemetry:query` — or the capability is off) or `error` (the section ' +
+        'threw, timed out or broke its schema; its data is dropped). The rest of the bundle is always intact.\n\n' +
+        `**Bounded.** Sections run in parallel, each cut off after ${options.supportBundle.sectionTimeoutMs} ms ` +
+        `unless it declares otherwise; ${support_bundle_options_1.SUPPORT_BUNDLE_SECTION_MAX_BYTES} bytes per section and ` +
+        `${support_bundle_options_1.SUPPORT_BUNDLE_MAX_BYTES} bytes per bundle (larger sections are truncated). The doctor report is ` +
+        'served from its cache, so a download never multiplies probes.\n\n' +
+        'Audited as `support_bundle:download`. ' +
+        `Requires \`${options.permission}\`.`);
+}
+/**
+ * Creates the support bundle's controller class for one set of options: the
+ * route at `<options.path>/support-bundle`, guarded by
+ * `options.host.access.requirePermissions([options.permission])`.
+ * `DoctorModule.forRoot()` calls it; an app never needs to.
+ *
+ * @param options - the resolved Doctor module options.
+ * @returns a controller class named `SupportBundleController` with a `download` handler.
+ *
+ * @stability experimental
+ */
+function createSupportBundleController(options) {
+    const requireAccess = options.host.access.requirePermissions([options.permission]);
+    let SupportBundleController = class SupportBundleController {
+        bundles;
+        constructor(bundles) {
+            this.bundles = bundles;
+        }
+        async download(request, reply) {
+            const actor = options.supportBundle.principal(request);
+            if (!actor)
+                throw new common_1.ForbiddenException('The caller could not be identified.');
+            const built = await this.bundles.download(actor);
+            return reply
+                .status(200)
+                .header('Content-Type', 'application/json; charset=utf-8')
+                .header('Content-Disposition', `attachment; filename="${built.filename}"`)
+                .header('Content-Length', String(built.body.length))
+                .header('Cache-Control', 'no-store')
+                .header('X-Content-Type-Options', 'nosniff')
+                .send(built.body);
+        }
+    };
+    __decorate([
+        (0, common_1.Get)(support_bundle_options_1.SUPPORT_BUNDLE_SUBPATH),
+        requireAccess,
+        (0, swagger_1.ApiOperation)({
+            summary: 'Download a redacted support bundle (Admin only)',
+            description: describeOperation(options),
+        }),
+        (0, swagger_1.ApiProduces)('application/json'),
+        (0, swagger_1.ApiResponse)({
+            status: 200,
+            description: 'The support bundle, as a JSON attachment.',
+            type: SupportBundleDto,
+            headers: {
+                'Content-Disposition': {
+                    description: "`attachment; filename=\"support-bundle-<slug>-<yyyyMMdd'T'HHmmss'Z'>.json\"`",
+                    schema: { type: 'string' },
+                },
+                'Cache-Control': { description: '`no-store`', schema: { type: 'string' } },
+            },
+        }),
+        (0, swagger_1.ApiResponse)({ status: 401, description: 'Not signed in' }),
+        (0, swagger_1.ApiResponse)({ status: 403, description: `Missing \`${options.permission}\`` }),
+        __param(0, (0, common_1.Req)()),
+        __param(1, (0, common_1.Res)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object, Object]),
+        __metadata("design:returntype", Promise)
+    ], SupportBundleController.prototype, "download", null);
+    SupportBundleController = __decorate([
+        (0, swagger_1.ApiTags)('Doctor'),
+        (0, common_1.Controller)(options.path),
+        __param(0, (0, common_1.Inject)(support_bundle_service_1.SupportBundleService)),
+        __metadata("design:paramtypes", [support_bundle_service_1.SupportBundleService])
+    ], SupportBundleController);
+    return SupportBundleController;
+}
+//# sourceMappingURL=support-bundle.controller.js.map

package/dist/doctor/support-bundle/support-bundle.controller.js.map

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

package/dist/doctor/support-bundle/support-bundle.options.d.ts

@@ -0,0 +1,92 @@
+import type { SupportBundlePrincipal } from './support-bundle-section.interface';
+/**
+ * Ceiling for one section's `collect()` when it declares no `timeoutMs`, in
+ * milliseconds.
+ *
+ * @stability experimental
+ */
+export declare const SUPPORT_BUNDLE_SECTION_TIMEOUT_MS = 10000;
+/**
+ * A section whose serialized data is larger than this many bytes is replaced
+ * by `{ status: 'ok', data: null, truncated: true }`.
+ *
+ * @stability experimental
+ */
+export declare const SUPPORT_BUNDLE_SECTION_MAX_BYTES: number;
+/**
+ * The whole bundle's ceiling, in bytes of pretty-printed JSON. Above it the
+ * largest sections are truncated first until it fits.
+ *
+ * @stability experimental
+ */
+export declare const SUPPORT_BUNDLE_MAX_BYTES: number;
+/**
+ * The route path under the Doctor's own path (`admin/doctor/support-bundle`).
+ *
+ * @stability experimental
+ */
+export declare const SUPPORT_BUNDLE_SUBPATH = "support-bundle";
+/**
+ * The audit action of one download.
+ *
+ * @stability experimental
+ */
+export declare const SUPPORT_BUNDLE_AUDIT_ACTION = "support_bundle:download";
+/**
+ * What an app passes as `DoctorModuleOptions.supportBundle`.
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export interface SupportBundleOptions {
+    /**
+     * The app's slug, used in the download's filename
+     * (`support-bundle-<appSlug>-<yyyyMMdd'T'HHmmss'Z'>.json`). Lowercase
+     * letters, digits and dashes. Default `'app'`.
+     */
+    appSlug?: string;
+    /**
+     * Resolves the signed-in caller from the request, after the route's access
+     * check has passed. Default: `request.requestUser`, then `request.user`,
+     * when either has a string `id` and a string-array `permissions`. Returning
+     * `null` refuses the download with 403.
+     */
+    principal?: (request: unknown) => SupportBundlePrincipal | null;
+    /** Per-section ceiling when a section declares none, in milliseconds. Default {@link SUPPORT_BUNDLE_SECTION_TIMEOUT_MS}. */
+    sectionTimeoutMs?: number;
+}
+/**
+ * `SupportBundleOptions` with every default applied.
+ *
+ * @stability experimental
+ */
+export interface ResolvedSupportBundleOptions {
+    /** `false` when the app passed `supportBundle: false`: no route, no built-in sections. */
+    readonly enabled: boolean;
+    /** The slug in the download's filename. */
+    readonly appSlug: string;
+    /** Resolves the caller from the request. */
+    readonly principal: (request: unknown) => SupportBundlePrincipal | null;
+    /** Per-section ceiling when a section declares none, in milliseconds. */
+    readonly sectionTimeoutMs: number;
+}
+/**
+ * The default {@link SupportBundleOptions.principal}: `request.requestUser`,
+ * then `request.user`, when either carries a string `id` and a string-array
+ * `permissions` (the reference app's `RequestUser`).
+ *
+ * @param request - the framework request.
+ * @returns the caller, or `null` when neither property has that shape.
+ *
+ * @stability experimental
+ */
+export declare function defaultSupportBundlePrincipal(request: unknown): SupportBundlePrincipal | null;
+/**
+ * Validates `supportBundle` and applies its defaults.
+ *
+ * @param options - what the app passed (`undefined`, `false` or an object).
+ * @param fail - throws the module's own error.
+ * @returns the resolved, frozen options.
+ */
+export declare function resolveSupportBundleOptions(options: SupportBundleOptions | false | undefined, fail: (why: string) => never): ResolvedSupportBundleOptions;
+//# sourceMappingURL=support-bundle.options.d.ts.map

package/dist/doctor/support-bundle/support-bundle.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-bundle.options.d.ts","sourceRoot":"","sources":["../../../src/doctor/support-bundle/support-bundle.options.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAEjF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,QAAa,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAkB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,sBAAsB,GAAG,IAAI,CAAC;IAChE,4HAA4H;IAC5H,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,sBAAsB,GAAG,IAAI,CAAC;IACxE,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAMD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAS7F;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,GAAG,KAAK,GAAG,SAAS,EACjD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,KAAK,GAC3B,4BAA4B,CAuB9B"}