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

package/dist/core/data-access/user-owned-data.registry.js

@@ -0,0 +1,140 @@
+"use strict";
+// =============================================================================
+// User-owned data registry (issue #688 PP-1.9, moved to core by #699)
+// =============================================================================
+//
+// Every Prisma model holding a foreign key to `User` is registered here, with
+// the role of each such key (OWNER: the row belongs to the user; ACTOR: the
+// row only names a user who acted), what happens to the row when the user's
+// data is purged, and whether the user's data export includes it.
+//
+// Two things read it:
+//
+//   - the `userOwnedData` conformance suite (`@marinoscar/platform-api/testing`):
+//     fails when a model gains a `User` relation without an entry, when an
+//     entry names a model or field that does not exist, or when a purge policy
+//     contradicts the relation's `onDelete`;
+//   - the scoped client (./scoped-client.ts): confines a scoped client's
+//     queries on a registered owner model to the scope's user, and refuses
+//     every other model.
+//
+// ⚠ FRAMEWORK-FREE ON PURPOSE, like the registry primitive: seeds and
+// standalone scripts may read it without a Nest container. The app fills it
+// from one manifest (platform entries, then its own); a packaged slice
+// registers its own models when it is extracted.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userOwnedModelRegistry = void 0;
+exports.registerUserOwnedModels = registerUserOwnedModels;
+exports.ownerFieldOf = ownerFieldOf;
+exports.ownerRelationOf = ownerRelationOf;
+const registry_1 = require("../registry/registry");
+function validate(def) {
+    const actors = def.actorFields ?? [];
+    if (def.ownerField === undefined && actors.length === 0) {
+        throw new Error('declare an ownerField, actorFields, or both');
+    }
+    if (def.ownerField !== undefined && def.ownerField.trim() === '') {
+        throw new Error('ownerField must not be empty');
+    }
+    if (actors.some((field) => typeof field !== 'string' || field.trim() === '')) {
+        throw new Error('actorFields must be non-empty strings');
+    }
+    if (new Set(actors).size !== actors.length) {
+        throw new Error('actorFields must not repeat a field');
+    }
+    if (def.ownerField !== undefined && actors.includes(def.ownerField)) {
+        throw new Error(`"${def.ownerField}" cannot be both the ownerField and an actor field`);
+    }
+    if (def.ownerRelation !== undefined && def.ownerField === undefined) {
+        throw new Error('ownerRelation requires an ownerField');
+    }
+    if (!['delete', 'detach', 'retain'].includes(def.purge)) {
+        throw new Error(`purge must be 'delete', 'detach' or 'retain', not ${JSON.stringify(def.purge)}`);
+    }
+    if (def.purge === 'retain' && def.ownerField !== undefined) {
+        throw new Error("purge 'retain' is only for actor-only models: a user's own rows are deleted or detached");
+    }
+    if (!['include', 'exclude'].includes(def.export)) {
+        throw new Error(`export must be 'include' or 'exclude', not ${JSON.stringify(def.export)}`);
+    }
+    if (def.exportOmit !== undefined && def.export === 'exclude' && def.exportOmit.length > 0) {
+        throw new Error("exportOmit is meaningless when export is 'exclude'");
+    }
+    if (typeof def.rationale !== 'string' || def.rationale.trim() === '') {
+        throw new Error('rationale is required');
+    }
+}
+/**
+ * The static registry of models holding a foreign key to `User`, keyed by
+ * model name. One per process: the app fills it from a manifest imported
+ * before bootstrap, and `RegistryFreezeService` freezes it with every other
+ * `defineRegistry` registry.
+ *
+ * @stability experimental
+ * @extensionPoint registry
+ * @example
+ * ```ts
+ * // apps/api/src/prisma/ownership/user-owned-model.manifest.ts
+ * registerUserOwnedModels(PLATFORM_USER_OWNED_MODELS);
+ * registerUserOwnedModels(APP_USER_OWNED_MODELS);
+ *
+ * userOwnedModelRegistry.get('UserCredential')?.ownerField; // 'userId'
+ * ```
+ */
+exports.userOwnedModelRegistry = (0, registry_1.defineRegistry)({
+    name: 'user-owned-models',
+    idOf: (def) => def.model,
+    // A Prisma model name: PascalCase identifier.
+    idPattern: /^[A-Z][A-Za-z0-9_]*$/,
+    validate,
+});
+/**
+ * Registers a batch of definitions in {@link userOwnedModelRegistry}, all or
+ * nothing.
+ *
+ * @param defs - the definitions; an app may type them with its own model names.
+ * @throws RegistryError `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * registerUserOwnedModels([
+ *   { model: 'Workout', ownerField: 'userId', purge: 'delete', export: 'include', rationale: "The user's own log." },
+ * ]);
+ * ```
+ */
+function registerUserOwnedModels(defs) {
+    exports.userOwnedModelRegistry.registerAll(defs);
+}
+/**
+ * The owner field of a registered model, or `undefined` (actor-only or
+ * unregistered).
+ *
+ * @param model - the Prisma model name.
+ * @stability experimental
+ * @example
+ * ```ts
+ * ownerFieldOf('StorageObject'); // 'uploadedById'
+ * ```
+ */
+function ownerFieldOf(model) {
+    return exports.userOwnedModelRegistry.get(model)?.ownerField;
+}
+/**
+ * The relation field backing a definition's owner field: `ownerRelation`
+ * when given, otherwise the owner field without its trailing `Id`.
+ *
+ * @param def - a registered (or candidate) definition.
+ * @stability experimental
+ * @example
+ * ```ts
+ * ownerRelationOf({ model: 'WorkerNode', ownerField: 'createdById', purge: 'delete', export: 'exclude', rationale: 'x' }); // 'createdBy'
+ * ```
+ */
+function ownerRelationOf(def) {
+    if (def.ownerField === undefined)
+        return undefined;
+    return def.ownerRelation ?? def.ownerField.replace(/Id$/, '');
+}
+//# sourceMappingURL=user-owned-data.registry.js.map

