Merge main checkpoint c01a388 into feat/erp-inventar-export

Brings the ERP inventory export up to date with the platform backbone and
field capture work. Conflicts in ARCHITECTURE.md, the API key service and
the API key settings tab resolved by keeping both sides:
- read and write keys stay separate; erp-inventory:read is read-only and
  cannot be combined with a write scope
- the failed-attempt lockout counts in the shared ThrottlerHit table so it
  holds across API pods
- the UI offers only scopes the user holds and creates one scope per key

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

ApiCore-Backend/src/api-keys/failed-attempt-limiter.ts

@@ -1,94 +1,57 @@
-export interface FailedAttemptLimiterOptions {
-  /** Ab so vielen Fehlversuchen im Fenster ist die Quelle gesperrt. */
-  maxFailures: number;
-  /** Länge des Fensters in Millisekunden, gezählt ab dem ersten Fehlversuch. */
-  windowMs: number;
-  /** Obergrenze gemerkter Quellen - schützt den Speicher bei verteilten Angriffen. */
-  maxTrackedSources: number;
-  clock?: () => number;
-}
+import { Injectable } from '@nestjs/common';
+import { PrismaThrottlerStorage } from '../common/throttler/prisma-throttler.storage';
 
-interface Window {
-  failures: number;
-  startedAt: number;
+/**
+ * Unknown, revoked or expired keys per client network before that network
+ * gets 429 for further invalid keys - the same budget the ERP export
+ * contract names (docs/erp-inventar-export.md). It slows down guessing and a
+ * misconfigured client; a valid key is never refused by it. Otherwise
+ * anyone able to send requests from (or forge) a shared address - the
+ * cluster egress, a proxy - could lock ERPNext or the shop out, and a key
+ * holds 256 random bits, so letting it through costs nothing.
+ */
+export const API_KEY_FAILURE_LIMIT = {
+  maxFailures: 20,
+  windowMs: 15 * 60 * 1000,
+} as const;
+
+/**
+ * Throttler name and key prefix of these counters in "ThrottlerHit", so
+ * they never mix with the request rate limits stored in the same table.
+ */
+export const API_KEY_FAILURE_THROTTLER = 'api-key-failures';
+
+export interface FailedAttemptVerdict {
+  /** The source is over the limit: refuse the request with 429. */
+  blocked: boolean;
+  /** This failure is the one that reached the limit (once per window). */
+  limitReached: boolean;
 }
 
 /**
- * Zählt fehlgeschlagene Anmeldungen je Quelle (Client-IP) in einem festen
- * Zeitfenster und sperrt die Quelle, sobald die Obergrenze erreicht ist.
- *
- * Bewusst im Speicher des Prozesses, wie der globale Throttler: ApiCore läuft
- * mit einem Backend-Pod. Nach einem Neustart beginnt die Zählung von vorn -
- * das ist für eine Bremse gegen Durchprobieren ausreichend.
+ * Counts invalid API keys per source (client network) in the shared,
+ * database-backed rate-limit storage, so the limit holds across all api
+ * pods. One upsert per failure, every time comparison on the database
+ * clock (PrismaThrottlerStorage). The window starts with the first failure;
+ * the failure after the limit blocks the source for one window length.
+ * A database error propagates: the request fails instead of passing.
  */
+@Injectable()
 export class FailedAttemptLimiter {
-  private readonly windows = new Map<string, Window>();
-  private readonly clock: () => number;
+  constructor(private readonly storage: PrismaThrottlerStorage) {}
 
-  constructor(private readonly options: FailedAttemptLimiterOptions) {
-    this.clock = options.clock ?? Date.now;
-  }
-
-  isBlocked(source: string): boolean {
-    const window = this.activeWindow(source);
-    return window !== undefined && window.failures >= this.options.maxFailures;
-  }
-
-  /** Zählt einen Fehlversuch; true genau dann, wenn er die Sperre auslöst. */
-  recordFailure(source: string): boolean {
-    const now = this.clock();
-    const current = this.activeWindow(source);
-    if (!current) {
-      this.makeRoom(now);
-    }
-    const failures = (current?.failures ?? 0) + 1;
-    this.windows.set(source, {
-      failures,
-      startedAt: current?.startedAt ?? now,
-    });
-    return failures === this.options.maxFailures;
-  }
-
-  trackedSources(): number {
-    return this.windows.size;
-  }
-
-  private activeWindow(source: string): Window | undefined {
-    const window = this.windows.get(source);
-    if (window && this.clock() - window.startedAt > this.options.windowMs) {
-      this.windows.delete(source);
-      return undefined;
-    }
-    return window;
-  }
-
-  private makeRoom(now: number): void {
-    if (this.windows.size < this.options.maxTrackedSources) return;
-    for (const [source, window] of this.windows) {
-      if (now - window.startedAt > this.options.windowMs) {
-        this.windows.delete(source);
-      }
-    }
-    // Immer noch voll: lieber eine Zählung verlieren als unbegrenzt wachsen.
-    // Zuerst den ältesten nicht gesperrten Eintrag verdrängen - sonst könnte
-    // ein Angreifer mit vielen Adressen seine eigene Sperre hinausschieben.
-    // Nur wenn alle gesperrt sind, geht der älteste gesperrte (die Map behält
-    // die Einfügereihenfolge).
-    if (this.windows.size >= this.options.maxTrackedSources) {
-      const victim =
-        this.oldestWhere(
-          (window) => window.failures < this.options.maxFailures,
-        ) ?? this.oldestWhere(() => true);
-      if (victim !== undefined) this.windows.delete(victim);
-    }
-  }
-
-  private oldestWhere(
-    matches: (window: Window) => boolean,
-  ): string | undefined {
-    for (const [source, window] of this.windows) {
-      if (matches(window)) return source;
-    }
-    return undefined;
+  async recordFailure(source: string): Promise<FailedAttemptVerdict> {
+    const { maxFailures, windowMs } = API_KEY_FAILURE_LIMIT;
+    const record = await this.storage.increment(
+      `${API_KEY_FAILURE_THROTTLER}:${source}`,
+      windowMs,
+      maxFailures,
+      windowMs,
+      API_KEY_FAILURE_THROTTLER,
+    );
+    return {
+      blocked: record.isBlocked,
+      limitReached: !record.isBlocked && record.totalHits === maxFailures,
+    };
   }
 }