@stacksjs/ts-cloud 0.7.108 → 0.7.109

package/dist/protection/controls.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Operator controls for edge protection.
+ *
+ * The generators in `ddos.ts` and `waf.ts` decide what a box does in the
+ * ordinary case. This is the set of levers someone reaches for during an
+ * incident, when the ordinary case is not what is happening:
+ *
+ *   - **Attack mode** challenges every visitor, not only the suspicious ones.
+ *   - **IP rules** allow or block specific ranges outright.
+ *   - **Pausing mitigations** turns automatic blocking off for a project whose
+ *     legitimate traffic is being caught by it.
+ *
+ * Two of these are dangerous in opposite directions, and both are time-boxed
+ * for that reason. Attack mode challenges real users, so leaving it on
+ * indefinitely is a slow outage. Pausing mitigations means paying for whatever
+ * arrives, so leaving *that* on indefinitely is a slow invoice. Neither
+ * defaults to permanent, and both record who did it.
+ */
+import type { ControlPlaneStore } from '../control-plane';
+import type { RateLimitRule } from './ratelimit';
+import type { DdosConfig } from './ddos';
+export declare const PROTECTION_SETTING = "protection.controls";
+/** The hardest ceiling on a temporary control, matching what operators expect. */
+export declare const MAX_CONTROL_HOURS = 24;
+/** Attack mode defaults short: it challenges real users while it is on. */
+export declare const DEFAULT_ATTACK_MODE_HOURS = 4;
+export interface TimeBoxedControl {
+    enabled: boolean;
+    /** ISO timestamp. The control is inert past it, with no action needed. */
+    expiresAt: string;
+    startedAt: string;
+    reason: string;
+    actorId?: string;
+}
+export interface IpRules {
+    /** CIDRs that bypass every limit. */
+    allow: string[];
+    /** CIDRs refused outright. */
+    block: string[];
+}
+export interface ProtectionControls {
+    attackMode?: TimeBoxedControl;
+    /** Automatic mitigation suspended. You pay for what arrives while it is on. */
+    mitigationPause?: TimeBoxedControl;
+    ipRules: IpRules;
+    updatedAt?: string;
+}
+export declare class ProtectionControlStore {
+    private readonly controlPlane;
+    private readonly options;
+    constructor(controlPlane: ControlPlaneStore, options?: {
+        now?: () => Date;
+    });
+    private now;
+    private read;
+    private write;
+    /** Everything as stored, expired controls included. For an audit view. */
+    raw(): ProtectionControls;
+    /** Only what is in force right now. What the enforcement path should read. */
+    current(): {
+        attackMode?: TimeBoxedControl;
+        mitigationPause?: TimeBoxedControl;
+        ipRules: IpRules;
+    };
+    /**
+     * Challenge every visitor for a bounded window.
+     *
+     * The expiry is the point. An operator who enables this at 2am must not have
+     * to remember to turn it off, because the failure mode of forgetting is that
+     * every real user keeps getting challenged and nobody connects the two.
+     */
+    enableAttackMode(input: {
+        hours?: number;
+        reason: string;
+        actorId?: string;
+    }): TimeBoxedControl;
+    disableAttackMode(): boolean;
+    /**
+     * Suspend automatic mitigation for a project being caught by it.
+     *
+     * A reason is required, not optional. This is the control that costs money
+     * while it is on, and "why is our bill up" should be answerable from the
+     * record rather than from memory.
+     */
+    pauseMitigations(input: {
+        hours?: number;
+        reason: string;
+        actorId?: string;
+    }): TimeBoxedControl;
+    resumeMitigations(): boolean;
+    /** Add a CIDR to the allow or block list. Validated before it is stored. */
+    addIpRule(list: 'allow' | 'block', cidr: string): IpRules;
+    removeIpRule(list: 'allow' | 'block', cidr: string): IpRules;
+}
+export interface ProtectionPosture {
+    attackMode: boolean;
+    mitigationPaused: boolean;
+    /** Human-readable, for a dashboard banner and a CLI line. */
+    summary: string;
+    expiresAt?: string;
+}
+export declare function describePosture(controls: ReturnType<ProtectionControlStore['current']>): ProtectionPosture;
+/**
+ * Apply the controls to a rate-limit rule set.
+ *
+ * Attack mode does not tighten the numbers - it changes the *action*. A limit
+ * low enough to stop an attack by counting would also stop a real user, whereas
+ * a challenge lets a browser through and a script not. Pausing mitigations
+ * disables the rules outright, which is the honest reading of "paused".
+ */
+export declare function applyControlsToRateLimits(rules: readonly RateLimitRule[], controls: ReturnType<ProtectionControlStore['current']>): RateLimitRule[];
+/** Apply the controls to a firewall config before it is rendered. */
+export declare function applyControlsToDdos(config: DdosConfig, controls: ReturnType<ProtectionControlStore['current']>): DdosConfig;