package/dist/core/data-access/user-owned-data.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-owned-data.registry.js","sourceRoot":"","sources":["../../../src/core/data-access/user-owned-data.registry.ts"],"names":[],"mappings":"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"}

package/dist/core/errors/database-seed.exception.d.ts

@@ -0,0 +1,23 @@
+import { InternalServerErrorException } from '@nestjs/common';
+/**
+ * Exception thrown when required database seed data is missing.
+ * This indicates the database migrations have been run but seeds have not.
+ *
+ * A 500 whose envelope `details` carries `missingData`, `seedCommand` and
+ * operator `instructions`; the response `code` is `INTERNAL_ERROR` like any
+ * other 500 (see {@link HttpExceptionFilter}).
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * if (!defaultRole) throw new DatabaseSeedException('default role "Viewer"');
+ * ```
+ */
+export declare class DatabaseSeedException extends InternalServerErrorException {
+    /**
+     * @param missingData - What is missing, for the message and `details.missingData`.
+     * @param seedCommand - The command that seeds it; defaults to `npm run prisma:seed`.
+     */
+    constructor(missingData: string, seedCommand?: string);
+}
+//# sourceMappingURL=database-seed.exception.d.ts.map

package/dist/core/errors/database-seed.exception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-seed.exception.d.ts","sourceRoot":"","sources":["../../../src/core/errors/database-seed.exception.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,SAAQ,4BAA4B;IACrE;;;OAGG;gBACS,WAAW,EAAE,MAAM,EAAE,WAAW,SAAwB;CAuBrE"}

