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

package/dist/core/data-access/rls.js

@@ -0,0 +1,357 @@
+"use strict";
+// =============================================================================
+// Row-level security: the contract constants and the two client shapes
+// (ADR 0002 D5, issue #725 PP-6.5)
+// =============================================================================
+//
+// The database enforces organisation isolation: every org-owned table has a
+// policy keyed on three TRANSACTION-LOCAL settings, and these functions are the
+// only code that sets them. The policy text lives in the platform-db migration;
+// this file is the other half of that contract.
+//
+//   app.org_id      the active organisation's UUID   (every scoped operation)
+//   app.user_id     the acting user's UUID, or ''    (every scoped operation)
+//   app.rls_bypass  'on'                             (the SYSTEM client only)
+//
+// ⚠ NEVER A SESSION-LEVEL SETTING. Every value is written with
+// `set_config(name, value, true)` (the third argument is `is_local`) inside a
+// transaction, so it disappears at COMMIT or ROLLBACK. A session-level value
+// leaks to the next request on a pooled connection, and it leaks harder behind
+// a transaction-mode pooler (PgBouncer, RDS Proxy) that hands the next statement
+// of one client to another server connection. The ADR's negative control
+// reproduced 600 cross-org rows with a pool of one.
+//
+// Two shapes, each in a per-operation and an interactive form:
+//
+//   forOrg / orgScopeExtension / forScope
+//       A Prisma client extension: every operation becomes
+//       `$transaction([ set_config(...), operation ])` on ONE connection.
+//       Covers every model operation AND `$queryRaw` / `$executeRaw`.
+//   runInOrg / runInScope
+//       One interactive transaction: set_config first, then `fn(tx)` where `tx`
+//       is the UNEXTENDED transaction client. Use it for any unit of work of
+//       more than one statement.
+//
+//   forSystem / systemScopeExtension / runAsSystem
+//       The same two forms for the bypass flag. They belong on a SEPARATE
+//       PrismaClient with its own pool (the app's `PrismaSystemService`).
+//
+// ⚠ Never use an extended client inside `$transaction(async tx => ...)`: its
+// operations open their own transaction and ESCAPE the outer one (a create
+// followed by a throw leaves the row committed). That is why `runInOrg` hands
+// out the plain `tx`. The extension refuses to run inside an interactive
+// transaction when Prisma tells it so (see `insideInteractiveTransaction`).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_ACCESS_REASONS = exports.RLS_SETTINGS = void 0;
+exports.orgScopeExtension = orgScopeExtension;
+exports.systemScopeExtension = systemScopeExtension;
+exports.forOrg = forOrg;
+exports.forScope = forScope;
+exports.forSystem = forSystem;
+exports.runInOrg = runInOrg;
+exports.runInScope = runInScope;
+exports.runAsSystem = runAsSystem;
+const api_1 = require("@opentelemetry/api");
+const extension_1 = require("@prisma/client/extension");
+const access_reason_registry_1 = require("./access-reason.registry");
+const scoped_access_error_1 = require("./scoped-access.error");
+/**
+ * The transaction-local settings the row-level-security policies read.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * // current_setting(RLS_SETTINGS.orgId, true) inside a policy
+ * ```
+ */
+exports.RLS_SETTINGS = Object.freeze({
+    /** The active organisation's UUID. */
+    orgId: 'app.org_id',
+    /** The acting user's UUID, or the empty string. Reserved for owner-based policies. */
+    userId: 'app.user_id',
+    /** `'on'` lets a transaction see every organisation. Set only by the system client. */
+    bypass: 'app.rls_bypass',
+});
+/**
+ * The platform's own access reasons, for validation and tests.
+ *
+ * @deprecated Use {@link BUILTIN_SYSTEM_ACCESS_REASONS}; this list does not include the reasons an app registered. Read `systemAccessReasonRegistry.ids()` for those.
+ * @stability experimental
+ */
+exports.SYSTEM_ACCESS_REASONS = access_reason_registry_1.BUILTIN_SYSTEM_ACCESS_REASONS;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Throws unless `value` is a UUID. The ids reach `set_config` as bound
+ * parameters, never as SQL text, but the policy casts `app.org_id` to `uuid`,
+ * so a malformed value would otherwise surface as an opaque cast error on the
+ * first query.
+ */
+function assertUuid(value, what) {
+    if (typeof value !== 'string' || !UUID.test(value)) {
+        throw new scoped_access_error_1.ScopedAccessError(`${what} must be a UUID, got ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
+function validateOrgScope(scope) {
+    const orgId = assertUuid(scope?.orgId, 'scope.orgId');
+    const userId = scope.userId === undefined || scope.userId === '' ? '' : assertUuid(scope.userId, 'scope.userId');
+    return { orgId, userId };
+}
+function validateReason(reason) {
+    if (!(0, access_reason_registry_1.isSystemAccessReason)(reason)) {
+        throw new scoped_access_error_1.ScopedAccessError(`A system access needs a registered reason (${access_reason_registry_1.systemAccessReasonRegistry.ids().join(', ')}), got ${JSON.stringify(reason)}. ` +
+            'Add one with registerSystemAccessReason() at import time.');
+    }
+    return reason;
+}
+/** The `set_config` statement for a scope: one round trip, two settings, both transaction-local. */
+function setScopeStatement(client, scope) {
+    return client.$executeRaw `SELECT set_config('app.org_id', ${scope.orgId}, true), set_config('app.user_id', ${scope.userId}, true)`;
+}
+/** The `set_config` statement that lifts row-level security for the transaction. */
+function setBypassStatement(client) {
+    return client.$executeRaw `SELECT set_config('app.rls_bypass', 'on', true)`;
+}
+function recordSystemAccess(reason) {
+    const span = api_1.trace.getActiveSpan();
+    span?.setAttributes({ 'db.access.scope': 'system', 'db.access.reason': reason });
+    span?.addEvent('db.rls_bypass', { 'db.access.reason': reason });
+}
+function batch(client, statements) {
+    return client.$transaction.call(client, statements);
+}
+/**
+ * The scope an interactive transaction was opened with, so a nested
+ * {@link runInOrg} reuses the outer setting instead of opening another.
+ */
+const TRANSACTION_SCOPES = new WeakMap();
+function scopeKey(scope) {
+    return `${scope.orgId}|${scope.userId}`;
+}
+function isTransactionClient(client) {
+    // Prisma's interactive-transaction client has no `$connect` and no `$extends`
+    // (it keeps a `$transaction` that only throws), and the one `runInOrg` handed
+    // out is remembered in TRANSACTION_SCOPES.
+    const c = client;
+    return TRANSACTION_SCOPES.has(client) || (typeof c.$connect !== 'function' && typeof c.$extends !== 'function');
+}
+/**
+ * The Prisma client extension behind {@link forOrg}: every operation (model
+ * operations and raw SQL alike) runs as
+ * `$transaction([ set_config('app.org_id', …, true), operation ])`, so the
+ * policies see the organisation on the very connection that runs the query.
+ *
+ * `base` is the client whose pool runs the transaction, usually the client the
+ * extension is then applied to.
+ *
+ * @param base - the app's Prisma client (or the `PLATFORM_PRISMA` port).
+ * @param scope - the organisation (and optionally the user); validated as UUIDs.
+ * @throws ScopedAccessError when an id is not a UUID.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * // apps/api/src/prisma/prisma.service.ts
+ * forOrg(orgId: string, opts?: { userId?: string }) {
+ *   return this.$extends(orgScopeExtension(this, { orgId, userId: opts?.userId }));
+ * }
+ * ```
+ */
+function orgScopeExtension(base, scope) {
+    const pinned = validateOrgScope(scope);
+    return extension_1.Prisma.defineExtension({
+        name: 'org-scope',
+        query: {
+            async $allOperations({ args, query, ...rest }) {
+                assertNotInsideTransaction(rest);
+                const [, result] = await batch(base, [setScopeStatement(base, pinned), query(args)]);
+                return result;
+            },
+        },
+    });
+}
+/**
+ * The extension behind {@link forSystem}: the same per-operation batch, setting
+ * `app.rls_bypass = 'on'` instead of an organisation. Apply it only to a
+ * SEPARATE client (its own pool), so the tenant pool never carries the flag.
+ *
+ * @param base - the system `PrismaClient`.
+ * @param reason - why; recorded on the active span.
+ * @throws ScopedAccessError for a reason that is not registered ({@link systemAccessReasonRegistry}).
+ *
+ * @stability experimental
+ */
+function systemScopeExtension(base, reason) {
+    const checked = validateReason(reason);
+    return extension_1.Prisma.defineExtension({
+        name: 'system-scope',
+        query: {
+            async $allOperations({ args, query, ...rest }) {
+                assertNotInsideTransaction(rest);
+                recordSystemAccess(checked);
+                const [, result] = await batch(base, [setBypassStatement(base), query(args)]);
+                return result;
+            },
+        },
+    });
+}
+/**
+ * Prisma passes the call's internal parameters beside the public ones. Inside
+ * an interactive transaction they carry the transaction handle; an extended
+ * client used there would open a second transaction and escape the first.
+ */
+function assertNotInsideTransaction(rest) {
+    const internal = rest.__internalParams;
+    if (internal?.transaction !== undefined && internal.transaction !== null) {
+        throw new scoped_access_error_1.ScopedAccessError('A scoped client was used inside $transaction(async tx => ...). Its operations would escape the transaction; ' +
+            'use runInOrg()/runAsSystem() and the plain `tx` they hand out instead.');
+    }
+}
+/**
+ * A client whose every operation runs in a transaction that first sets
+ * `app.org_id` (and `app.user_id`) transaction-locally. Fails closed: the
+ * policies show this client nothing of another organisation, and refuse an
+ * insert naming one.
+ *
+ * Built per call; `$extends` shares the underlying pool, so this is cheap. Use
+ * it for single operations and {@link runInOrg} for a unit of work.
+ *
+ * @param client - the app's Prisma client.
+ * @param orgId - the organisation: `principal.activeOrgId` or a job payload's `orgId`, never request input.
+ * @param opts - `userId`, the acting user.
+ * @throws ScopedAccessError when an id is not a UUID.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const db = forOrg(prisma, principal.activeOrgId!, { userId: principal.userId });
+ * await db.storageObject.findMany(); // only this organisation's rows
+ * ```
+ */
+function forOrg(client, orgId, opts = {}) {
+    const extension = orgScopeExtension(client, { orgId, ...(opts.userId !== undefined ? { userId: opts.userId } : {}) });
+    return client.$extends(extension);
+}
+/**
+ * {@link forOrg} for a {@link Scope}: `scope.orgId` is required here.
+ *
+ * @param client - the app's Prisma client.
+ * @param scope - derived from the principal; `orgId` must be set.
+ * @throws ScopedAccessError when `scope.orgId` is missing or an id is not a UUID.
+ *
+ * @stability experimental
+ */
+function forScope(client, scope) {
+    if (scope.orgId === undefined) {
+        throw new scoped_access_error_1.ScopedAccessError('forScope() needs scope.orgId: a client without an organisation sees nothing (fail closed).');
+    }
+    return forOrg(client, scope.orgId, { userId: scope.userId });
+}
+/**
+ * A client whose every operation sets the bypass flag transaction-locally.
+ * Hand it only a client built on its own pool; see {@link systemScopeExtension}.
+ *
+ * @param client - the system `PrismaClient`.
+ * @param reason - why; recorded on the active span.
+ * @throws ScopedAccessError for a reason that is not registered ({@link systemAccessReasonRegistry}).
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const db = forSystem(systemPrisma, 'retention');
+ * await db.aiUsageEvent.deleteMany({ where: { createdAt: { lt: cutoff } } });
+ * ```
+ */
+function forSystem(client, reason) {
+    return client.$extends(systemScopeExtension(client, reason));
+}
+/**
+ * One interactive transaction in an organisation's scope: `set_config` is the
+ * first statement, then `fn(tx)` where `tx` is the plain (unextended)
+ * transaction client. Rolls back when `fn` throws.
+ *
+ * Nested use reuses the outer transaction: calling it with a transaction client
+ * that is already scoped to the same organisation runs `fn` directly, and
+ * calling it with a different organisation throws.
+ *
+ * Prisma waits only 2 s for a pooled connection by default; pass `maxWait` when
+ * many transactions queue behind a small pool (or size the pool for the load).
+ *
+ * @param client - the app's Prisma client, or a transaction client from an outer {@link runInOrg}.
+ * @param scope - the organisation and optionally the user.
+ * @param fn - the unit of work; receives the transaction client.
+ * @param options - `maxWait` and `timeout`, forwarded to Prisma.
+ * @throws ScopedAccessError when an id is not a UUID or a nested call names another organisation.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * await runInOrg(prisma, { orgId, userId }, async (tx) => {
+ *   const object = await tx.storageObject.create({ data });
+ *   await tx.auditEvent.create({ data: auditFor(object) });
+ * });
+ * ```
+ */
+async function runInOrg(client, scope, fn, options = {}) {
+    const pinned = validateOrgScope(scope);
+    const key = scopeKey(pinned);
+    if (isTransactionClient(client)) {
+        const outer = TRANSACTION_SCOPES.get(client);
+        if (outer !== undefined) {
+            if (outer !== key) {
+                throw new scoped_access_error_1.ScopedAccessError('runInOrg() was nested inside a transaction scoped to another organisation or user.');
+            }
+            return fn(client);
+        }
+        await setScopeStatement(client, pinned);
+        TRANSACTION_SCOPES.set(client, key);
+        return fn(client);
+    }
+    return client.$transaction(async (tx) => {
+        await setScopeStatement(tx, pinned);
+        TRANSACTION_SCOPES.set(tx, key);
+        return fn(tx);
+    }, options);
+}
+/**
+ * {@link runInOrg} for a {@link Scope}: `scope.orgId` is required.
+ *
+ * @stability experimental
+ */
+function runInScope(client, scope, fn, options = {}) {
+    if (scope.orgId === undefined) {
+        return Promise.reject(new scoped_access_error_1.ScopedAccessError('runInScope() needs scope.orgId: a transaction without an organisation sees nothing (fail closed).'));
+    }
+    return runInOrg(client, { orgId: scope.orgId, userId: scope.userId }, fn, options);
+}
+/**
+ * One interactive transaction with the bypass flag set transaction-locally.
+ * Run it on the SEPARATE system client. `fn` receives the plain transaction
+ * client.
+ *
+ * @param client - the system `PrismaClient`.
+ * @param reason - why; recorded on the active span.
+ * @param fn - the unit of work.
+ * @param options - `maxWait` and `timeout`, forwarded to Prisma.
+ * @throws ScopedAccessError for a reason that is not registered ({@link systemAccessReasonRegistry}).
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const total = await runAsSystem(systemPrisma, 'doctor', (tx) => tx.storageObject.count());
+ * ```
+ */
+async function runAsSystem(client, reason, fn, options = {}) {
+    const checked = validateReason(reason);
+    recordSystemAccess(checked);
+    if (isTransactionClient(client)) {
+        await setBypassStatement(client);
+        return fn(client);
+    }
+    return client.$transaction(async (tx) => {
+        await setBypassStatement(tx);
+        return fn(tx);
+    }, options);
+}
+//# sourceMappingURL=rls.js.map

package/dist/core/data-access/rls.js.map

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

package/dist/core/database-url.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The subset of the environment this builder reads.
+ *
+ * @stability stable
+ */
+export interface DatabaseEnv {
+    /** An explicit connection string; wins untouched when set. */
+    DATABASE_URL?: string | undefined;
+    /** Host; default `localhost`. */
+    POSTGRES_HOST?: string | undefined;
+    /** Port; default `5432`. */
+    POSTGRES_PORT?: string | undefined;
+    /** Role; default `postgres`. Percent-encoded. */
+    POSTGRES_USER?: string | undefined;
+    /** Password; default `postgres`. Percent-encoded. */
+    POSTGRES_PASSWORD?: string | undefined;
+    /** Database; default `appdb`. */
+    POSTGRES_DB?: string | undefined;
+    /** Exactly `'true'` adds `?sslmode=require`. */
+    POSTGRES_SSL?: string | undefined;
+}
+/**
+ * Builds the PostgreSQL connection string.
+ *
+ * Two rules, both of which every caller now shares:
+ *
+ *  1. An already-set DATABASE_URL WINS and is returned untouched. It is the
+ *     escape hatch for a connection this formula cannot express — a socket
+ *     path, a pgbouncer URL, extra query parameters — and re-deriving over the
+ *     top of it would silently discard the operator's intent.
+ *  2. The user and the password are BOTH percent-encoded. The password is the
+ *     one that bites in practice, but a username can contain `@` too, and
+ *     encoding only one of them is how this class of bug comes back.
+ *
+ * @stability stable
+ */
+export declare function buildDatabaseUrl(env?: DatabaseEnv): string;
+//# sourceMappingURL=database-url.d.ts.map

package/dist/core/database-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-url.d.ts","sourceRoot":"","sources":["../../src/core/database-url.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,iCAAiC;IACjC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,WAAyB,GAAG,MAAM,CAsBvE"}

package/dist/core/database-url.js

@@ -0,0 +1,52 @@
+"use strict";
+// =============================================================================
+// The one place a PostgreSQL connection string is built (issue #172; packaged
+// by #740)
+// =============================================================================
+//
+// DATABASE_URL is not a primary input in the platform: it is derived from the
+// individual POSTGRES_* variables. Three hand-written copies of this
+// derivation once disagreed about percent-encoding (a password containing `@`,
+// `/` or `%` connected for migrations and then not for the application), which
+// is why every caller goes through this function. The reference app's
+// `common/database-url.ts` re-exports it, and its spec holds it together with
+// the CommonJS copy in `apps/api/scripts/prisma-env.js` over a table of
+// awkward inputs.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDatabaseUrl = buildDatabaseUrl;
+/**
+ * Builds the PostgreSQL connection string.
+ *
+ * Two rules, both of which every caller now shares:
+ *
+ *  1. An already-set DATABASE_URL WINS and is returned untouched. It is the
+ *     escape hatch for a connection this formula cannot express — a socket
+ *     path, a pgbouncer URL, extra query parameters — and re-deriving over the
+ *     top of it would silently discard the operator's intent.
+ *  2. The user and the password are BOTH percent-encoded. The password is the
+ *     one that bites in practice, but a username can contain `@` too, and
+ *     encoding only one of them is how this class of bug comes back.
+ *
+ * @stability stable
+ */
+function buildDatabaseUrl(env = process.env) {
+    const existing = env.DATABASE_URL;
+    if (existing !== undefined && existing !== '') {
+        return existing;
+    }
+    const host = env.POSTGRES_HOST || 'localhost';
+    const port = env.POSTGRES_PORT || '5432';
+    const user = env.POSTGRES_USER || 'postgres';
+    const password = env.POSTGRES_PASSWORD || 'postgres';
+    const database = env.POSTGRES_DB || 'appdb';
+    // Exact string comparison, deliberately: 'TRUE', '1' and 'yes' are NOT true
+    // here, because that is the rule the other two builders already used and
+    // widening it would change the meaning of existing .env files.
+    const ssl = env.POSTGRES_SSL === 'true';
+    const sslParam = ssl ? '?sslmode=require' : '';
+    const encodedUser = encodeURIComponent(user);
+    const encodedPassword = encodeURIComponent(password);
+    return `postgresql://${encodedUser}:${encodedPassword}@${host}:${port}/${database}${sslParam}`;
+}
+//# sourceMappingURL=database-url.js.map

package/dist/core/database-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-url.js","sourceRoot":"","sources":["../../src/core/database-url.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,8EAA8E;AAC9E,WAAW;AACX,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,qEAAqE;AACrE,+EAA+E;AAC/E,+EAA+E;AAC/E,sEAAsE;AACtE,8EAA8E;AAC9E,wEAAwE;AACxE,kBAAkB;AAClB,gFAAgF;;AAuChF,4CAsBC;AArCD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,gBAAgB,CAAC,MAAmB,OAAO,CAAC,GAAG;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC;IAClC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,WAAW,CAAC;IAC9C,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,MAAM,CAAC;IACzC,MAAM,IAAI,GAAG,GAAG,CAAC,aAAa,IAAI,UAAU,CAAC;IAC7C,MAAM,QAAQ,GAAG,GAAG,CAAC,iBAAiB,IAAI,UAAU,CAAC;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC;IAE5C,4EAA4E;IAC5E,yEAAyE;IACzE,+DAA+D;IAC/D,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,KAAK,MAAM,CAAC;IACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;IAE/C,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,eAAe,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAErD,OAAO,gBAAgB,WAAW,IAAI,eAAe,IAAI,IAAI,IAAI,IAAI,IAAI,QAAQ,GAAG,QAAQ,EAAE,CAAC;AACjG,CAAC"}

package/dist/core/errors/error-codes.d.ts

@@ -0,0 +1,114 @@
+import type { HttpException } from '@nestjs/common';
+import { type Registry } from '../registry/registry';
+/**
+ * The pattern an error code matches: UPPER_SNAKE, 3 to 64 characters, starting
+ * with a letter (`NOTE_TITLE_TAKEN`).
+ *
+ * @stability experimental
+ */
+export declare const ERROR_CODE_PATTERN: RegExp;
+/**
+ * The code of a failure whose status has no registered default (for example a
+ * 503). Never registered: it has no single status.
+ *
+ * @stability experimental
+ */
+export declare const FALLBACK_ERROR_CODE = "ERROR";
+/**
+ * One registered error code.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const def: ErrorCodeDef = { code: 'NOTE_TITLE_TAKEN', status: 409, description: 'A note with this title already exists.' };
+ * ```
+ */
+export interface ErrorCodeDef {
+    /** The code. See {@link ERROR_CODE_PATTERN}. */
+    readonly code: string;
+    /** The HTTP status the code is for (an integer from 400 to 599). The filter passes the code through only for an exception of this status. */
+    readonly status: number;
+    /** One sentence for the API docs: when a client sees this code. */
+    readonly description: string;
+}
+/**
+ * The platform's status-derived codes, in the order the OpenAPI examples list
+ * them. The FIRST entry for a status is the default `code` of that status.
+ *
+ * @stability experimental
+ */
+export declare const BUILTIN_ERROR_CODES: readonly ErrorCodeDef[];
+/**
+ * Every registered error code: the platform's ten first, then the app's.
+ * Frozen once the application has bootstrapped.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const errorCodeRegistry: Registry<ErrorCodeDef>;
+/**
+ * Registers a domain error code. Call it at module load, before the
+ * application is created; a duplicate code (including a built-in one) throws.
+ *
+ * A code is for ONE status. To let the filter pass it through, throw an
+ * `HttpException` of that status whose payload carries `code`.
+ *
+ * @param def - the code, its status and a description.
+ * @throws RegistryError `INVALID_ID`, `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+ *
+ * @example
+ * ```ts
+ * registerErrorCode({ code: 'NOTE_TITLE_TAKEN', status: 409, description: 'A note with this title already exists.' });
+ * // in a service:
+ * throw new ConflictException({ code: 'NOTE_TITLE_TAKEN', message: 'Title already used', details: { field: 'title' } });
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerErrorCode(def: ErrorCodeDef): void;
+/**
+ * The default code of an HTTP status: the first registered code for it, else
+ * {@link FALLBACK_ERROR_CODE}.
+ *
+ * @param status - an HTTP status.
+ * @returns the code the envelope carries when the exception names none.
+ *
+ * @stability experimental
+ */
+export declare function defaultErrorCodeForStatus(status: number): string;
+/**
+ * Whether `code` may appear in the envelope of an exception with `status`: it
+ * is registered, for that status.
+ *
+ * @param code - a payload `code`, as thrown.
+ * @param status - the exception's HTTP status.
+ * @returns `true` only for a registered code of that status.
+ *
+ * @stability experimental
+ */
+export declare function isErrorCodeForStatus(code: unknown, status: number): code is string;
+/**
+ * Turns an error the platform does not know (a Prisma error, an SDK error) into
+ * an `HttpException`, or returns `null` to pass. Mappers run, in order, only for
+ * values that are NOT already an `HttpException`; the first to return one wins.
+ *
+ * ⚠ Build the result's `message` and `details` yourself and keep them free of
+ * the original error's text: a Prisma or SDK message can carry SQL, table names,
+ * hostnames or credentials. The filter never copies a mapped error's message,
+ * and logs the original server-side only.
+ *
+ * @param error - whatever was thrown.
+ * @returns the exception to respond with, or `null` when this mapper does not handle it.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const uniqueViolation: ErrorMapper = (error) =>
+ *   isPrismaError(error, 'P2002')
+ *     ? new ConflictException({ code: 'ALREADY_EXISTS', message: 'Already exists', details: { fields: error.meta?.target } })
+ *     : null;
+ * ```
+ */
+export type ErrorMapper = (error: unknown) => HttpException | null;
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/core/errors/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../../src/core/errors/error-codes.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAA2B,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6IAA6I;IAC7I,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAWrD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,YAAY,CAenD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,IAAI,MAAM,CAElF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,aAAa,GAAG,IAAI,CAAC"}