package/dist/protection/controls.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/protection/ddos.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Layer 3/4 DDoS mitigation for a box we control.
+ *
+ * ts-cloud has no anycast scrubbing network, and pretending otherwise would be
+ * dishonest - a 500 Gbps flood saturates the uplink before any of this runs.
+ * What this does cover is the attack traffic that actually reaches most
+ * self-hosted infrastructure: SYN floods, connection exhaustion, slow-loris,
+ * amplified UDP, and single-source hammering. Those are stopped in the kernel,
+ * for free, and stopping them there is the difference between a box that
+ * degrades and a box that falls over.
+ *
+ * Everything here *generates configuration* rather than executing it, which is
+ * the pattern the rest of the driver layer already uses (see `ufw.ts` and
+ * `image-recipe.ts`): the deploy renders it, ships it, and reconciles it, so a
+ * rule survives a reprovision instead of living only in a live `iptables`
+ * table that the next boot discards.
+ */
+export interface DdosThresholds {
+    /** New connections per second, per source IP, before the source is dropped. */
+    newConnectionsPerSecond: number;
+    /** Concurrent established connections allowed from one source IP. */
+    concurrentPerSource: number;
+    /** SYN packets per second accepted platform-wide before SYN cookies do the work. */
+    synPerSecond: number;
+    /** Burst allowance on top of the per-second rates. */
+    burst: number;
+    /** ICMP echo requests per second. Ping stays useful; ping floods do not. */
+    icmpPerSecond: number;
+    /** Seconds a source stays in the drop set once it trips a limit. */
+    banSeconds: number;
+}
+export declare const DEFAULT_DDOS_THRESHOLDS: DdosThresholds;
+export interface DdosConfig {
+    enabled?: boolean;
+    thresholds?: Partial<DdosThresholds>;
+    /** Ports the ruleset protects. 80 and 443 unless told otherwise. */
+    ports?: number[];
+    /** CIDRs that bypass every limit: monitoring, office IPs, a load balancer. */
+    allowlist?: string[];
+    /** CIDRs dropped outright. */
+    blocklist?: string[];
+    /**
+     * Count without dropping. The way to deploy a ruleset on a live box and see
+     * what it *would* have blocked before it blocks anything.
+     */
+    monitorOnly?: boolean;
+    /** Also drop traffic that reaches the box bypassing the CDN, when one is used. */
+    originProtection?: {
+        enabled: boolean;
+        cdnRanges: string[];
+    };
+}
+/**
+ * Validate a CIDR before it reaches a generated ruleset.
+ *
+ * The list is operator-supplied and goes straight into a file the kernel
+ * parses; an unvalidated entry is both a syntax error that bricks the ruleset
+ * and an injection vector into the generated script.
+ */
+export declare function isValidCidr(value: string): boolean;
+/**
+ * Kernel tunables that make a box survive a flood.
+ *
+ * `syncookies` is the important one: without it, a SYN flood fills the backlog
+ * with half-open connections and the box stops accepting anything, at a packet
+ * rate a single host can produce. The rest bound how much memory an attacker
+ * can make the kernel hold on their behalf.
+ */
+export declare function sysctlHardening(config?: DdosConfig): Record<string, string>;
+/** Render the tunables as a drop-in sysctl file. */
+export declare function renderSysctlFile(config?: DdosConfig): string;
+/**
+ * Render an nftables ruleset.
+ *
+ * nftables rather than iptables: sets and rate meters are first-class, so
+ * per-source limiting is one rule against a hash table instead of a chain that
+ * grows with the attack. The generated table is named and flushed atomically,
+ * which is what makes a redeploy idempotent instead of additive.
+ */
+export declare function renderNftablesRuleset(config?: DdosConfig): string;
+/**
+ * A script that installs the ruleset and the tunables.
+ *
+ * The validation step is not optional: an nftables file with one bad line
+ * leaves the box with no rules at all, and finding that out during an attack
+ * is the worst possible time. `nft -c` checks before anything is applied.
+ */
+export declare function renderDdosInstallScript(config?: DdosConfig): string;
+export type MitigationLevel = 'off' | 'monitor' | 'rate_limit' | 'challenge' | 'lockdown';
+export interface TrafficSignals {
+    /** Requests per second at the edge right now. */
+    requestsPerSecond: number;
+    /** The same figure under normal conditions, for comparison. */
+    baselineRequestsPerSecond: number;
+    /** Share of requests currently failing, 0-1. */
+    errorRate: number;
+    /** Distinct source IPs seen in the sampling window. */
+    uniqueSources: number;
+    /** Share of traffic from the single busiest source, 0-1. */
+    topSourceShare: number;
+    /** Established connections on the box. */
+    concurrentConnections: number;
+    /** Share of requests with no or an obviously scripted user agent, 0-1. */
+    suspiciousAgentShare?: number;
+}
+export interface MitigationPlan {
+    level: MitigationLevel;
+    reasons: string[];
+    /** Rate-limit multiplier to apply to normal limits; 1 means unchanged. */
+    rateLimitFactor: number;
+    /** Ask suspicious clients to prove they are a browser. */
+    challengeEnabled: boolean;
+    /** Only serve cached and static responses; skip dynamic rendering. */
+    staticOnly: boolean;
+    /** Sources worth adding to the drop set. */
+    banCandidates: string[];
+}
+/**
+ * Choose a mitigation level from live signals.
+ *
+ * Traffic volume alone is a bad trigger: a launch and an attack look identical
+ * on a request-rate graph, and mitigating a launch is a self-inflicted outage.
+ * The distinguishing signals are *shape* - a real surge arrives from many
+ * sources with a normal error rate, an attack concentrates on few sources, or
+ * drives errors, or both. Escalation needs volume plus at least one shape
+ * signal; volume by itself only ever reaches `monitor`.
+ */
+export declare function planMitigation(signals: TrafficSignals, topSources?: readonly string[]): MitigationPlan;
+/** Scale a rate limit by a mitigation plan, never below 1. */
+export declare function applyMitigationFactor(limit: number, plan: MitigationPlan): number;