package/dist/core/errors/database-seed.exception.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseSeedException = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Exception thrown when required database seed data is missing.
+ * This indicates the database migrations have been run but seeds have not.
+ *
+ * A 500 whose envelope `details` carries `missingData`, `seedCommand` and
+ * operator `instructions`; the response `code` is `INTERNAL_ERROR` like any
+ * other 500 (see {@link HttpExceptionFilter}).
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * if (!defaultRole) throw new DatabaseSeedException('default role "Viewer"');
+ * ```
+ */
+class DatabaseSeedException extends common_1.InternalServerErrorException {
+    /**
+     * @param missingData - What is missing, for the message and `details.missingData`.
+     * @param seedCommand - The command that seeds it; defaults to `npm run prisma:seed`.
+     */
+    constructor(missingData, seedCommand = 'npm run prisma:seed') {
+        const message = `Database seed data missing: ${missingData}. Please run: ${seedCommand}`;
+        super({
+            // NOT on the wire. `HttpExceptionFilter` always derives the response's
+            // `code` from the HTTP status (500 -> INTERNAL_ERROR) and ignores any
+            // `code` on the payload — that is the published contract in
+            // `./error.dto.ts`, whose `code` is a closed enum of the
+            // status-derived values. Kept here as the internal name for this failure,
+            // which is what the log line and `details.missingData` identify it by.
+            // Do not add a client that branches on seeing it in a response (#153).
+            code: 'DATABASE_SEED_REQUIRED',
+            message,
+            details: {
+                missingData,
+                seedCommand,
+                instructions: [
+                    'Database migrations have been run but seed data is missing',
+                    `Run the following command: ${seedCommand}`,
+                    'This will populate required data like roles and permissions',
+                ],
+            },
+        });
+    }
+}
+exports.DatabaseSeedException = DatabaseSeedException;
+//# sourceMappingURL=database-seed.exception.js.map

package/dist/core/errors/database-seed.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-seed.exception.js","sourceRoot":"","sources":["../../../src/core/errors/database-seed.exception.ts"],"names":[],"mappings":";;;AAAA,2CAA8D;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAa,qBAAsB,SAAQ,qCAA4B;IACrE;;;OAGG;IACH,YAAY,WAAmB,EAAE,WAAW,GAAG,qBAAqB;QAClE,MAAM,OAAO,GAAG,+BAA+B,WAAW,iBAAiB,WAAW,EAAE,CAAC;QACzF,KAAK,CAAC;YACJ,uEAAuE;YACvE,sEAAsE;YACtE,4DAA4D;YAC5D,yDAAyD;YACzD,0EAA0E;YAC1E,uEAAuE;YACvE,uEAAuE;YACvE,IAAI,EAAE,wBAAwB;YAC9B,OAAO;YACP,OAAO,EAAE;gBACP,WAAW;gBACX,WAAW;gBACX,YAAY,EAAE;oBACZ,4DAA4D;oBAC5D,8BAA8B,WAAW,EAAE;oBAC3C,6DAA6D;iBAC9D;aACF;SACF,CAAC,CAAC;IACL,CAAC;CACF;AA5BD,sDA4BC"}

package/dist/core/errors/error.dto.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The error body this API returns for every endpoint but one.
+ *
+ * `HttpExceptionFilter` rebuilds error responses from a fixed key allowlist —
+ * `statusCode`, `code`, `message`, `details`, `timestamp`, `path` and nothing
+ * else — so this class is not an approximation of the wire format, it is the
+ * complete set of keys that can appear. In particular a custom top-level field
+ * on a thrown `HttpException` payload is silently dropped; endpoint-specific
+ * data belongs under {@link details}.
+ *
+ * THE ONE EXCEPTION (#153): an endpoint whose error body is fixed by an
+ * external standard can opt out of this envelope entirely, by branding its
+ * exception with `withVerbatimErrorBody`
+ * (`./verbatim-error-body.exception.ts`). Its body is then sent
+ * exactly as thrown, with none of the keys below. Today the only user is
+ * `POST /auth/device/token`, which RFC 8628 §3.5 requires to answer with
+ * `{ error, error_description }` — see `DeviceTokenErrorDto`, which the
+ * operation declares for its 400 and 401 responses. That opt-out is deliberately
+ * hard to reach and rare; assume this envelope unless an operation documents
+ * otherwise.
+ *
+ * Kept as an `@ApiProperty` class rather than a zod DTO because nothing
+ * validates it — it is documentation-only, produced by the filter and never
+ * parsed on the way in. The OpenAPI schema name is `ErrorDto`; it is
+ * published, so the class name does not change.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * @ApiResponse({ status: 409, description: 'Already exists', type: ErrorDto })
+ * ```
+ */
+export declare class ErrorDto {
+    /** HTTP status code, repeated in the body. */
+    statusCode: number;
+    /** Status-derived machine-readable code (closed enum, see the property's `@ApiProperty`). */
+    code: string;
+    /** Human-readable description of what went wrong. */
+    message: string;
+    /** Endpoint-specific structured data, when the failure carried any. */
+    details?: unknown;
+    /** When the error was produced, ISO 8601 UTC. */
+    timestamp: string;
+    /** Request path that produced the error. */
+    path: string;
+}
+//# sourceMappingURL=error.dto.d.ts.map

