@flaredev/core 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,34 @@
+import { R as RealtimePresenceData, a as RealtimeReconnectPolicy, b as RealtimeStatus, c as RealtimeMember } from './types-B6Y73BgH.js';
+export { RealtimeClient } from './realtime/client.js';
+
+interface UseRealtimeOptions {
+    /** Presence announced on join, and re-sent whenever its value changes. `null` clears it. */
+    presence?: RealtimePresenceData;
+    /** Reconnect/keepalive tuning (see RealtimeReconnectPolicy). */
+    reconnect?: RealtimeReconnectPolicy;
+    /** Channel endpoint path if the app mounted realtime elsewhere (default /realtime). */
+    path?: string;
+    /** Connect immediately on mount (default true). Set false to defer. */
+    autoConnect?: boolean;
+    /** Called for every application event received on the channel. */
+    onEvent?: (e: string, d: unknown, from?: string) => void;
+}
+interface UseRealtimeResult {
+    /** Lifecycle: connecting | open | reconnecting | dead | closed. */
+    status: RealtimeStatus;
+    /** Currently connected members (id + presence). */
+    members: RealtimeMember[];
+    /** Broadcast an app event to every other member (needs a `send` grant from the server). */
+    publish: (e: string, d: unknown) => boolean;
+    /** True when the underlying socket is open. */
+    connected: boolean;
+    /** Connect (with autoConnect: false), or resume after close(). */
+    connect: () => void;
+    /** Close the channel's shared socket for every component using it. */
+    close: () => void;
+    /** Update this connection's presence. */
+    setPresence: (presence: RealtimePresenceData) => void;
+}
+declare function useRealtime(channel: string, opts?: UseRealtimeOptions): UseRealtimeResult;
+
+export { RealtimeMember, RealtimePresenceData, RealtimeReconnectPolicy, RealtimeStatus, type UseRealtimeOptions, type UseRealtimeResult, useRealtime };

package/dist/react.js

@@ -0,0 +1,95 @@
+"use client";
+import {
+  RealtimeClient
+} from "./chunk-LYQT4S47.js";
+import "./chunk-ZJPJGME5.js";
+
+// src/realtime/react.ts
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+var registry = /* @__PURE__ */ new Map();
+function acquire(key, channel, opts) {
+  const existing = registry.get(key);
+  if (existing) {
+    existing.refs += 1;
+    return existing.client;
+  }
+  const client = new RealtimeClient(channel, { reconnect: opts.reconnect, path: opts.path });
+  registry.set(key, { client, refs: 1 });
+  return client;
+}
+function release(key) {
+  const entry = registry.get(key);
+  if (!entry) return;
+  entry.refs -= 1;
+  if (entry.refs <= 0) {
+    entry.client.close();
+    registry.delete(key);
+  }
+}
+var SERVER_SNAPSHOT = { status: "connecting", members: [] };
+var noopUnsubscribe = () => {
+};
+function useRealtime(channel, opts = {}) {
+  const { presence, reconnect, path, autoConnect = true, onEvent } = opts;
+  const key = `${path ?? "/realtime"}|${channel}`;
+  const [client, setClient] = useState(null);
+  const reconnectRef = useRef(reconnect);
+  reconnectRef.current = reconnect;
+  useEffect(() => {
+    const acquired = acquire(key, channel, { reconnect: reconnectRef.current, path });
+    setClient(acquired);
+    if (autoConnect) acquired.connect();
+    return () => {
+      release(key);
+      setClient(null);
+    };
+  }, [key, channel, path, autoConnect]);
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  useEffect(() => client?.onAny((e, d, from) => onEventRef.current?.(e, d, from)), [client]);
+  const presenceKey = presence === void 0 ? void 0 : JSON.stringify(presence);
+  useEffect(() => {
+    if (!client || presenceKey === void 0) return;
+    client.setPresence(JSON.parse(presenceKey));
+  }, [client, presenceKey]);
+  const cache = useRef(null);
+  const getSnapshot = () => {
+    if (!client) return SERVER_SNAPSHOT;
+    const cached = cache.current;
+    if (cached && cached.client === client && cached.value.status === client.status && cached.value.members === client.members) {
+      return cached.value;
+    }
+    const value = { status: client.status, members: client.members };
+    cache.current = { client, value };
+    return value;
+  };
+  const subscribe = useMemo(
+    () => (notify) => {
+      if (!client) return noopUnsubscribe;
+      const offStatus = client.onStatus(notify);
+      const offMembers = client.onMembers(notify);
+      return () => {
+        offStatus();
+        offMembers();
+      };
+    },
+    [client]
+  );
+  const { status, members } = useSyncExternalStore(subscribe, getSnapshot, () => SERVER_SNAPSHOT);
+  return useMemo(
+    () => ({
+      status,
+      members,
+      connected: status === "open",
+      publish: (e, d) => client?.publish(e, d) ?? false,
+      connect: () => void client?.connect(),
+      close: () => client?.close(),
+      setPresence: (next) => client?.setPresence(next)
+    }),
+    [client, status, members]
+  );
+}
+export {
+  RealtimeClient,
+  useRealtime
+};

