@flaghoist/server 0.1.3 → 0.2.0

package/dist/index.cjs

@@ -23,6 +23,8 @@ __export(index_exports, {
   apiKey: () => apiKey,
   bearerToken: () => bearerToken,
   createFlagServer: () => createFlagServer,
+  defaultRateLimitKey: () => defaultRateLimitKey,
+  memoryRateLimit: () => memoryRateLimit,
   oidc: () => oidc,
   openApiDocument: () => openApiDocument
 });
@@ -58,6 +60,9 @@ function buildFlag(key, body, identity, existing) {
   const rollout = typeof b.rollout === "object" && b.rollout !== null ? b.rollout : {};
   const percentage = typeof rollout.percentage === "number" ? (0, import_core.clampPercentage)(rollout.percentage) : 0;
   const description = typeof b.description === "string" ? b.description : "";
+  if (description.length > import_core.LIMITS.maxDescriptionLength) {
+    return { ok: false, error: `Description exceeds ${import_core.LIMITS.maxDescriptionLength} characters` };
+  }
   const inputRules = Array.isArray(b.rules) ? b.rules : [];
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const candidate = {
@@ -402,6 +407,49 @@ var openApiDocument = {
   }
 };
 
+// src/ratelimit.ts
+function defaultRateLimitKey(headers) {
+  const cf = headers.get("cf-connecting-ip");
+  if (cf) return cf;
+  const fwd = headers.get("x-forwarded-for");
+  if (fwd) {
+    const first = fwd.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  return "anonymous";
+}
+function memoryRateLimit(options = {}) {
+  const max = options.max ?? 120;
+  const windowMs = options.windowMs ?? 6e4;
+  const maxKeys = options.maxKeys ?? 1e5;
+  const hits = /* @__PURE__ */ new Map();
+  const sweep = (now) => {
+    for (const [key, entry] of hits) {
+      if (entry.resetAt <= now) hits.delete(key);
+    }
+  };
+  return {
+    key: defaultRateLimitKey,
+    check(key) {
+      const now = Date.now();
+      let entry = hits.get(key);
+      if (!entry || entry.resetAt <= now) {
+        if (!hits.has(key) && hits.size >= maxKeys) {
+          sweep(now);
+          if (hits.size >= maxKeys) return { ok: true };
+        }
+        entry = { count: 0, resetAt: now + windowMs };
+        hits.set(key, entry);
+      }
+      entry.count += 1;
+      if (entry.count > max) {
+        return { ok: false, retryAfter: Math.max(1, Math.ceil((entry.resetAt - now) / 1e3)) };
+      }
+      return { ok: true };
+    }
+  };
+}
+
 // src/auth.ts
 var import_jose = require("jose");
 function extractBearer(headers) {
@@ -423,7 +471,22 @@ async function safeEqual(a, b) {
   for (let i = 0; i < va.length; i++) diff |= va[i] ^ vb[i];
   return diff === 0;
 }
+var MIN_SECRET_LENGTH = 16;
+var warnedWeakSecrets = /* @__PURE__ */ new Set();
+function warnIfWeakSecret(kind, secret) {
+  if (secret.length >= MIN_SECRET_LENGTH) return;
+  void (async () => {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+    const id = Array.from(new Uint8Array(digest).slice(0, 6)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    if (warnedWeakSecrets.has(id)) return;
+    warnedWeakSecrets.add(id);
+    console.warn(
+      `[flaghoist] the ${kind} is ${secret.length} characters. Use a long random value (for example \`openssl rand -hex 32\`); a short secret is guessable, especially since Flaghoist does not rate limit authentication.`
+    );
+  })();
+}
 function apiKey(expected) {
+  warnIfWeakSecret("read API key", expected);
   return async (headers) => {
     const provided = headers.get("x-api-key");
     if (!provided || !await safeEqual(provided, expected)) {
@@ -433,6 +496,7 @@ function apiKey(expected) {
   };
 }
 function bearerToken(expected) {
+  warnIfWeakSecret("admin token", expected);
   return async (headers) => {
     const provided = extractBearer(headers);
     if (!provided || !await safeEqual(provided, expected)) {
@@ -525,8 +589,23 @@ function createFlagServer(config) {
     }
     return next();
   });
+  app.use("*", async (c, next) => {
+    const cfg = resolve(c.env);
+    if (!cfg.rateLimit || c.req.path === "/health") return next();
+    const deriveKey = cfg.rateLimit.key ?? defaultRateLimitKey;
+    const result = await cfg.rateLimit.check(deriveKey(c.req.raw.headers));
+    if (!result.ok) {
+      if (result.retryAfter) c.header("Retry-After", String(result.retryAfter));
+      return c.json({ error: "Too many requests" }, 429);
+    }
+    return next();
+  });
   app.get("/health", (c) => c.json({ status: "ok" }));
-  app.get("/api/v1/openapi.json", (c) => c.json(openApiDocument));
+  app.get("/api/v1/openapi.json", (c) => {
+    const cfg = resolve(c.env);
+    if (cfg.exposeOpenApi === false) return c.text("Not found", 404);
+    return c.json(openApiDocument);
+  });
   app.get("/admin", (c) => {
     const cfg = resolve(c.env);
     return cfg.dashboard ? c.html(cfg.dashboard) : c.text("Dashboard not configured", 404);
@@ -646,6 +725,8 @@ function createFlagServer(config) {
   apiKey,
   bearerToken,
   createFlagServer,
+  defaultRateLimitKey,
+  memoryRateLimit,
   oidc,
   openApiDocument
 });

package/dist/index.d.cts

@@ -3,6 +3,61 @@ import { Hono } from 'hono';
 import { StorageAdapter, AttributeValue } from '@flaghoist/core';
 import { JWTVerifyGetKey } from 'jose';
 
+/**
+ * Rate limiting for the server. Opt-in: with no `rateLimit` in the config the server behaves
+ * exactly as before, because a limiter with the wrong bucket key is worse than none, and only the
+ * operator knows how their deployment is fronted.
+ *
+ * On a single Node or container process the in-memory limiter here is genuinely effective. On
+ * Cloudflare Workers it is per-isolate, so it caps a burst against one isolate but not the fleet;
+ * the real answer there is Cloudflare's own Rate Limiting rules in front of the Worker. The read
+ * path already fails closed under a 429 (an OFREP client returns the caller's default), so limiting
+ * it degrades safely.
+ */
+/** Outcome of a rate-limit check. `retryAfter` is whole seconds until the caller may try again. */
+interface RateLimitResult {
+    ok: boolean;
+    retryAfter?: number;
+}
+/**
+ * A rate limiter. `check` decides whether a bucket may proceed; `key` chooses the bucket for a
+ * request. Bring your own (a Cloudflare binding, a Redis counter) or use `memoryRateLimit`.
+ */
+interface RateLimit {
+    check(key: string): RateLimitResult | Promise<RateLimitResult>;
+    /**
+     * Derive the bucket key from request headers. The default trusts `CF-Connecting-IP` (set by
+     * Cloudflare and not spoofable there), then the first hop of `X-Forwarded-For`, then a single
+     * shared `anonymous` bucket. On a Node process exposed directly, with no proxy setting a
+     * forwarded header, every caller lands in that shared bucket, which caps total throughput rather
+     * than per-client; supply your own `key` if you have a trustworthy client identifier.
+     */
+    key?(headers: Headers): string;
+}
+interface MemoryRateLimitOptions {
+    /** Maximum requests allowed per key within the window. Default 120. */
+    max?: number;
+    /** Window length in milliseconds. Default 60000 (one minute). */
+    windowMs?: number;
+    /**
+     * Cap on how many distinct keys are tracked, to bound memory against a many-IP flood. When the
+     * table is full of live entries the limiter fails open (allows) rather than growing without
+     * limit or blocking new clients. Default 100000.
+     */
+    maxKeys?: number;
+}
+/** The default bucket key: Cloudflare's client IP, then a forwarded header, then a shared bucket. */
+declare function defaultRateLimitKey(headers: Headers): string;
+/**
+ * A fixed-window, in-memory rate limiter. Counts requests per key within a window and denies once
+ * the count exceeds `max`, reporting the seconds until the window resets. Memory is bounded: expired
+ * entries are swept lazily, and if the table stays full the limiter fails open rather than growing.
+ */
+declare function memoryRateLimit(options?: MemoryRateLimitOptions): {
+    check(key: string): RateLimitResult;
+    key(headers: Headers): string;
+};
+
 /** Result of an authentication attempt. `ok: false` carries the status/message to return. */
 interface AuthResult {
     ok: boolean;
@@ -31,6 +86,12 @@ interface ServerConfig {
     allowedOrigins?: string[];
     /** TTL in seconds for the in-isolate flag-definition cache on the read path. Default: 30. */
     cacheTtlSeconds?: number;
+    /**
+     * Optional rate limiter, applied to every route except `/health`. Off by default. On a single
+     * process the built-in `memoryRateLimit` is effective; on Cloudflare it is per-isolate, so prefer
+     * Cloudflare's own Rate Limiting there. See `packages/server/src/ratelimit.ts`.
+     */
+    rateLimit?: RateLimit;
     /**
      * Inject trusted context attributes derived from headers you control (e.g. a validated
      * session). These override client-supplied context, so security-relevant targeting can be
@@ -39,9 +100,16 @@ interface ServerConfig {
     trustedContext?: (headers: Headers) => Record<string, AttributeValue>;
     /**
      * Prebuilt admin dashboard HTML (a single-file SPA build) to serve at `/admin`. When set, a
-     * single deploy gives you the read API, the admin API, and the management UI together.
+     * single deploy gives you the read API, the admin API, and the management UI together. Omit it
+     * (or set `dashboard = false` in flaghoist.toml) to run the APIs without the UI.
      */
     dashboard?: string;
+    /**
+     * Serve the OpenAPI 3.1 document at `/api/v1/openapi.json`. On by default. It is unauthenticated
+     * and describes every route and auth scheme, so a locked-down deployment that does not need it can
+     * set this to `false` and stop advertising its own API surface.
+     */
+    exposeOpenApi?: boolean;
 }
 /** Config, or a function that derives it from the runtime environment (e.g. Workers bindings). */
 type ConfigResolver<Env> = ServerConfig | ((env: Env) => ServerConfig);
@@ -98,4 +166,4 @@ declare function createFlagServer<Env extends object = Record<string, unknown>>(
     Bindings: Env;
 }, hono_types.BlankSchema, "/">;
 
-export { type AuthResult, type Authenticator, type ConfigResolver, type OidcOptions, type ServerConfig, apiKey, bearerToken, createFlagServer, oidc, openApiDocument };
+export { type AuthResult, type Authenticator, type ConfigResolver, type MemoryRateLimitOptions, type OidcOptions, type RateLimit, type RateLimitResult, type ServerConfig, apiKey, bearerToken, createFlagServer, defaultRateLimitKey, memoryRateLimit, oidc, openApiDocument };

package/dist/index.d.ts

@@ -3,6 +3,61 @@ import { Hono } from 'hono';
 import { StorageAdapter, AttributeValue } from '@flaghoist/core';
 import { JWTVerifyGetKey } from 'jose';
 
+/**
+ * Rate limiting for the server. Opt-in: with no `rateLimit` in the config the server behaves
+ * exactly as before, because a limiter with the wrong bucket key is worse than none, and only the
+ * operator knows how their deployment is fronted.
+ *
+ * On a single Node or container process the in-memory limiter here is genuinely effective. On
+ * Cloudflare Workers it is per-isolate, so it caps a burst against one isolate but not the fleet;
+ * the real answer there is Cloudflare's own Rate Limiting rules in front of the Worker. The read
+ * path already fails closed under a 429 (an OFREP client returns the caller's default), so limiting
+ * it degrades safely.
+ */
+/** Outcome of a rate-limit check. `retryAfter` is whole seconds until the caller may try again. */
+interface RateLimitResult {
+    ok: boolean;
+    retryAfter?: number;
+}
+/**
+ * A rate limiter. `check` decides whether a bucket may proceed; `key` chooses the bucket for a
+ * request. Bring your own (a Cloudflare binding, a Redis counter) or use `memoryRateLimit`.
+ */
+interface RateLimit {
+    check(key: string): RateLimitResult | Promise<RateLimitResult>;
+    /**
+     * Derive the bucket key from request headers. The default trusts `CF-Connecting-IP` (set by
+     * Cloudflare and not spoofable there), then the first hop of `X-Forwarded-For`, then a single
+     * shared `anonymous` bucket. On a Node process exposed directly, with no proxy setting a
+     * forwarded header, every caller lands in that shared bucket, which caps total throughput rather
+     * than per-client; supply your own `key` if you have a trustworthy client identifier.
+     */
+    key?(headers: Headers): string;
+}
+interface MemoryRateLimitOptions {
+    /** Maximum requests allowed per key within the window. Default 120. */
+    max?: number;
+    /** Window length in milliseconds. Default 60000 (one minute). */
+    windowMs?: number;
+    /**
+     * Cap on how many distinct keys are tracked, to bound memory against a many-IP flood. When the
+     * table is full of live entries the limiter fails open (allows) rather than growing without
+     * limit or blocking new clients. Default 100000.
+     */
+    maxKeys?: number;
+}
+/** The default bucket key: Cloudflare's client IP, then a forwarded header, then a shared bucket. */
+declare function defaultRateLimitKey(headers: Headers): string;
+/**
+ * A fixed-window, in-memory rate limiter. Counts requests per key within a window and denies once
+ * the count exceeds `max`, reporting the seconds until the window resets. Memory is bounded: expired
+ * entries are swept lazily, and if the table stays full the limiter fails open rather than growing.
+ */
+declare function memoryRateLimit(options?: MemoryRateLimitOptions): {
+    check(key: string): RateLimitResult;
+    key(headers: Headers): string;
+};
+
 /** Result of an authentication attempt. `ok: false` carries the status/message to return. */
 interface AuthResult {
     ok: boolean;
@@ -31,6 +86,12 @@ interface ServerConfig {
     allowedOrigins?: string[];
     /** TTL in seconds for the in-isolate flag-definition cache on the read path. Default: 30. */
     cacheTtlSeconds?: number;
+    /**
+     * Optional rate limiter, applied to every route except `/health`. Off by default. On a single
+     * process the built-in `memoryRateLimit` is effective; on Cloudflare it is per-isolate, so prefer
+     * Cloudflare's own Rate Limiting there. See `packages/server/src/ratelimit.ts`.
+     */
+    rateLimit?: RateLimit;
     /**
      * Inject trusted context attributes derived from headers you control (e.g. a validated
      * session). These override client-supplied context, so security-relevant targeting can be
@@ -39,9 +100,16 @@ interface ServerConfig {
     trustedContext?: (headers: Headers) => Record<string, AttributeValue>;
     /**
      * Prebuilt admin dashboard HTML (a single-file SPA build) to serve at `/admin`. When set, a
-     * single deploy gives you the read API, the admin API, and the management UI together.
+     * single deploy gives you the read API, the admin API, and the management UI together. Omit it
+     * (or set `dashboard = false` in flaghoist.toml) to run the APIs without the UI.
      */
     dashboard?: string;
+    /**
+     * Serve the OpenAPI 3.1 document at `/api/v1/openapi.json`. On by default. It is unauthenticated
+     * and describes every route and auth scheme, so a locked-down deployment that does not need it can
+     * set this to `false` and stop advertising its own API surface.
+     */
+    exposeOpenApi?: boolean;
 }
 /** Config, or a function that derives it from the runtime environment (e.g. Workers bindings). */
 type ConfigResolver<Env> = ServerConfig | ((env: Env) => ServerConfig);
@@ -98,4 +166,4 @@ declare function createFlagServer<Env extends object = Record<string, unknown>>(
     Bindings: Env;
 }, hono_types.BlankSchema, "/">;
 
-export { type AuthResult, type Authenticator, type ConfigResolver, type OidcOptions, type ServerConfig, apiKey, bearerToken, createFlagServer, oidc, openApiDocument };
+export { type AuthResult, type Authenticator, type ConfigResolver, type MemoryRateLimitOptions, type OidcOptions, type RateLimit, type RateLimitResult, type ServerConfig, apiKey, bearerToken, createFlagServer, defaultRateLimitKey, memoryRateLimit, oidc, openApiDocument };

package/dist/index.js

@@ -20,7 +20,7 @@ function createDefinitionCache() {
 }
 
 // src/flags.ts
-import { clampPercentage, parseFlag } from "@flaghoist/core";
+import { clampPercentage, LIMITS, parseFlag } from "@flaghoist/core";
 function buildFlag(key, body, identity, existing) {
   if (typeof body !== "object" || body === null) {
     return { ok: false, error: "Request body must be a JSON object" };
@@ -30,6 +30,9 @@ function buildFlag(key, body, identity, existing) {
   const rollout = typeof b.rollout === "object" && b.rollout !== null ? b.rollout : {};
   const percentage = typeof rollout.percentage === "number" ? clampPercentage(rollout.percentage) : 0;
   const description = typeof b.description === "string" ? b.description : "";
+  if (description.length > LIMITS.maxDescriptionLength) {
+    return { ok: false, error: `Description exceeds ${LIMITS.maxDescriptionLength} characters` };
+  }
   const inputRules = Array.isArray(b.rules) ? b.rules : [];
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const candidate = {
@@ -374,6 +377,49 @@ var openApiDocument = {
   }
 };
 
+// src/ratelimit.ts
+function defaultRateLimitKey(headers) {
+  const cf = headers.get("cf-connecting-ip");
+  if (cf) return cf;
+  const fwd = headers.get("x-forwarded-for");
+  if (fwd) {
+    const first = fwd.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  return "anonymous";
+}
+function memoryRateLimit(options = {}) {
+  const max = options.max ?? 120;
+  const windowMs = options.windowMs ?? 6e4;
+  const maxKeys = options.maxKeys ?? 1e5;
+  const hits = /* @__PURE__ */ new Map();
+  const sweep = (now) => {
+    for (const [key, entry] of hits) {
+      if (entry.resetAt <= now) hits.delete(key);
+    }
+  };
+  return {
+    key: defaultRateLimitKey,
+    check(key) {
+      const now = Date.now();
+      let entry = hits.get(key);
+      if (!entry || entry.resetAt <= now) {
+        if (!hits.has(key) && hits.size >= maxKeys) {
+          sweep(now);
+          if (hits.size >= maxKeys) return { ok: true };
+        }
+        entry = { count: 0, resetAt: now + windowMs };
+        hits.set(key, entry);
+      }
+      entry.count += 1;
+      if (entry.count > max) {
+        return { ok: false, retryAfter: Math.max(1, Math.ceil((entry.resetAt - now) / 1e3)) };
+      }
+      return { ok: true };
+    }
+  };
+}
+
 // src/auth.ts
 import { createRemoteJWKSet, jwtVerify } from "jose";
 function extractBearer(headers) {
@@ -395,7 +441,22 @@ async function safeEqual(a, b) {
   for (let i = 0; i < va.length; i++) diff |= va[i] ^ vb[i];
   return diff === 0;
 }
+var MIN_SECRET_LENGTH = 16;
+var warnedWeakSecrets = /* @__PURE__ */ new Set();
+function warnIfWeakSecret(kind, secret) {
+  if (secret.length >= MIN_SECRET_LENGTH) return;
+  void (async () => {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret));
+    const id = Array.from(new Uint8Array(digest).slice(0, 6)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    if (warnedWeakSecrets.has(id)) return;
+    warnedWeakSecrets.add(id);
+    console.warn(
+      `[flaghoist] the ${kind} is ${secret.length} characters. Use a long random value (for example \`openssl rand -hex 32\`); a short secret is guessable, especially since Flaghoist does not rate limit authentication.`
+    );
+  })();
+}
 function apiKey(expected) {
+  warnIfWeakSecret("read API key", expected);
   return async (headers) => {
     const provided = headers.get("x-api-key");
     if (!provided || !await safeEqual(provided, expected)) {
@@ -405,6 +466,7 @@ function apiKey(expected) {
   };
 }
 function bearerToken(expected) {
+  warnIfWeakSecret("admin token", expected);
   return async (headers) => {
     const provided = extractBearer(headers);
     if (!provided || !await safeEqual(provided, expected)) {
@@ -497,8 +559,23 @@ function createFlagServer(config) {
     }
     return next();
   });
+  app.use("*", async (c, next) => {
+    const cfg = resolve(c.env);
+    if (!cfg.rateLimit || c.req.path === "/health") return next();
+    const deriveKey = cfg.rateLimit.key ?? defaultRateLimitKey;
+    const result = await cfg.rateLimit.check(deriveKey(c.req.raw.headers));
+    if (!result.ok) {
+      if (result.retryAfter) c.header("Retry-After", String(result.retryAfter));
+      return c.json({ error: "Too many requests" }, 429);
+    }
+    return next();
+  });
   app.get("/health", (c) => c.json({ status: "ok" }));
-  app.get("/api/v1/openapi.json", (c) => c.json(openApiDocument));
+  app.get("/api/v1/openapi.json", (c) => {
+    const cfg = resolve(c.env);
+    if (cfg.exposeOpenApi === false) return c.text("Not found", 404);
+    return c.json(openApiDocument);
+  });
   app.get("/admin", (c) => {
     const cfg = resolve(c.env);
     return cfg.dashboard ? c.html(cfg.dashboard) : c.text("Dashboard not configured", 404);
@@ -617,6 +694,8 @@ export {
   apiKey,
   bearerToken,
   createFlagServer,
+  defaultRateLimitKey,
+  memoryRateLimit,
   oidc,
   openApiDocument
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaghoist/server",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Hono app factory for Flaghoist: OFREP evaluate, admin CRUD, and pluggable auth.",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,10 +46,10 @@
   "dependencies": {
     "hono": "^4.13.3",
     "jose": "^6.2.9",
-    "@flaghoist/core": "0.1.1"
+    "@flaghoist/core": "0.1.2"
   },
   "devDependencies": {
-    "@flaghoist/adapter-memory": "0.1.1",
+    "@flaghoist/adapter-memory": "0.1.2",
     "@flaghoist/dashboard": "0.0.0"
   },
   "publishConfig": {