package/dist/core/errors/error.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.dto.d.ts","sourceRoot":"","sources":["../../../src/core/errors/error.dto.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,QAAQ;IACnB,8CAA8C;IAK9C,UAAU,EAAG,MAAM,CAAC;IAEpB,6FAA6F;IAsB7F,IAAI,EAAG,MAAM,CAAC;IAEd,qDAAqD;IAKrD,OAAO,EAAG,MAAM,CAAC;IAEjB,uEAAuE;IAQvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,iDAAiD;IAKjD,SAAS,EAAG,MAAM,CAAC;IAEnB,4CAA4C;IAK5C,IAAI,EAAG,MAAM,CAAC;CACf"}

package/dist/core/errors/error.dto.js

@@ -0,0 +1,121 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorDto = void 0;
+const swagger_1 = require("@nestjs/swagger");
+/**
+ * The error body this API returns for every endpoint but one.
+ *
+ * `HttpExceptionFilter` rebuilds error responses from a fixed key allowlist —
+ * `statusCode`, `code`, `message`, `details`, `timestamp`, `path` and nothing
+ * else — so this class is not an approximation of the wire format, it is the
+ * complete set of keys that can appear. In particular a custom top-level field
+ * on a thrown `HttpException` payload is silently dropped; endpoint-specific
+ * data belongs under {@link details}.
+ *
+ * THE ONE EXCEPTION (#153): an endpoint whose error body is fixed by an
+ * external standard can opt out of this envelope entirely, by branding its
+ * exception with `withVerbatimErrorBody`
+ * (`./verbatim-error-body.exception.ts`). Its body is then sent
+ * exactly as thrown, with none of the keys below. Today the only user is
+ * `POST /auth/device/token`, which RFC 8628 §3.5 requires to answer with
+ * `{ error, error_description }` — see `DeviceTokenErrorDto`, which the
+ * operation declares for its 400 and 401 responses. That opt-out is deliberately
+ * hard to reach and rare; assume this envelope unless an operation documents
+ * otherwise.
+ *
+ * Kept as an `@ApiProperty` class rather than a zod DTO because nothing
+ * validates it — it is documentation-only, produced by the filter and never
+ * parsed on the way in. The OpenAPI schema name is `ErrorDto`; it is
+ * published, so the class name does not change.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * @ApiResponse({ status: 409, description: 'Already exists', type: ErrorDto })
+ * ```
+ */
+class ErrorDto {
+    /** HTTP status code, repeated in the body. */
+    statusCode;
+    /** Status-derived machine-readable code (closed enum, see the property's `@ApiProperty`). */
+    code;
+    /** Human-readable description of what went wrong. */
+    message;
+    /** Endpoint-specific structured data, when the failure carried any. */
+    details;
+    /** When the error was produced, ISO 8601 UTC. */
+    timestamp;
+    /** Request path that produced the error. */
+    path;
+}
+exports.ErrorDto = ErrorDto;
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'HTTP status code, repeated in the body so a logged payload is self-describing.',
+        example: 409,
+    }),
+    __metadata("design:type", Number)
+], ErrorDto.prototype, "statusCode", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Stable machine-readable code. Derived from the status by the exception filter, which ' +
+            'overwrites any `code` a thrown exception supplied — so it is always one of the values ' +
+            'below. Prefer branching on this over matching `message`, which is prose and may change.',
+        example: 'CONFLICT',
+        // Mirrors `HttpExceptionFilter.getCodeFromStatus`: the mapped statuses,
+        // plus the `ERROR` fallback an unmapped status produces.
+        enum: [
+            'BAD_REQUEST',
+            'UNAUTHORIZED',
+            'FORBIDDEN',
+            'NOT_FOUND',
+            'CONFLICT',
+            'PRECONDITION_FAILED',
+            'UNPROCESSABLE_ENTITY',
+            'TOO_MANY_REQUESTS',
+            'INTERNAL_ERROR',
+            'ERROR',
+        ],
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "code", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Human-readable description of what went wrong.',
+        example: 'Email already in allowlist',
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "message", void 0);
+__decorate([
+    (0, swagger_1.ApiPropertyOptional)({
+        description: 'Endpoint-specific structured data — the only place a custom field survives the exception ' +
+            'filter. Omitted when the failure carried none. Shape varies by endpoint and is documented ' +
+            'on the operation that returns it.',
+        example: { field: 'email' },
+    }),
+    __metadata("design:type", Object)
+], ErrorDto.prototype, "details", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'When the error was produced, ISO 8601 UTC.',
+        example: '2026-08-17T04:37:58.000Z',
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "timestamp", void 0);
+__decorate([
+    (0, swagger_1.ApiProperty)({
+        description: 'Request path that produced the error.',
+        example: '/api/allowlist',
+    }),
+    __metadata("design:type", String)
+], ErrorDto.prototype, "path", void 0);
+//# sourceMappingURL=error.dto.js.map