package/dist/protection/ddos.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/protection/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Recursion protection lives in `@ts-cloud/core` because the function runtime
+ * has to run it, and the runtime cannot depend on this package. Re-exported
+ * here so `ts-cloud/protection` stays the one place to find edge protection.
+ */
+export { CHAIN_HEADER, DEFAULT_RECURSION_LIMITS, DEPTH_HEADER, functionFingerprint, inspectInvocation, parseChain, propagationHeaders, RecursionGuard, recursionBlockedResponse, TRACE_HEADER, } from '@ts-cloud/core';
+export type { InvocationContext, RecursionLimits, RecursionReason, RecursionVerdict, } from '@ts-cloud/core';
+export * from './ratelimit';
+export * from './ddos';
+export * from './controls';
+export * from './waf';

package/dist/protection/index.js

@@ -0,0 +1,87 @@
+import {
+  DEFAULT_ATTACK_MODE_HOURS,
+  MAX_CONTROL_HOURS,
+  PROTECTION_SETTING,
+  ProtectionControlStore,
+  RATE_LIMIT_KEY_SEPARATOR,
+  RateLimiter,
+  applyControlsToDdos,
+  applyControlsToRateLimits,
+  defaultRateLimitRules,
+  describePosture,
+  globMatches,
+  rateLimitHeaders,
+  rateLimitKey,
+  ruleMatches
+} from "../chunk-xrtwv3v2.js";
+import {
+  escapeSecLang,
+  globToRegex,
+  isSafePattern,
+  renderWafConfig,
+  renderWafInstallScript,
+  wafEventTelemetry
+} from "../chunk-va2yd85b.js";
+import {
+  DEFAULT_DDOS_THRESHOLDS,
+  applyMitigationFactor,
+  isValidCidr,
+  planMitigation,
+  renderDdosInstallScript,
+  renderNftablesRuleset,
+  renderSysctlFile,
+  sysctlHardening
+} from "../chunk-aa2dkn7b.js";
+import {
+  CHAIN_HEADER,
+  DEFAULT_RECURSION_LIMITS,
+  DEPTH_HEADER,
+  RecursionGuard,
+  TRACE_HEADER,
+  functionFingerprint,
+  inspectInvocation,
+  parseChain,
+  propagationHeaders,
+  recursionBlockedResponse
+} from "../chunk-t2s3gdq6.js";
+import"../chunk-v0bahtg2.js";
+export {
+  wafEventTelemetry,
+  sysctlHardening,
+  ruleMatches,
+  renderWafInstallScript,
+  renderWafConfig,
+  renderSysctlFile,
+  renderNftablesRuleset,
+  renderDdosInstallScript,
+  recursionBlockedResponse,
+  rateLimitKey,
+  rateLimitHeaders,
+  propagationHeaders,
+  planMitigation,
+  parseChain,
+  isValidCidr,
+  isSafePattern,
+  inspectInvocation,
+  globToRegex,
+  globMatches,
+  functionFingerprint,
+  escapeSecLang,
+  describePosture,
+  defaultRateLimitRules,
+  applyMitigationFactor,
+  applyControlsToRateLimits,
+  applyControlsToDdos,
+  TRACE_HEADER,
+  RecursionGuard,
+  RateLimiter,
+  RATE_LIMIT_KEY_SEPARATOR,
+  ProtectionControlStore,
+  PROTECTION_SETTING,
+  MAX_CONTROL_HOURS,
+  DEPTH_HEADER,
+  DEFAULT_RECURSION_LIMITS,
+  DEFAULT_DDOS_THRESHOLDS,
+  DEFAULT_ATTACK_MODE_HOURS,
+  CHAIN_HEADER
+};

