@flaghoist/server 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -1,8 +1,182 @@
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
-import { StorageAdapter, AttributeValue } from '@flaghoist/core';
+import { StorageAdapter, AttributeValue, AuditEntry, AuditListOptions, AuditPage, FlagWebhookEvent, FlagSnapshot, MemberWebhookEvent } from '@flaghoist/core';
+export { AuditEntry, AuditPage, FlagSnapshot } from '@flaghoist/core';
 import { JWTVerifyGetKey } from 'jose';
 
+/**
+ * Admin roles, lowest to highest. Roles are hierarchical: each one can do everything the roles
+ * below it can.
+ */
+declare const ROLES: readonly ["viewer", "editor", "admin", "owner"];
+type Role = (typeof ROLES)[number];
+/** Something an admin request can do. Each admin route requires exactly one. */
+type Permission = 'flags:read' | 'flags:write' | 'flags:delete' | 'flags:import' | 'audit:read' | 'audit:security' | 'webhooks:manage' | 'members:manage';
+declare function minimumRole(permission: Permission): Role;
+/** Whether `role` holds `permission`. Anything that is not a known role holds nothing. */
+declare function can(role: unknown, permission: Permission): boolean;
+
+/**
+ * Optional email for invites and password reset links. Flaghoist ships no email provider: you
+ * pass a small object that sends a message however you like (Resend, Postmark, Amazon SES,
+ * Cloudflare Email, your own SMTP relay behind an HTTP API). Without one, the dashboard and CLI
+ * show the link for you to pass on yourself, as before.
+ */
+interface EmailMessage {
+    to: string;
+    subject: string;
+    text: string;
+    html: string;
+}
+interface EmailSender {
+    /** Send one message. Throw on failure; Flaghoist logs it and still returns the link. */
+    send(message: EmailMessage): Promise<void>;
+}
+
+/**
+ * Single sign-on with an OpenID Connect provider (Okta, Microsoft Entra, Google, Auth0, Keycloak).
+ * The authorization code flow with PKCE, run by the server so a client secret never reaches the
+ * browser. Nothing is stored between the redirect out and the redirect back: what the callback
+ * needs travels in the `state` parameter, encrypted and authenticated with a key derived from the
+ * pepper. That avoids cookies, which Flaghoist does not use, and Cloudflare KV's replication delay.
+ */
+interface SsoConfig {
+    /** The provider's issuer URL, exactly as it appears in its ID tokens. */
+    issuer: string;
+    clientId: string;
+    /** For a confidential client. Sent with HTTP Basic auth. Omit for a public client using PKCE. */
+    clientSecret?: string;
+    /** The name on the sign-in button, as in "Continue with Okta". Default `SSO`. */
+    label?: string;
+    /** Default `['openid', 'email', 'profile']`. Add your provider's groups scope if it needs one. */
+    scopes?: string[];
+    /** Only these email domains may sign in. Omit to allow any the provider vouches for. */
+    allowedDomains?: string[];
+    /** The ID token claim holding the person's groups. Default `groups`. */
+    groupsClaim?: string;
+    /**
+     * Group to role. When set, the provider decides roles: they are applied at every sign-in and
+     * cannot be changed in Flaghoist. Someone in several mapped groups gets the highest role.
+     */
+    roleMapping?: Record<string, Role>;
+    /**
+     * The role for someone in no mapped group. Omit to refuse them. Without `roleMapping`, this is
+     * the role new people get on their first sign-in.
+     */
+    defaultRole?: Role;
+    /** Require `email_verified: true` before trusting the email. Default true. See the docs for Entra. */
+    requireVerifiedEmail?: boolean;
+    /** Set false to turn off password sign-in for everyone. The admin token still works. */
+    passwordSignIn?: boolean;
+    /**
+     * The callback URL registered with the provider. Default: this server's own origin plus
+     * `/api/v1/auth/sso/callback`. Set it when a proxy changes the origin the server sees.
+     */
+    redirectUri?: string;
+}
+
+/**
+ * User accounts, password sign-in and server sessions. Everything here is stored through the
+ * adapter's generic record store, so accounts live in whatever storage the deployment already uses.
+ *
+ * Passwords never reach the server. The client stretches the password with PBKDF2 and sends the
+ * result (the "client key"); the server keys that with a secret pepper and stores only the HMAC.
+ * The slow hash therefore costs the client about 100 ms once per sign-in, and the server two HMACs,
+ * which keeps sign-in inside the 10 ms CPU budget of the Cloudflare Workers free plan.
+ */
+interface UsersConfig {
+    /**
+     * Server secret that keys every stored password verifier, at least 32 characters (for example
+     * `openssl rand -hex 32`). Keep it out of the storage backend and back it up: a database leak
+     * without the pepper reveals nothing useful, but losing the pepper invalidates every password.
+     */
+    pepper: string;
+    /** A short label stored with each verifier, so the pepper can be rotated later. Default `p1`. */
+    pepperId?: string;
+    session?: {
+        /** Sign a session out after this many minutes without a request. Default 30. */
+        idleMinutes?: number;
+        /** Sign a session out this many hours after sign-in, active or not. Default 12. */
+        maxHours?: number;
+    };
+    invites?: {
+        /** How long an invite link stays valid. Default 7 days. Password reset links last 24 hours. */
+        expiresInDays?: number;
+    };
+    /** Sign in with an OpenID Connect provider as well as, or instead of, a password. */
+    sso?: SsoConfig;
+    /**
+     * Who must use a two-factor code with their password: `optional` (the default), `admins` (admins
+     * and owners) or `everyone`. Someone who must but has not set it up is asked to at their next
+     * sign-in and can do nothing else until they have. SSO sign-ins are exempt; the identity
+     * provider's own two-factor covers them.
+     */
+    twoFactor?: 'optional' | 'admins' | 'everyone';
+    /**
+     * Email invites and password reset links as well as showing them. Flaghoist bundles no
+     * provider: pass an object with `send({ to, subject, text, html })`. See the docs for Resend and
+     * Postmark examples.
+     */
+    email?: EmailSender;
+}
+type UserStatus = 'active' | 'disabled';
+/** What the API returns for a user: never the verifier. */
+interface PublicUser {
+    id: string;
+    email: string;
+    name: string;
+    role: Role;
+    status: UserStatus;
+    /** Whether the account has a password. SSO-only accounts do not. */
+    hasPassword: boolean;
+    /** Whether the account has signed in with SSO. */
+    sso?: boolean;
+    /** Set when the SSO provider decides the role, so it cannot be changed here. */
+    roleManagedBy?: 'sso';
+    /** Whether the account uses two-factor codes. */
+    twoFactor: boolean;
+    /** Roles that differ from `role` in particular environments. */
+    environmentRoles?: Record<string, Role>;
+    createdAt: string;
+    lastLoginAt?: string;
+}
+/** An invite to join, or a link to set a new password. Stored under the hash of its token. */
+interface InviteRecord {
+    id: string;
+    kind: 'invite' | 'reset';
+    email: string;
+    role: Role;
+    /** The account a reset link is for. Absent on invites, whose account does not exist yet. */
+    userId?: string;
+    invitedBy: string;
+    createdAt: string;
+    expiresAt: string;
+}
+type PublicInvite = Omit<InviteRecord, 'userId'>;
+/** A personal access token. Stored under the hash of the token itself. */
+interface TokenRecord {
+    id: string;
+    userId: string;
+    name: string;
+    /** The most this token may do. Its owner's current role caps it further on every request. */
+    role: Role;
+    /** The first characters of the token, so people can tell their tokens apart. */
+    prefix: string;
+    createdAt: string;
+    /** Absent means the token never expires. */
+    expiresAt?: string;
+    lastUsedAt?: string;
+}
+type PublicToken = Omit<TokenRecord, 'userId'>;
+interface PublicSession {
+    id: string;
+    createdAt: string;
+    lastSeenAt: string;
+    expiresAt: string;
+    userAgent?: string;
+    current: boolean;
+}
+
 /**
  * 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
@@ -63,6 +237,18 @@ interface AuthResult {
     ok: boolean;
     /** Caller identity (email/subject/'api-key') recorded in audit metadata when ok. */
     identity?: string;
