@saasicat/nest 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/issuer-identity.check-CBO0vcsq.d.cts

@@ -0,0 +1,197 @@
+import * as _nestjs_common from '@nestjs/common';
+import { ExecutionContext, DynamicModule, OnModuleInit } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { SuperAdminProvisioningPort, SetupStatusResponse, SetupRequest, SetupResult, SetupConfirmMfaRequest, SetupConfirmMfaResponse, PlanCatalogSettings, AppliedSettingsPort, SubscriptionContractRepository, RlsBypassPort, IssuerIdentityChange, RunningContractIssuers } from '@saasicat/core';
+import { M as MfaService } from './admin-stats.service-DrZrU8IJ.cjs';
+import { c as SaaSiCatModuleOptions } from './module-options-qAOwinHR.cjs';
+
+/**
+ * Shared metadata key for endpoints that intentionally run without application
+ * authentication. `Symbol.for` keeps the marker stable across package entries.
+ */
+declare const SAASICAT_PUBLIC_ROUTE_KEY: unique symbol;
+/** Marks a SaaSiCat controller or handler as intentionally public. */
+declare const SaaSiCatPublicRoute: () => _nestjs_common.CustomDecorator<typeof SAASICAT_PUBLIC_ROUTE_KEY>;
+/** Returns whether the current endpoint is marked as a public SaaSiCat route. */
+declare function isSaaSiCatPublicRoute(reflector: Reflector, context: ExecutionContext): boolean;
+
+declare const SETUP_PROVISIONING_PORT_TOKEN: unique symbol;
+declare const SETUP_CONFIG_TOKEN: unique symbol;
+interface SetupConfig {
+    /** Env-var name of the setup token. Without the var set, setup is disabled. */
+    setupTokenEnvVar: string;
+    /** Authenticator issuer for the MFA enrollment in the wizard. */
+    mfaIssuer: string;
+}
+
+declare class SetupService {
+    private readonly users;
+    private readonly config;
+    private readonly mfa;
+    constructor(users: SuperAdminProvisioningPort, config: SetupConfig, mfa: MfaService);
+    status(): Promise<SetupStatusResponse>;
+    setup(req: SetupRequest): Promise<SetupResult>;
+    confirmMfa(req: SetupConfirmMfaRequest): Promise<SetupConfirmMfaResponse>;
+    private assertToken;
+    private assertNoSuperAdmin;
+}
+
+/**
+ * Bundles the complete standard SaaSiCat backend stack into a single
+ * `forRoot({...})` call. Reduces AppModule boilerplate and eliminates the
+ * ordering trap.
+ *
+ * Quickstart path (Prisma + PostgreSQL on the canonical schema):
+ *
+ * ```ts
+ * SaaSiCatModule.forRoot({
+ *     planCatalog: loadPlanCatalogFromFile({ path: 'config/saas.yaml' }),
+ *     controller: { guards: [JwtAuthGuard] },
+ *     imports: [AuthModule],
+ *     persistence: prismaPersistence({ client: PrismaService }), // @saasicat/adapter-prisma
+ * })
+ * ```
+ *
+ * Individual `adapters` entries stay supported (custom schema / other ORM)
+ * and override bundle slices field by field.
+ */
+declare class SaaSiCatModule {
+    static forRoot(options: SaaSiCatModuleOptions): DynamicModule;
+}
+
+/**
+ * Typed identity helper for the high-level SaaSiCat configuration. It keeps
+ * literal types and gives editors one place for completion without adding
+ * runtime behavior.
+ */
+declare function defineSaaSiCat<const T extends SaaSiCatModuleOptions>(options: T): T;
+
+/** An undeclared change is the only one that refuses a start. */
+type UndeclaredChange = Extract<IssuerIdentityChange, {
+    kind: 'undeclared';
+}>;
+/** What a start, or `<app> doctor`, finds when it compares the two. */
+type IssuerIdentityVerdict = 
+/**
+ * There was no previous identity to compare the file with — nothing records
+ * the applied settings, or the record could not be read while the file
+ * names no issuer at all. `why` says which.
+ */
+{
+    kind: 'not-compared';
+    why: string;
+}
+/** The file and the record agree, or the difference is declared. */
+ | {
+    kind: 'settled';
+    change: Exclude<IssuerIdentityChange, UndeclaredChange>;
+}
+/** Another legal entity, undeclared. The start does not continue. */
+ | {
+    kind: 'refused';
+    change: UndeclaredChange;
+    /** The contracts still running, or `null` where they could not be read. */
+    running: RunningContractIssuers | null;
+    /** What the start dies with, and what `<app> doctor` prints. */
+    refusal: string;
+};
+/**
+ * The comparison, and nothing else.
+ *
+ * Kept apart from the hook below so that asking the question costs nothing: a
+ * class whose construction is also a lifecycle hook cannot be injected by
+ * anything that only wants the answer.
+ */
+declare class IssuerIdentityInspector {
+    private readonly fileSettings;
+    private readonly source;
+    private readonly settings;
+    private readonly contracts;
+    private readonly rlsBypass;
+    private readonly logger;
+    /** This start's answer, settled the first time anything asks for it. */
+    private verdict;
+    constructor(fileSettings: PlanCatalogSettings, source: string, settings?: AppliedSettingsPort | null, contracts?: SubscriptionContractRepository | null, rlsBypass?: RlsBypassPort | null);
+    /**
+     * What the issuer in the file is, against the identity the record holds.
+     *
+     * Answered once per process, and the cached answer is the point rather than
+     * the saved query: `AppliedSettingsRecorder` replaces the record moments
+     * later, in a bootstrap hook, so a second comparison would find the file
+     * agreeing with what this very start wrote. A reader asking afterwards —
+     * `<app> doctor`, a health endpoint — would then be told that nothing had
+     * moved, on a start that had just carried a correction through. What this
+     * start found is a fact about this start, so it is settled when the start
+     * asks and does not change afterwards.
+     */
+    inspect(): Promise<IssuerIdentityVerdict>;
+    /**
+     * How many contracts are running, for a report that says what changing the
+     * identity would cost. A query of its own rather than a field on the
+     * verdict: a start needs this only to name the contracts in a refusal, and
+     * no boot should pay for a number nobody reads. `null` where they are not
+     * known.
+     */
+    runningContractCount(): Promise<number | null>;
+    private compare;
+    /**
+     * The settings of the last start, or what stopped this from reading them.
+     *
+     * A read that fails while the file names an issuer takes the boot down: a
+     * guard that cannot see is not a guard that saw nothing, and an installation
+     * that puts a legal entity on every contract it concludes should not conclude
+     * one while nothing can tell whether that entity is still the recorded one.
+     *
+     * Where the file names no issuer, the same failure is only a warning. There
+     * is then no entity to conclude a contract on behalf of, and the promise the
+     * record makes — an installation whose record cannot be kept still runs the
+     * right configuration — is worth more than a boot refused over a comparison
+     * with nothing on one side. What that leaves uncaught is narrow and worth
+     * naming: an operator who removes the issuer block while contracts run, in
+     * the same start where the record cannot be read.
+     */
+    private readRecorded;
+    /**
+     * The contracts a refusal is about. Best effort on purpose: the refusal is
+     * already decided, and losing it because the list behind it could not be
+     * read would replace a message an operator can act on with one they cannot.
+     * Where they are not known, the message says which of the two it is —
+     * "nothing here writes contracts" and "the query failed" send an operator
+     * looking in different places.
+     */
+    private readRunning;
+    /**
+     * Inside the bypass frame where one is bound, and plainly where none is.
+     *
+     * An installation without row-level security binds a port that only calls
+     * through; one that has it cannot be read platform-wide without this.
+     * `@Optional()` rather than required because a hand-wired application may
+     * have no `AdminModule` in scope, and a boot check is not the place to
+     * refuse to construct over a message.
+     */
+    private withBypass;
+    /**
+     * The line a start that continues is worth, and nothing where it is worth
+     * none. Public because the hook beside this class calls it; not an offer.
+     *
+     * @internal
+     */
+    report(verdict: Exclude<IssuerIdentityVerdict, {
+        kind: 'refused';
+    }>): void;
+}
+/**
+ * Refuses a start whose file names another legal entity than the record does.
+ *
+ * A module hook, not a bootstrap one: `AppliedSettingsRecorder` replaces the
+ * record in `onApplicationBootstrap`, and Nest runs every module hook before a
+ * single bootstrap hook. That is what makes the comparison see the previous
+ * start's values rather than this start's own.
+ */
+declare class IssuerIdentityCheck implements OnModuleInit {
+    private readonly inspector;
+    constructor(inspector: IssuerIdentityInspector);
+    onModuleInit(): Promise<void>;
+}
+
+export { IssuerIdentityCheck as I, SetupService as S, IssuerIdentityInspector as a, type IssuerIdentityVerdict as b, SAASICAT_PUBLIC_ROUTE_KEY as c, SETUP_CONFIG_TOKEN as d, SETUP_PROVISIONING_PORT_TOKEN as e, SaaSiCatModule as f, SaaSiCatPublicRoute as g, type SetupConfig as h, defineSaaSiCat as i, isSaaSiCatPublicRoute as j };