package/dist/realtime/client.d.ts

@@ -0,0 +1,82 @@
+import { c as RealtimeMember, b as RealtimeStatus, a as RealtimeReconnectPolicy, R as RealtimePresenceData } from '../types-B6Y73BgH.js';
+export { d as RealtimeEvent } from '../types-B6Y73BgH.js';
+
+/**
+ * Flare Realtime client transport. A framework-agnostic reconnecting WebSocket
+ * that speaks the `types.ts` wire protocol. `useRealtime` (react.ts) wraps it
+ * for React; this class is usable directly in plain JS/TS and tests.
+ */
+
+interface RealtimeClientOptions {
+    /** Reconnect/keepalive tuning (see RealtimeReconnectPolicy). */
+    reconnect?: RealtimeReconnectPolicy;
+    /** Initial presence announced on `join`. */
+    presence?: RealtimePresenceData;
+}
+type EventHandler = (payload: unknown, from?: string) => void;
+type AnyHandler = (e: string, d: unknown, from?: string) => void;
+type MembersHandler = (members: RealtimeMember[]) => void;
+type StatusHandler = (status: RealtimeStatus) => void;
+declare class RealtimeClient {
+    readonly channel: string;
+    members: RealtimeMember[];
+    status: RealtimeStatus;
+    /** This connection's id, from the server's `hello` (new on every reconnect). */
+    connectionId: string | null;
+    private readonly url;
+    private readonly policy;
+    private presence;
+    private ws;
+    private attempt;
+    private explicitClose;
+    private reconnectTimer;
+    private deadTimer;
+    private stableTimer;
+    private heartbeatInterval;
+    private lastPongAt;
+    private readonly listeners;
+    private readonly anyHandlers;
+    private readonly memberHandlers;
+    private readonly statusHandlers;
+    /**
+     * @param channel Channel name to join, e.g. `"deals"`.
+     * @param opts.path Websocket endpoint (default `/realtime`); the URL is
+     *          resolved against `location` in the browser, or the given
+     *          `baseUrl`. Scheme is upgraded to `wss:` / `ws:` automatically.
+     */
+    constructor(channel: string, opts?: RealtimeClientOptions & {
+        path?: string;
+        baseUrl?: string;
+    });
+    /** Subscribe to one application event type. Returns an unsubscribe fn. */
+    on(e: string, handler: EventHandler): () => void;
+    /** Subscribe to every application event on the channel. */
+    onAny(handler: AnyHandler): () => void;
+    /** Presence change notifications (full member list on every change). */
+    onMembers(handler: MembersHandler): () => void;
+    onStatus(handler: StatusHandler): () => void;
+    /** Set presence for this connection; sends a `join` frame if already connected. */
+    setPresence(presence: RealtimePresenceData): void;
+    /** Broadcast an application event to every other member (needs a `send` grant). */
+    publish(e: string, d: unknown): boolean;
+    connected(): boolean;
+    /** Connect and join; no-op if already connected or connecting. Resumes after close(). */
+    connect(): this;
+    /** Close and stop reconnecting and keepalive, until connect() is called again. */
+    close(): void;
+    private send;
+    private handleOpen;
+    private handleMessage;
+    private setMembers;
+    private dispatch;
+    private handleClose;
+    private scheduleReconnect;
+    /** Exponential backoff with jitter, never above maxDelayMs. */
+    private nextDelay;
+    private startHeartbeat;
+    private clearTimers;
+    private clearHeartbeat;
+    private setStatus;
+}
+
+export { RealtimeClient, type RealtimeClientOptions, RealtimeMember, RealtimePresenceData, RealtimeStatus };

