@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.40

package/src/foundation/router-waf-rate-rehearsal.d.ts

@@ -0,0 +1,97 @@
+export declare const ROUTER_WAF_RATE_RULE_NAME: "RateLimitPerIP";
+export declare const ROUTER_WAF_REHEARSAL_MAX_TOTAL_HTTP_REQUESTS: 2200;
+export declare const ROUTER_WAF_RATE_REHEARSAL_BASELINE_REQUESTS: 1;
+export declare const ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS: 2199;
+export declare const ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY: 16;
+export declare const ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_REQUESTS: 40;
+export declare const ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_INTERVAL_MS: 5000;
+export declare const ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_POLLS: 36;
+export declare const ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_INTERVAL_MS: 5000;
+export declare const ROUTER_WAF_RATE_REHEARSAL_MAX_RATE_LIMIT: 2159;
+type Sha256Digest = `sha256:${string}`;
+export interface RouterWafRateObservationSample {
+    action: string;
+    markerDigest: Sha256Digest;
+    method: string;
+    ruleMetricName: string;
+    ruleName: string;
+    timestamp: Date;
+    uri: string;
+}
+export interface RouterWafRateObservationMetric {
+    name: string;
+    namespace: string;
+    ruleMetricName: string;
+    timestamp: Date;
+    value: number;
+    webAclMetricName: string;
+}
+export interface RouterWafRateObservationSnapshot {
+    metrics: RouterWafRateObservationMetric[];
+    samples: RouterWafRateObservationSample[];
+}
+export interface RouterWafRateRehearsalEvidence {
+    blockedAt: string;
+    blockedRequestStatus: 403;
+    blockedSequence: number;
+    burstRequests: number;
+    concurrency: typeof ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY;
+    followUpIntervalMs: typeof ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_INTERVAL_MS;
+    followUpRequests: number;
+    maximumRequests: typeof ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS;
+    metric: {
+        name: 'BlockedRequests';
+        namespace: 'AWS/WAFV2';
+        timestamp: string;
+        value: number;
+        webAclMetricName: string;
+    };
+    observationPolls: number;
+    requestsSent: number;
+    ruleMetricName: string;
+    ruleName: typeof ROUTER_WAF_RATE_RULE_NAME;
+    sample: {
+        action: 'BLOCK';
+        markerDigest: Sha256Digest;
+        method: 'GET';
+        timestamp: string;
+        uri: string;
+    };
+    upstream429Responses: number;
+}
+export interface RouterWafRateRehearsalDependencies {
+    now?: () => Date;
+    observe: (input: {
+        endTime: Date;
+        markerDigest: Sha256Digest;
+        ruleMetricName: string;
+        sequence: number;
+        startTime: Date;
+        webAclMetricName: string;
+    }) => Promise<RouterWafRateObservationSnapshot>;
+    request: (sequence: number) => Promise<{
+        markerDigest: Sha256Digest;
+        status: number;
+    }>;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+export declare function routerWafRateRuleMetricName(stage: 'development' | 'staging'): string;
+export declare function routerWafWebAclMetricName(stage: 'development' | 'staging'): string;
+export declare function correlateRouterWafRateObservation(input: {
+    endTime: Date;
+    markerDigest: Sha256Digest;
+    ruleMetricName: string;
+    snapshot: RouterWafRateObservationSnapshot;
+    startTime: Date;
+    webAclMetricName: string;
+}): {
+    metric: RouterWafRateObservationMetric;
+    sample: RouterWafRateObservationSample;
+} | null;
+export declare function runRouterWafRateRehearsal(input: {
+    dependencies: RouterWafRateRehearsalDependencies;
+    rateLimitPerIp: number;
+    stage: 'development' | 'staging';
+    webAclMetricName: string;
+}): Promise<RouterWafRateRehearsalEvidence>;
+export {};

package/src/foundation/router-waf-rate-rehearsal.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTER_WAF_RATE_REHEARSAL_MAX_RATE_LIMIT = exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_INTERVAL_MS = exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_POLLS = exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_INTERVAL_MS = exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_REQUESTS = exports.ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY = exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS = exports.ROUTER_WAF_RATE_REHEARSAL_BASELINE_REQUESTS = exports.ROUTER_WAF_REHEARSAL_MAX_TOTAL_HTTP_REQUESTS = exports.ROUTER_WAF_RATE_RULE_NAME = void 0;
+exports.routerWafRateRuleMetricName = routerWafRateRuleMetricName;
+exports.routerWafWebAclMetricName = routerWafWebAclMetricName;
+exports.correlateRouterWafRateObservation = correlateRouterWafRateObservation;
+exports.runRouterWafRateRehearsal = runRouterWafRateRehearsal;
+exports.ROUTER_WAF_RATE_RULE_NAME = 'RateLimitPerIP';
+exports.ROUTER_WAF_REHEARSAL_MAX_TOTAL_HTTP_REQUESTS = 2_200;
+exports.ROUTER_WAF_RATE_REHEARSAL_BASELINE_REQUESTS = 1;
+exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS = (exports.ROUTER_WAF_REHEARSAL_MAX_TOTAL_HTTP_REQUESTS -
+    exports.ROUTER_WAF_RATE_REHEARSAL_BASELINE_REQUESTS);
+exports.ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY = 16;
+exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_REQUESTS = 40;
+exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_INTERVAL_MS = 5_000;
+exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_POLLS = 36;
+exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_INTERVAL_MS = 5_000;
+exports.ROUTER_WAF_RATE_REHEARSAL_MAX_RATE_LIMIT = (exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS -
+    exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_REQUESTS);
+function capitalizedStage(stage) {
+    return `${stage[0].toUpperCase()}${stage.slice(1)}`;
+}
+function routerWafRateRuleMetricName(stage) {
+    return `Ebk${capitalizedStage(stage)}RateLimitPerIP`;
+}
+function routerWafWebAclMetricName(stage) {
+    return `Ebk${capitalizedStage(stage)}FoundationRouterWaf`;
+}
+function requireDate(value, label) {
+    if (!Number.isFinite(value.getTime())) {
+        throw new Error(`${label} must be a valid timestamp.`);
+    }
+    return value;
+}
+function sameUtcMinute(left, right) {
+    return (Math.floor(left.getTime() / 60_000) === Math.floor(right.getTime() / 60_000));
+}
+function correlateRouterWafRateObservation(input) {
+    const start = requireDate(input.startTime, 'Router WAF rate window start');
+    const end = requireDate(input.endTime, 'Router WAF rate window end');
+    if (end.getTime() < start.getTime()) {
+        throw new Error('Router WAF rate observation window is reversed.');
+    }
+    for (const sample of input.snapshot.samples) {
+        const sampledAt = requireDate(sample.timestamp, 'Router WAF rate sample timestamp');
+        if (sample.ruleName !== exports.ROUTER_WAF_RATE_RULE_NAME ||
+            sample.ruleMetricName !== input.ruleMetricName ||
+            sample.action !== 'BLOCK' ||
+            sample.markerDigest !== input.markerDigest ||
+            sample.method !== 'GET' ||
+            sampledAt.getTime() < start.getTime() ||
+            sampledAt.getTime() > end.getTime()) {
+            continue;
+        }
+        const metric = input.snapshot.metrics.find((candidate) => {
+            const metricAt = requireDate(candidate.timestamp, 'Router WAF blocked metric timestamp');
+            return (candidate.namespace === 'AWS/WAFV2' &&
+                candidate.name === 'BlockedRequests' &&
+                candidate.ruleMetricName === input.ruleMetricName &&
+                candidate.webAclMetricName === input.webAclMetricName &&
+                Number.isFinite(candidate.value) &&
+                candidate.value > 0 &&
+                sameUtcMinute(sampledAt, metricAt));
+        });
+        if (metric)
+            return { metric, sample };
+    }
+    return null;
+}
+function validateRateLimit(rateLimitPerIp) {
+    if (!Number.isSafeInteger(rateLimitPerIp) || rateLimitPerIp < 100) {
+        throw new Error('Router WAF rate rehearsal requires an integer rate limit of at least 100.');
+    }
+    if (rateLimitPerIp > exports.ROUTER_WAF_RATE_REHEARSAL_MAX_RATE_LIMIT) {
+        throw new Error(`Router WAF rate limit ${rateLimitPerIp} exceeds the exact rehearsal-proveable maximum ${exports.ROUTER_WAF_RATE_REHEARSAL_MAX_RATE_LIMIT}.`);
+    }
+}
+function requireRequestResult(value, sequence) {
+    if (!Number.isSafeInteger(value.status) ||
+        value.status < 100 ||
+        value.status > 599 ||
+        !/^sha256:[a-f0-9]{64}$/.test(value.markerDigest)) {
+        throw new Error(`Router WAF rate request ${sequence} returned an invalid status or marker digest.`);
+    }
+    return value;
+}
+async function runBurst(input) {
+    let requestsSent = 0;
+    let upstream429Responses = 0;
+    for (let offset = 0; offset < input.targetRequests; offset += exports.ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY) {
+        const batchSize = Math.min(exports.ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY, input.targetRequests - offset);
+        const results = await Promise.all(Array.from({ length: batchSize }, (_, index) => input
+            .request(input.startSequence + offset + index + 1)
+            .then((value) => requireRequestResult(value, input.startSequence + offset + index + 1))));
+        requestsSent += results.length;
+        upstream429Responses += results.filter(({ status }) => status === 429).length;
+        const blockedIndex = results.findIndex(({ status }) => status === 403);
+        if (blockedIndex !== -1) {
+            return {
+                blockedAtSequence: input.startSequence + offset + blockedIndex + 1,
+                blockedMarkerDigest: results[blockedIndex]?.markerDigest ?? null,
+                requestsSent,
+                upstream429Responses,
+            };
+        }
+    }
+    return {
+        blockedAtSequence: null,
+        blockedMarkerDigest: null,
+        requestsSent,
+        upstream429Responses,
+    };
+}
+async function runRouterWafRateRehearsal(input) {
+    validateRateLimit(input.rateLimitPerIp);
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(input.webAclMetricName)) {
+        throw new Error('Router WAF rate rehearsal requires the exact physical Web ACL metric dimension.');
+    }
+    const now = input.dependencies.now ?? (() => new Date());
+    const sleep = input.dependencies.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const startedAt = requireDate(now(), 'Router WAF rate rehearsal start');
+    const burstTarget = Math.min(input.rateLimitPerIp + 160, exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS -
+        exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_REQUESTS);
+    const burst = await runBurst({
+        request: input.dependencies.request,
+        startSequence: 0,
+        targetRequests: burstTarget,
+    });
+    let blockedAtSequence = burst.blockedAtSequence;
+    let blockedMarkerDigest = burst.blockedMarkerDigest;
+    let followUpRequests = 0;
+    let requestsSent = burst.requestsSent;
+    let upstream429Responses = burst.upstream429Responses;
+    while (blockedAtSequence === null &&
+        followUpRequests < exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_REQUESTS &&
+        requestsSent < exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS) {
+        await sleep(exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_INTERVAL_MS);
+        const result = requireRequestResult(await input.dependencies.request(requestsSent + 1), requestsSent + 1);
+        followUpRequests += 1;
+        requestsSent += 1;
+        if (result.status === 429)
+            upstream429Responses += 1;
+        if (result.status === 403) {
+            blockedAtSequence = requestsSent;
+            blockedMarkerDigest = result.markerDigest;
+        }
+    }
+    if (blockedAtSequence === null || blockedMarkerDigest === null) {
+        throw new Error(`Router WAF RateLimitPerIP did not return HTTP 403 within ${requestsSent}/${exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS} requests; ${upstream429Responses} upstream HTTP 429 responses were observed but are not WAF blocking evidence.`);
+    }
+    const blockedAt = requireDate(now(), 'Router WAF rate block time');
+    const ruleMetricName = routerWafRateRuleMetricName(input.stage);
+    const webAclMetricName = input.webAclMetricName;
+    for (let observationPolls = 1; observationPolls <= exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_POLLS; observationPolls += 1) {
+        const observedAt = requireDate(now(), 'Router WAF observation time');
+        const snapshot = await input.dependencies.observe({
+            endTime: observedAt,
+            markerDigest: blockedMarkerDigest,
+            ruleMetricName,
+            sequence: blockedAtSequence,
+            startTime: startedAt,
+            webAclMetricName,
+        });
+        const correlation = correlateRouterWafRateObservation({
+            endTime: observedAt,
+            markerDigest: blockedMarkerDigest,
+            ruleMetricName,
+            snapshot,
+            startTime: startedAt,
+            webAclMetricName,
+        });
+        if (correlation) {
+            return {
+                blockedAt: blockedAt.toISOString(),
+                blockedRequestStatus: 403,
+                blockedSequence: blockedAtSequence,
+                burstRequests: burst.requestsSent,
+                concurrency: exports.ROUTER_WAF_RATE_REHEARSAL_MAX_CONCURRENCY,
+                followUpIntervalMs: exports.ROUTER_WAF_RATE_REHEARSAL_FOLLOW_UP_INTERVAL_MS,
+                followUpRequests,
+                maximumRequests: exports.ROUTER_WAF_RATE_REHEARSAL_MAX_REQUESTS,
+                metric: {
+                    name: 'BlockedRequests',
+                    namespace: 'AWS/WAFV2',
+                    timestamp: correlation.metric.timestamp.toISOString(),
+                    value: correlation.metric.value,
+                    webAclMetricName,
+                },
+                observationPolls,
+                requestsSent,
+                ruleMetricName,
+                ruleName: exports.ROUTER_WAF_RATE_RULE_NAME,
+                sample: {
+                    action: 'BLOCK',
+                    markerDigest: correlation.sample.markerDigest,
+                    method: 'GET',
+                    timestamp: correlation.sample.timestamp.toISOString(),
+                    uri: correlation.sample.uri,
+                },
+                upstream429Responses,
+            };
+        }
+        if (observationPolls < exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_POLLS) {
+            await sleep(exports.ROUTER_WAF_RATE_REHEARSAL_OBSERVATION_INTERVAL_MS);
+        }
+    }
+    throw new Error(`Router WAF returned HTTP 403, but the exact ${exports.ROUTER_WAF_RATE_RULE_NAME} BLOCK sample and correlated AWS/WAFV2 BlockedRequests metric did not appear within the bounded observation window.`);
+}
+//# sourceMappingURL=router-waf-rate-rehearsal.js.map