package/dist/issuer-identity.check-Cz9CEMkZ.d.ts

@@ -0,0 +1,197 @@
+import * as _nestjs_common from '@nestjs/common';
+import { ExecutionContext, DynamicModule, OnModuleInit } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { SuperAdminProvisioningPort, SetupStatusResponse, SetupRequest, SetupResult, SetupConfirmMfaRequest, SetupConfirmMfaResponse, PlanCatalogSettings, AppliedSettingsPort, SubscriptionContractRepository, RlsBypassPort, IssuerIdentityChange, RunningContractIssuers } from '@saasicat/core';
+import { M as MfaService } from './admin-stats.service-CsLNt19Z.js';
+import { c as SaaSiCatModuleOptions } from './module-options-DmQ3G4sZ.js';
+
+/**
+ * Shared metadata key for endpoints that intentionally run without application
+ * authentication. `Symbol.for` keeps the marker stable across package entries.
+ */
+declare const SAASICAT_PUBLIC_ROUTE_KEY: unique symbol;
+/** Marks a SaaSiCat controller or handler as intentionally public. */
+declare const SaaSiCatPublicRoute: () => _nestjs_common.CustomDecorator<typeof SAASICAT_PUBLIC_ROUTE_KEY>;
+/** Returns whether the current endpoint is marked as a public SaaSiCat route. */
+declare function isSaaSiCatPublicRoute(reflector: Reflector, context: ExecutionContext): boolean;
+
+declare const SETUP_PROVISIONING_PORT_TOKEN: unique symbol;
+declare const SETUP_CONFIG_TOKEN: unique symbol;
+interface SetupConfig {
+    /** Env-var name of the setup token. Without the var set, setup is disabled. */
+    setupTokenEnvVar: string;
+    /** Authenticator issuer for the MFA enrollment in the wizard. */
+    mfaIssuer: string;
+}
+
+declare class SetupService {
+    private readonly users;
+    private readonly config;
+    private readonly mfa;
+    constructor(users: SuperAdminProvisioningPort, config: SetupConfig, mfa: MfaService);
+    status(): Promise<SetupStatusResponse>;
+    setup(req: SetupRequest): Promise<SetupResult>;
+    confirmMfa(req: SetupConfirmMfaRequest): Promise<SetupConfirmMfaResponse>;
+    private assertToken;
+    private assertNoSuperAdmin;
+}
+
+/**
+ * Bundles the complete standard SaaSiCat backend stack into a single
+ * `forRoot({...})` call. Reduces AppModule boilerplate and eliminates the
+ * ordering trap.
+ *
+ * Quickstart path (Prisma + PostgreSQL on the canonical schema):
+ *
+ * ```ts
+ * SaaSiCatModule.forRoot({
+ *     planCatalog: loadPlanCatalogFromFile({ path: 'config/saas.yaml' }),
+ *     controller: { guards: [JwtAuthGuard] },
+ *     imports: [AuthModule],
+ *     persistence: prismaPersistence({ client: PrismaService }), // @saasicat/adapter-prisma
+ * })
+ * ```
+ *
+ * Individual `adapters` entries stay supported (custom schema / other ORM)
+ * and override bundle slices field by field.
+ */
+declare class SaaSiCatModule {
+    static forRoot(options: SaaSiCatModuleOptions): DynamicModule;
+}
+
+/**
+ * Typed identity helper for the high-level SaaSiCat configuration. It keeps
+ * literal types and gives editors one place for completion without adding
+ * runtime behavior.
+ */
+declare function defineSaaSiCat<const T extends SaaSiCatModuleOptions>(options: T): T;
+
+/** An undeclared change is the only one that refuses a start. */
+type UndeclaredChange = Extract<IssuerIdentityChange, {
+    kind: 'undeclared';
+}>;
+/** What a start, or `<app> doctor`, finds when it compares the two. */
+type IssuerIdentityVerdict = 
+/**
+ * There was no previous identity to compare the file with — nothing records
+ * the applied settings, or the record could not be read while the file
+ * names no issuer at all. `why` says which.
+ */
+{
+    kind: 'not-compared';
+    why: string;
+}
+/** The file and the record agree, or the difference is declared. */
+ | {
+    kind: 'settled';
+    change: Exclude<IssuerIdentityChange, UndeclaredChange>;
+}
+/** Another legal entity, undeclared. The start does not continue. */
+ | {
+    kind: 'refused';
+    change: UndeclaredChange;
+    /** The contracts still running, or `null` where they could not be read. */
+    running: RunningContractIssuers | null;
+    /** What the start dies with, and what `<app> doctor` prints. */
+    refusal: string;
+};
+/**
+ * The comparison, and nothing else.
+ *
+ * Kept apart from the hook below so that asking the question costs nothing: a
+ * class whose construction is also a lifecycle hook cannot be injected by
+ * anything that only wants the answer.
+ */
+declare class IssuerIdentityInspector {
+    private readonly fileSettings;
+    private readonly source;
+    private readonly settings;
+    private readonly contracts;
+    private readonly rlsBypass;
+    private readonly logger;
+    /** This start's answer, settled the first time anything asks for it. */
+    private verdict;
+    constructor(fileSettings: PlanCatalogSettings, source: string, settings?: AppliedSettingsPort | null, contracts?: SubscriptionContractRepository | null, rlsBypass?: RlsBypassPort | null);
+    /**
+     * What the issuer in the file is, against the identity the record holds.
+     *
+     * Answered once per process, and the cached answer is the point rather than
+     * the saved query: `AppliedSettingsRecorder` replaces the record moments
+     * later, in a bootstrap hook, so a second comparison would find the file
+     * agreeing with what this very start wrote. A reader asking afterwards —
+     * `<app> doctor`, a health endpoint — would then be told that nothing had
+     * moved, on a start that had just carried a correction through. What this
+     * start found is a fact about this start, so it is settled when the start
+     * asks and does not change afterwards.
+     */
+    inspect(): Promise<IssuerIdentityVerdict>;
+    /**
+     * How many contracts are running, for a report that says what changing the
+     * identity would cost. A query of its own rather than a field on the
+     * verdict: a start needs this only to name the contracts in a refusal, and
+     * no boot should pay for a number nobody reads. `null` where they are not
+     * known.
+     */
+    runningContractCount(): Promise<number | null>;
+    private compare;
+    /**
+     * The settings of the last start, or what stopped this from reading them.
+     *
+     * A read that fails while the file names an issuer takes the boot down: a
+     * guard that cannot see is not a guard that saw nothing, and an installation
+     * that puts a legal entity on every contract it concludes should not conclude
+     * one while nothing can tell whether that entity is still the recorded one.
+     *
+     * Where the file names no issuer, the same failure is only a warning. There
+     * is then no entity to conclude a contract on behalf of, and the promise the
+     * record makes — an installation whose record cannot be kept still runs the
+     * right configuration — is worth more than a boot refused over a comparison
+     * with nothing on one side. What that leaves uncaught is narrow and worth
+     * naming: an operator who removes the issuer block while contracts run, in
+     * the same start where the record cannot be read.
+     */
+    private readRecorded;
+    /**
+     * The contracts a refusal is about. Best effort on purpose: the refusal is
+     * already decided, and losing it because the list behind it could not be
+     * read would replace a message an operator can act on with one they cannot.
+     * Where they are not known, the message says which of the two it is —
+     * "nothing here writes contracts" and "the query failed" send an operator
+     * looking in different places.
+     */
+    private readRunning;
+    /**
+     * Inside the bypass frame where one is bound, and plainly where none is.
+     *
+     * An installation without row-level security binds a port that only calls
+     * through; one that has it cannot be read platform-wide without this.
+     * `@Optional()` rather than required because a hand-wired application may
+     * have no `AdminModule` in scope, and a boot check is not the place to
+     * refuse to construct over a message.
+     */
+    private withBypass;
+    /**
+     * The line a start that continues is worth, and nothing where it is worth
+     * none. Public because the hook beside this class calls it; not an offer.
+     *
+     * @internal
+     */
+    report(verdict: Exclude<IssuerIdentityVerdict, {
+        kind: 'refused';
+    }>): void;
+}
+/**
+ * Refuses a start whose file names another legal entity than the record does.
+ *
+ * A module hook, not a bootstrap one: `AppliedSettingsRecorder` replaces the
+ * record in `onApplicationBootstrap`, and Nest runs every module hook before a
+ * single bootstrap hook. That is what makes the comparison see the previous
+ * start's values rather than this start's own.
+ */
+declare class IssuerIdentityCheck implements OnModuleInit {
+    private readonly inspector;
+    constructor(inspector: IssuerIdentityInspector);
+    onModuleInit(): Promise<void>;
+}
+
+export { IssuerIdentityCheck as I, SetupService as S, IssuerIdentityInspector as a, type IssuerIdentityVerdict as b, SAASICAT_PUBLIC_ROUTE_KEY as c, SETUP_CONFIG_TOKEN as d, SETUP_PROVISIONING_PORT_TOKEN as e, SaaSiCatModule as f, SaaSiCatPublicRoute as g, type SetupConfig as h, defineSaaSiCat as i, isSaaSiCatPublicRoute as j };