package/dist/realtime/client.js

@@ -0,0 +1,7 @@
+import {
+  RealtimeClient
+} from "../chunk-LYQT4S47.js";
+import "../chunk-ZJPJGME5.js";
+export {
+  RealtimeClient
+};

package/dist/realtime/server.d.ts

@@ -0,0 +1,109 @@
+import { DurableObject } from 'cloudflare:workers';
+import { c as RealtimeMember, R as RealtimePresenceData } from '../types-B6Y73BgH.js';
+
+/**
+ * Flare Realtime server primitive: one WebSocket-hibernatable Durable Object
+ * per channel, providing broadcast (rooms) and presence.
+ *
+ * - One DO instance per channel name (`hubs.get(hubs.idFromName(channel))`).
+ * - WebSocket Hibernation API: sockets, their tags, and per-socket attachment
+ *   data survive hibernation; presence rebuilds from `state.getWebSockets()`
+ *   with no durable storage dependency.
+ * - Connectivity: the app's `worker/index.ts` intercepts `/realtime/<channel>/ws`
+ *   upgrades and hands them to `handleRealtimeUpgrade`, which checks the Origin,
+ *   asks the app's `authorize` hook, and routes to this DO.
+ * - Server-driven publishes call `hub.publish(event, data)` on the DO stub
+ *   from any app code that has access to the `FLARE_REALTIME` binding.
+ *
+ * Wire protocol lives in `types.ts`.
+ *
+ * @see https://developers.cloudflare.com/durable-objects/api/websockets/
+ */
+
+/** What an authorized connection may do beyond receiving events and presence. */
+interface RealtimeGrant {
+    /** Allow `send` frames (client-to-client broadcast). Off unless granted. */
+    send?: boolean;
+}
+/**
+ * Decides whether a WebSocket upgrade may join `channel`. Return a grant to allow
+ * it, or `false`/`null` to refuse (401). A Response is returned to the client as-is.
+ */
+type RealtimeAuthorize = (request: Request, channel: string) => RealtimeGrant | false | null | Response | Promise<RealtimeGrant | false | null | Response>;
+interface RealtimeUpgradeOptions {
+    /** Required: there is no default, so every app decides who may connect. */
+    authorize: RealtimeAuthorize;
+    /**
+     * Origins allowed to open sockets besides the app's own. Browsers always send
+     * Origin on WebSocket upgrades, so this is what blocks cross-site WebSocket hijacking.
+     */
+    allowedOrigins?: string[];
+}
+/**
+ * The subset of a `DurableObjectNamespace` the realtime primitive needs.
+ * Structural so core's published d.ts stays independent of
+ * `@cloudflare/workers-types`; any `DurableObjectNamespace<RealtimeChannel>`
+ * binding (e.g. `env.FLARE_REALTIME`) satisfies it.
+ */
+interface RealtimeChannelNamespace {
+    idFromName(name: string): {
+        toString(): string;
+        equals(other: unknown): boolean;
+        readonly name?: string;
+        readonly jurisdiction?: string;
+    };
+    get(id: {
+        toString(): string;
+        equals(other: unknown): boolean;
+        readonly name?: string;
+        readonly jurisdiction?: string;
+    }): unknown;
+}
+/**
+ * The Durable Object backing one channel. Extend it only via composition in
+ * the app's `worker/index.ts`; the class is exported for wrangler's `migrations`
+ * block and app-side RPC typing.
+ */
+declare class RealtimeChannel extends DurableObject {
+    /** Upgrade path for `/realtime/<channel>/ws`, reached only through handleRealtimeUpgrade. */
+    fetch(request: Request): Response;
+    /**
+     * App-facing RPC: broadcast an application event to every live member.
+     * Returns the number of sockets that accepted the frame.
+     */
+    publish(e: string, d: unknown): number;
+    /** App-facing RPC: the channel's currently connected members. */
+    presence(): RealtimeMember[];
+    /** RPC for server logic that knows a connectionId. Returns false if not found or too large. */
+    setPresence(connectionId: string, presence: RealtimePresenceData): boolean;
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(ws: WebSocket, code: number, reason: string): void;
+    webSocketError(ws: WebSocket): void;
+    private members;
+    private announcePresence;
+    private frame;
+}
+/**
+ * Route a WebSocket upgrade for `/realtime/<channel>/ws` to the channel's DO,
+ * after checking the Origin and asking `options.authorize` whether this request
+ * may join. Returns `undefined` for any other path so the caller falls through
+ * to the app handler.
+ *
+ * ```ts
+ * // worker/index.ts
+ * const realtime = await handleRealtimeUpgrade(request, env.FLARE_REALTIME, { authorize: authorizeRealtime });
+ * if (realtime) return realtime;
+ * return app.fetch(request, env, ctx);
+ * ```
+ */
+declare function handleRealtimeUpgrade(request: Request, namespace: RealtimeChannelNamespace, options: RealtimeUpgradeOptions): Promise<Response | undefined>;
+/**
+ * Resolve a channel hub (DO stub) for app-driven publish/presence calls.
+ *
+ * ```ts
+ * await realtimeHub(env.FLARE_REALTIME, "deals").publish("deal.stage", { id, stage });
+ * ```
+ */
+declare function realtimeHub(namespace: RealtimeChannelNamespace, channel: string): RealtimeChannel;
+
+export { type RealtimeAuthorize, RealtimeChannel, type RealtimeChannelNamespace, type RealtimeGrant, RealtimeMember, RealtimePresenceData, type RealtimeUpgradeOptions, handleRealtimeUpgrade, realtimeHub };

