@flaredev/core 0.1.0

package/dist/security/index.js

@@ -0,0 +1,147 @@
+import {
+  DEFAULT_DETECTORS,
+  clientIp,
+  defineSecurity,
+  detectorMatches,
+  isFlareRule,
+  isIp,
+  recordHit,
+  zoneRuleTag
+} from "../chunk-KSVLQLJD.js";
+
+// src/security/zone.ts
+var API = "https://api.cloudflare.com/client/v4";
+var CloudflareApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "CloudflareApiError";
+  }
+  status;
+};
+function createZoneClient(options) {
+  const doFetch = options.fetch ?? fetch;
+  const zone = `${API}/zones/${options.zoneId}`;
+  async function call(url, init = {}) {
+    const response = await doFetch(url, {
+      ...init,
+      headers: { authorization: `Bearer ${options.apiToken}`, "content-type": "application/json", ...init.headers }
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok || body?.success === false) {
+      const message = body?.errors?.map((error) => error.message).join("; ") || `Cloudflare API ${response.status}`;
+      throw new CloudflareApiError(response.status, message);
+    }
+    return body?.result;
+  }
+  async function replacePhase(phase, ours) {
+    let existing = [];
+    try {
+      existing = (await call(`${zone}/rulesets/phases/${phase}/entrypoint`)).rules ?? [];
+    } catch (error) {
+      if (!(error instanceof CloudflareApiError && error.status === 404)) throw error;
+    }
+    const kept = existing.filter((rule) => !isFlareRule(options.app, rule.description)).map(({ id, ref, action, expression, description, enabled, action_parameters, ratelimit, logging }) => ({
+      id,
+      ref,
+      action,
+      expression,
+      description,
+      enabled,
+      action_parameters,
+      ratelimit,
+      logging
+    }));
+    await call(`${zone}/rulesets/phases/${phase}/entrypoint`, { method: "PUT", body: JSON.stringify({ rules: [...kept, ...ours] }) });
+    return { kept: kept.length, written: ours.length };
+  }
+  return {
+    /** Provision this app's rate-limiting rules, leaving the zone's other rules alone. */
+    syncRateLimits(rules) {
+      return replacePhase(
+        "http_ratelimit",
+        rules.map((rule) => ({
+          action: "block",
+          expression: rule.expression,
+          description: zoneRuleTag(options.app, rule.name),
+          enabled: true,
+          ratelimit: {
+            characteristics: ["cf.colo.id", "ip.src"],
+            period: rule.periodSeconds,
+            requests_per_period: rule.requests,
+            mitigation_timeout: rule.mitigationSeconds
+          }
+        }))
+      );
+    },
+    /** Provision this app's WAF custom rules, leaving the zone's other rules alone. */
+    syncCustomRules(rules) {
+      return replacePhase(
+        "http_request_firewall_custom",
+        rules.map((rule) => ({ action: rule.action, expression: rule.expression, description: zoneRuleTag(options.app, rule.name), enabled: true }))
+      );
+    },
+    /** Block an IP at the edge for the whole zone. Idempotent. */
+    async ban(ip, reason) {
+      const existing = (await this.bans()).find((ban) => ban.ip === ip);
+      if (existing) return existing;
+      const rule = await call(`${zone}/firewall/access_rules/rules`, {
+        method: "POST",
+        body: JSON.stringify({ mode: "block", configuration: { target: ip.includes(":") ? "ip6" : "ip", value: ip }, notes: `${zoneRuleTag(options.app, "ban")} ${reason}`.slice(0, 250) })
+      });
+      return { id: rule.id, ip, notes: rule.notes, createdAt: rule.created_on };
+    },
+    /** Remove this app's ban on an IP (never a ban someone else added). */
+    async unban(ip) {
+      const ban = (await this.bans()).find((entry) => entry.ip === ip);
+      if (!ban) return false;
+      await call(`${zone}/firewall/access_rules/rules/${ban.id}`, { method: "DELETE" });
+      return true;
+    },
+    /** This app's active zone bans. */
+    async bans() {
+      const rules = await call(
+        `${zone}/firewall/access_rules/rules?mode=block&per_page=500`
+      );
+      return rules.filter((rule) => isFlareRule(options.app, rule.notes)).map((rule) => ({ id: rule.id, ip: rule.configuration.value, notes: rule.notes, createdAt: rule.created_on }));
+    },
+    /** Firewall events on the zone since `since`, grouped by action and source (for the dashboard). */
+    async firewallEvents(since) {
+      const query = `query FlareFirewall($zoneTag: string, $since: Time) {
+        viewer { zones(filter: { zoneTag: $zoneTag }) {
+          firewallEventsAdaptiveGroups(limit: 50, filter: { datetime_geq: $since }, orderBy: [count_DESC]) {
+            count
+            dimensions { action source description }
+          }
+        } }
+      }`;
+      const response = await doFetch(`${API}/graphql`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${options.apiToken}`, "content-type": "application/json" },
+        body: JSON.stringify({ query, variables: { zoneTag: options.zoneId, since: since.toISOString() } })
+      });
+      const body = await response.json().catch(() => null);
+      if (!response.ok || body?.errors?.length) {
+        throw new CloudflareApiError(response.status, body?.errors?.map((error) => error.message).join("; ") || `GraphQL ${response.status}`);
+      }
+      return (body?.data?.viewer?.zones?.[0]?.firewallEventsAdaptiveGroups ?? []).map((group) => ({
+        count: group.count,
+        action: group.dimensions.action,
+        source: group.dimensions.source,
+        description: group.dimensions.description ?? null
+      }));
+    }
+  };
+}
+export {
+  CloudflareApiError,
+  DEFAULT_DETECTORS,
+  clientIp,
+  createZoneClient,
+  defineSecurity,
+  detectorMatches,
+  isFlareRule,
+  isIp,
+  recordHit,
+  zoneRuleTag
+};

package/dist/security/worker.d.ts

@@ -0,0 +1,104 @@
+import { DurableObject } from 'cloudflare:workers';
+import { SecurityConfig, ZoneClient, Detector } from './index.js';
+export { Severity } from './index.js';
+
+/**
+ * The Worker layer of Flare security: runs in the app's `worker/index.ts` around
+ * every request, before any app code.
+ *
+ * - Refuses IPs on the ban list (KV, so a ban is a cheap edge read and expires by TTL).
+ * - Applies the Workers rate-limit binding to the configured paths.
+ * - Feeds responses to the detectors. Counting lives in `SecurityMonitor`, one Durable
+ *   Object per IP, so counts are exact rather than eventually consistent; the hit that
+ *   crosses a threshold bans the IP, logs a SecurityEvent, and (with a zone configured)
+ *   adds a zone IP Access Rule.
+ */
+
+/** The KV subset Flare uses for the ban list. */
+interface BanStore {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+        metadata?: unknown;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options: {
+        prefix: string;
+        cursor?: string;
+    }): Promise<{
+        keys: Array<{
+            name: string;
+            metadata?: unknown;
+            expiration?: number;
+        }>;
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/** The Workers rate-limit binding. */
+interface RateLimiter {
+    limit(options: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+}
+/** The DurableObjectNamespace subset used to reach SecurityMonitor instances. */
+interface MonitorNamespace {
+    idFromName(name: string): unknown;
+    get(id: never): unknown;
+}
+interface Ban {
+    ip: string;
+    reason: string;
+    detector: string | null;
+    createdAt: string;
+    /** When the ban lifts; null for a manual ban without an expiry. */
+    until: string | null;
+}
+interface SecurityTrip {
+    ip: string;
+    detector: Detector;
+    count: number;
+    path: string;
+    userAgent: string | null;
+    banned: boolean;
+}
+/** Per-IP counters. One instance per IP (idFromName(ip)), so increments are exact. */
+declare class SecurityMonitor extends DurableObject {
+    /** Record one hit for a detector and say whether it crossed the threshold. */
+    hit(detector: string, windowSeconds: number, threshold: number): Promise<{
+        count: number;
+        tripped: boolean;
+    }>;
+    /** Count a request refused because this IP is banned. */
+    blocked(): Promise<number>;
+    /** Requests refused since the IP was banned. */
+    blockedCount(): Promise<number>;
+    /** Forget this IP's counters (on unban). */
+    reset(): Promise<void>;
+}
+interface GuardOptions {
+    config: SecurityConfig;
+    bans: BanStore;
+    monitors: MonitorNamespace;
+    rateLimiter?: RateLimiter;
+    /** The zone layer, when this app has a zone and token configured. */
+    zone?: ZoneClient | null;
+    /** Log a tripped detector (the app writes a SecurityEvent row). */
+    onTrip?: (trip: SecurityTrip) => Promise<void>;
+}
+interface WaitUntil {
+    waitUntil(promise: Promise<unknown>): void;
+}
+declare function createSecurity(options: GuardOptions): {
+    protect: (request: Request, ctx: WaitUntil, next: () => Promise<Response>) => Promise<Response>;
+    ban: (ip: string, reason: string, seconds: number | null, detector: string | null) => Promise<Ban>;
+    unban: (ip: string) => Promise<void>;
+    bans: () => Promise<Array<Ban & {
+        blocked: number;
+    }>>;
+};
+type Security = ReturnType<typeof createSecurity>;
+
+export { type Ban, type BanStore, Detector, type GuardOptions, type MonitorNamespace, type RateLimiter, type Security, SecurityConfig, SecurityMonitor, type SecurityTrip, type WaitUntil, createSecurity };

package/dist/security/worker.js

@@ -0,0 +1,116 @@
+import {
+  clientIp,
+  detectorMatches,
+  recordHit
+} from "../chunk-KSVLQLJD.js";
+
+// src/security/worker.ts
+import { DurableObject } from "cloudflare:workers";
+var BAN_PREFIX = "ban:";
+var SecurityMonitor = class extends DurableObject {
+  /** Record one hit for a detector and say whether it crossed the threshold. */
+  async hit(detector, windowSeconds, threshold) {
+    const key = `hits:${detector}`;
+    const previous = await this.ctx.storage.get(key) ?? [];
+    const { hits, tripped } = recordHit(previous, Date.now(), windowSeconds, threshold);
+    await this.ctx.storage.put(key, hits);
+    return { count: hits.length, tripped };
+  }
+  /** Count a request refused because this IP is banned. */
+  async blocked() {
+    const count = (await this.ctx.storage.get("blocked") ?? 0) + 1;
+    await this.ctx.storage.put("blocked", count);
+    return count;
+  }
+  /** Requests refused since the IP was banned. */
+  async blockedCount() {
+    return await this.ctx.storage.get("blocked") ?? 0;
+  }
+  /** Forget this IP's counters (on unban). */
+  async reset() {
+    await this.ctx.storage.deleteAll();
+  }
+};
+function createSecurity(options) {
+  const { config, bans } = options;
+  const allowed = new Set(config.allow ?? []);
+  const monitor = (ip) => options.monitors.get(options.monitors.idFromName(ip));
+  const detectors = config.detectors ?? [];
+  const recentBans = /* @__PURE__ */ new Map();
+  const RECENT_MS = 6e4;
+  async function ban(ip, reason, seconds, detector) {
+    const record = {
+      ip,
+      reason,
+      detector,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      until: seconds ? new Date(Date.now() + seconds * 1e3).toISOString() : null
+    };
+    await bans.put(`${BAN_PREFIX}${ip}`, JSON.stringify(record), { ...seconds ? { expirationTtl: seconds } : {}, metadata: record });
+    recentBans.set(ip, Date.now() + Math.min((seconds ?? Infinity) * 1e3, RECENT_MS));
+    if (options.zone) await options.zone.ban(ip, reason);
+    return record;
+  }
+  async function unban(ip) {
+    await bans.delete(`${BAN_PREFIX}${ip}`);
+    recentBans.delete(ip);
+    await monitor(ip).reset();
+    if (options.zone) await options.zone.unban(ip);
+  }
+  async function listBans() {
+    const found = [];
+    let cursor;
+    do {
+      const page = await bans.list({ prefix: BAN_PREFIX, cursor });
+      for (const key of page.keys) if (key.metadata) found.push(key.metadata);
+      cursor = page.list_complete ? void 0 : page.cursor;
+    } while (cursor);
+    return Promise.all(found.map(async (entry) => ({ ...entry, blocked: await monitor(entry.ip).blockedCount() })));
+  }
+  async function inspect(request, response, ip) {
+    for (const detector of detectors) {
+      if (!detectorMatches(detector, request, response.status)) continue;
+      const { count, tripped } = await monitor(ip).hit(detector.name, detector.windowSeconds, detector.threshold);
+      if (!tripped) continue;
+      const reason = `${detector.description ?? detector.name}: ${count} in ${detector.windowSeconds}s`;
+      if (detector.ban) {
+        await ban(ip, reason, detector.ban.seconds, detector.name).catch((error) => console.error("[flare] zone ban failed:", error));
+      }
+      await options.onTrip?.({
+        ip,
+        detector,
+        count,
+        path: new URL(request.url).pathname,
+        userAgent: request.headers.get("user-agent"),
+        banned: Boolean(detector.ban)
+      });
+    }
+  }
+  async function protect(request, ctx, next) {
+    const ip = clientIp(request);
+    if (!ip || allowed.has(ip)) return next();
+    const remembered = recentBans.get(ip);
+    if (remembered !== void 0 && remembered <= Date.now()) recentBans.delete(ip);
+    if (remembered !== void 0 && remembered > Date.now() || await bans.get(`${BAN_PREFIX}${ip}`)) {
+      ctx.waitUntil(monitor(ip).blocked());
+      return new Response("Access denied.", { status: 403, headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" } });
+    }
+    if (options.rateLimiter && config.rateLimit?.paths.test(new URL(request.url).pathname)) {
+      const { success } = await options.rateLimiter.limit({ key: ip });
+      if (!success) {
+        return new Response("Too many requests. Slow down and try again shortly.", {
+          status: 429,
+          headers: { "content-type": "text/plain; charset=utf-8", "retry-after": "60", "cache-control": "no-store" }
+        });
+      }
+    }
+    const response = await next();
+    if (detectors.length) ctx.waitUntil(inspect(request, response, ip).catch((error) => console.error("[flare] security detector failed:", error)));
+    return response;
+  }
+  return { protect, ban, unban, bans: listBans };
+}
+export {
+  SecurityMonitor,
+  createSecurity
+};

package/dist/server.d.ts

@@ -0,0 +1,156 @@
+import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
+import { BaseSQLiteDatabase, SQLiteTable } from 'drizzle-orm/sqlite-core';
+import { S as StoredField, R as Resource, F as Field } from './define-D5CtCkOm.js';
+
+interface ListQuery {
+    page: number;
+    perPage: number;
+    sort: {
+        field: string;
+        direction: "asc" | "desc";
+    };
+    q?: string;
+    /** Field key → coerced value; `null` means IS NULL. */
+    filters: Record<string, string | number | boolean | null>;
+}
+interface QueryIssue {
+    param: string;
+    message: string;
+}
+declare function isSortable(def: StoredField): boolean;
+declare function isFilterable(def: StoredField): boolean;
+declare function isSearchable(def: StoredField): boolean;
+/**
+ * Parse `?page=2&perPage=50&sort=-createdAt&q=ada&filter[status]=lead` against a
+ * resource. Only fields the descriptor marks sortable/filterable/searchable are
+ * accepted, so clients can't probe arbitrary columns.
+ */
+declare function parseListQuery(resource: Resource, params: URLSearchParams): {
+    query: ListQuery;
+} | {
+    issues: QueryIssue[];
+};
+
+type AnyDatabase = BaseSQLiteDatabase<"sync" | "async", any, any>;
+type ResourceAction = "list" | "read" | "create" | "update" | "delete";
+interface FieldIssue {
+    /** Dotted field path; "" for the whole body (e.g. unknown keys). */
+    path: string;
+    message: string;
+}
+type Failure = {
+    ok: false;
+    status: 400 | 404 | 409 | 422;
+    error: string;
+    /** Validation issues per field. */
+    issues?: FieldIssue[];
+    /** Invalid query parameters. */
+    queryIssues?: QueryIssue[];
+    /** Field that caused a conflict (e.g. a unique violation). */
+    field?: string;
+};
+type Result<T> = {
+    ok: true;
+    data: T;
+} | Failure;
+interface ListResult<T = Record<string, unknown>> {
+    data: T[];
+    meta: {
+        page: number;
+        perPage: number;
+        total: number;
+        totalPages: number;
+    };
+}
+interface ChangeEvent {
+    /** Resource name, e.g. "Deal". */
+    resource: string;
+    action: "create" | "update" | "delete";
+    id: string;
+}
+interface ResourceStoreOptions {
+    resource: Resource;
+    table: SQLiteTable;
+    getDb: () => AnyDatabase;
+    /**
+     * Called after a write succeeds, for cache invalidation. Runs before the
+     * operation returns, so a caller that revalidates tags can't hand back a
+     * response the cache would then contradict. Failures are logged, not thrown:
+     * the write already happened.
+     */
+    onChange?: (event: ChangeEvent) => void | Promise<void>;
+}
+/**
+ * CRUD operations for one resource, driven by its descriptor. Shared by the REST
+ * handlers and the admin's server actions, so validation, constraint handling, and
+ * search behave identically everywhere. Operations never throw for expected failures;
+ * they return `{ ok: false, status, error }`.
+ */
+declare function createResourceStore(options: ResourceStoreOptions): {
+    resource: Resource<Record<string, Field>>;
+    table: SQLiteTable<drizzle_orm_sqlite_core.TableConfig>;
+    /** `params`: page, perPage, sort, q, filter[field] (as parsed by parseListQuery). */
+    list(params: URLSearchParams): Promise<Result<ListResult>>;
+    get(id: string): Promise<Result<Record<string, unknown>>>;
+    /** Title-field values for a set of ids (for showing relations). Missing ids are omitted. */
+    titles(ids: string[]): Promise<Record<string, string>>;
+    create(input: unknown): Promise<Result<Record<string, unknown>>>;
+    /** Partial update (PATCH semantics). */
+    update(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
+    /** Full replacement (PUT semantics): omitted fields go back to their default, or null when optional. */
+    replace(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
+    delete(id: string): Promise<Result<{
+        id: string;
+    }>>;
+};
+type ResourceStore = ReturnType<typeof createResourceStore>;
+
+interface AuthorizeContext {
+    request: Request;
+    resource: Resource;
+    action: ResourceAction;
+    id?: string;
+}
+/** Return a Response (e.g. 401/403) to deny the request; return nothing to allow it. */
+type Authorize = (context: AuthorizeContext) => Response | void | Promise<Response | void>;
+interface ResourceHandlerOptions {
+    resource: Resource;
+    table: SQLiteTable;
+    getDb: () => AnyDatabase;
+    authorize: Authorize;
+    /** Called after a write succeeds, for cache invalidation. */
+    onChange?: (event: ChangeEvent) => void | Promise<void>;
+}
+type RouteContext = {
+    params: Promise<{
+        id: string;
+    }>;
+};
+/** REST route handlers for a resource: thin HTTP wrappers over `createResourceStore`. */
+declare function createResourceHandlers(options: ResourceHandlerOptions): {
+    collection: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+    };
+    item: {
+        GET: (request: Request, context: RouteContext) => Promise<Response>;
+        PATCH: (request: Request, context: RouteContext) => Promise<Response>;
+        PUT: (request: Request, context: RouteContext) => Promise<Response>;
+        DELETE: (request: Request, context: RouteContext) => Promise<Response>;
+    };
+    store: {
+        resource: Resource<Record<string, Field>>;
+        table: SQLiteTable<drizzle_orm_sqlite_core.TableConfig>;
+        list(params: URLSearchParams): Promise<Result<ListResult>>;
+        get(id: string): Promise<Result<Record<string, unknown>>>;
+        titles(ids: string[]): Promise<Record<string, string>>;
+        create(input: unknown): Promise<Result<Record<string, unknown>>>;
+        update(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
+        replace(id: string, input: unknown): Promise<Result<Record<string, unknown>>>;
+        delete(id: string): Promise<Result<{
+            id: string;
+        }>>;
+    };
+};
+
+export { type AnyDatabase, type Authorize, type AuthorizeContext, type ChangeEvent, type Failure, type FieldIssue, type ListQuery, type ListResult, type QueryIssue, type ResourceAction, type ResourceHandlerOptions, type ResourceStore, type ResourceStoreOptions, type Result, createResourceHandlers, createResourceStore, isFilterable, isSearchable, isSortable, parseListQuery };