@flaghoist/server 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,101 @@
+import * as hono_types from 'hono/types';
+import { Hono } from 'hono';
+import { StorageAdapter, AttributeValue } from '@flaghoist/core';
+import { JWTVerifyGetKey } from 'jose';
+
+/** Result of an authentication attempt. `ok: false` carries the status/message to return. */
+interface AuthResult {
+    ok: boolean;
+    /** Caller identity (email/subject/'api-key') recorded in audit metadata when ok. */
+    identity?: string;
+    /** HTTP status to return when not ok. */
+    status?: 401 | 403;
+    /** Public, non-sensitive error message when not ok. */
+    message?: string;
+}
+/**
+ * Authenticates a request from its headers. Verifiers extract whatever credential they need
+ * (an API key header, a bearer token, …) and never throw for an ordinary auth failure.
+ */
+type Authenticator = (headers: Headers) => Promise<AuthResult> | AuthResult;
+interface ServerConfig {
+    /** Storage backend (any StorageAdapter — Cloudflare KV, memory, or your own). */
+    storage: StorageAdapter;
+    auth: {
+        /** Guards the admin/write path (create/update/delete + full flag reads). */
+        admin: Authenticator;
+        /** Guards the OFREP read/evaluate path. */
+        read: Authenticator;
+    };
+    /** Exact-match CORS origin allowlist. Omit for same-origin only (no CORS headers emitted). */
+    allowedOrigins?: string[];
+    /** TTL in seconds for the in-isolate flag-definition cache on the read path. Default: 30. */
+    cacheTtlSeconds?: number;
+    /**
+     * 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
+     * made trustworthy rather than self-asserted.
+     */
+    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.
+     */
+    dashboard?: string;
+}
+/** Config, or a function that derives it from the runtime environment (e.g. Workers bindings). */
+type ConfigResolver<Env> = ServerConfig | ((env: Env) => ServerConfig);
+
+/** Read-path verifier: matches the `x-api-key` header against a shared secret in constant time. */
+declare function apiKey(expected: string): Authenticator;
+/**
+ * Admin-path verifier: matches an `Authorization: Bearer <token>` against a shared secret in
+ * constant time. The zero-config default — possession of the token is admin authorization.
+ */
+declare function bearerToken(expected: string): Authenticator;
+interface OidcOptions {
+    /** Token issuer URL, validated against the `iss` claim. */
+    issuer: string;
+    /** Expected `aud` claim (your app/client id). */
+    audience: string;
+    /** JWKS URL. Defaults to `<issuer>/.well-known/jwks.json`. */
+    jwksUri?: string;
+    /** Allowed signature algorithms. Defaults to `['RS256']`. `alg: none` is always rejected. */
+    algorithms?: string[];
+    /** Optional `token_use` claim to require (e.g. `'id'` for Cognito id tokens). */
+    tokenUse?: string;
+    /** Claim holding the caller's groups. Defaults to `'groups'`. */
+    groupsClaim?: string;
+    /** If set, the caller must belong to at least one of these groups (authorization). */
+    allowedGroups?: string[];
+    /** Advanced/testing: supply a key resolver instead of fetching the remote JWKS. */
+    keyResolver?: JWTVerifyGetKey;
+}
+/**
+ * Admin-path verifier backed by an OIDC provider (Cognito, Auth0, Okta, Keycloak, Entra, …).
+ * Validates the JWT signature against the provider's JWKS with a pinned algorithm allowlist,
+ * checks `iss`/`aud`/`exp`/`nbf` (and optionally `token_use`), then enforces group membership.
+ * Signature/claim validation is delegated to the audited `jose` library.
+ */
+declare function oidc(options: OidcOptions): Authenticator;
+
+/**
+ * OpenAPI 3.1 description of the Flaghoist HTTP API. It is served at `GET /api/v1/openapi.json`
+ * and exported for tooling (`import { openApiDocument } from '@flaghoist/server'`).
+ *
+ * The admin API (`/api/v1/flags`) is Flaghoist's own, versioned surface for building dashboards
+ * and integrations. The read API (`/ofrep/v1/...`) follows the OpenFeature Remote Evaluation
+ * Protocol and is described here for completeness.
+ */
+declare const openApiDocument: Record<string, unknown>;
+
+/**
+ * Build a Flaghoist server as a Hono app. Pass a config object, or a function that derives the
+ * config from the runtime environment (e.g. Cloudflare Workers bindings). The returned app has a
+ * `fetch` handler, so `export default createFlagServer(...)` works as a Worker entrypoint.
+ */
+declare function createFlagServer<Env extends object = Record<string, unknown>>(config: ConfigResolver<Env>): Hono<{
+    Bindings: Env;
+}, hono_types.BlankSchema, "/">;
+
+export { type AuthResult, type Authenticator, type ConfigResolver, type OidcOptions, type ServerConfig, apiKey, bearerToken, createFlagServer, oidc, openApiDocument };

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import * as hono_types from 'hono/types';
+import { Hono } from 'hono';
+import { StorageAdapter, AttributeValue } from '@flaghoist/core';
+import { JWTVerifyGetKey } from 'jose';
+
+/** Result of an authentication attempt. `ok: false` carries the status/message to return. */
+interface AuthResult {
+    ok: boolean;
+    /** Caller identity (email/subject/'api-key') recorded in audit metadata when ok. */
+    identity?: string;
+    /** HTTP status to return when not ok. */
+    status?: 401 | 403;
+    /** Public, non-sensitive error message when not ok. */
+    message?: string;
+}
+/**
+ * Authenticates a request from its headers. Verifiers extract whatever credential they need
+ * (an API key header, a bearer token, …) and never throw for an ordinary auth failure.
+ */
+type Authenticator = (headers: Headers) => Promise<AuthResult> | AuthResult;
+interface ServerConfig {
+    /** Storage backend (any StorageAdapter — Cloudflare KV, memory, or your own). */
+    storage: StorageAdapter;
+    auth: {
+        /** Guards the admin/write path (create/update/delete + full flag reads). */
+        admin: Authenticator;
+        /** Guards the OFREP read/evaluate path. */
+        read: Authenticator;
+    };
+    /** Exact-match CORS origin allowlist. Omit for same-origin only (no CORS headers emitted). */
+    allowedOrigins?: string[];
+    /** TTL in seconds for the in-isolate flag-definition cache on the read path. Default: 30. */
+    cacheTtlSeconds?: number;
+    /**
+     * 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
+     * made trustworthy rather than self-asserted.
+     */
+    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.
+     */
+    dashboard?: string;
+}
+/** Config, or a function that derives it from the runtime environment (e.g. Workers bindings). */
+type ConfigResolver<Env> = ServerConfig | ((env: Env) => ServerConfig);
+
+/** Read-path verifier: matches the `x-api-key` header against a shared secret in constant time. */
+declare function apiKey(expected: string): Authenticator;
+/**
+ * Admin-path verifier: matches an `Authorization: Bearer <token>` against a shared secret in
+ * constant time. The zero-config default — possession of the token is admin authorization.
+ */
+declare function bearerToken(expected: string): Authenticator;
+interface OidcOptions {
+    /** Token issuer URL, validated against the `iss` claim. */
+    issuer: string;
+    /** Expected `aud` claim (your app/client id). */
+    audience: string;
+    /** JWKS URL. Defaults to `<issuer>/.well-known/jwks.json`. */
+    jwksUri?: string;
+    /** Allowed signature algorithms. Defaults to `['RS256']`. `alg: none` is always rejected. */
+    algorithms?: string[];
+    /** Optional `token_use` claim to require (e.g. `'id'` for Cognito id tokens). */
+    tokenUse?: string;
+    /** Claim holding the caller's groups. Defaults to `'groups'`. */
+    groupsClaim?: string;
+    /** If set, the caller must belong to at least one of these groups (authorization). */
+    allowedGroups?: string[];
+    /** Advanced/testing: supply a key resolver instead of fetching the remote JWKS. */
+    keyResolver?: JWTVerifyGetKey;
+}
+/**
+ * Admin-path verifier backed by an OIDC provider (Cognito, Auth0, Okta, Keycloak, Entra, …).
+ * Validates the JWT signature against the provider's JWKS with a pinned algorithm allowlist,
+ * checks `iss`/`aud`/`exp`/`nbf` (and optionally `token_use`), then enforces group membership.
+ * Signature/claim validation is delegated to the audited `jose` library.
+ */
+declare function oidc(options: OidcOptions): Authenticator;
+
+/**
+ * OpenAPI 3.1 description of the Flaghoist HTTP API. It is served at `GET /api/v1/openapi.json`
+ * and exported for tooling (`import { openApiDocument } from '@flaghoist/server'`).
+ *
+ * The admin API (`/api/v1/flags`) is Flaghoist's own, versioned surface for building dashboards
+ * and integrations. The read API (`/ofrep/v1/...`) follows the OpenFeature Remote Evaluation
+ * Protocol and is described here for completeness.
+ */
+declare const openApiDocument: Record<string, unknown>;
+
+/**
+ * Build a Flaghoist server as a Hono app. Pass a config object, or a function that derives the
+ * config from the runtime environment (e.g. Cloudflare Workers bindings). The returned app has a
+ * `fetch` handler, so `export default createFlagServer(...)` works as a Worker entrypoint.
+ */
+declare function createFlagServer<Env extends object = Record<string, unknown>>(config: ConfigResolver<Env>): Hono<{
+    Bindings: Env;
+}, hono_types.BlankSchema, "/">;
+
+export { type AuthResult, type Authenticator, type ConfigResolver, type OidcOptions, type ServerConfig, apiKey, bearerToken, createFlagServer, oidc, openApiDocument };