@consilioweb/payload-support 4.0.0 → 6.0.0

package/dist/index.d.cts

@@ -11,9 +11,29 @@ interface RateLimitStore {
 /**
  * Process-local fallback store. Applications running more than one process
  * should provide a persistent RateLimitStore through the plugin options.
+ *
+ * BOUNDED, because the keys come from anonymous HTTP traffic: `/support/login`
+ * and `/support/chatbot` key their limiter on the client IP, and the IP is read
+ * from `x-forwarded-for`. A caller rotating that header wrote one PERMANENT
+ * entry per value into a map that had no ceiling, no expiry sweep and no
+ * eviction — only `reset()` ever removed anything, and the login path never
+ * calls it. Worse, every fresh key opened a fresh window, so the limiter did
+ * not even slow down the flood that was exhausting it.
+ *
+ * Two independent bounds, the same pair `endpoints/typing.ts` already applies
+ * to its own module-level map: `clientIpRateKey` caps the SIZE of a key, the
+ * ceiling below caps their NUMBER.
  */
 declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly maxKeys;
     private readonly entries;
+    constructor(maxKeys?: number);
+    /** Distinct keys currently held. Exposed so the ceiling can be asserted. */
+    get size(): number;
+    /** Reclaims every window that has already closed. */
+    private sweepExpired;
+    /** Soonest-closing window first, so the ceiling drops the least useful entry. */
+    private evictOldest;
     increment(key: string, windowMs: number): Promise<RateLimitEntry>;
     reset(key: string): Promise<void>;
 }
@@ -45,6 +65,94 @@ declare class RateLimiter {
     reset(key: string, context?: unknown): Promise<void>;
 }
 