package/src/foundation/router-waf.d.ts

@@ -0,0 +1,149 @@
+import { type FoundationStage } from './stages.js';
+import { type DeploymentProfile } from '../repository-policy/policy.js';
+import { type RouterWafRateRehearsalEvidence } from './router-waf-rate-rehearsal.js';
+export declare const ROUTER_WAF_POLICY_KIND: "ebk-router-waf-policy";
+export declare const ROUTER_WAF_REHEARSAL_KIND: "ebk-router-waf-blocking-rehearsal";
+export declare const ROUTER_WAF_SCHEMA_VERSION: 1;
+export declare const ROUTER_WAF_CONTRACT_SCHEMA_VERSION: 1;
+export declare const ROUTER_WAF_REHEARSAL_SCHEMA_VERSION: 4;
+export declare const ROUTER_WAF_LIVE_EVIDENCE_SCHEMA_VERSION: 4;
+export declare const ROUTER_WAF_REQUIRED_MANAGED_RULES: readonly ["AWSManagedRulesCommonRuleSet", "AWSManagedRulesKnownBadInputsRuleSet", "AWSManagedRulesAmazonIpReputationList"];
+export type RouterWafAccess = 'allowlist' | 'public';
+export type RouterWafMode = 'block' | 'count';
+export interface RouterWafStagePolicy {
+    access: RouterWafAccess;
+    allowedCidrs: string[];
+    mode: RouterWafMode;
+}
+export interface RouterWafPolicy {
+    deploymentProfile: DeploymentProfile;
+    kind: typeof ROUTER_WAF_POLICY_KIND;
+    logging: {
+        enabled: boolean;
+        retention: '1 day' | '3 days' | '5 days' | '1 week' | '2 weeks';
+    };
+    rateLimitPerIp: number;
+    schemaVersion: typeof ROUTER_WAF_SCHEMA_VERSION;
+    stages: Record<'development' | 'production', RouterWafStagePolicy> & Partial<Record<'staging', RouterWafStagePolicy>>;
+}
+export interface RouterWafBlockingRehearsal {
+    accountId: string;
+    completedAt: string;
+    deploymentRoleArn: string;
+    evidenceDigest: `sha256:${string}`;
+    kind: typeof ROUTER_WAF_REHEARSAL_KIND;
+    mode: 'block';
+    policyDigest: `sha256:${string}`;
+    region: string;
+    schemaVersion: typeof ROUTER_WAF_REHEARSAL_SCHEMA_VERSION;
+    stage: 'development' | 'staging';
+    status: 'passed';
+    wafContractDigest: `sha256:${string}`;
+    workspace: string;
+}
+export interface RouterWafLiveEvidence {
+    accountId: string;
+    completedAt: string;
+    deploymentRoleArn: string;
+    distributionId: string;
+    kind: 'ebk-router-waf-live-evidence';
+    mode: 'block';
+    policyDigest: `sha256:${string}`;
+    probes: {
+        allowedRequestStatus: number;
+        cloudWatchMetricsObserved: true;
+        countModeTuningObserved: boolean;
+        managedRule: RouterWafOperatorBlockEvidence;
+        nonAllowlisted: RouterWafOperatorBlockEvidence;
+        rateLimit: RouterWafRateRehearsalEvidence;
+        sampledRequestsObserved: true;
+    };
+    region: string;
+    requiredRules: string[];
+    result: 'passed';
+    schemaVersion: typeof ROUTER_WAF_LIVE_EVIDENCE_SCHEMA_VERSION;
+    sourceCommit: string;
+    stage: 'development' | 'staging';
+    startedAt: string;
+    webAclArn: string;
+    webAclScope: 'CLOUDFRONT';
+    wafContractDigest: `sha256:${string}`;
+    workspace: string;
+}
+export interface RouterWafOperatorBlockEvidence {
+    blockedAt: string;
+    marker: string;
+    method: 'GET';
+    path: string;
+    ruleName: string;
+    status: 403;
+}
+export interface RouterWafRehearsalBinding {
+    accountId: string;
+    deploymentRoleArn: string;
+    region: string;
+    stage: 'development' | 'staging';
+    wafContractDigest: `sha256:${string}`;
+    workspace: string;
+}
+export interface RouterWafStagePlan {
+    access: RouterWafAccess;
+    ipv4Cidrs: string[];
+    ipv6Cidrs: string[];
+    logging: false | {
+        include: 'blocked';
+        redact: {
+            headers: string[];
+            queryString: true;
+        };
+        retention: RouterWafPolicy['logging']['retention'];
+    };
+    mode: RouterWafMode;
+    policyDigest: `sha256:${string}`;
+    rateLimitPerIp: number;
+    stage: FoundationStage;
+}
+type WafRule = Readonly<Record<string, unknown>>;
+export declare function normalizeRouterWafPolicy(value: unknown): RouterWafPolicy;
+export declare function routerWafPolicyDigest(policy: RouterWafPolicy): `sha256:${string}`;
+export declare function normalizeRouterWafBlockingRehearsal(value: unknown): RouterWafBlockingRehearsal | null;
+export interface ValidatedRouterWafLiveEvidenceSeed {
+    accountId: string;
+    completedAt: number;
+    deploymentRoleArn: string;
+    distributionId: string;
+    probes: Record<string, unknown>;
+    region: string;
+    stage: 'development' | 'staging';
+    startedAt: number;
+    wafContractDigest: `sha256:${string}`;
+    webAclArn: string;
+    webAclName: string;
+    workspace: string;
+}
+export declare function validateRouterWafLiveEvidenceSeed(input: {
+    evidence: unknown;
+    policy: RouterWafPolicy;
+}): ValidatedRouterWafLiveEvidenceSeed;
+export declare function createRouterWafBlockingRehearsal(input: {
+    evidence: unknown;
+    policy: RouterWafPolicy;
+}): RouterWafBlockingRehearsal;
+export declare function reconcileRouterWafBlockingRehearsal(input: {
+    evidence: unknown;
+    expected: RouterWafRehearsalBinding;
+    policy: RouterWafPolicy;
+    receipt: unknown;
+}): RouterWafBlockingRehearsal | null;
+export declare function createRouterWafStagePlan(input: {
+    policy: RouterWafPolicy;
+    rehearsal: RouterWafBlockingRehearsal | null;
+    stage: string;
+}): RouterWafStagePlan;
+export declare function createRouterWafRules(plan: RouterWafStagePlan, ipSets: {
+    ipv4Arn?: unknown;
+    ipv6Arn?: unknown;
+    smokeArn?: unknown;
+}): WafRule[];
+export declare function routerWafContractDigest(policy: RouterWafPolicy): `sha256:${string}`;
+export {};