@saasicat/nest 0.2.0

package/dist/registration/index.d.cts

@@ -0,0 +1,444 @@
+import { PendingRegistrationRepository, RegistrationOtpDelivery, UserAccountLookup, SlugAvailabilityCheck, PlanCatalogLookup, PaymentProvider, PaymentEventLog, ActivationOrchestrator, RegistrationAuditLogger, RegistrationResumeTokenSigner, RegistrationResumeDelivery, RegistrationConfiguratorLookup, RegistrationPromoPreview, RegistrationBusinessTypeLookup, PublicSignupPlan, SelectPlanInput, RegistrationAuditContext, SelectPlanResult, StartCheckoutInput, StartCheckoutResult, HandlePaymentEventInput, HandlePaymentEventResult, CleanupResult, StartRegistrationInput, StartRegistrationResult, VerifyRegistrationOtpResult, ResumeRegistrationInput, ResumeRegistrationResult, ConfiguratorCatalog, SaveRegistrationConfigInput, SaveRegistrationConfigResult, ConfiguratorPriceBreakdown, RegistrationConfigSelection } from '@saasicat/types';
+import { CanActivate, ExecutionContext, Type, DynamicModule, ForwardReference, Provider } from '@nestjs/common';
+import { P as ProviderSpec } from '../di-CcNeq9v-.cjs';
+export { CronExpression } from '@nestjs/schedule';
+
+/** 6-digit numeric OTP code, uniformly distributed from 100000..999999. */
+declare function generateOtpCode(): string;
+/** SHA-256 hash of an OTP code (hex). OTPs are never stored in plaintext. */
+declare function hashOtpCode(code: string): string;
+/**
+ * Constant-time comparison of an OTP hash against a plaintext code.
+ * Prevents timing attacks against short numeric codes.
+ */
+declare function verifyOtpCode(expectedHash: string, code: string): boolean;
+/**
+ * Club/Tenant slug from a plaintext name.
+ * Lowercase, ASCII, only a-z0-9 and hyphen.
+ * Whitespace and special characters are collapsed to '-'.
+ * The result is never empty (fallback `'verein'`).
+ */
+declare function slugify(name: string): string;
+
+declare const PENDING_REGISTRATION_REPOSITORY_TOKEN: unique symbol;
+declare const REGISTRATION_OTP_DELIVERY_TOKEN: unique symbol;
+declare const USER_ACCOUNT_LOOKUP_TOKEN: unique symbol;
+declare const SLUG_AVAILABILITY_CHECK_TOKEN: unique symbol;
+declare const PASSWORD_HASHER_TOKEN: unique symbol;
+declare const PLAN_CATALOG_LOOKUP_TOKEN: unique symbol;
+declare const PAYMENT_PROVIDER_TOKEN: unique symbol;
+declare const PAYMENT_EVENT_LOG_TOKEN: unique symbol;
+declare const ACTIVATION_ORCHESTRATOR_TOKEN: unique symbol;
+declare const REGISTRATION_AUDIT_LOGGER_TOKEN: unique symbol;
+declare const REGISTRATION_RESUME_TOKEN_SIGNER_TOKEN: unique symbol;
+declare const REGISTRATION_RESUME_DELIVERY_TOKEN: unique symbol;
+declare const REGISTRATION_RESUME_BASE_URL_TOKEN: unique symbol;
+declare const REGISTRATION_CONFIGURATOR_LOOKUP_TOKEN: unique symbol;
+declare const REGISTRATION_PROMO_PREVIEW_TOKEN: unique symbol;
+/** SPEC_V2 §11.1 M5.3 — published BusinessTypeVersion lookup for configurator selection. */
+declare const REGISTRATION_BUSINESS_TYPE_LOOKUP_TOKEN: unique symbol;
+/** Optionally injectable configuration — falls back to default TTLs from saas-platform-types. */
+declare const REGISTRATION_CONFIG_TOKEN: unique symbol;
+interface PasswordHasher {
+    hash(plain: string): Promise<string>;
+    verify(hash: string, plain: string): Promise<boolean>;
+}
+
+/**
+ * Orchestrates step 1 (capture registration data) and step 2 (OTP verification)
+ * of the multi-step registration flow.
+ *
+ * Important invariants:
+ *  - `start()` ALWAYS returns a neutral response (account-enumeration protection).
+ *  - The OTP is only stored as a SHA-256 hash, never in plaintext.
+ *  - Passwords are hashed by the injected PasswordHasher (usually Argon2).
+ *  - On a rate-limit hit the OTP send is silently discarded — no 429 response,
+ *    otherwise an attacker could infer the existence of a PendingRegistration
+ *    record from the status code.
+ *  - OTP failed attempts are counted persistently: at `OTP_VERIFY_MAX_ATTEMPTS`
+ *    `verifyOtp()` throws `OTP_LOCKED` — even for a subsequently correct code.
+ *    Only a newly generated OTP (resend, rate-limited separately) unlocks it.
+ */
+declare class PendingRegistrationService {
+    private readonly repo;
+    private readonly otpDelivery;
+    private readonly userLookup;
+    private readonly slugCheck;
+    private readonly passwordHasher;
+    private readonly planCatalog;
+    private readonly paymentProvider;
+    private readonly paymentEventLog;
+    private readonly activationOrchestrator;
+    private readonly audit;
+    private readonly resumeTokenSigner?;
+    private readonly resumeDelivery?;
+    private readonly resumeBaseUrl?;
+    private readonly configuratorLookup?;
+    private readonly promoPreview?;
+    private readonly businessTypeLookup?;
+    private readonly logger;
+    constructor(repo: PendingRegistrationRepository, otpDelivery: RegistrationOtpDelivery, userLookup: UserAccountLookup, slugCheck: SlugAvailabilityCheck, passwordHasher: PasswordHasher, planCatalog: PlanCatalogLookup, paymentProvider: PaymentProvider, paymentEventLog: PaymentEventLog, activationOrchestrator: ActivationOrchestrator, audit: RegistrationAuditLogger, resumeTokenSigner?: RegistrationResumeTokenSigner | undefined, resumeDelivery?: RegistrationResumeDelivery | undefined, resumeBaseUrl?: string | undefined, configuratorLookup?: RegistrationConfiguratorLookup | undefined, promoPreview?: RegistrationPromoPreview | undefined, businessTypeLookup?: RegistrationBusinessTypeLookup | undefined);
+    private record;
+    /** Public signup plan list for step 3 (frontend `usePublicPlans()`). */
+    listPublicPlans(): Promise<PublicSignupPlan[]>;
+    selectPlan(input: SelectPlanInput, context?: RegistrationAuditContext): Promise<SelectPlanResult>;
+    startCheckout(input: StartCheckoutInput, context?: RegistrationAuditContext): Promise<StartCheckoutResult>;
+    /**
+     * Processes a payment webhook idempotently:
+     *  1. `tryClaim` pins the event ID via a @unique INSERT. Duplicates are
+     *     dropped silently (`ALREADY_PROCESSED`).
+     *  2. On status `SUCCEEDED` the PendingRegistration is resolved from the
+     *     checkout session and the ActivationOrchestrator triggers the final
+     *     user+tenant+subscription creation in a single transaction.
+     *  3. After activation the PendingRegistration is deleted.
+     *
+     * On errors in step 2/3 the EventLog entry remains — provider retries then
+     * run into ALREADY_PROCESSED. Operational repair is done manually (status
+     * inspection + cleanup).
+     */
+    handlePaymentEvent(input: HandlePaymentEventInput, context?: RegistrationAuditContext): Promise<HandlePaymentEventResult>;
+    /**
+     * Deletes all PendingRegistration records with `expiresAt < now`.
+     * Full deletion (no anonymization path) is the simpler option: the schema
+     * holds `email`, `firstName`, `lastName`, `passwordHash` as NOT NULL, and
+     * the unique email is exactly what needs to become free again after expiry.
+     *
+     * The batch `limit` guards against memory spikes on large backlogs — the
+     * caller (cron) keeps calling until `moreAvailable === false`.
+     */
+    runCleanup(now: Date, limit?: number): Promise<CleanupResult>;
+    start(input: StartRegistrationInput, context?: RegistrationAuditContext): Promise<StartRegistrationResult>;
+    verifyOtp(emailRaw: string, code: string, context?: RegistrationAuditContext): Promise<VerifyRegistrationOtpResult>;
+    resendOtp(emailRaw: string, context?: RegistrationAuditContext): Promise<StartRegistrationResult>;
+    private regenerateOtp;
+    private deliverOtp;
+    /**
+     * Creates a signed resume token (60 min TTL) and sends a magic link to the
+     * stored email. Mail send errors are logged but not escalated
+     * (account-enumeration protection).
+     */
+    private sendResumeLink;
+    /**
+     * Resolves a resume token to the matching onboarding step. Called by the
+     * frontend from `/register?resume=<jwt>`. On an invalid token the method
+     * throws `RESUME_TOKEN_INVALID`.
+     *
+     * Also returns a public-safe snapshot of the PendingRegistration so the
+     * frontend can prefill completed steps with the existing data (first name /
+     * last name, organization name, plan selection ...).
+     */
+    resumeWithToken(input: ResumeRegistrationInput, context?: RegistrationAuditContext): Promise<ResumeRegistrationResult>;
+    /**
+     * Signs a short-lived resume token for an existing PendingRegistration —
+     * the login endpoint uses this to send the user into the wizard with
+     * prefill after successful password verification.
+     */
+    signResumeToken(pendingRegistrationId: string): Promise<string | null>;
+    /** Returns the (app-specific) configurator catalog. */
+    getConfiguratorCatalog(): Promise<ConfiguratorCatalog>;
+    /**
+     * Saves the configurator selection (model + cycle + promo) and returns the
+     * full price breakdown.
+     *
+     * Sets:
+     *  - `status = PLAN_SELECTED`
+     *  - `currentStep = 4`
+     *  - `selectedPlanId = <planId from the chosen model>`
+     *  - `configJson` / `billingCycle` / `appliedPromoCode`
+     *  - `expiresAt = now + ONBOARDING_TTL`
+     */
+    saveConfiguration(input: SaveRegistrationConfigInput, context?: RegistrationAuditContext): Promise<SaveRegistrationConfigResult>;
+    /**
+     * Validates a promo code against the currently stored configuration and
+     * returns a new breakdown. Does NOT modify the pending — for live preview
+     * in the frontend. If `null` is passed as `code`, the promo effect is
+     * removed.
+     */
+    previewConfigPromo(pendingRegistrationId: string, code: string | null): Promise<ConfiguratorPriceBreakdown>;
+    /**
+     * Helper for step 3 resume: the frontend needs the current breakdown when
+     * the pending already has a configuration. Pure recomputation against the
+     * catalog (without promo validation, since promos should be freshly checked
+     * anyway).
+     */
+    getCurrentBreakdown(pendingRegistrationId: string): Promise<ConfiguratorPriceBreakdown | null>;
+    private resolveSlug;
+}
+
+/**
+ * Daily cleanup cron for expired `PendingRegistration` records.
+ *
+ * Runs at 04:15 Europe/Berlin (aligned with `trial-expiration.cron` and
+ * `PromoCodeExpirer`). Deletes in batches of 500 — the cron
+ * keeps running until `moreAvailable` is false (protection against memory
+ * spikes on large backlogs).
+ *
+ * Can be disabled via `RegistrationModule.forRoot({ includeCleanupCron: false })`
+ * — e.g. for CLI boots or test setups without `ScheduleModule`.
+ */
+declare class RegistrationCleanupCron {
+    private readonly service;
+    private readonly logger;
+    constructor(service: PendingRegistrationService);
+    runDaily(): Promise<void>;
+    /**
+     * Public API: can be triggered manually from an admin endpoint /
+     * `/admin/registration/run-cleanup` (same pattern as
+     * `PromoCodeExpirer.run` in the consuming apps).
+     */
+    runCleanup(now?: Date, batchSize?: number): Promise<void>;
+}
+
+/**
+ * Configurable in-memory rate limiter (per IP, sliding window).
+ *
+ * Deliberately without external dependencies (`@nestjs/throttler`, Redis) —
+ * for the auth routes a single-instance memory bucket is sufficient. For
+ * scaled multi-instance deploys this guard should be replaced by a
+ * Redis-based counter (same CanActivate contract).
+ *
+ * The pattern matches `PromoCodeRateLimitGuard`, but is generic: subclasses
+ * pass window + limit + bucket map to the base constructor and thus create
+ * their own limits per route (login / register / OTP resend / password reset).
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class LoginRateLimitGuard extends BaseIpRateLimitGuard {
+ *     constructor() {
+ *         super({ windowMs: 15 * 60_000, limit: 10, name: 'login' });
+ *     }
+ * }
+ * ```
+ */
+declare abstract class BaseIpRateLimitGuard implements CanActivate {
+    protected readonly options: {
+        /** Sliding window in ms (e.g. 15 * 60_000 for 15 min). */
+        windowMs: number;
+        /** Max requests per window per IP. */
+        limit: number;
+        /** Telemetry name (appears in reason + logs). */
+        name: string;
+    };
+    private readonly buckets;
+    constructor(options: {
+        /** Sliding window in ms (e.g. 15 * 60_000 for 15 min). */
+        windowMs: number;
+        /** Max requests per window per IP. */
+        limit: number;
+        /** Telemetry name (appears in reason + logs). */
+        name: string;
+    });
+    canActivate(context: ExecutionContext): boolean;
+    private exceeded;
+}
+
+interface RegistrationModuleOptions {
+    pendingRegistrationRepository: ProviderSpec<PendingRegistrationRepository>;
+    otpDelivery: ProviderSpec<RegistrationOtpDelivery>;
+    userAccountLookup: ProviderSpec<UserAccountLookup>;
+    slugAvailabilityCheck: ProviderSpec<SlugAvailabilityCheck>;
+    passwordHasher: ProviderSpec<PasswordHasher>;
+    planCatalogLookup: ProviderSpec<PlanCatalogLookup>;
+    paymentProvider: ProviderSpec<PaymentProvider>;
+    paymentEventLog: ProviderSpec<PaymentEventLog>;
+    activationOrchestrator: ProviderSpec<ActivationOrchestrator>;
+    auditLogger: ProviderSpec<RegistrationAuditLogger>;
+    /**
+     * P3.4 (optional): Signs + verifies resume tokens for cases C/D
+     * (EMAIL_VERIFIED / PLAN_SELECTED / CHECKOUT_STARTED). If the port
+     * is not provided, the service falls back to OTP resend for all
+     * statuses.
+     */
+    resumeTokenSigner?: ProviderSpec<RegistrationResumeTokenSigner>;
+    /** P3.4 (optional): Sends the resume mail with a magic link. */
+    resumeDelivery?: ProviderSpec<RegistrationResumeDelivery>;
+    /** P3.4 (optional): Base URL of the app for the resume link (e.g. `https://app.example.com`). */
+    resumeBaseUrl?: string;
+    /**
+     * Phase A: Provides the app-specific configurator catalog. Without
+     * this port, `saveConfiguration()` throws `CONFIGURATOR_NOT_CONFIGURED`.
+     */
+    configuratorLookup?: ProviderSpec<RegistrationConfiguratorLookup>;
+    /**
+     * Phase A: Promo-code preview adapter (typically wraps
+     * `PromoCodesService.preview()`). Without the adapter the promo code
+     * is ignored (snapshot is stored, discount=0).
+     */
+    promoPreview?: ProviderSpec<RegistrationPromoPreview>;
+    /**
+     * SPEC_V2 §11.1 M5.3: validates an optionally set
+     * `RegistrationConfigSelection.businessTypeVersionId` against the
+     * SuperAdmin catalog (published BusinessTypeVersions). Without an adapter
+     * the ID is passed through unchecked — fine for apps without a
+     * BusinessType catalog.
+     */
+    businessTypeLookup?: ProviderSpec<RegistrationBusinessTypeLookup>;
+    /**
+     * Modules that should be visible in the DynamicModule scope — needed so
+     * that factory providers with `inject: [...]` can resolve classes from
+     * these modules. Analogous to AdminStatsModule.
+     */
+    imports?: Array<Type<unknown> | DynamicModule | ForwardReference | Promise<DynamicModule>>;
+    /**
+     * Additional providers registered directly in the DynamicModule scope.
+     * Usually the app adapters (Prisma repos, email-service wrapper,
+     * Argon2 hasher), so that their `inject: [...]` tokens are resolvable
+     * (otherwise UnknownDependenciesException on strict NestJS versions).
+     */
+    extraProviders?: Provider[];
+    /**
+     * Default `true`. Registers `RegistrationCleanupCron` (daily 04:15
+     * Europe/Berlin). Set to `false` when the consumer has no active
+     * `@nestjs/schedule` (e.g. CLI boot, unit tests).
+     */
+    includeCleanupCron?: boolean;
+    /** Register module globally — default `false`. */
+    global?: boolean;
+}
+declare class RegistrationModule {
+    static forRoot(options: RegistrationModuleOptions): DynamicModule;
+}
+
+/**
+ * Input for step 1 (registration data) — `POST /auth/register/start`.
+ * Collects Tenant and admin data in one step; the final Tenant/User creation
+ * only happens after successful payment (step 4).
+ */
+declare class RegisterStartDto {
+    /** Association/tenant name (required). */
+    tenantName: string;
+    /** Optional slug. If left empty, it is generated from `tenantName`. */
+    tenantSlug?: string;
+    /** Salutation of the administrator (optional). */
+    salutation?: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    password: string;
+    /** Terms / privacy / data processing — mandatory acceptance (must be `true`). */
+    termsAccepted: true;
+    locale?: 'de' | 'tr';
+}
+
+declare class VerifyRegistrationOtpDto {
+    email: string;
+    otp: string;
+}
+
+declare class ResendRegistrationOtpDto {
+    email: string;
+}
+
+/**
+ * Input for step 3 (plan selection) — `POST /auth/register/select-plan`.
+ * The frontend passes the PendingRegistration ID (from the verify-otp response
+ * or the login onboarding response) and the chosen PlanId.
+ */
+declare class SelectRegistrationPlanDto {
+    pendingRegistrationId: string;
+    planId: string;
+}
+
+/**
+ * Input for step 4 (start checkout) — `POST /auth/register/start-checkout`.
+ * The frontend passes the PendingRegistration ID and the redirect URLs
+ * (success / cancel) that the payment provider redirects to after the payment
+ * action.
+ */
+declare class StartRegistrationCheckoutDto {
+    pendingRegistrationId: string;
+    successUrl: string;
+    cancelUrl: string;
+}
+
+/**
+ * Webhook contract for `POST /webhooks/payment`.
+ *
+ * Provider-agnostic: the Stripe adapter (phase 2.4) maps Stripe's
+ * `checkout.session.completed` → `{ eventId, sessionId, status: 'SUCCEEDED' }`,
+ * `payment_intent.payment_failed` → `{ status: 'FAILED' }`, etc.
+ *
+ * In production the signature verification (Stripe `Stripe-Signature`
+ * header) should run BEFORE the DTO validation — see StripeWebhookGuard in
+ * the app module.
+ */
+declare class PaymentWebhookDto {
+    eventId: string;
+    sessionId?: string;
+    provider: string;
+    status: 'SUCCEEDED' | 'FAILED';
+    payload?: Record<string, unknown>;
+}
+
+/**
+ * Input for `POST /auth/register/continue`. The frontend reads the
+ * `?resume=<jwt>` query from the magic link in the resume email and passes
+ * it to this endpoint.
+ */
+declare class ContinueRegistrationDto {
+    token: string;
+}
+
+/**
+ * Configurator selection payload for `POST /auth/register/save-config`.
+ *
+ * Intentionally kept flat — model validation happens in the service against
+ * the Catalog. The DTO only checks structural types.
+ */
+declare class SaveRegistrationConfigSelectionDto {
+    modelId: string;
+    billingCycle: 'MONTHLY' | 'YEARLY';
+    appliedPromoCode?: string | null;
+    /**
+     * SPEC_V2 §11.1 M5.3 — optional business-type choice. UUID of a
+     * **published** BusinessTypeVersion. The service validates existence +
+     * live status against `RegistrationBusinessTypeLookup`. `null` = no
+     * choice (legacy Plan-only path).
+     */
+    businessTypeVersionId?: string | null;
+    /**
+     * METAMODELL §17a — Bundle consistency. ID of the `CheckoutOffer` that was
+     * created on the pricing page (`<app>/register?offer=<id>`). Passed
+     * through unchanged in `configJson`; the ActivationOrchestrator freezes it
+     * as `packageSnapshot` when the subscription is created and sets the offer
+     * to `consumed`. `null` = direct registration without a website offer.
+     */
+    offerId?: string | null;
+}
+declare class SaveRegistrationConfigDto {
+    pendingRegistrationId: string;
+    selection: SaveRegistrationConfigSelectionDto;
+}
+
+/**
+ * Input for `POST /auth/register/preview-promo`. If `code` is empty, the
+ * effect of a previously applied code is removed (preview without promo).
+ * Does NOT change the stored pending — only the preview calculation.
+ */
+declare class PreviewRegistrationPromoDto {
+    pendingRegistrationId: string;
+    code?: string;
+}
+
+interface PromoEvaluation {
+    /** Discount in EUR on the subtotal (gross or net depending on catalog convention; here on net). */
+    discountAmount: number;
+    /** Percentage for UI display. */
+    percent: number;
+    label: string;
+}
+/**
+ * Validates the selection against the catalog and returns the complete price
+ * breakdown. On invalid inputs (e.g. unknown model) it throws an `Error` — the
+ * service translates that into a BadRequestException.
+ */
+declare function computeBreakdown(catalog: ConfiguratorCatalog, selection: RegistrationConfigSelection, promo?: PromoEvaluation): ConfiguratorPriceBreakdown;
+/** Pull a model from the catalog; throws if unknown. */
+declare function resolveModel(catalog: ConfiguratorCatalog, modelId: string): {
+    planId: string;
+    monthlyNet: number;
+    yearlyNet: number;
+};
+
+export { ACTIVATION_ORCHESTRATOR_TOKEN, BaseIpRateLimitGuard, ContinueRegistrationDto, PASSWORD_HASHER_TOKEN, PAYMENT_EVENT_LOG_TOKEN, PAYMENT_PROVIDER_TOKEN, PENDING_REGISTRATION_REPOSITORY_TOKEN, PLAN_CATALOG_LOOKUP_TOKEN, type PasswordHasher, PaymentWebhookDto, PendingRegistrationService, PreviewRegistrationPromoDto, type PromoEvaluation, REGISTRATION_AUDIT_LOGGER_TOKEN, REGISTRATION_BUSINESS_TYPE_LOOKUP_TOKEN, REGISTRATION_CONFIGURATOR_LOOKUP_TOKEN, REGISTRATION_CONFIG_TOKEN, REGISTRATION_OTP_DELIVERY_TOKEN, REGISTRATION_PROMO_PREVIEW_TOKEN, REGISTRATION_RESUME_BASE_URL_TOKEN, REGISTRATION_RESUME_DELIVERY_TOKEN, REGISTRATION_RESUME_TOKEN_SIGNER_TOKEN, RegisterStartDto, RegistrationCleanupCron, RegistrationModule, type RegistrationModuleOptions, ResendRegistrationOtpDto, SLUG_AVAILABILITY_CHECK_TOKEN, SaveRegistrationConfigDto, SaveRegistrationConfigSelectionDto, SelectRegistrationPlanDto, StartRegistrationCheckoutDto, USER_ACCOUNT_LOOKUP_TOKEN, VerifyRegistrationOtpDto, computeBreakdown, generateOtpCode, hashOtpCode, resolveModel, slugify, verifyOtpCode };