+    /**
+     * The environment this credential is scoped to, when the read verifier is environment-aware
+     * (see `apiKeys()` in auth.ts). Absent means "not environment-specific": the request maps to
+     * the server's default environment.
+     */
+    environment?: string;
+    /**
+     * The caller's admin role, on the admin path. Absent means `owner`, which is exactly the access
+     * every admin verifier granted before roles existed, so existing verifiers keep working
+     * unchanged. A value that is not a known role grants nothing.
+     */
+    role?: Role;
     /** HTTP status to return when not ok. */
     status?: 401 | 403;
     /** Public, non-sensitive error message when not ok. */
@@ -110,12 +296,56 @@ interface ServerConfig {
      * set this to `false` and stop advertising its own API surface.
      */
     exposeOpenApi?: boolean;
+    /**
+     * Named environments this deployment serves (e.g. `['production', 'staging', 'development']`).
+     * When set, flags are partitioned per environment: the same key can be on in staging and off in
+     * production, each with its own audit trail. Admin requests choose one with the
+     * `X-Flaghoist-Environment` header (defaulting to `defaultEnvironment` when omitted); the read
+     * (OFREP) path is scoped by whichever environment the read credential maps to (see `apiKeys()`).
+     *
+     * Omit entirely to run with a single, unnamed environment exactly as before. No migration
+     * needed, and existing flags are unaffected.
+     */
+    environments?: string[];
+    /**
+     * Which configured environment is the default: it uses bare storage keys and never stamps
+     * `environment` on a flag, so flags created before environments existed are already in it with
+     * zero migration. Default: `'production'`.
+     */
+    defaultEnvironment?: string;
+    /**
+     * Turn on user accounts: people sign in to the dashboard with an email and password, get a role,
+     * and every change is recorded against their email. Needs a storage adapter with the record
+     * store (every bundled adapter has one) and a `pepper` secret. The `auth.admin` verifier keeps
+     * working as an Owner credential, for creating the first account and for recovery.
+     *
+     * Omit to keep the single shared admin token, exactly as before.
+     */
+    users?: UsersConfig;
 }
 /** Config, or a function that derives it from the runtime environment (e.g. Workers bindings). */
 type ConfigResolver<Env> = ServerConfig | ((env: Env) => ServerConfig);
 