+/**
+ * Default collection slugs used by the support plugin.
+ * All slugs can be overridden via SupportPluginConfig.collectionSlugs.
+ */
+interface CollectionSlugs {
+    tickets: string;
+    ticketMessages: string;
+    supportClients: string;
+    timeEntries: string;
+    cannedResponses: string;
+    ticketActivityLog: string;
+    satisfactionSurveys: string;
+    knowledgeBase: string;
+    chatMessages: string;
+    pendingEmails: string;
+    emailLogs: string;
+    authLogs: string;
+    webhookEndpoints: string;
+    slaPolicies: string;
+    macros: string;
+    ticketStatuses: string;
+    ticketFeedback: string;
+    notificationQueue: string;
+    automationRules: string;
+    supportTeams: string;
+    pushSubscriptions: string;
+    rateLimits: string;
+    counters: string;
+    users: string;
+    media: string;
+}
+declare const DEFAULT_SLUGS: CollectionSlugs;
+/**
+ * Resolve collection slugs merging user overrides with defaults.
+ */
+declare function resolveSlugs(overrides?: Partial<CollectionSlugs>): CollectionSlugs;
+
+/**
+ * How long the two journals are kept, in days.
+ *
+ * Defaults follow the CNIL guidance the README documents: six months would be
+ * the floor for connection logs, a year is the ceiling usually accepted, and
+ * these two values sit inside that range while staying long enough to
+ * investigate an intrusion. Set a value to 0 to disable the automatic purge of
+ * that journal — never to mean "delete everything", which is what `days=0`
+ * means on the manual endpoint.
+ */
+interface RetentionConfig {
+    /** Retention of `auth-logs` in days. `0` disables the scheduled purge. */
+    authLogsDays?: number;
+    /** Retention of `email-logs` in days. `0` disables the scheduled purge. */
+    emailLogsDays?: number;
+    /**
+     * Cron for the scheduled purge. Payload's cron takes an optional leading
+     * seconds field. Default: every day at 03:30.
+     */
+    cron?: string;
+    /** Queue the scheduled job is pushed to. Default: `default`. */
+    queue?: string;
+}
+declare const DEFAULT_RETENTION: {
+    readonly authLogsDays: 180;
+    readonly emailLogsDays: 365;
+    readonly cron: "0 30 3 * * *";
+    readonly queue: "default";
+};
+declare const PURGE_LOGS_TASK_SLUG = "support-purge-logs";
+/** Journals the purge is allowed to touch, keyed by their public name. */
+declare function purgeableCollections(slugs: CollectionSlugs): Record<string, string>;
+/**
+ * Delete rows of `slug` created more than `days` days ago.
+ *
+ * `days <= 0` means "everything" and is only reachable from the manual
+ * admin-only endpoint. The scheduled task refuses it: a misconfigured cron
+ * that wipes the whole security journal every night is a far worse outcome
+ * than a journal that grows.
+ */
+declare function purgeOlderThan(payload: Payload, slug: string, days: number, req?: PayloadRequest): Promise<number>;
+interface ScheduledPurgeResult {
+    purged: Record<string, number>;
+    skipped: string[];
+}
+/**
+ * The scheduled half of the purge. Never accepts `days <= 0`, and silently
+ * skips a journal whose collection is not registered (its feature flag is off).
+ */
+declare function runScheduledPurge(payload: Payload, slugs: CollectionSlugs, retention: RetentionConfig | false | undefined, req?: PayloadRequest): Promise<ScheduledPurgeResult>;
+
 interface InboundEmailLimits {
     maxRequestBytes: number;
     maxAttachmentBytes: number;
@@ -208,6 +316,24 @@ interface SupportPluginConfig {
     email?: EmailConfig;
     /** Shared rate-limit storage. Defaults to process-local memory. */
     rateLimitStore?: RateLimitStore | 'payload';
+    /**
+     * Automatic retention of the two journals the plugin writes.
+     *
+     * The plugin registers a daily Payload Jobs task that deletes rows older
+     * than the configured number of days. Set a value to 0 to keep that journal
+     * forever (the manual `DELETE /api/support/purge-logs` endpoint stays
+     * available either way).
+     *
+     * Defaults: auth-logs 180 days, email-logs 365 days, cron `0 30 3 * * *`.
+     *
+     * `false` registers no task at all. That is the ONLY value that changes the
+     * schema footprint: registering a task turns Payload's job queue on, which
+     * adds the `payload-jobs` collection and the `payload-jobs-stats` global to
+     * an app that had no jobs — two tables you would have to migrate. Pass
+     * `false` if you would rather purge from your own cron, calling
+     * `DELETE /api/support/purge-logs`.
+     */
+    retention?: RetentionConfig | false;
     /** Sequential ticket number formatting. */
     ticketNumber?: {
         prefix?: string;
@@ -356,43 +482,6 @@ declare const DEFAULT_FEATURES: Required<SupportFeatures>;
  */
 declare function supportPlugin(config?: SupportPluginConfig): Plugin;
 
-/**
- * Default collection slugs used by the support plugin.
- * All slugs can be overridden via SupportPluginConfig.collectionSlugs.
- */
-interface CollectionSlugs {
-    tickets: string;
-    ticketMessages: string;
-    supportClients: string;
-    timeEntries: string;
-    cannedResponses: string;
-    ticketActivityLog: string;
-    satisfactionSurveys: string;
-    knowledgeBase: string;
-    chatMessages: string;
-    pendingEmails: string;
-    emailLogs: string;
-    authLogs: string;
-    webhookEndpoints: string;
-    slaPolicies: string;
-    macros: string;
-    ticketStatuses: string;
-    ticketFeedback: string;
-    notificationQueue: string;
-    automationRules: string;
-    supportTeams: string;
-    pushSubscriptions: string;
-    rateLimits: string;
-    counters: string;
-    users: string;
-    media: string;
-}
-declare const DEFAULT_SLUGS: CollectionSlugs;
-/**
- * Resolve collection slugs merging user overrides with defaults.
- */
-declare function resolveSlugs(overrides?: Partial<CollectionSlugs>): CollectionSlugs;
-
 /**
  * Ticketing feature flags — single source of truth (client + server).
  *
@@ -690,4 +779,4 @@ declare function createTicketStatusesCollection(slugs: CollectionSlugs): Collect
  */
 declare function createTicketCollaboratorsCollection(slugs: CollectionSlugs): CollectionConfig;
 
-export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_TICKETING_FEATURES, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type SatisfactionSurveyData, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type SupportSettingsState, type TicketData, type TicketSynthesisResult, type TicketingFeatures, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, normalizeFeatures, projectAutoClose, readSupportSettings, readSupportSettingsState, readUserPrefs, resolveSlugs, stripProjectedFeatures, supportPlugin, validateInboundEmailPayload, verifySecret };
+export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_RETENTION, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_TICKETING_FEATURES, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PURGE_LOGS_TASK_SLUG, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type RetentionConfig, type SatisfactionSurveyData, type ScheduledPurgeResult, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type SupportSettingsState, type TicketData, type TicketSynthesisResult, type TicketingFeatures, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, normalizeFeatures, projectAutoClose, purgeOlderThan, purgeableCollections, readSupportSettings, readSupportSettingsState, readUserPrefs, resolveSlugs, runScheduledPurge, stripProjectedFeatures, supportPlugin, validateInboundEmailPayload, verifySecret };

package/dist/index.d.ts

@@ -11,9 +11,29 @@ interface RateLimitStore {
 /**
  * Process-local fallback store. Applications running more than one process
  * should provide a persistent RateLimitStore through the plugin options.
+ *
+ * BOUNDED, because the keys come from anonymous HTTP traffic: `/support/login`
+ * and `/support/chatbot` key their limiter on the client IP, and the IP is read
+ * from `x-forwarded-for`. A caller rotating that header wrote one PERMANENT
+ * entry per value into a map that had no ceiling, no expiry sweep and no
+ * eviction — only `reset()` ever removed anything, and the login path never
+ * calls it. Worse, every fresh key opened a fresh window, so the limiter did
+ * not even slow down the flood that was exhausting it.
+ *
+ * Two independent bounds, the same pair `endpoints/typing.ts` already applies
+ * to its own module-level map: `clientIpRateKey` caps the SIZE of a key, the
+ * ceiling below caps their NUMBER.
  */
 declare class MemoryRateLimitStore implements RateLimitStore {
+    private readonly maxKeys;
     private readonly entries;
+    constructor(maxKeys?: number);
+    /** Distinct keys currently held. Exposed so the ceiling can be asserted. */
+    get size(): number;
+    /** Reclaims every window that has already closed. */
+    private sweepExpired;
+    /** Soonest-closing window first, so the ceiling drops the least useful entry. */
+    private evictOldest;
     increment(key: string, windowMs: number): Promise<RateLimitEntry>;
     reset(key: string): Promise<void>;
 }
@@ -45,6 +65,94 @@ declare class RateLimiter {
     reset(key: string, context?: unknown): Promise<void>;
 }
 
+/**
+ * Default collection slugs used by the support plugin.
+ * All slugs can be overridden via SupportPluginConfig.collectionSlugs.
+ */
+interface CollectionSlugs {
+    tickets: string;
+    ticketMessages: string;
+    supportClients: string;
+    timeEntries: string;
+    cannedResponses: string;
+    ticketActivityLog: string;
+    satisfactionSurveys: string;
+    knowledgeBase: string;
+    chatMessages: string;
+    pendingEmails: string;
+    emailLogs: string;
+    authLogs: string;
+    webhookEndpoints: string;
+    slaPolicies: string;
+    macros: string;
+    ticketStatuses: string;
+    ticketFeedback: string;
+    notificationQueue: string;
+    automationRules: string;
+    supportTeams: string;
+    pushSubscriptions: string;
+    rateLimits: string;
+    counters: string;
+    users: string;
+    media: string;
+}
+declare const DEFAULT_SLUGS: CollectionSlugs;
+/**
+ * Resolve collection slugs merging user overrides with defaults.
+ */
+declare function resolveSlugs(overrides?: Partial<CollectionSlugs>): CollectionSlugs;
+
+/**
+ * How long the two journals are kept, in days.
+ *
+ * Defaults follow the CNIL guidance the README documents: six months would be
+ * the floor for connection logs, a year is the ceiling usually accepted, and
+ * these two values sit inside that range while staying long enough to
+ * investigate an intrusion. Set a value to 0 to disable the automatic purge of
+ * that journal — never to mean "delete everything", which is what `days=0`
+ * means on the manual endpoint.
+ */
+interface RetentionConfig {
+    /** Retention of `auth-logs` in days. `0` disables the scheduled purge. */
+    authLogsDays?: number;
+    /** Retention of `email-logs` in days. `0` disables the scheduled purge. */
+    emailLogsDays?: number;
+    /**
+     * Cron for the scheduled purge. Payload's cron takes an optional leading
+     * seconds field. Default: every day at 03:30.
+     */
+    cron?: string;
+    /** Queue the scheduled job is pushed to. Default: `default`. */
+    queue?: string;
+}
+declare const DEFAULT_RETENTION: {
+    readonly authLogsDays: 180;
+    readonly emailLogsDays: 365;
+    readonly cron: "0 30 3 * * *";
+    readonly queue: "default";
+};
+declare const PURGE_LOGS_TASK_SLUG = "support-purge-logs";
+/** Journals the purge is allowed to touch, keyed by their public name. */
+declare function purgeableCollections(slugs: CollectionSlugs): Record<string, string>;
+/**
+ * Delete rows of `slug` created more than `days` days ago.
+ *
+ * `days <= 0` means "everything" and is only reachable from the manual
+ * admin-only endpoint. The scheduled task refuses it: a misconfigured cron
+ * that wipes the whole security journal every night is a far worse outcome
+ * than a journal that grows.
+ */
+declare function purgeOlderThan(payload: Payload, slug: string, days: number, req?: PayloadRequest): Promise<number>;
+interface ScheduledPurgeResult {
+    purged: Record<string, number>;
+    skipped: string[];
+}
+/**
+ * The scheduled half of the purge. Never accepts `days <= 0`, and silently
+ * skips a journal whose collection is not registered (its feature flag is off).
+ */
+declare function runScheduledPurge(payload: Payload, slugs: CollectionSlugs, retention: RetentionConfig | false | undefined, req?: PayloadRequest): Promise<ScheduledPurgeResult>;
+
 interface InboundEmailLimits {
     maxRequestBytes: number;
     maxAttachmentBytes: number;
@@ -208,6 +316,24 @@ interface SupportPluginConfig {
     email?: EmailConfig;
     /** Shared rate-limit storage. Defaults to process-local memory. */
     rateLimitStore?: RateLimitStore | 'payload';
+    /**
+     * Automatic retention of the two journals the plugin writes.
+     *
+     * The plugin registers a daily Payload Jobs task that deletes rows older
+     * than the configured number of days. Set a value to 0 to keep that journal
+     * forever (the manual `DELETE /api/support/purge-logs` endpoint stays
+     * available either way).
+     *
+     * Defaults: auth-logs 180 days, email-logs 365 days, cron `0 30 3 * * *`.
+     *
+     * `false` registers no task at all. That is the ONLY value that changes the
+     * schema footprint: registering a task turns Payload's job queue on, which
+     * adds the `payload-jobs` collection and the `payload-jobs-stats` global to
+     * an app that had no jobs — two tables you would have to migrate. Pass
+     * `false` if you would rather purge from your own cron, calling
+     * `DELETE /api/support/purge-logs`.
+     */
+    retention?: RetentionConfig | false;
     /** Sequential ticket number formatting. */
     ticketNumber?: {
         prefix?: string;
@@ -356,43 +482,6 @@ declare const DEFAULT_FEATURES: Required<SupportFeatures>;
  */
 declare function supportPlugin(config?: SupportPluginConfig): Plugin;
 
-/**
- * Default collection slugs used by the support plugin.
- * All slugs can be overridden via SupportPluginConfig.collectionSlugs.
- */
-interface CollectionSlugs {
-    tickets: string;
-    ticketMessages: string;
-    supportClients: string;
-    timeEntries: string;
-    cannedResponses: string;
-    ticketActivityLog: string;
-    satisfactionSurveys: string;
-    knowledgeBase: string;
-    chatMessages: string;
-    pendingEmails: string;
-    emailLogs: string;
-    authLogs: string;
-    webhookEndpoints: string;
-    slaPolicies: string;
-    macros: string;
-    ticketStatuses: string;
-    ticketFeedback: string;
-    notificationQueue: string;
-    automationRules: string;
-    supportTeams: string;
-    pushSubscriptions: string;
-    rateLimits: string;
-    counters: string;
-    users: string;
-    media: string;
-}
-declare const DEFAULT_SLUGS: CollectionSlugs;
-/**
- * Resolve collection slugs merging user overrides with defaults.
- */
-declare function resolveSlugs(overrides?: Partial<CollectionSlugs>): CollectionSlugs;
-
 /**
  * Ticketing feature flags — single source of truth (client + server).
  *
@@ -690,4 +779,4 @@ declare function createTicketStatusesCollection(slugs: CollectionSlugs): Collect
  */
 declare function createTicketCollaboratorsCollection(slugs: CollectionSlugs): CollectionConfig;
 
-export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_TICKETING_FEATURES, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type SatisfactionSurveyData, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type SupportSettingsState, type TicketData, type TicketSynthesisResult, type TicketingFeatures, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, normalizeFeatures, projectAutoClose, readSupportSettings, readSupportSettingsState, readUserPrefs, resolveSlugs, stripProjectedFeatures, supportPlugin, validateInboundEmailPayload, verifySecret };
+export { type AIProviderConfig, type ActivityEntryData, type CannedResponseData, type ClientData, type CollectionSlugs, DEFAULT_FEATURES, DEFAULT_INBOUND_EMAIL_LIMITS, DEFAULT_RETENTION, DEFAULT_SETTINGS, DEFAULT_SLUGS, DEFAULT_TICKETING_FEATURES, DEFAULT_USER_PREFS, type EmailConfig, type InboundEmailInput, type InboundEmailLimits, type InboundEmailValidationError, MemoryRateLimitStore, type MessageData, PURGE_LOGS_TASK_SLUG, PayloadRateLimitStore, type RateLimitEntry, type RateLimitStore, RateLimiter, type RetentionConfig, type SatisfactionSurveyData, type ScheduledPurgeResult, type SupportFeatures, type SupportPluginConfig, type SupportSettings, type SupportSettingsState, type TicketData, type TicketSynthesisResult, type TicketingFeatures, type TimeEntryData, type UserPrefs, calculateBusinessHoursDeadline, createAdminNotification, createAssignSlaDeadlines, createAuthLogsCollection, createCannedResponsesCollection, createChatMessagesCollection, createCheckSlaOnReply, createCheckSlaOnResolve, createEmailLogsCollection, createKnowledgeBaseCollection, createLoginEndpoint, createMacrosCollection, createOAuthGoogleEndpoint, createPendingEmailsCollection, createSatisfactionSurveysCollection, createSlaPoliciesCollection, createSupportClientsCollection, createTicketActivityLogCollection, createTicketCollaboratorsCollection, createTicketMessagesCollection, createTicketStatusEmail, createTicketStatusesCollection, createTicketsCollection, createTimeEntriesCollection, createTrackOpenEndpoint, createWebhookEndpointsCollection, dispatchWebhook, generateTicketSynthesis, normalizeFeatures, projectAutoClose, purgeOlderThan, purgeableCollections, readSupportSettings, readSupportSettingsState, readUserPrefs, resolveSlugs, runScheduledPurge, stripProjectedFeatures, supportPlugin, validateInboundEmailPayload, verifySecret };