package/dist/core/errors/error.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.dto.js","sourceRoot":"","sources":["../../../src/core/errors/error.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,6CAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,QAAQ;IACnB,8CAA8C;IAK9C,UAAU,CAAU;IAEpB,6FAA6F;IAsB7F,IAAI,CAAU;IAEd,qDAAqD;IAKrD,OAAO,CAAU;IAEjB,uEAAuE;IAQvE,OAAO,CAAW;IAElB,iDAAiD;IAKjD,SAAS,CAAU;IAEnB,4CAA4C;IAK5C,IAAI,CAAU;CACf;AA9DD,4BA8DC;AAxDC;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,gFAAgF;QAC7F,OAAO,EAAE,GAAG;KACb,CAAC;;4CACkB;AAwBpB;IArBC,IAAA,qBAAW,EAAC;QACX,WAAW,EACT,uFAAuF;YACvF,wFAAwF;YACxF,yFAAyF;QAC3F,OAAO,EAAE,UAAU;QACnB,wEAAwE;QACxE,yDAAyD;QACzD,IAAI,EAAE;YACJ,aAAa;YACb,cAAc;YACd,WAAW;YACX,WAAW;YACX,UAAU;YACV,qBAAqB;YACrB,sBAAsB;YACtB,mBAAmB;YACnB,gBAAgB;YAChB,OAAO;SACR;KACF,CAAC;;sCACY;AAOd;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,gDAAgD;QAC7D,OAAO,EAAE,4BAA4B;KACtC,CAAC;;yCACe;AAUjB;IAPC,IAAA,6BAAmB,EAAC;QACnB,WAAW,EACT,2FAA2F;YAC3F,4FAA4F;YAC5F,mCAAmC;QACrC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;KAC5B,CAAC;;yCACgB;AAOlB;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,4CAA4C;QACzD,OAAO,EAAE,0BAA0B;KACpC,CAAC;;2CACiB;AAOnB;IAJC,IAAA,qBAAW,EAAC;QACX,WAAW,EAAE,uCAAuC;QACpD,OAAO,EAAE,gBAAgB;KAC1B,CAAC;;sCACY"}

