@flaghoist/server 0.1.0

package/dist/index.js

@@ -0,0 +1,621 @@
+// src/index.ts
+import { evaluate } from "@flaghoist/core";
+import { Hono } from "hono";
+
+// src/cache.ts
+function createDefinitionCache() {
+  let entry = null;
+  return {
+    async load(storage, ttlMs2) {
+      const now = Date.now();
+      if (entry && entry.expiresAt > now) return entry.flags;
+      const flags = await storage.list();
+      entry = { flags, expiresAt: now + ttlMs2 };
+      return flags;
+    },
+    invalidate() {
+      entry = null;
+    }
+  };
+}
+
+// src/flags.ts
+import { clampPercentage, 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" };
+  }
+  const b = body;
+  const enabled = typeof b.enabled === "boolean" ? b.enabled : false;
+  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 : "";
+  const inputRules = Array.isArray(b.rules) ? b.rules : [];
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const candidate = {
+    key,
+    enabled,
+    rollout: { percentage },
+    rules: inputRules,
+    description,
+    metadata: {
+      createdBy: existing?.metadata.createdBy ?? identity,
+      createdAt: existing?.metadata.createdAt ?? now,
+      updatedBy: identity,
+      updatedAt: now
+    }
+  };
+  const validated = parseFlag(candidate);
+  if (!validated) return { ok: false, error: "Invalid flag definition" };
+  if ((validated.rules?.length ?? 0) !== inputRules.length) {
+    return { ok: false, error: "One or more targeting rules are invalid" };
+  }
+  return { ok: true, flag: validated };
+}
+
+// src/openapi.ts
+var openApiDocument = {
+  openapi: "3.1.0",
+  info: {
+    title: "Flaghoist API",
+    version: "0.1.0",
+    description: "Manage and evaluate feature flags. The admin API (`/api/v1/flags`) is Flaghoist's own; the read API (`/ofrep/v1`) follows the OpenFeature Remote Evaluation Protocol (OFREP). The unversioned `/flags` paths remain as a legacy alias of `/api/v1/flags`.",
+    license: { name: "Apache-2.0", url: "https://www.apache.org/licenses/LICENSE-2.0" }
+  },
+  servers: [{ url: "/", description: "This Flaghoist server" }],
+  tags: [
+    { name: "admin", description: "Manage flag definitions (admin auth)." },
+    {
+      name: "evaluate",
+      description: "Evaluate flags for a context (OFREP read path, API-key auth)."
+    },
+    { name: "meta", description: "Health and discovery." }
+  ],
+  paths: {
+    "/api/v1/flags": {
+      get: {
+        tags: ["admin"],
+        summary: "List all flags",
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "200": {
+            description: "All flags",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  required: ["flags"],
+                  properties: {
+                    flags: { type: "array", items: { $ref: "#/components/schemas/FeatureFlag" } }
+                  }
+                }
+              }
+            }
+          },
+          "401": { $ref: "#/components/responses/Unauthorized" }
+        }
+      }
+    },
+    "/api/v1/flags/{key}": {
+      parameters: [{ $ref: "#/components/parameters/FlagKey" }],
+      get: {
+        tags: ["admin"],
+        summary: "Get one flag",
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "200": {
+            description: "The flag",
+            content: {
+              "application/json": { schema: { $ref: "#/components/schemas/FeatureFlag" } }
+            }
+          },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "404": { $ref: "#/components/responses/NotFound" }
+        }
+      },
+      put: {
+        tags: ["admin"],
+        summary: "Create or replace a flag",
+        description: "A full replace. Creation metadata (createdBy/createdAt) is preserved; the updater and updatedAt are stamped server-side. Invalid targeting rules are rejected with 400.",
+        security: [{ bearerAuth: [] }],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: { $ref: "#/components/schemas/FlagInput" } } }
+        },
+        responses: {
+          "200": {
+            description: "The stored flag",
+            content: {
+              "application/json": { schema: { $ref: "#/components/schemas/FeatureFlag" } }
+            }
+          },
+          "400": { $ref: "#/components/responses/BadRequest" },
+          "401": { $ref: "#/components/responses/Unauthorized" },
+          "413": { description: "Payload too large" }
+        }
+      },
+      delete: {
+        tags: ["admin"],
+        summary: "Delete a flag",
+        security: [{ bearerAuth: [] }],
+        responses: {
+          "204": { description: "Deleted (idempotent)" },
+          "401": { $ref: "#/components/responses/Unauthorized" }
+        }
+      }
+    },
+    "/ofrep/v1/evaluate/flags": {
+      post: {
+        tags: ["evaluate"],
+        summary: "Evaluate all flags for a context (OFREP bulk)",
+        security: [{ apiKeyAuth: [] }],
+        requestBody: {
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/EvaluationRequest" } }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Evaluated flags",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    flags: { type: "array", items: { $ref: "#/components/schemas/EvaluatedFlag" } }
+                  }
+                }
+              }
+            }
+          },
+          "401": { $ref: "#/components/responses/Unauthorized" }
+        }
+      }
+    },
+    "/ofrep/v1/evaluate/flags/{key}": {
+      parameters: [{ $ref: "#/components/parameters/FlagKey" }],
+      post: {
+        tags: ["evaluate"],
+        summary: "Evaluate one flag (OFREP)",
+        security: [{ apiKeyAuth: [] }],
+        requestBody: {
+          content: {
+            "application/json": { schema: { $ref: "#/components/schemas/EvaluationRequest" } }
+          }
+        },
+        responses: {
+          "200": {
+            description: "Evaluated flag",
+            content: {
+              "application/json": { schema: { $ref: "#/components/schemas/EvaluatedFlag" } }
+            }
+          },
+          "404": { description: "Unknown flag (errorCode FLAG_NOT_FOUND)" }
+        }
+      }
+    },
+    "/api/v1/openapi.json": {
+      get: {
+        tags: ["meta"],
+        summary: "This OpenAPI document",
+        responses: { "200": { description: "The OpenAPI document" } }
+      }
+    },
+    "/health": {
+      get: {
+        tags: ["meta"],
+        summary: "Health check",
+        responses: {
+          "200": {
+            description: "ok",
+            content: {
+              "application/json": {
+                schema: { type: "object", properties: { status: { type: "string" } } }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  components: {
+    securitySchemes: {
+      bearerAuth: {
+        type: "http",
+        scheme: "bearer",
+        description: "Admin token (or a validated OIDC JWT)."
+      },
+      apiKeyAuth: {
+        type: "apiKey",
+        in: "header",
+        name: "x-api-key",
+        description: "Read-only API key."
+      }
+    },
+    parameters: {
+      FlagKey: {
+        name: "key",
+        in: "path",
+        required: true,
+        description: "Flag key.",
+        schema: { type: "string", pattern: "^[A-Za-z0-9][A-Za-z0-9._-]*$", maxLength: 256 }
+      }
+    },
+    responses: {
+      Unauthorized: {
+        description: "Missing or invalid credentials",
+        content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }
+      },
+      BadRequest: {
+        description: "Invalid request or flag definition",
+        content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }
+      },
+      NotFound: {
+        description: "Flag not found",
+        content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } }
+      }
+    },
+    schemas: {
+      Error: { type: "object", required: ["error"], properties: { error: { type: "string" } } },
+      Condition: {
+        type: "object",
+        required: ["attribute", "operator", "value"],
+        properties: {
+          attribute: { type: "string", maxLength: 256 },
+          operator: {
+            type: "string",
+            enum: [
+              "eq",
+              "neq",
+              "in",
+              "notIn",
+              "contains",
+              "startsWith",
+              "endsWith",
+              "gt",
+              "gte",
+              "lt",
+              "lte",
+              "semverGte",
+              "semverLt"
+            ]
+          },
+          value: {
+            description: "A scalar, or an array of scalars for `in` / `notIn`.",
+            oneOf: [
+              { type: "string" },
+              { type: "number" },
+              { type: "boolean" },
+              { type: "array", items: { oneOf: [{ type: "string" }, { type: "number" }] } }
+            ]
+          }
+        }
+      },
+      RuleResult: {
+        type: "object",
+        required: ["enabled"],
+        properties: {
+          enabled: { type: "boolean" },
+          rollout: {
+            type: "object",
+            properties: { percentage: { type: "number", minimum: 0, maximum: 100 } }
+          }
+        }
+      },
+      TargetingRule: {
+        type: "object",
+        required: ["conditions", "result"],
+        properties: {
+          description: { type: "string" },
+          conditions: { type: "array", items: { $ref: "#/components/schemas/Condition" } },
+          result: { $ref: "#/components/schemas/RuleResult" }
+        }
+      },
+      FlagMetadata: {
+        type: "object",
+        properties: {
+          createdBy: { type: "string" },
+          createdAt: { type: "string", format: "date-time" },
+          updatedBy: { type: "string" },
+          updatedAt: { type: "string", format: "date-time" }
+        }
+      },
+      FlagInput: {
+        type: "object",
+        required: ["enabled", "rollout"],
+        properties: {
+          enabled: { type: "boolean" },
+          rollout: {
+            type: "object",
+            required: ["percentage"],
+            properties: { percentage: { type: "number", minimum: 0, maximum: 100 } }
+          },
+          rules: { type: "array", items: { $ref: "#/components/schemas/TargetingRule" } },
+          description: { type: "string" }
+        }
+      },
+      FeatureFlag: {
+        allOf: [
+          { $ref: "#/components/schemas/FlagInput" },
+          {
+            type: "object",
+            required: ["key", "metadata"],
+            properties: {
+              key: { type: "string" },
+              metadata: { $ref: "#/components/schemas/FlagMetadata" }
+            }
+          }
+        ]
+      },
+      EvaluationRequest: {
+        type: "object",
+        properties: {
+          context: {
+            type: "object",
+            description: "OpenFeature evaluation context.",
+            properties: { targetingKey: { type: "string" } },
+            additionalProperties: true
+          }
+        }
+      },
+      EvaluatedFlag: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          value: { type: "boolean" },
+          reason: {
+            type: "string",
+            enum: ["DISABLED", "TARGETING_MATCH", "SPLIT", "DEFAULT"]
+          },
+          variant: { type: "string" }
+        }
+      }
+    }
+  }
+};
+
+// src/auth.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+function extractBearer(headers) {
+  const header = headers.get("authorization");
+  if (!header) return null;
+  const [scheme, token] = header.split(" ");
+  if (!token || scheme?.toLowerCase() !== "bearer") return null;
+  return token.trim() || null;
+}
+async function safeEqual(a, b) {
+  const encoder = new TextEncoder();
+  const [da, db] = await Promise.all([
+    crypto.subtle.digest("SHA-256", encoder.encode(a)),
+    crypto.subtle.digest("SHA-256", encoder.encode(b))
+  ]);
+  const va = new Uint8Array(da);
+  const vb = new Uint8Array(db);
+  let diff = 0;
+  for (let i = 0; i < va.length; i++) diff |= va[i] ^ vb[i];
+  return diff === 0;
+}
+function apiKey(expected) {
+  return async (headers) => {
+    const provided = headers.get("x-api-key");
+    if (!provided || !await safeEqual(provided, expected)) {
+      return { ok: false, status: 401, message: "Invalid or missing API key" };
+    }
+    return { ok: true, identity: "api-key" };
+  };
+}
+function bearerToken(expected) {
+  return async (headers) => {
+    const provided = extractBearer(headers);
+    if (!provided || !await safeEqual(provided, expected)) {
+      return { ok: false, status: 401, message: "Invalid or missing bearer token" };
+    }
+    return { ok: true, identity: "admin" };
+  };
+}
+function defaultJwksUri(issuer) {
+  const base = issuer.endsWith("/") ? issuer : `${issuer}/`;
+  return new URL(".well-known/jwks.json", base).toString();
+}
+function extractGroups(payload, claim) {
+  const value = payload[claim];
+  if (Array.isArray(value)) return value.filter((x) => typeof x === "string");
+  if (typeof value === "string") return value.split(/[,\s]+/).filter(Boolean);
+  return [];
+}
+function oidc(options) {
+  const resolveKey = options.keyResolver ?? createRemoteJWKSet(new URL(defaultJwksUri(options.issuer)));
+  const algorithms = options.algorithms ?? ["RS256"];
+  return async (headers) => {
+    const token = extractBearer(headers);
+    if (!token) return { ok: false, status: 401, message: "Missing bearer token" };
+    let payload;
+    try {
+      const verified = await jwtVerify(token, resolveKey, {
+        issuer: options.issuer,
+        audience: options.audience,
+        algorithms
+      });
+      payload = verified.payload;
+    } catch {
+      return { ok: false, status: 401, message: "Invalid token" };
+    }
+    if (options.tokenUse && payload["token_use"] !== options.tokenUse) {
+      return { ok: false, status: 401, message: "Invalid token" };
+    }
+    if (options.allowedGroups && options.allowedGroups.length > 0) {
+      const groups = extractGroups(payload, options.groupsClaim ?? "groups");
+      const allowed = options.allowedGroups;
+      if (!groups.some((group) => allowed.includes(group))) {
+        return { ok: false, status: 403, message: "Admin group required" };
+      }
+    }
+    const email = typeof payload["email"] === "string" ? payload["email"] : void 0;
+    const sub = typeof payload.sub === "string" ? payload.sub : void 0;
+    return { ok: true, identity: email ?? sub ?? "unknown" };
+  };
+}
+
+// src/index.ts
+var DEFAULT_CACHE_TTL_SECONDS = 30;
+var MAX_BODY_BYTES = 64 * 1024;
+async function readJsonBody(text) {
+  if (new TextEncoder().encode(text).length > MAX_BODY_BYTES) {
+    return { ok: false, status: 413, message: "Payload too large" };
+  }
+  if (!text) return { ok: true, value: {} };
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false, status: 400, message: "Invalid JSON body" };
+  }
+}
+function ttlMs(cfg) {
+  return (cfg.cacheTtlSeconds ?? DEFAULT_CACHE_TTL_SECONDS) * 1e3;
+}
+function resolveContext(body, cfg, headers) {
+  const client = body && typeof body === "object" && "context" in body && typeof body.context === "object" ? body.context : {};
+  const trusted = cfg.trustedContext?.(headers) ?? {};
+  return { ...client, ...trusted };
+}
+function createFlagServer(config) {
+  const cache = createDefinitionCache();
+  const resolve = (env) => typeof config === "function" ? config(env) : config;
+  const app = new Hono();
+  app.use("*", async (c, next) => {
+    const cfg = resolve(c.env);
+    const origin = c.req.header("Origin");
+    if (origin && cfg.allowedOrigins?.includes(origin)) {
+      c.header("Access-Control-Allow-Origin", origin);
+      c.header("Access-Control-Allow-Credentials", "true");
+      c.header("Vary", "Origin");
+    }
+    if (c.req.method === "OPTIONS") {
+      c.header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+      c.header("Access-Control-Allow-Headers", "Content-Type, Authorization, x-api-key");
+      return c.body(null, 204);
+    }
+    return next();
+  });
+  app.get("/health", (c) => c.json({ status: "ok" }));
+  app.get("/api/v1/openapi.json", (c) => 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);
+  });
+  app.get("/admin/*", (c) => {
+    const cfg = resolve(c.env);
+    return cfg.dashboard ? c.html(cfg.dashboard) : c.text("Dashboard not configured", 404);
+  });
+  app.post("/ofrep/v1/evaluate/flags", async (c) => {
+    const cfg = resolve(c.env);
+    const auth = await cfg.auth.read(c.req.raw.headers);
+    if (!auth.ok) {
+      return c.json({ errorCode: "GENERAL", errorDetails: auth.message }, auth.status ?? 401);
+    }
+    const parsed = await readJsonBody(await c.req.text());
+    if (!parsed.ok) {
+      const errorCode = parsed.status === 413 ? "GENERAL" : "PARSE_ERROR";
+      return c.json({ errorCode, errorDetails: parsed.message }, parsed.status);
+    }
+    const context = resolveContext(parsed.value, cfg, c.req.raw.headers);
+    const flags = await cache.load(cfg.storage, ttlMs(cfg));
+    const results = await Promise.all(
+      flags.map(async (flag) => {
+        const result = await evaluate(flag, context);
+        return {
+          key: flag.key,
+          value: result.value,
+          reason: result.reason,
+          variant: result.value ? "on" : "off"
+        };
+      })
+    );
+    return c.json({ flags: results });
+  });
+  app.post("/ofrep/v1/evaluate/flags/:key", async (c) => {
+    const cfg = resolve(c.env);
+    const key = c.req.param("key");
+    const auth = await cfg.auth.read(c.req.raw.headers);
+    if (!auth.ok) {
+      return c.json({ key, errorCode: "GENERAL", errorDetails: auth.message }, auth.status ?? 401);
+    }
+    const parsed = await readJsonBody(await c.req.text());
+    if (!parsed.ok) {
+      const errorCode = parsed.status === 413 ? "GENERAL" : "PARSE_ERROR";
+      return c.json({ key, errorCode, errorDetails: parsed.message }, parsed.status);
+    }
+    const context = resolveContext(parsed.value, cfg, c.req.raw.headers);
+    const flags = await cache.load(cfg.storage, ttlMs(cfg));
+    const flag = flags.find((f) => f.key === key);
+    if (!flag) {
+      return c.json(
+        { key, errorCode: "FLAG_NOT_FOUND", errorDetails: `Flag ${key} not found` },
+        404
+      );
+    }
+    const result = await evaluate(flag, context);
+    return c.json({
+      key,
+      value: result.value,
+      reason: result.reason,
+      variant: result.value ? "on" : "off"
+    });
+  });
+  const registerAdmin = (prefix) => {
+    app.get(`${prefix}/flags`, async (c) => {
+      const cfg = resolve(c.env);
+      const auth = await cfg.auth.admin(c.req.raw.headers);
+      if (!auth.ok) return c.json({ error: auth.message ?? "Unauthorized" }, auth.status ?? 401);
+      return c.json({ flags: await cfg.storage.list() });
+    });
+    app.get(`${prefix}/flags/:key`, async (c) => {
+      const cfg = resolve(c.env);
+      const auth = await cfg.auth.admin(c.req.raw.headers);
+      if (!auth.ok) return c.json({ error: auth.message ?? "Unauthorized" }, auth.status ?? 401);
+      const flag = await cfg.storage.get(c.req.param("key"));
+      if (!flag) return c.json({ error: "Flag not found" }, 404);
+      return c.json(flag);
+    });
+    app.put(`${prefix}/flags/:key`, async (c) => {
+      const cfg = resolve(c.env);
+      const auth = await cfg.auth.admin(c.req.raw.headers);
+      if (!auth.ok) return c.json({ error: auth.message ?? "Unauthorized" }, auth.status ?? 401);
+      const key = c.req.param("key");
+      const parsed = await readJsonBody(await c.req.text());
+      if (!parsed.ok) return c.json({ error: parsed.message }, parsed.status);
+      const built = buildFlag(
+        key,
+        parsed.value,
+        auth.identity ?? "unknown",
+        await cfg.storage.get(key)
+      );
+      if (!built.ok) return c.json({ error: built.error }, 400);
+      await cfg.storage.put(key, built.flag);
+      cache.invalidate();
+      return c.json(built.flag);
+    });
+    app.delete(`${prefix}/flags/:key`, async (c) => {
+      const cfg = resolve(c.env);
+      const auth = await cfg.auth.admin(c.req.raw.headers);
+      if (!auth.ok) return c.json({ error: auth.message ?? "Unauthorized" }, auth.status ?? 401);
+      await cfg.storage.delete(c.req.param("key"));
+      cache.invalidate();
+      return c.body(null, 204);
+    });
+  };
+  registerAdmin("/api/v1");
+  registerAdmin("");
+  app.onError((err, c) => {
+    console.error("[flaghoist] unhandled error", err);
+    return c.json({ error: "Internal server error" }, 500);
+  });
+  return app;
+}
+export {
+  apiKey,
+  bearerToken,
+  createFlagServer,
+  oidc,
+  openApiDocument
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@flaghoist/server",
+  "version": "0.1.0",
+  "description": "Hono app factory for Flaghoist: OFREP evaluate, admin CRUD, and pluggable auth.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./dashboard": {
+      "import": {
+        "types": "./dist/dashboard.d.ts",
+        "default": "./dist/dashboard.js"
+      },
+      "require": {
+        "types": "./dist/dashboard.d.cts",
+        "default": "./dist/dashboard.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "dashboard": [
+        "./dist/dashboard.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "hono": "^4.13.0",
+    "jose": "^6.2.8",
+    "@flaghoist/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@flaghoist/adapter-memory": "0.1.0",
+    "@flaghoist/dashboard": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/embed-dashboard.mjs && tsup src/index.ts src/dashboard.ts --format esm,cjs --dts --clean",
+    "test": "node scripts/embed-dashboard.mjs && vitest run --passWithNoTests",
+    "typecheck": "node scripts/embed-dashboard.mjs && tsc --noEmit",
+    "check:package": "publint --strict && attw --pack ."
+  }
+}