package/dist/realtime/server.js

@@ -0,0 +1,200 @@
+import {
+  parseClientFrame
+} from "../chunk-ZJPJGME5.js";
+
+// src/realtime/server.ts
+import { DurableObject } from "cloudflare:workers";
+var MEMBER_TAG = "member";
+var MAX_FRAME_CHARS = 1024 * 1024;
+var MAX_SEND_CHARS = 64 * 1024;
+var MAX_PRESENCE_CHARS = 1024;
+var MAX_PRESENCE = 256;
+var MAX_CONNECTIONS = 1e3;
+var GRANT_HEADER = "x-flare-realtime-grant";
+function makeWebSocketPair() {
+  const Ctor = globalThis.WebSocketPair;
+  if (!Ctor) throw new Error("The WebSocketPair global is unavailable in this runtime.");
+  return new Ctor();
+}
+function readGrant(request) {
+  try {
+    const grant = JSON.parse(request.headers.get(GRANT_HEADER) ?? "null");
+    return { send: grant?.send === true };
+  } catch {
+    return { send: false };
+  }
+}
+function presenceFits(presence) {
+  try {
+    return JSON.stringify(presence ?? null).length <= MAX_PRESENCE_CHARS;
+  } catch {
+    return false;
+  }
+}
+function asHibernatable(ws) {
+  return ws;
+}
+var RealtimeChannel = class extends DurableObject {
+  /** Upgrade path for `/realtime/<channel>/ws`, reached only through handleRealtimeUpgrade. */
+  fetch(request) {
+    if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("This endpoint is for WebSocket upgrades.", { status: 426 });
+    }
+    if (this.ctx.getWebSockets(MEMBER_TAG).length >= MAX_CONNECTIONS) {
+      return new Response("This channel is full.", { status: 503 });
+    }
+    const pair = makeWebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    const connectionId = crypto.randomUUID();
+    const grant = readGrant(request);
+    server.serializeAttachment({ connectionId, joinedAt: Date.now(), presence: null, send: grant.send === true });
+    this.ctx.acceptWebSocket(server, [MEMBER_TAG]);
+    server.send(this.frame({ t: "hello", connectionId, members: this.members() }));
+    this.announcePresence({ joined: { connectionId, presence: null } });
+    return new Response(null, { status: 101, webSocket: client });
+  }
+  /**
+   * App-facing RPC: broadcast an application event to every live member.
+   * Returns the number of sockets that accepted the frame.
+   */
+  publish(e, d) {
+    const frame = this.frame({ t: "event", e, d });
+    let sent = 0;
+    for (const ws of this.ctx.getWebSockets(MEMBER_TAG)) {
+      try {
+        ws.send(frame);
+        sent += 1;
+      } catch {
+      }
+    }
+    return sent;
+  }
+  /** App-facing RPC: the channel's currently connected members. */
+  presence() {
+    return this.members();
+  }
+  /** RPC for server logic that knows a connectionId. Returns false if not found or too large. */
+  setPresence(connectionId, presence) {
+    if (!presenceFits(presence)) return false;
+    for (const ws of this.ctx.getWebSockets(MEMBER_TAG)) {
+      const attachment = ws.deserializeAttachment();
+      if (attachment.connectionId === connectionId) {
+        ws.serializeAttachment({ ...attachment, presence });
+        this.announcePresence({ joined: { connectionId, presence } });
+        return true;
+      }
+    }
+    return false;
+  }
+  async webSocketMessage(ws, message) {
+    if (typeof message !== "string") return;
+    const hij = asHibernatable(ws);
+    if (message.length > MAX_FRAME_CHARS) {
+      hij.send(this.frame({ t: "error", code: "too_large", message: "Frame exceeds 1 MiB." }));
+      return;
+    }
+    const attachment = hij.deserializeAttachment();
+    const parsed = parseClientFrame(message);
+    if (!parsed.ok) {
+      hij.send(this.frame({ t: "error", code: "bad_frame", message: parsed.reason }));
+      return;
+    }
+    const frame = parsed.frame;
+    if (frame.t === "join") {
+      const presence = frame.presence ?? null;
+      if (!presenceFits(presence)) {
+        hij.send(this.frame({ t: "error", code: "presence_too_large", message: `Presence must serialize to at most ${MAX_PRESENCE_CHARS} characters.` }));
+        return;
+      }
+      hij.serializeAttachment({ ...attachment, presence });
+      this.announcePresence({ joined: { connectionId: attachment.connectionId, presence } });
+    } else if (frame.t === "ping") {
+      hij.send(this.frame({ t: "pong" }));
+    } else if (frame.t === "send") {
+      if (!attachment.send) {
+        hij.send(this.frame({ t: "error", code: "forbidden", message: "This connection may not broadcast on this channel." }));
+        return;
+      }
+      if (message.length > MAX_SEND_CHARS) {
+        hij.send(this.frame({ t: "error", code: "too_large", message: `Broadcasts are limited to ${MAX_SEND_CHARS / 1024} KiB.` }));
+        return;
+      }
+      const eventFrame = this.frame({ t: "event", e: frame.e, d: frame.d, from: attachment.connectionId });
+      for (const other of this.ctx.getWebSockets(MEMBER_TAG)) {
+        if (other === hij) continue;
+        try {
+          other.send(eventFrame);
+        } catch {
+        }
+      }
+    }
+  }
+  webSocketClose(ws, code, reason) {
+    const attachment = asHibernatable(ws).deserializeAttachment();
+    if (attachment?.connectionId) {
+      this.announcePresence({ left: attachment.connectionId }, ws);
+    }
+    try {
+      ws.close(code === 1005 || code === 1006 ? 1e3 : code, reason);
+    } catch {
+    }
+  }
+  webSocketError(ws) {
+    void ws;
+  }
+  members(exclude) {
+    return this.ctx.getWebSockets(MEMBER_TAG).filter((ws) => ws !== exclude).map((ws) => {
+      const attachment = ws.deserializeAttachment();
+      return { connectionId: attachment.connectionId, presence: attachment.presence };
+    }).slice(0, MAX_PRESENCE);
+  }
+  announcePresence(change, exclude) {
+    const frame = this.frame({ t: "presence", members: this.members(exclude), ...change });
+    for (const ws of this.ctx.getWebSockets(MEMBER_TAG)) {
+      if (ws === exclude) continue;
+      try {
+        ws.send(frame);
+      } catch {
+      }
+    }
+  }
+  frame(frame) {
+    try {
+      return JSON.stringify(frame);
+    } catch {
+      return '{"t":"error","code":"serialize","message":"Serialization failure"}';
+    }
+  }
+};
+async function handleRealtimeUpgrade(request, namespace, options) {
+  const url = new URL(request.url);
+  const match = /^\/realtime\/([^/]+)\/ws\/?$/.exec(url.pathname);
+  if (!match) return void 0;
+  const channel = match[1] ?? "";
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(channel)) {
+    return new Response("Invalid channel name.", { status: 400 });
+  }
+  if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") {
+    return new Response("This endpoint expects a WebSocket upgrade.", { status: 426 });
+  }
+  const origin = request.headers.get("origin");
+  if (origin !== null && origin !== url.origin && !(options.allowedOrigins ?? []).includes(origin)) {
+    return new Response("Cross-origin WebSocket upgrade refused.", { status: 403 });
+  }
+  const decision = await options.authorize(request, channel);
+  if (decision instanceof Response) return decision;
+  if (!decision) return new Response("Not allowed to join this channel.", { status: 401 });
+  const forwarded = new Request(request);
+  forwarded.headers.delete(GRANT_HEADER);
+  forwarded.headers.set(GRANT_HEADER, JSON.stringify({ send: decision.send === true }));
+  return namespace.get(namespace.idFromName(channel)).fetch(forwarded);
+}
+function realtimeHub(namespace, channel) {
+  return namespace.get(namespace.idFromName(channel));
+}
+export {
+  RealtimeChannel,
+  handleRealtimeUpgrade,
+  realtimeHub
+};