package/dist/core/errors/http-exception.filter.d.ts

@@ -0,0 +1,63 @@
+import { ExceptionFilter, ArgumentsHost } from '@nestjs/common';
+/**
+ * The application-wide exception filter: turns every thrown value into the one
+ * error envelope (`{ statusCode, code, message, details?, timestamp, path }`,
+ * documented by {@link ErrorDto}) on a Fastify reply, and logs one line per
+ * failure (`warn` below 500, `error` with the stack from 500 up).
+ *
+ * `code` is always derived from the HTTP status; a `code` on the thrown
+ * payload is ignored. `details` is the only place endpoint-specific data
+ * survives. An exception branded with {@link withVerbatimErrorBody} skips the
+ * envelope and is sent exactly as thrown. A 429 whose `details.retryAfterMs`
+ * is a positive number also gets a `Retry-After` header (whole seconds,
+ * rounded up). A `ZodValidationException` without explicit details answers
+ * `details.issues` (`[{ path, message }]`), never the submitted value. A
+ * non-`HttpException` error is a 500 whose `details` carries the stack unless
+ * `NODE_ENV` is `production`.
+ *
+ * Register it once, as an `APP_FILTER` provider of the root module. There is
+ * no module to import and nothing to configure.
+ *
+ * @stability stable
+ * @extensionPoint component
+ * @example
+ * ```ts
+ * import { APP_FILTER } from '@nestjs/core';
+ * import { HttpExceptionFilter } from '@marinoscar/platform-api/core';
+ *
+ * @Module({ providers: [{ provide: APP_FILTER, useClass: HttpExceptionFilter }] })
+ * export class AppModule {}
+ * ```
+ */
+export declare class HttpExceptionFilter implements ExceptionFilter {
+    private readonly logger;
+    /**
+     * Nest's `ExceptionFilter` hook: write the error response for `exception`
+     * on the HTTP reply of `host`. Called by Nest, not by application code.
+     *
+     * @param exception - Whatever was thrown.
+     * @param host - The Nest arguments host of the failed request (HTTP only).
+     */
+    catch(exception: unknown, host: ArgumentsHost): void;
+    /**
+     * One log line per handled failure, identical for enveloped and verbatim
+     * responses. Extracted so the verbatim early-return above cannot silently
+     * skip logging — a device-flow `slow_down` storm has to be visible in the
+     * logs like any other 4xx.
+     */
+    private logOutcome;
+    /**
+     * A short log-only description of a verbatim body.
+     *
+     * Reading `error` here is for the LOG LINE ONLY and shapes nothing — an RFC
+     * body's `error` is the single most useful thing to see in operations
+     * (`slow_down` and `access_denied` mean very different things at 3am), and
+     * without it every device-flow failure logs as an indistinguishable 400. The
+     * body itself is never stringified into the log: a verbatim payload is
+     * whatever the spec says it is, and this filter should not assume the rest of
+     * it is safe to print.
+     */
+    private summarize;
+    private getCodeFromStatus;
+}
+//# sourceMappingURL=http-exception.filter.d.ts.map

package/dist/core/errors/http-exception.filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-exception.filter.d.ts","sourceRoot":"","sources":["../../../src/core/errors/http-exception.filter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EAEf,aAAa,EAId,MAAM,gBAAgB,CAAC;AAaxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBACa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAE/D;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa;IAmI7C;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAkBlB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,iBAAiB;CAe1B"}