api-security-shield 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,750 @@
+import { z } from 'zod';
+import { RequestHandler } from 'express';
+
+/**
+ * Shared primitive and domain types for API Security Shield.
+ */
+type ShieldEnvironment = "development" | "test" | "production";
+type ThreatCategory = "sqli" | "xss" | "bot" | "brute_force" | "honeypot" | "reputation" | "rate_limit" | "geo" | "openapi" | "custom";
+type ThreatSeverity = "low" | "medium" | "high" | "critical";
+type ThreatLevel = "low" | "watch" | "warning" | "high" | "critical";
+type ShieldActionType = "allow" | "warn" | "throttle" | "challenge" | "block" | "ban";
+type RequestLocation = "query" | "body" | "headers" | "params" | "path" | "ip" | "fingerprint";
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+interface RedactedEvidence {
+    readonly location: RequestLocation;
+    readonly sample?: string;
+    readonly patternId?: string;
+}
+interface AuthContext {
+    readonly userIdHash?: string;
+    readonly accountIdHash?: string;
+    readonly apiKeyHash?: string;
+    readonly roles?: readonly string[];
+}
+interface FingerprintResult {
+    readonly strict: string;
+    readonly loose: string;
+    readonly components: readonly string[];
+}
+interface DetectorFinding {
+    readonly id: string;
+    readonly category: ThreatCategory;
+    readonly severity: ThreatSeverity;
+    readonly confidence: number;
+    readonly score: number;
+    readonly location?: RequestLocation;
+    readonly evidence?: RedactedEvidence;
+    readonly message: string;
+}
+interface ThreatScore {
+    readonly value: number;
+    readonly level: ThreatLevel;
+    readonly reasons: readonly string[];
+    readonly findings: readonly DetectorFinding[];
+}
+interface RequestContext {
+    readonly requestId: string;
+    readonly method: string;
+    readonly path: string;
+    readonly route?: string;
+    readonly ip: string;
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    readonly query: unknown;
+    readonly body: unknown;
+    readonly params: Readonly<Record<string, string>>;
+    readonly fingerprint?: FingerprintResult;
+    readonly auth?: AuthContext;
+    readonly findings: readonly DetectorFinding[];
+    readonly score?: ThreatScore;
+}
+interface ShieldDecision {
+    readonly action: ShieldActionType;
+    readonly score: ThreatScore;
+    readonly statusCode?: number;
+    readonly reason: string;
+}
+interface ActionResult {
+    readonly handled: boolean;
+    readonly statusCode?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: JsonValue;
+}
+interface StorageHealth {
+    readonly ok: boolean;
+    readonly latencyMs?: number;
+    readonly message?: string;
+}
+
+interface FingerprintEngineOptions {
+    readonly salt?: string;
+}
+/**
+ * Basic deterministic fingerprint engine.
+ */
+declare class FingerprintEngine {
+    private readonly salt;
+    /**
+     * Creates a fingerprint engine.
+     */
+    constructor(options?: FingerprintEngineOptions);
+    /**
+     * Generates strict and loose fingerprints for a request context.
+     */
+    generate(context: RequestContext): FingerprintResult;
+    private collectStrictComponents;
+    private collectLooseComponents;
+    private header;
+    private normalizeUserAgent;
+    private hash;
+}
+
+/**
+ * Runtime configuration schema for API Security Shield.
+ */
+declare const securityShieldConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    environment: z.ZodDefault<z.ZodEnum<["development", "test", "production"]>>;
+    trustProxy: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodArray<z.ZodString, "many">]>>;
+    threatEngine: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    fingerprinting: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    adaptiveRateLimit: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    botDetection: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    bruteForce: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    sqli: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    xss: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    reputation: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    logger: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    redis: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    dashboard: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    webhooks: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+}, "strip", z.ZodTypeAny, {
+    sqli: boolean | Record<string, unknown>;
+    xss: boolean | Record<string, unknown>;
+    reputation: boolean | Record<string, unknown>;
+    enabled: boolean;
+    environment: "development" | "test" | "production";
+    threatEngine: boolean | Record<string, unknown>;
+    fingerprinting: boolean | Record<string, unknown>;
+    adaptiveRateLimit: boolean | Record<string, unknown>;
+    botDetection: boolean | Record<string, unknown>;
+    bruteForce: boolean | Record<string, unknown>;
+    logger: boolean | Record<string, unknown>;
+    trustProxy?: boolean | string[] | undefined;
+    redis?: Record<string, unknown> | undefined;
+    dashboard?: boolean | Record<string, unknown> | undefined;
+    webhooks?: Record<string, unknown>[] | undefined;
+    plugins?: unknown[] | undefined;
+}, {
+    sqli?: boolean | Record<string, unknown> | undefined;
+    xss?: boolean | Record<string, unknown> | undefined;
+    reputation?: boolean | Record<string, unknown> | undefined;
+    enabled?: boolean | undefined;
+    environment?: "development" | "test" | "production" | undefined;
+    trustProxy?: boolean | string[] | undefined;
+    threatEngine?: boolean | Record<string, unknown> | undefined;
+    fingerprinting?: boolean | Record<string, unknown> | undefined;
+    adaptiveRateLimit?: boolean | Record<string, unknown> | undefined;
+    botDetection?: boolean | Record<string, unknown> | undefined;
+    bruteForce?: boolean | Record<string, unknown> | undefined;
+    logger?: boolean | Record<string, unknown> | undefined;
+    redis?: Record<string, unknown> | undefined;
+    dashboard?: boolean | Record<string, unknown> | undefined;
+    webhooks?: Record<string, unknown>[] | undefined;
+    plugins?: unknown[] | undefined;
+}>;
+type SecurityShieldConfigInput = z.input<typeof securityShieldConfigSchema>;
+type SecurityShieldConfig = z.output<typeof securityShieldConfigSchema>;
+
+interface DetectorScanOptions {
+    readonly maxDepth?: number;
+    readonly maxValues?: number;
+    readonly maxStringLength?: number;
+    readonly headers?: readonly string[];
+}
+interface ScannedValue {
+    readonly location: RequestLocation;
+    readonly path: string;
+    readonly value: string;
+}
+/**
+ * Collects bounded string values from request locations detectors are allowed to inspect.
+ */
+declare function collectScannedValues(context: RequestContext, options?: DetectorScanOptions): readonly ScannedValue[];
+/**
+ * Produces a short redacted evidence sample.
+ */
+declare function evidenceSample(value: string): string;
+/**
+ * Safely URL-decodes a value a bounded number of times.
+ */
+declare function decodeSafely(value: string, attempts?: number): string;
+
+type ConsoleLoggerFormat = "json" | "pretty";
+interface ConsoleLoggerOptions {
+    readonly minSeverity?: SecurityEventSeverity;
+    readonly format?: ConsoleLoggerFormat;
+    readonly includeData?: boolean;
+}
+/**
+ * Console-backed event logger for development and basic production setups.
+ */
+declare class ConsoleLoggerAdapter implements SecurityEventHandler {
+    private readonly minSeverity;
+    private readonly format;
+    private readonly includeData;
+    /**
+     * Creates a console logger adapter.
+     */
+    constructor(options?: ConsoleLoggerOptions);
+    /**
+     * Handles a security event by writing it to the appropriate console method.
+     */
+    handle(event: SecurityEvent): void;
+    private shouldLog;
+    private formatEvent;
+}
+
+type EventBusHandler = (event: SecurityEvent) => void | Promise<void>;
+interface EventBusSubscriptionOptions {
+    readonly signal?: AbortSignal;
+}
+/**
+ * Typed event bus for security events.
+ */
+declare class EventBus {
+    private readonly emitter;
+    private emittingDiagnostic;
+    /**
+     * Creates an event bus instance.
+     */
+    constructor();
+    /**
+     * Subscribes to an event and returns an unsubscribe function.
+     */
+    on(event: SecurityEventType, handler: EventBusHandler, options?: EventBusSubscriptionOptions): () => void;
+    /**
+     * Subscribes to a single event occurrence.
+     */
+    once(event: SecurityEventType, handler: EventBusHandler): () => void;
+    /**
+     * Removes an event handler.
+     */
+    off(event: SecurityEventType, handler: EventBusHandler): void;
+    /**
+     * Emits an event synchronously through EventEmitter.
+     */
+    emit(event: SecurityEvent): boolean;
+    /**
+     * Emits an event and catches synchronous or asynchronous listener failures.
+     */
+    emitSafe(event: SecurityEvent): Promise<void>;
+    /**
+     * Returns the number of listeners for an event.
+     */
+    listenerCount(event: SecurityEventType): number;
+    private emitHandlerError;
+}
+
+/**
+ * Public event names emitted by the security platform.
+ */
+type SecurityEventType = "request.received" | "request.analyzed" | "threat.detected" | "threat.scored" | "action.enforced" | "rate_limit.triggered" | "rate_limit.exceeded" | "brute_force.detected" | "ip.blacklisted" | "security.alert" | "fingerprint.changed" | "honeypot.triggered" | "bot.detected" | "webhook.triggered" | "threat.blocked" | "plugin.registered" | "plugin.error" | "storage.error";
+type SecurityEventSeverity = "debug" | "info" | "warn" | "error" | "critical";
+interface SecurityEvent {
+    readonly id: string;
+    readonly type: SecurityEventType;
+    readonly timestamp: string;
+    readonly requestId?: string;
+    readonly severity: SecurityEventSeverity;
+    readonly data: JsonObject;
+}
+interface SecurityEventHandler {
+    /**
+     * Handles a security event emitted by the platform.
+     */
+    handle(event: SecurityEvent): void | Promise<void>;
+}
+interface ThreatDetectedEventData extends JsonObject {
+    readonly category: ThreatSeverity | string;
+    readonly detector: string;
+}
+
+/**
+ * Contract for request detectors that produce security findings.
+ */
+declare abstract class AbstractDetector {
+    readonly name: string;
+    readonly category: string;
+    readonly priority: number;
+    /**
+     * Creates a detector contract.
+     */
+    constructor(name: string, category: string, priority?: number);
+    /**
+     * Analyzes a request context and returns detector findings.
+     */
+    abstract analyze(context: RequestContext): Promise<readonly DetectorFinding[]> | readonly DetectorFinding[];
+}
+/**
+ * Contract for custom enforcement actions.
+ */
+declare abstract class AbstractAction {
+    readonly name: string;
+    /**
+     * Creates an action contract.
+     */
+    constructor(name: string);
+    /**
+     * Executes an action after the shield resolves a decision.
+     */
+    abstract execute(context: RequestContext, decision: ShieldDecision): Promise<ActionResult> | ActionResult;
+}
+/**
+ * Contract for scoring rules that can adjust a threat decision.
+ */
+declare abstract class AbstractScoringRule {
+    readonly name: string;
+    /**
+     * Creates a scoring rule contract.
+     */
+    constructor(name: string);
+    /**
+     * Calculates a score contribution for the request context.
+     */
+    abstract score(context: RequestContext): Promise<number> | number;
+}
+/**
+ * Contract for platform storage adapters.
+ */
+declare abstract class AbstractStorage {
+    readonly name: string;
+    /**
+     * Creates a storage adapter contract.
+     */
+    constructor(name: string);
+    /**
+     * Reads a value from storage.
+     */
+    abstract get<T>(key: string): Promise<T | null>;
+    /**
+     * Writes a value to storage.
+     */
+    abstract set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Increments a numeric value in storage.
+     */
+    abstract increment(key: string, ttlSeconds: number): Promise<number>;
+    /**
+     * Deletes a value from storage.
+     */
+    abstract delete(key: string): Promise<void>;
+    /**
+     * Reports storage health.
+     */
+    abstract health(): Promise<StorageHealth>;
+}
+/**
+ * Contract for plugins that extend the platform.
+ */
+declare abstract class AbstractPlugin {
+    readonly name: string;
+    readonly version: string;
+    /**
+     * Creates a plugin contract.
+     */
+    constructor(name: string, version: string);
+    /**
+     * Registers plugin capabilities with the host context.
+     */
+    abstract register(context: PluginContext): void | Promise<void>;
+}
+interface PluginContext {
+    /**
+     * Adds a detector to the detector pipeline.
+     */
+    addDetector(detector: AbstractDetector): void;
+    /**
+     * Adds a custom action to the action registry.
+     */
+    addAction(action: AbstractAction): void;
+    /**
+     * Adds a custom scoring rule to the scoring pipeline.
+     */
+    addScoringRule(rule: AbstractScoringRule): void;
+    /**
+     * Subscribes to a platform event.
+     */
+    on(event: SecurityEventType, handler: (event: SecurityEvent) => void | Promise<void>): void;
+}
+
+interface SqlInjectionPattern {
+    readonly id: string;
+    readonly pattern: RegExp;
+    readonly score: number;
+    readonly confidence: number;
+    readonly severity: DetectorFinding["severity"];
+    readonly message: string;
+}
+interface SqlInjectionDetectorOptions extends DetectorScanOptions {
+    readonly patterns?: readonly SqlInjectionPattern[];
+}
+/**
+ * Detects common SQL injection payloads in bounded request fields.
+ */
+declare class SqlInjectionDetector extends AbstractDetector {
+    private readonly options;
+    private readonly patterns;
+    /**
+     * Creates a SQL injection detector.
+     */
+    constructor(options?: SqlInjectionDetectorOptions);
+    /**
+     * Analyzes request values for SQL injection patterns.
+     */
+    analyze(context: RequestContext): readonly DetectorFinding[];
+}
+
+interface XssPattern {
+    readonly id: string;
+    readonly pattern: RegExp;
+    readonly score: number;
+    readonly confidence: number;
+    readonly severity: DetectorFinding["severity"];
+    readonly message: string;
+}
+interface XssDetectorOptions extends DetectorScanOptions {
+    readonly patterns?: readonly XssPattern[];
+}
+/**
+ * Detects common cross-site scripting payloads in bounded request fields.
+ */
+declare class XssDetector extends AbstractDetector {
+    private readonly options;
+    private readonly patterns;
+    /**
+     * Creates an XSS detector.
+     */
+    constructor(options?: XssDetectorOptions);
+    /**
+     * Analyzes request values for XSS patterns.
+     */
+    analyze(context: RequestContext): readonly DetectorFinding[];
+}
+
+interface BasicThreatEngineOptions {
+    readonly detectors?: readonly AbstractDetector[];
+    readonly warnAt?: number;
+    readonly blockAt?: number;
+    readonly criticalAt?: number;
+    readonly eventBus?: EventBus;
+}
+interface ThreatEngineResult {
+    readonly context: RequestContext;
+    readonly findings: readonly DetectorFinding[];
+    readonly score: ThreatScore;
+    readonly decision: ShieldDecision;
+}
+/**
+ * Basic deterministic threat engine for Phase 1 detection and enforcement.
+ */
+declare class BasicThreatEngine {
+    private readonly detectors;
+    private readonly warnAt;
+    private readonly blockAt;
+    private readonly criticalAt;
+    private readonly eventBus?;
+    /**
+     * Creates a basic threat engine.
+     */
+    constructor(options?: BasicThreatEngineOptions);
+    /**
+     * Runs detectors, calculates score, resolves action, and emits security events.
+     */
+    analyze(context: RequestContext): Promise<ThreatEngineResult>;
+    private calculateScore;
+    private resolveLevel;
+    private resolveDecision;
+    private eventSeverity;
+}
+
+interface BruteForceProtectionOptions {
+    readonly storage?: AbstractStorage;
+    readonly eventBus?: EventBus;
+    readonly loginRoutes?: readonly string[];
+    readonly maxAttempts?: number;
+    readonly windowSeconds?: number;
+    readonly lockSeconds?: number;
+    readonly accountResolver?: (context: RequestContext) => string | null;
+}
+interface BruteForceResult {
+    readonly allowed: boolean;
+    readonly routeMatched: boolean;
+    readonly identity: string;
+    readonly attempts: number;
+    readonly locked: boolean;
+    readonly retryAfterSeconds: number;
+    readonly reason: string;
+}
+/**
+ * Tracks repeated login attempts by account and IP and applies temporary locks.
+ */
+declare class BruteForceProtection {
+    private readonly storage;
+    private readonly eventBus?;
+    private readonly loginRoutes;
+    private readonly maxAttempts;
+    private readonly windowSeconds;
+    private readonly lockSeconds;
+    private readonly accountResolver;
+    /**
+     * Creates brute force protection.
+     */
+    constructor(options?: BruteForceProtectionOptions);
+    /**
+     * Checks whether the request is currently locked by brute force policy.
+     */
+    check(context: RequestContext): Promise<BruteForceResult>;
+    /**
+     * Records a login attempt and locks identity after too many attempts.
+     */
+    recordAttempt(context: RequestContext): Promise<BruteForceResult>;
+    /**
+     * Records a failed authentication attempt for host application integrations.
+     */
+    recordFailure(context: RequestContext): Promise<BruteForceResult>;
+    /**
+     * Clears brute force counters after successful authentication.
+     */
+    recordSuccess(context: RequestContext): Promise<void>;
+    private isLoginRoute;
+    private identity;
+    private safe;
+    private attemptKey;
+    private lockKey;
+    private result;
+    private emitDetected;
+}
+
+interface RouteRateLimitPolicy {
+    readonly route: string;
+    readonly limit: number;
+    readonly windowSeconds: number;
+}
+interface AdaptiveRateLimiterOptions {
+    readonly storage?: AbstractStorage;
+    readonly eventBus?: EventBus;
+    readonly defaultLimit?: number;
+    readonly windowSeconds?: number;
+    readonly blockDurationSeconds?: number;
+    readonly highRiskLimit?: number;
+    readonly highRiskScore?: number;
+    readonly identityResolver?: (context: RequestContext) => string;
+    readonly routePolicies?: readonly RouteRateLimitPolicy[];
+}
+interface RateLimitResult {
+    readonly allowed: boolean;
+    readonly identity: string;
+    readonly key: string;
+    readonly limit: number;
+    readonly remaining: number;
+    readonly count: number;
+    readonly resetAt: string;
+    readonly retryAfterSeconds: number;
+    readonly blocked: boolean;
+    readonly reason: string;
+}
+/**
+ * Adaptive rate limiter with route-aware and risk-aware limits.
+ */
+declare class AdaptiveRateLimiter {
+    private readonly storage;
+    private readonly eventBus?;
+    private readonly defaultLimit;
+    private readonly windowSeconds;
+    private readonly blockDurationSeconds;
+    private readonly highRiskLimit;
+    private readonly highRiskScore;
+    private readonly identityResolver;
+    private readonly routePolicies;
+    /**
+     * Creates an adaptive rate limiter.
+     */
+    constructor(options?: AdaptiveRateLimiterOptions);
+    /**
+     * Evaluates and records a request against the adaptive rate-limit policy.
+     */
+    evaluate(context: RequestContext, score?: ThreatScore): Promise<RateLimitResult>;
+    /**
+     * Converts a denied rate-limit result into a shield decision.
+     */
+    toDecision(result: RateLimitResult): ShieldDecision;
+    private resolvePolicy;
+    private result;
+    private safeIdentity;
+    private emitTriggered;
+}
+
+interface RedisStorageOptions {
+    readonly url?: string;
+    readonly keyPrefix?: string;
+    readonly client?: RedisLike;
+    readonly connectTimeoutMs?: number;
+}
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode?: "EX", ttlSeconds?: number): Promise<unknown>;
+    incr(key: string): Promise<number>;
+    expire(key: string, ttlSeconds: number): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    ping(): Promise<string>;
+}
+
+interface MemoryStorageOptions {
+    readonly now?: () => number;
+}
+/**
+ * Error thrown when memory storage receives invalid input.
+ */
+declare class MemoryStorageError extends Error {
+    /**
+     * Creates a memory storage error.
+     */
+    constructor(message: string);
+}
+/**
+ * In-memory storage adapter for development, tests, and single-process deployments.
+ */
+declare class MemoryStorageAdapter extends AbstractStorage {
+    private readonly entries;
+    private readonly now;
+    /**
+     * Creates a memory storage adapter.
+     */
+    constructor(options?: MemoryStorageOptions);
+    /**
+     * Reads a value from storage if the key exists and has not expired.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Writes a value to storage with an optional TTL.
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Increments a numeric value, initializing missing values at zero.
+     */
+    increment(key: string, ttlSeconds: number): Promise<number>;
+    /**
+     * Deletes a value from storage.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Reports memory storage health.
+     */
+    health(): Promise<StorageHealth>;
+    /**
+     * Removes all values from storage.
+     */
+    clear(): void;
+    /**
+     * Returns the number of non-expired values.
+     */
+    size(): number;
+    private validateKey;
+    private validateTtl;
+    private resolveExpiresAt;
+    private isExpired;
+    private pruneExpired;
+}
+
+interface IpReputationOptions {
+    readonly storage?: AbstractStorage;
+    readonly eventBus?: EventBus;
+    readonly historyTtlSeconds?: number;
+    readonly blacklistTtlSeconds?: number;
+    readonly blacklistScore?: number;
+    readonly scoreDecay?: number;
+}
+interface IpReputationRecord {
+    readonly ip: string;
+    readonly score: number;
+    readonly firstSeen: string;
+    readonly lastSeen: string;
+    readonly requests: number;
+    readonly threats: number;
+}
+interface IpReputationResult {
+    readonly ip: string;
+    readonly score: number;
+    readonly allowed: boolean;
+    readonly whitelisted: boolean;
+    readonly blacklisted: boolean;
+    readonly reason: string;
+}
+/**
+ * Tracks IP behavior, reputation score, and allow/block state.
+ */
+declare class IpReputationService {
+    private readonly storage;
+    private readonly eventBus?;
+    private readonly historyTtlSeconds;
+    private readonly blacklistTtlSeconds;
+    private readonly blacklistScore;
+    private readonly scoreDecay;
+    /**
+     * Creates an IP reputation service.
+     */
+    constructor(options?: IpReputationOptions);
+    /**
+     * Assesses whether an IP is currently allowed.
+     */
+    assess(context: RequestContext): Promise<IpReputationResult>;
+    /**
+     * Records threat activity and blacklists IPs that exceed the threshold.
+     */
+    recordThreat(context: RequestContext, score: ThreatScore, findings: readonly DetectorFinding[]): Promise<IpReputationRecord>;
+    /**
+     * Adds an IP to the whitelist.
+     */
+    whitelist(ip: string, ttlSeconds?: number): Promise<void>;
+    /**
+     * Adds an IP to the blacklist.
+     */
+    blacklist(ip: string, reason: string, ttlSeconds?: number, requestId?: string): Promise<void>;
+    private touch;
+    private getRecord;
+    private result;
+    private normalizeIp;
+    private recordKey;
+    private allowKey;
+    private blockKey;
+}
+
+type SecurityShieldMiddlewareOptions = SecurityShieldConfigInput & {
+    readonly eventBus?: EventBus;
+    readonly loggerOptions?: ConsoleLoggerOptions;
+    readonly storage?: AbstractStorage;
+    readonly detectors?: readonly AbstractDetector[];
+    readonly fingerprintOptions?: FingerprintEngineOptions;
+    readonly threatEngineOptions?: Omit<BasicThreatEngineOptions, "detectors" | "eventBus">;
+    readonly sqliOptions?: SqlInjectionDetectorOptions;
+    readonly xssOptions?: XssDetectorOptions;
+    readonly redisStorageOptions?: RedisStorageOptions;
+    readonly rateLimiter?: AdaptiveRateLimiter;
+    readonly rateLimiterOptions?: Omit<AdaptiveRateLimiterOptions, "storage" | "eventBus">;
+    readonly ipReputation?: IpReputationService;
+    readonly ipReputationOptions?: Omit<IpReputationOptions, "storage" | "eventBus">;
+    readonly bruteForceProtection?: BruteForceProtection;
+    readonly bruteForceOptions?: Omit<BruteForceProtectionOptions, "storage" | "eventBus">;
+};
+/**
+ * Creates Express middleware for Phase 1 API security analysis.
+ */
+declare function securityShield(options?: SecurityShieldMiddlewareOptions): RequestHandler;
+
+export { AbstractAction, AbstractDetector, AbstractPlugin, AbstractScoringRule, AbstractStorage, type ActionResult, type AuthContext, BasicThreatEngine, type BasicThreatEngineOptions, ConsoleLoggerAdapter, type ConsoleLoggerFormat, type ConsoleLoggerOptions, type DetectorFinding, type DetectorScanOptions, EventBus, type EventBusHandler, type EventBusSubscriptionOptions, FingerprintEngine, type FingerprintEngineOptions, type FingerprintResult, type JsonObject, type JsonPrimitive, type JsonValue, MemoryStorageAdapter, MemoryStorageError, type MemoryStorageOptions, type PluginContext, type RedactedEvidence, type RequestContext, type RequestLocation, type ScannedValue, type SecurityEvent, type SecurityEventHandler, type SecurityEventSeverity, type SecurityEventType, type SecurityShieldConfig, type SecurityShieldConfigInput, type SecurityShieldMiddlewareOptions, type ShieldActionType, type ShieldDecision, type ShieldEnvironment, SqlInjectionDetector, type SqlInjectionDetectorOptions, type StorageHealth, type ThreatCategory, type ThreatDetectedEventData, type ThreatEngineResult, type ThreatLevel, type ThreatScore, type ThreatSeverity, XssDetector, type XssDetectorOptions, collectScannedValues, decodeSafely, evidenceSample, securityShield, securityShieldConfigSchema };