package/dist/security/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Flare security: what an app's `security.config.ts` declares, and the pure rules
+ * that apply it. Nothing here touches Cloudflare or storage, so it is unit-tested.
+ *
+ * Two layers enforce the config:
+ *
+ * - **Worker layer** (always on, any plan, works on workers.dev): before the app runs,
+ *   the Worker refuses banned IPs and applies the Workers rate-limit binding; after it
+ *   runs, detectors count matching responses per IP and ban an IP that trips one.
+ * - **Zone layer** (optional): when the app has a zone and a scoped API token, the same
+ *   bans become zone IP Access Rules and `flare deploy` provisions the zone's WAF
+ *   custom rules and rate-limiting rules. Flare only ever touches rules it tagged.
+ */
+type Severity = "low" | "medium" | "high";
+/** A pattern of responses that signals abuse when one IP produces too many of them. */
+interface Detector {
+    /** Stable id, e.g. "login-brute-force". Used as the SecurityEvent kind. */
+    name: string;
+    /** Human description for the dashboard. */
+    description?: string;
+    match: {
+        /** HTTP method, e.g. "POST". Any method when omitted. */
+        method?: string;
+        /** Exact path ("/api/auth/sign-in/email") or a RegExp. */
+        path: string | RegExp;
+        /** Response statuses that count, e.g. [401]. Any status when omitted. */
+        status?: number | number[];
+    };
+    /** How many matches within `windowSeconds` trip the detector. */
+    threshold: number;
+    windowSeconds: number;
+    /** Ban the IP when tripped. Omit to only log a SecurityEvent. */
+    ban?: {
+        seconds: number;
+    };
+    severity?: Severity;
+}
+/** A zone rate-limiting rule (Cloudflare's http_ratelimit phase). */
+interface ZoneRateLimit {
+    name: string;
+    /** Cloudflare rules-language expression, e.g. `http.request.uri.path eq "/api/auth/sign-in/email"`. */
+    expression: string;
+    /** Requests allowed per `periodSeconds` per IP before blocking. */
+    requests: number;
+    /** 10 on the Free plan; 60, 120, 300, 600, 3600 on paid plans. */
+    periodSeconds: number;
+    /** How long to block once the limit is hit. 10 on the Free plan. */
+    mitigationSeconds: number;
+}
+/** A zone WAF custom rule (Cloudflare's http_request_firewall_custom phase). */
+interface ZoneCustomRule {
+    name: string;
+    expression: string;
+    action: "block" | "managed_challenge" | "js_challenge" | "log";
+}
+interface SecurityConfig {
+    /** IPs that are never banned or rate-limited (your office, uptime monitors). */
+    allow?: string[];
+    /** Response patterns that indicate abuse. */
+    detectors?: Detector[];
+    /**
+     * Worker-level rate limit through the Workers rate-limit binding. Its limit and
+     * period are set on the binding in wrangler.jsonc; this chooses which paths use it.
+     */
+    rateLimit?: {
+        binding: string;
+        paths: RegExp;
+    };
+    /** Zone rules `flare deploy` provisions when a zone and token are configured. */
+    zone?: {
+        rateLimits?: ZoneRateLimit[];
+        customRules?: ZoneCustomRule[];
+    };
+}
+/** Validate and return a security config (the value `security.config.ts` default-exports). */
+declare function defineSecurity(config: SecurityConfig): SecurityConfig;
+/** Whether a response to this request counts for the detector. */
+declare function detectorMatches(detector: Detector, request: {
+    method: string;
+    url: string;
+}, status: number): boolean;
+/**
+ * Sliding-window count: keep the hits still inside the window, add this one, and
+ * say whether it reaches the threshold. `tripped` is true only on the hit that
+ * crosses it, so one burst produces one event and one ban, not one per request.
+ */
+declare function recordHit(previous: number[], now: number, windowSeconds: number, threshold: number): {
+    hits: number[];
+    tripped: boolean;
+};
+/**
+ * The client's IP. On Cloudflare, CF-Connecting-IP is set by the edge and can't be
+ * forged by the client; anything else (X-Forwarded-For) could be, so it's ignored.
+ */
+declare function clientIp(request: Request): string | null;
+/** IPv4, or an IPv6 address in any of its textual forms. */
+declare function isIp(value: string): boolean;
+/** Tag Flare writes on every zone rule it owns, so re-provisioning never touches anyone else's. */
+declare const zoneRuleTag: (app: string, name: string) => string;
+declare const isFlareRule: (app: string, description: string | undefined | null) => boolean;
+/** The default detectors every app starts with. */
+declare const DEFAULT_DETECTORS: Detector[];
+
+/**
+ * The zone layer: a small client over Cloudflare's API for the three things Flare
+ * manages on an app's zone. IP Access Rules (bans), the rate-limiting phase and the
+ * custom WAF phase, plus firewall analytics for the dashboard.
+ *
+ * Every rule Flare writes is tagged `flare:<app>:<name>` (see zoneRuleTag), and every
+ * write keeps whatever rules the zone already had that aren't Flare's. Use an API
+ * token scoped to this one zone with Zone WAF Edit, Firewall Services Edit,
+ * Analytics Read and Zone Read.
+ */
+
+interface ZoneOptions {
+    zoneId: string;
+    apiToken: string;
+    /** Tag prefix for this app's rules, usually the Worker's name. */
+    app: string;
+    fetch?: typeof fetch;
+}
+interface ZoneBan {
+    id: string;
+    ip: string;
+    notes: string;
+    createdAt: string;
+}
+declare class CloudflareApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare function createZoneClient(options: ZoneOptions): {
+    /** Provision this app's rate-limiting rules, leaving the zone's other rules alone. */
+    syncRateLimits(rules: ZoneRateLimit[]): Promise<{
+        kept: number;
+        written: number;
+    }>;
+    /** Provision this app's WAF custom rules, leaving the zone's other rules alone. */
+    syncCustomRules(rules: ZoneCustomRule[]): Promise<{
+        kept: number;
+        written: number;
+    }>;
+    /** Block an IP at the edge for the whole zone. Idempotent. */
+    ban(ip: string, reason: string): Promise<ZoneBan>;
+    /** Remove this app's ban on an IP (never a ban someone else added). */
+    unban(ip: string): Promise<boolean>;
+    /** This app's active zone bans. */
+    bans(): Promise<ZoneBan[]>;
+    /** Firewall events on the zone since `since`, grouped by action and source (for the dashboard). */
+    firewallEvents(since: Date): Promise<Array<{
+        count: number;
+        action: string;
+        source: string;
+        description: string | null;
+    }>>;
+};
+type ZoneClient = ReturnType<typeof createZoneClient>;
+
+export { CloudflareApiError, DEFAULT_DETECTORS, type Detector, type SecurityConfig, type Severity, type ZoneBan, type ZoneClient, type ZoneCustomRule, type ZoneOptions, type ZoneRateLimit, clientIp, createZoneClient, defineSecurity, detectorMatches, isFlareRule, isIp, recordHit, zoneRuleTag };