+interface AuditLog {
+    record(entry: Omit<AuditEntry, 'id' | 'timestamp'>): Promise<void>;
+    list(options?: AuditListOptions): Promise<AuditPage>;
+}
+
 /** Read-path verifier: matches the `x-api-key` header against a shared secret in constant time. */
 declare function apiKey(expected: string): Authenticator;
+/**
+ * Read-path verifier for multiple environments: each environment gets its own `x-api-key`
+ * secret, so a key scoped to staging cannot read production and a leaked staging key has no
+ * blast radius beyond it. The matched environment is attached to the `AuthResult` and flows
+ * through to `ServerConfig.environments` scoping; see `resolveReadEnvironment` in
+ * environments.ts.
+ *
+ * All configured keys are compared in parallel (rather than short-circuiting on first match) so
+ * the number of environments configured does not itself become a timing signal.
+ *
+ * @example apiKeys({ production: env.READ_KEY_PROD, staging: env.READ_KEY_STAGING })
+ */
+declare function apiKeys(keys: Record<string, 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.
@@ -147,6 +377,41 @@ interface OidcOptions {
  */
 declare function oidc(options: OidcOptions): Authenticator;
 
+/**
+ * Wrap a StorageAdapter so its flag methods (`get`/`put`/`delete`/`list`) are scoped to one
+ * environment. The default environment uses bare keys and never stamps `environment` on the
+ * flag, so a deployment that turns environments on for the first time needs no migration:
+ * existing flags are already the default environment. A named environment prefixes the storage
+ * key and stamps `environment` on write, so `list()`, which sees every key in the shared
+ * backend, can tell environments apart.
+ *
+ * Non-flag concerns (audit, webhooks) are deliberately not scoped here; they stay on the
+ * unscoped adapter passed to `createAuditLog`/`createWebhookStore` in index.ts.
+ */
+declare function scopedStorage(storage: StorageAdapter, environment: string, defaultEnvironment: string): StorageAdapter;
+type EnvironmentResolution = {
+    ok: true;
+    environment: string;
+} | {
+    ok: false;
+    status: 400;
+    message: string;
+};
+/**
+ * Resolve which environment an admin request targets, from the `X-Flaghoist-Environment` header.
+ * When the server has no `environments` configured, the feature is fully off: every request maps
+ * to `defaultEnvironment` regardless of the header, so `scopedStorage` acts as a no-op passthrough
+ * and a deployment that never opts in sees no behavior change at all.
+ */
+declare function resolveAdminEnvironment(environments: string[] | undefined, defaultEnvironment: string, headers: Headers): EnvironmentResolution;
+/**
+ * Resolve which environment a read (OFREP) request targets, from the environment the auth
+ * verifier attached to its result (see `apiKeys()` in auth.ts). A verifier that does not name an
+ * environment (the plain `apiKey()` single-secret verifier) always maps to the default
+ * environment, and so does any value outside the configured list.
+ */
+declare function resolveReadEnvironment(environments: string[] | undefined, defaultEnvironment: string, authEnvironment: string | undefined): string;
+
 /**
  * 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'`).
@@ -157,6 +422,48 @@ declare function oidc(options: OidcOptions): Authenticator;
  */
 declare const openApiDocument: Record<string, unknown>;
 
+interface FlagWebhookPayload {
+    event: FlagWebhookEvent;
+    timestamp: string;
+    flag: {
+        key: string;
+        enabled: boolean;
+        rollout: {
+            percentage: number;
+        };
+        description: string;
+    };
+    actor: string;
+    previous?: FlagSnapshot;
+    /** The environment the change happened in. Absent means the default environment. */
+    environment?: string;
+}
+/** A team change. Only sent to webhooks that list the member event. */
+interface MemberWebhookPayload {
+    event: MemberWebhookEvent;
+    timestamp: string;
+    actor: string;
+    member: {
+        /** Absent for `member.invited`: the account does not exist yet. */
+        id?: string;
+        email: string;
+        role: string;
+        status?: string;
+        environmentRoles?: Record<string, string>;
+    };
+    /** What changed from, on `member.role_changed`. */
+    previous?: {
+        role: string;
+        environmentRoles?: Record<string, string>;
+    };
+}
+type WebhookPayload = FlagWebhookPayload | MemberWebhookPayload;
+
+/**
+ * How the shared admin token appears in the audit log, flag metadata and webhooks once user
+ * accounts are on, so its changes stand out from those made by a named person.
+ */
+declare const ADMIN_TOKEN_IDENTITY = "admin token";
 /**
  * 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
@@ -166,4 +473,4 @@ declare function createFlagServer<Env extends object = Record<string, unknown>>(
     Bindings: Env;
 }, hono_types.BlankSchema, "/">;
 
-export { type AuthResult, type Authenticator, type ConfigResolver, type MemoryRateLimitOptions, type OidcOptions, type RateLimit, type RateLimitResult, type ServerConfig, apiKey, bearerToken, createFlagServer, defaultRateLimitKey, memoryRateLimit, oidc, openApiDocument };
+export { ADMIN_TOKEN_IDENTITY, type AuditLog, type AuthResult, type Authenticator, type ConfigResolver, type EmailMessage, type EmailSender, type EnvironmentResolution, type FlagWebhookPayload, type MemberWebhookPayload, type MemoryRateLimitOptions, type OidcOptions, type Permission, type PublicInvite, type PublicSession, type PublicToken, type PublicUser, ROLES, type RateLimit, type RateLimitResult, type Role, type ServerConfig, type SsoConfig, type UsersConfig, type WebhookPayload, apiKey, apiKeys, bearerToken, can, createFlagServer, defaultRateLimitKey, memoryRateLimit, minimumRole, oidc, openApiDocument, resolveAdminEnvironment, resolveReadEnvironment, scopedStorage };