package/dist/protection/ratelimit.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Layer 7 rate limiting - the application-aware half of DDoS mitigation.
+ *
+ * L3/L4 filtering (see `ddos.ts`) stops packet floods, but the expensive
+ * attacks now are perfectly valid HTTP: a few thousand requests a second to a
+ * route that renders a page, hits a database, or invokes a function. Those
+ * cost real money per request and no packet filter can tell them from traffic.
+ *
+ * Two algorithms, because they answer different questions:
+ *
+ *   - **Token bucket** allows a burst and then a steady rate. Right for
+ *     interactive traffic, where a page load legitimately fires twenty
+ *     requests at once and then goes quiet.
+ *   - **Sliding window** counts precisely over a period. Right for quotas
+ *     ("100 signups an hour") where a burst is exactly what you want to stop.
+ *
+ * Everything is clock-injected and in-memory. A limiter that consults a shared
+ * store on every request adds a network hop to the hot path of the thing it is
+ * protecting, which is how rate limiting becomes the outage.
+ */
+export type RateLimitAlgorithm = 'token_bucket' | 'sliding_window';
+export type RateLimitAction = 'allow' | 'log' | 'throttle' | 'challenge' | 'deny';
+/** Where the identity being limited comes from. */
+export type RateLimitKeySource = 'ip' | 'header' | 'cookie' | 'path' | 'host' | 'global';
+export interface RateLimitKeySpec {
+    source: RateLimitKeySource;
+    /** Header or cookie name when the source needs one. */
+    name?: string;
+    /**
+     * Fall back to the client IP when the named header or cookie is absent.
+     *
+     * On by default: without it, an attacker omits the header and becomes
+     * unlimited, which is worse than no rule at all.
+     */
+    fallbackToIp?: boolean;
+}
+export interface RateLimitRule {
+    id: string;
+    /** Requests allowed per window (sliding) or refill target (bucket). */
+    limit: number;
+    windowMs: number;
+    algorithm?: RateLimitAlgorithm;
+    /** Token-bucket burst ceiling. Defaults to `limit`. */
+    burst?: number;
+    key?: RateLimitKeySpec;
+    /** Glob against the path, e.g. `/api/*`. Omit to match every path. */
+    path?: string;
+    /** HTTP methods this rule covers. Omit for all. */
+    methods?: string[];
+    /** Host to match, exact or `*.example.com`. */
+    host?: string;
+    action?: RateLimitAction;
+    /** Rules are evaluated low-to-high; the first blocking match wins. */
+    priority?: number;
+    enabled?: boolean;
+}
+export interface RequestDescriptor {
+    ip: string;
+    method: string;
+    path: string;
+    host?: string;
+    headers?: Record<string, string | undefined>;
+    cookies?: Record<string, string | undefined>;
+}
+export interface RateLimitDecision {
+    action: RateLimitAction;
+    allowed: boolean;
+    ruleId?: string;
+    limit?: number;
+    remaining?: number;
+    /** Milliseconds until the caller may retry. */
+    retryAfterMs?: number;
+    /** When the current window or bucket is fully replenished. */
+    resetAt?: number;
+    key?: string;
+}
+/**
+ * Separates the rule id from the identity in a counter key.
+ *
+ * A NUL rather than a space or a colon: rule ids and header values are both
+ * caller-supplied, and any printable separator lets one key be forged into
+ * another's bucket.
+ */
+export declare const RATE_LIMIT_KEY_SEPARATOR = "\0";
+/**
+ * Glob matcher for paths and hosts.
+ *
+ * Deliberately tiny: `*` within a segment, `**` across segments, and a leading
+ * `*.` for host wildcards. A full regex surface in a rule that runs on every
+ * request is an invitation to catastrophic backtracking.
+ */
+export declare function globMatches(pattern: string, value: string): boolean;
+export declare function ruleMatches(rule: RateLimitRule, request: RequestDescriptor): boolean;
+/** Build the counter key for a request under a rule. */
+export declare function rateLimitKey(rule: RateLimitRule, request: RequestDescriptor): string;
+/**
+ * Rate limiter over a set of rules.
+ *
+ * `check` is side-effecting - it consumes quota - so a caller that only wants
+ * to inspect state should use `peek`.
+ */
+export declare class RateLimiter {
+    private readonly clock;
+    private readonly maxTrackedKeys;
+    private readonly buckets;
+    private readonly windows;
+    private readonly rules;
+    constructor(rules: readonly RateLimitRule[], clock?: () => number, maxTrackedKeys?: number);
+    /**
+     * Evaluate every matching rule and return the strictest outcome.
+     *
+     * Two phases, and the order matters. First every matching rule is *tested*;
+     * only if they all have room does anything get consumed.
+     *
+     * Testing first is what keeps overlapping rules honest. Consuming as you go
+     * charges a request to the global counter even when a per-IP rule already
+     * refused it - so a single hammering client silently burns the budget that
+     * protects everyone else, and the global limit fires against innocent
+     * traffic. Consuming all rules for a request that is *allowed* is equally
+     * necessary: stop at the first match and the lower-priority counters never
+     * advance, and those rules quietly stop working.
+     */
+    check(request: RequestDescriptor): RateLimitDecision;
+    /** Non-mutating availability check for one rule. */
+    private test;
+    /** Inspect without consuming quota. */
+    peek(request: RequestDescriptor): RateLimitDecision;
+    private msPerToken;
+    private refill;
+    private blocked;
+    private consume;
+    /**
+     * Bound memory under an attack that rotates keys.
+     *
+     * A source IP per request is exactly what a botnet produces, so an unbounded
+     * map turns a rate limiter into an OOM. Dropping the oldest insertion is
+     * enough: the entries that matter are the ones seeing repeat traffic.
+     */
+    private evictIfNeeded;
+    /** Drop state for keys that have gone quiet. Cheap to call on a timer. */
+    sweep(): number;
+    get trackedKeys(): number;
+}
+/** Standard headers for a decision, so clients can back off intelligently. */
+export declare function rateLimitHeaders(decision: RateLimitDecision): Record<string, string>;
+/**
+ * Baseline rules every site gets.
+ *
+ * Chosen to be invisible to a human and expensive for a script: 600 requests a
+ * minute per IP is ten a second, far above real browsing and far below what a
+ * scraper wants. The per-route rules protect the endpoints that cost the most
+ * per call rather than the ones that get the most traffic.
+ */
+export declare function defaultRateLimitRules(): RateLimitRule[];

package/dist/protection/ratelimit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/protection/waf.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Web application firewall: generating zig-waf configuration.
+ *
+ * ts-cloud does not implement request inspection itself. `zig-waf` already is
+ * that engine - a ModSecurity/Coraza-compatible SecLang implementation with
+ * OWASP CRS anomaly scoring, native SQLi detection, and a `validate`
+ * subcommand - and a second, worse regex-based inspector living here would be
+ * a liability rather than defence in depth.
+ *
+ * The three layers divide cleanly, and none of them substitutes for another:
+ *
+ *   - `ddos.ts`  L3/L4. Packet floods, SYN storms, connection exhaustion.
+ *                Kernel-level, no idea what HTTP is.
+ *   - this file  L7 *content*. Is this request an attack? Injection, traversal,
+ *                scanners, protocol abuse. Delegated to zig-waf.
+ *   - `ratelimit.ts` L7 *volume*. Is this caller asking for too much? zig-waf
+ *                has no rate limiting at all, so this stays in-process.
+ *
+ * **zig-waf is pre-alpha and says so.** Generated configs therefore default to
+ * detection-only: rules evaluate, matches are logged and scored, nothing is
+ * blocked. Turning that into enforcement is a deliberate act by an operator
+ * who has read their own detection log, not something a deploy does quietly.
+ */
+import type { RateLimitRule } from './ratelimit';
+export type WafMode = 'off' | 'detection' | 'blocking';
+/**
+ * OWASP CRS paranoia level.
+ *
+ * 1 is the only level safe to enable unattended: it is tuned for near-zero
+ * false positives. Each level above trades precision for recall, and 3-4 will
+ * block legitimate traffic on almost any real application until tuned.
+ */
+export type ParanoiaLevel = 1 | 2 | 3 | 4;
+export interface WafRuleExclusion {
+    /** CRS rule id to disable. */
+    ruleId: number;
+    /** Only for requests to paths matching this regex. Omit to disable globally. */
+    pathPattern?: string;
+    /** Why, so the exclusion can be reviewed rather than inherited forever. */
+    reason: string;
+}
+export interface WafConfig {
+    mode?: WafMode;
+    paranoiaLevel?: ParanoiaLevel;
+    /**
+     * Inbound anomaly score at which a request is blocked, when mode is
+     * `blocking`. The CRS default is 5, which one critical-severity match
+     * reaches on its own.
+     */
+    inboundThreshold?: number;
+    /** Outbound score threshold, guarding against data leaking back out. */
+    outboundThreshold?: number;
+    /** Largest request body inspected, in bytes. Beyond it, see `rejectOversizedBody`. */
+    maxBodyBytes?: number;
+    /**
+     * Reject a body too large to inspect, rather than passing it through
+     * unexamined. Defaults to true: an attacker who can opt out of inspection by
+     * padding a request has defeated the WAF.
+     */
+    rejectOversizedBody?: boolean;
+    /** Paths never inspected, e.g. a large upload endpoint. Each one is a hole. */
+    bypassPaths?: string[];
+    exclusions?: WafRuleExclusion[];
+    /** Extra SecLang appended verbatim, for rules ts-cloud has no model for. */
+    customRules?: string[];
+    /** Where the engine writes its audit log. */
+    auditLogPath?: string;
+    /** Status returned to a blocked request. */
+    blockStatus?: number;
+}
+/**
+ * Escape a value for a SecLang double-quoted argument.
+ *
+ * Config text is assembled from operator input (paths, patterns, reasons); an
+ * unescaped quote or newline ends the argument early and everything after it
+ * becomes directives. That is config injection, and it is the one way a WAF
+ * config file can make a system less safe than having none.
+ */
+export declare function escapeSecLang(value: string): string;
+/**
+ * Whether a regex is safe to hand to the engine.
+ *
+ * Rejects nested quantifiers, the classic catastrophic-backtracking shape.
+ * A rule that hangs on one crafted request is an outage with extra steps.
+ */
+export declare function isSafePattern(pattern: string): boolean;
+export interface WafGenerationResult {
+    config: string;
+    /** Rate-limit rules that could not be expressed in SecLang, with the reason. */
+    unmappedRateLimits: Array<{
+        ruleId: string;
+        reason: string;
+    }>;
+    warnings: string[];
+    mode: WafMode;
+}
+/** Convert a ratelimit glob into an anchored regex for SecLang's `@rx`. */
+export declare function globToRegex(glob: string): string;
+/**
+ * Render a complete SecLang configuration.
+ *
+ * The output is deterministic - same input, same bytes - so a deploy can
+ * compare it against what is already on the box and skip a reload when
+ * nothing changed.
+ */
+export declare function renderWafConfig(config?: WafConfig, rateLimits?: readonly RateLimitRule[]): WafGenerationResult;
+/**
+ * Install script for the generated config.
+ *
+ * `zig-waf validate` runs before anything is swapped in, for the same reason
+ * `nft -c` does in `ddos.ts`: a config that fails to compile would otherwise
+ * leave the engine with no rules, and a WAF that silently stopped inspecting
+ * is worse than one that was never installed - the dashboard still says it is on.
+ */
+export declare function renderWafInstallScript(config?: WafConfig, rateLimits?: readonly RateLimitRule[], options?: {
+    binary?: string;
+    configPath?: string;
+}): string;
+/**
+ * A WAF audit event, normalized for the telemetry pipeline.
+ *
+ * Blocked requests are a spend signal as much as a security one: a scraper
+ * that the WAF stops still consumed the bandwidth to be stopped, and a sudden
+ * rise in blocks is often the first visible symptom of an attack that is about
+ * to show up on the bill.
+ */
+export interface WafEvent {
+    timestamp: string;
+    ruleId?: number;
+    anomalyScore: number;
+    action: 'passed' | 'logged' | 'blocked';
+    clientIp: string;
+    method: string;
+    path: string;
+    host?: string;
+    messages: string[];
+}
+/** Telemetry records for a batch of WAF events, ready for the spend meter. */
+export declare function wafEventTelemetry(events: readonly WafEvent[], scope: {
+    projectId: string;
+    environmentId?: string;
+    resourceId?: string;
+}): Array<Record<string, unknown>>;

package/dist/protection/waf.test.d.ts

@@ -0,0 +1 @@
+export {};