@kb-labs/gateway-auth 2.94.0 → 2.96.0

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 import { ICache } from '@kb-labs/core-platform';
 import { TokenType, JwtPayload, RegisterRequest, RegisterResponse, TokenResponse, AuthContext } from '@kb-labs/gateway-contracts';
+import { IDocumentDatabase, IKVStore } from '@kb-labs/core-platform/adapters';
+import { IdentityUserPort, IdentityCredentialPort, IIdentityProvider, IdentityProviderDeps, IRedirectIdentityProvider, IdentityProviderFactory, IPolicyDecisionPoint } from '@kb-labs/core-contracts';
+export { IPolicyDecisionPoint, Identity, PolicyContext, PolicyDecision, Resource } from '@kb-labs/core-contracts';
+import { z } from 'zod';
 
 /**
  * JWT sign / verify / refresh logic.
@@ -15,6 +19,8 @@ interface SignAccessTokenOptions {
     namespaceId: string;
     tier: 'free' | 'pro' | 'enterprise';
     type: TokenType;
+    /** Permissions to embed in the JWT payload. Defaults to [] when absent. */
+    permissions?: string[];
 }
 declare function signAccessToken(opts: SignAccessTokenOptions, config: JwtConfig): Promise<{
     token: string;
@@ -25,6 +31,52 @@ declare function verifyAccessToken(token: string, config: JwtConfig): Promise<Jw
 declare function verifyRefreshToken(token: string, config: JwtConfig): Promise<{
     hostId: string;
 } | null>;
+interface SignUserTokenOptions {
+    userId: string;
+    tenantId: string;
+    familyId: string;
+    /** TTL in seconds. */
+    ttlSec: number;
+}
+interface UserAccessPayload {
+    userId: string;
+    tenantId: string;
+    familyId: string;
+    jti: string;
+    /** Token type discriminator. Access tokens carry 'user'. */
+    type: 'user';
+    iat: number;
+    exp: number;
+}
+interface UserRefreshPayload {
+    userId: string;
+    tenantId: string;
+    familyId: string;
+    jti: string;
+    type: 'refresh';
+    iat: number;
+    exp: number;
+}
+interface UserAccessSignResult {
+    token: string;
+    expiresInSec: number;
+    jti: string;
+}
+declare function signUserAccessToken(opts: SignUserTokenOptions, config: JwtConfig): Promise<UserAccessSignResult>;
+/**
+ * Sign a user refresh token.
+ *
+ * When the caller already owns the `jti` (typical: the sessions-store
+ * minted it inside `createSession`/`rotateRefresh`), pass it via the
+ * second argument so the JWT and the store agree on the identifier.
+ * Otherwise the helper generates one — used by tests that don't go
+ * through sessions-store.
+ */
+declare function signUserRefreshToken(opts: SignUserTokenOptions & {
+    jti?: string;
+}, config: JwtConfig): Promise<string>;
+declare function verifyUserAccessToken(token: string, config: JwtConfig): Promise<UserAccessPayload | null>;
+declare function verifyUserRefreshToken(token: string, config: JwtConfig): Promise<UserRefreshPayload | null>;
 
 /**
  * AuthService — orchestrates registration, token issuance, and refresh.
@@ -40,6 +92,11 @@ declare class AuthService {
     }>;
     issueTokens(clientId: string, clientSecret: string): Promise<TokenResponse | null>;
     refreshTokens(refreshToken: string): Promise<TokenResponse | null>;
+    me(hostId: string): Promise<{
+        hostId: string;
+        handle?: string;
+        namespaceId: string;
+    } | null>;
     verify(token: string): Promise<AuthContext | null>;
 }
 
@@ -50,6 +107,7 @@ declare class AuthService {
  *   auth:client:{clientId}          → ClientRecord  (permanent)
  *   auth:refresh:{tokenHash}        → { hostId }     (TTL 30d)
  *   auth:publickey:{hostId}         → string (base64url X25519 public key)
+ *   auth:handle:{handle}            → clientId       (permanent, handle index)
  */
 
 interface ClientRecord {
@@ -61,22 +119,32 @@ interface ClientRecord {
     tier: 'free' | 'pro' | 'enterprise';
     name: string;
     capabilities: string[];
+    /** Permissions embedded in issued JWTs. If absent, defaults to ['host:connect']. */
+    permissions?: string[];
     publicKey?: string;
     createdAt: number;
+    /** Unique human-readable handle for the marketplace (e.g. "kirill"). Immutable once set. */
+    handle?: string;
+    email?: string;
 }
 declare function generateClientId(): string;
 declare function generateClientSecret(): string;
 declare function generateHostId(): string;
 declare function saveClient(cache: ICache, record: ClientRecord): Promise<void>;
+declare function isHandleTaken(cache: ICache, handle: string): Promise<boolean>;
+declare function getClientByHandle(cache: ICache, handle: string): Promise<ClientRecord | null>;
 declare function getClientByHostId(cache: ICache, hostId: string): Promise<ClientRecord | null>;
 declare function getClient(cache: ICache, clientId: string): Promise<ClientRecord | null>;
 declare function verifyClientSecret(cache: ICache, clientId: string, secret: string): Promise<ClientRecord | null>;
 declare function buildClientRecord(opts: {
     name: string;
     capabilities: string[];
+    permissions?: string[];
     publicKey?: string;
     secret: string;
     namespaceId?: string;
+    handle?: string;
+    email?: string;
 }): ClientRecord;
 declare function saveRefreshToken(cache: ICache, token: string, hostId: string, namespaceId: string): Promise<void>;
 declare function consumeRefreshToken(cache: ICache, token: string): Promise<{
@@ -86,4 +154,909 @@ declare function consumeRefreshToken(cache: ICache, token: string): Promise<{
 declare function savePublicKey(cache: ICache, hostId: string, publicKey: string): Promise<void>;
 declare function getPublicKey(cache: ICache, hostId: string): Promise<string | null>;
 
-export { AuthService, type ClientRecord, type JwtConfig, buildClientRecord, consumeRefreshToken, generateClientId, generateClientSecret, generateHostId, getClient, getClientByHostId, getPublicKey, saveClient, savePublicKey, saveRefreshToken, signAccessToken, signRefreshToken, verifyAccessToken, verifyClientSecret, verifyRefreshToken };
+/**
+ * @module @kb-labs/gateway-auth/users-store
+ *
+ * Document-backed store for `User` records (ADR-0020, Phase 1.1).
+ *
+ * Schema invariants:
+ * - `(tenantId, email)` is a unique compound — one user per email per
+ *   tenant. The same email can exist in different tenants.
+ * - `email` is **always** stored lowercased + trimmed (CD-4). Callers
+ *   may pass any casing; the store normalises before write/read.
+ * - **No** password hash on this document. Credentials live in the
+ *   separate `credentials` collection (CD-6) so a future Google/Okta
+ *   provider can attach to the same `User` without a schema migration.
+ *
+ * Pattern follows `plugins/gateway/core/src/stores/host-store.ts`:
+ * one-shot `ensureSchema()` plus per-method idempotent `ensureCollection`
+ * registration.
+ */
+
+type UserStatus = 'pending' | 'active' | 'disabled';
+interface User {
+    userId: string;
+    tenantId: string;
+    /** Lowercase + trimmed (CD-4). */
+    email: string;
+    displayName?: string;
+    status: UserStatus;
+    createdAt: number;
+    updatedAt?: number;
+}
+/**
+ * Canonical email form used everywhere this store touches.
+ *
+ * Exported so other modules (the email-password provider, invites-store)
+ * normalise identically — having one function prevents drift where one
+ * caller forgets to trim and lookups silently miss.
+ */
+declare const canonicalizeEmail: (raw: string) => string;
+interface CreateUserInput {
+    userId: string;
+    tenantId: string;
+    email: string;
+    status: UserStatus;
+    displayName?: string;
+}
+declare class UsersStore {
+    private readonly docs;
+    private initialised;
+    constructor(docs: IDocumentDatabase);
+    private ensureSchema;
+    create(input: CreateUserInput): Promise<User>;
+    getById(userId: string): Promise<User | null>;
+    findByEmailTenant(email: string, tenantId: string): Promise<User | null>;
+    setStatus(userId: string, status: UserStatus): Promise<void>;
+    /** List all users for a given tenant. */
+    listByTenant(tenantId: string): Promise<User[]>;
+    delete(userId: string): Promise<void>;
+}
+
+/**
+ * @module @kb-labs/gateway-auth/credentials-store
+ *
+ * Document-backed store for per-provider credentials (ADR-0020, CD-6,
+ * Phase 1.2).
+ *
+ * `User` does not carry a password hash. Credentials live here, keyed by
+ * the compound `(userId, providerId)`. Adding a new identity provider
+ * (Google, Okta, LDAP, ...) means writing a row with a new `providerId`
+ * — no schema migration on the `users` collection, no `passwordHash?:
+ * null` quirks.
+ *
+ * Hash format and algorithm are the provider's concern: this store only
+ * persists opaque strings. The `email-password` provider chooses bcrypt
+ * with a configured cost.
+ */
+
+interface Credential {
+    userId: string;
+    providerId: string;
+    /** Opaque to this store — bcrypt hash for email-password, OAuth refresh blob for future providers, etc. */
+    hash: string;
+    createdAt: number;
+    updatedAt?: number;
+}
+interface SetCredentialInput {
+    userId: string;
+    providerId: string;
+    hash: string;
+}
+declare class CredentialsStore {
+    private readonly docs;
+    private initialised;
+    constructor(docs: IDocumentDatabase);
+    private ensureSchema;
+    setCredential(input: SetCredentialInput): Promise<void>;
+    getCredential(userId: string, providerId: string): Promise<Credential | null>;
+    deleteCredential(userId: string, providerId: string): Promise<void>;
+    /**
+     * Cascade removal helper — call from the parent flow when a `User` is
+     * deleted so we never leave dangling credentials in the store.
+     */
+    deleteAllForUser(userId: string): Promise<void>;
+}
+
+/**
+ * @module @kb-labs/gateway-auth/memberships-store
+ *
+ * Document-backed store for `Membership` records (ADR-0020, Phase 1.3).
+ *
+ * A membership is one row per `(userId, tenantId)` with a single
+ * `groupId`. Group strings are hardcoded for this iteration —
+ * `tenant-admin` and `tenant-member` — and consumed by the stub PDP.
+ *
+ * When the real RBAC + ReBAC engine lands (ClickUp 869def338) the
+ * meaning of `groupId` becomes richer (multiple group memberships,
+ * group hierarchies, relations) but the store API stays — the engine
+ * sits behind the PDP and reads from here. The "one membership per
+ * (userId, tenantId)" invariant may need to flex later; for now we keep
+ * it tight so the stub PDP has unambiguous lookups.
+ */
+
+/** Hardcoded group ids for the stub PDP iteration. */
+type GroupId = 'tenant-admin' | 'tenant-member';
+interface Membership {
+    userId: string;
+    tenantId: string;
+    groupId: GroupId;
+    createdAt: number;
+    updatedAt?: number;
+}
+interface AddMembershipInput {
+    userId: string;
+    tenantId: string;
+    groupId: GroupId;
+}
+declare class MembershipsStore {
+    private readonly docs;
+    private initialised;
+    constructor(docs: IDocumentDatabase);
+    private ensureSchema;
+    addMembership(input: AddMembershipInput): Promise<void>;
+    setGroup(userId: string, tenantId: string, groupId: GroupId): Promise<void>;
+    listByUser(userId: string): Promise<Membership[]>;
+    listByTenant(tenantId: string): Promise<Membership[]>;
+    removeMembership(userId: string, tenantId: string): Promise<void>;
+    /** Cascade hook — call when a `User` is deleted. */
+    removeAllForUser(userId: string): Promise<void>;
+}
+
+/**
+ * @module @kb-labs/gateway-auth/invites-store
+ *
+ * Document-backed store for activation invites (ADR-0020, Phase 1.4).
+ *
+ * Invites are admin-issued tokens that bootstrap a user account: the
+ * recipient activates by POSTing the token along with a password.
+ *
+ * Security details worth keeping straight:
+ *
+ * - Token plaintext **never** lands in the database. We store
+ *   `tokenHash = sha256(plain)` and look up by hash. A snapshot of the
+ *   `invites` collection is useless without the original tokens.
+ * - The unique compound `(tenantId, email, status='active')` is not
+ *   easy to express across drivers, so uniqueness is enforced in code
+ *   on top of a non-unique compound index. Concurrent races during
+ *   `createInvite` are not a real attack vector here (admin UI is
+ *   single-clicked) and we accept the small theoretical window.
+ * - TTL is best-effort on the index; **every read path** explicitly
+ *   checks `expiresAt > now` (CD-9). Without that, a not-yet-swept row
+ *   would be returned and the activation flow would accept it.
+ * - Emails are canonicalised on the way in (CD-4) so admins can paste
+ *   "Alice@Example.COM" without breaking lookups.
+ */
+
+type InviteStatus = 'active' | 'used' | 'revoked';
+interface InviteRecord {
+    inviteId: string;
+    email: string;
+    tenantId: string;
+    groupId: GroupId;
+    status: InviteStatus;
+    createdBy: string;
+    createdAt: number;
+    expiresAt: number;
+    updatedAt?: number;
+}
+interface CreateInviteInput {
+    email: string;
+    tenantId: string;
+    groupId: GroupId;
+    createdBy: string;
+    ttlMs: number;
+}
+interface CreateInviteResult {
+    inviteId: string;
+    activationToken: string;
+    expiresAt: number;
+}
+declare class InvitesStore {
+    private readonly docs;
+    private readonly now;
+    private initialised;
+    constructor(docs: IDocumentDatabase, now?: () => number);
+    private ensureSchema;
+    createInvite(input: CreateInviteInput): Promise<CreateInviteResult>;
+    findById(inviteId: string): Promise<InviteRecord | null>;
+    /**
+     * Look up an invite by the plaintext activation token. Returns `null`
+     * for missing, expired, used, or revoked invites — callers do not
+     * need to filter further.
+     *
+     * Returns a discriminated result so callers can distinguish:
+     *   - { kind: 'not_found' }  — token hash not in DB (garbage/unknown token)
+     *   - { kind: 'invalid' }    — token exists but expired, used, or revoked
+     *   - { kind: 'ok', invite } — valid, active invite ready for activation
+     */
+    findByToken(plainToken: string): Promise<{
+        kind: 'not_found';
+    } | {
+        kind: 'invalid';
+    } | {
+        kind: 'ok';
+        invite: InviteRecord;
+    }>;
+    /**
+     * Atomically mark an active invite as used.
+     *
+     * Returns `true` if THIS call flipped the invite from `active` → `used`,
+     * `false` if it was already used/revoked (or unknown). The filter pins
+     * `status: 'active'`, so a concurrent double-activation of the same token
+     * results in exactly one caller seeing `true` — the activation flow relies
+     * on this to close the TOCTOU window between `findByToken` and account
+     * creation (a second parallel request must NOT create a duplicate account).
+     */
+    consume(inviteId: string): Promise<boolean>;
+    revoke(inviteId: string): Promise<void>;
+    /** List all invites for a tenant (active + used + revoked). */
+    listByTenant(tenantId: string): Promise<InviteRecord[]>;
+}
+
+/**
+ * @module @kb-labs/gateway-auth/sessions-store
+ *
+ * Session families + refresh tokens (ADR-0020, Phase 1.5).
+ *
+ * This module owns three things:
+ *
+ * 1. **Session families.** One row per device. The family is the unit
+ *    of revocation — "log out this device", "kick this user from all
+ *    devices", "the password just changed, keep the current device".
+ * 2. **Refresh tokens.** One-shot rotation: every refresh request
+ *    consumes the old jti and issues a new one in the same family.
+ * 3. **Reuse detection + 5-second grace window (CD-5).** Reusing an
+ *    already-consumed refresh is either a stolen cookie or a legit
+ *    multi-tab race. The grace window resolves the ambiguity: if the
+ *    client presents the same already-consumed jti within 5s, we
+ *    return the same replacement we issued first time. Beyond 5s, we
+ *    treat it as theft and kill the entire family.
+ *
+ * Notes on storage:
+ *
+ * - Refresh tokens carry an explicit `expiresAt` and we check it
+ *   manually on every read (CD-9) — the TTL index sweep is best-effort.
+ * - `rotateRefresh` runs inside a `transaction(cb)` so a concurrent
+ *   second caller sees the consumed state and goes through the
+ *   grace/reuse branch instead of inserting a parallel replacement.
+ */
+
+interface SessionFamily {
+    familyId: string;
+    userId: string;
+    tenantId: string;
+    createdAt: number;
+    lastUsedAt: number;
+    userAgent?: string;
+    ipFirst?: string;
+}
+declare class RefreshNotFoundError extends Error {
+    constructor();
+}
+declare class RefreshExpiredError extends Error {
+    constructor();
+}
+declare class RefreshReuseDetectedError extends Error {
+    readonly familyId: string;
+    constructor(familyId: string);
+}
+interface SessionsStoreOptions {
+    /** Override `Date.now` — only used in tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Refresh token TTL in ms. */
+    refreshTtlMs: number;
+    /** Grace window for legitimate retries (CD-5). Recommended 5_000ms. */
+    graceWindowMs: number;
+}
+interface CreateSessionInput {
+    userId: string;
+    tenantId: string;
+    deviceCtx: {
+        userAgent?: string;
+        ip?: string;
+    };
+}
+interface CreateSessionResult {
+    familyId: string;
+    refreshJti: string;
+    refreshExpiresAt: number;
+}
+interface RotateRefreshResult {
+    newJti: string;
+    familyId: string;
+    newRefreshExpiresAt: number;
+}
+declare class SessionsStore {
+    private readonly docs;
+    private initialised;
+    private readonly now;
+    private readonly refreshTtlMs;
+    private readonly graceWindowMs;
+    constructor(docs: IDocumentDatabase, opts: SessionsStoreOptions);
+    private ensureSchema;
+    createSession(input: CreateSessionInput): Promise<CreateSessionResult>;
+    /**
+     * Consume `oldJti` and issue a new refresh in the same family.
+     *
+     * Throws:
+     * - `RefreshNotFoundError` if jti is unknown or its family was revoked.
+     * - `RefreshExpiredError` if jti is past `expiresAt` (family stays alive).
+     * - `RefreshReuseDetectedError` if jti was already consumed and the
+     *   grace window has passed — family is killed before throwing.
+     *
+     * On grace-window retry (same already-consumed jti within
+     * `graceWindowMs`) the previously-issued replacement is returned and
+     * no new refresh is created.
+     */
+    rotateRefresh(oldJti: string): Promise<RotateRefreshResult>;
+    revokeFamily(familyId: string): Promise<void>;
+    revokeAllUserSessions(userId: string): Promise<void>;
+    revokeAllUserSessionsExcept(userId: string, exceptFamilyId: string): Promise<void>;
+    listFamiliesByUser(userId: string): Promise<SessionFamily[]>;
+}
+
+/**
+ * @module @kb-labs/gateway-auth/password-policy
+ *
+ * Password validation rules (ADR-0020, Phase 1.6).
+ *
+ * Length: 8..256. No complexity rules — NIST 800-63B explicitly
+ * recommends against them.
+ *
+ * HIBP check via k-anonymity (https://haveibeenpwned.com/API/v3#PwnedPasswords):
+ * we send the first 5 hex chars of SHA-1(password) and grep the
+ * suffix list locally. The full password never leaves the process.
+ *
+ * Availability vs. UX trade-off: HIBP outages return `{ ok: true,
+ * warning: 'hibp_unavailable' }`. A security check that hard-fails on
+ * network glitches breaks more user flows than it protects — we log
+ * the warning and let the activation/change-password flow continue.
+ */
+type ValidationResult = {
+    ok: true;
+    warning?: 'hibp_unavailable';
+} | {
+    ok: false;
+    reason: 'too_short' | 'too_long' | 'pwned';
+};
+interface PasswordPolicyLogger {
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+interface PasswordPolicyOptions {
+    minLength: number;
+    maxLength: number;
+    hibpEnabled: boolean;
+    /** Override for tests. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Override for tests / production logger. Defaults to console-shaped no-op. */
+    logger?: PasswordPolicyLogger;
+}
+interface PasswordPolicy {
+    validate(plain: string): Promise<ValidationResult>;
+}
+declare const createPasswordPolicy: (opts: PasswordPolicyOptions) => PasswordPolicy;
+
+/**
+ * @module @kb-labs/gateway-auth/csrf
+ *
+ * Double-submit CSRF helpers (ADR-0020, Phase 1.7).
+ *
+ * The contract is intentionally minimal: a token is just an opaque
+ * random string and verification is a constant-time string compare.
+ * No server-side state, no rotation logic — the cookie + header pair
+ * is the entire protocol.
+ *
+ * The `Path=/` non-HttpOnly cookie is set in the route layer
+ * alongside `kb_access`. Studio JS reads it via `document.cookie` and
+ * echoes it via `X-CSRF-Token` on every mutating request.
+ */
+/**
+ * Generate a fresh 32-byte token, base64url-encoded.
+ */
+declare const issueCsrfToken: () => string;
+/**
+ * Verify the double-submit pair.
+ *
+ * Returns `true` only when both inputs are non-empty strings of the
+ * same length and equal under a constant-time compare. Length
+ * mismatches return `false` without involving timingSafeEqual (which
+ * throws on length mismatch).
+ */
+declare const verifyCsrfToken: (cookie: string | undefined, header: string | undefined) => boolean;
+
+/**
+ * @module @kb-labs/gateway-auth/rate-limit
+ *
+ * Fixed-window rate limiter on top of `IKVStore` (ADR-0020, Phase 1.8).
+ *
+ * Used for per-email login limits and activation rate-limiting.
+ * Per-IP limits are configured at the gateway layer itself (its
+ * existing rate-limit plugin) and are not touched here.
+ *
+ * Fixed window, not sliding: TTL is applied **once** on the first
+ * increment and never extended. Subsequent increments within the
+ * window just bump the counter. Once the key expires, the counter
+ * starts over.
+ *
+ * The choice of fixed vs sliding matters: a sliding window would mean
+ * "5 attempts in any 60-second window", which an attacker can game by
+ * pacing exactly under the limit forever. Fixed window puts a hard
+ * ceiling per window and the counter actually resets.
+ */
+
+interface RateLimitConfig {
+    max: number;
+    windowMs: number;
+}
+type RateLimitResult = {
+    allowed: true;
+    remaining: number;
+} | {
+    allowed: false;
+    retryAfterSec: number;
+};
+interface RateLimiter {
+    /**
+     * Increment the counter and report whether this hit is allowed.
+     * Use on the event you want to count (e.g. a FAILED login attempt).
+     */
+    check(key: string, cfg: RateLimitConfig): Promise<RateLimitResult>;
+    /**
+     * Read the current counter WITHOUT incrementing and report whether the
+     * next `check()` would be allowed.
+     *
+     * This exists so a caller can reject early — before doing expensive work
+     * such as a bcrypt compare — once the window is already exhausted. Without
+     * a peek, the only way to know the limit is hit is to `check()` (which
+     * increments), forcing the expensive work to run first. peek() lets the
+     * login handler gate bcrypt on the existing failure count, closing a
+     * CPU-exhaustion DoS where an attacker spams requests past the limit and
+     * still pays for a bcrypt round-trip on each.
+     */
+    peek(key: string, cfg: RateLimitConfig): Promise<RateLimitResult>;
+}
+declare const createRateLimiter: (kv: IKVStore) => RateLimiter;
+
+/**
+ * @module @kb-labs/gateway-auth/tenant-resolver
+ *
+ * Map `Host`-header → `tenantId` (ADR-0020, Phase 1.9).
+ *
+ * Pattern is configurable (`{tenant}.kblabs.ru` in cloud) so the same
+ * resolver can be used in dev (`{tenant}.localhost`) or for on-prem
+ * customers (`{tenant}.acme.example.com`).
+ *
+ * Returns `null` instead of throwing on bad/reserved hosts — the
+ * middleware then renders the right 4xx and avoids surfacing an
+ * internal error. Slug rules are strict (`[a-z0-9-]{2,40}`, no
+ * leading/trailing dash) so a stray "weird" subdomain doesn't become a
+ * valid tenant by accident.
+ */
+declare const RESERVED_SUBDOMAINS: ReadonlySet<string>;
+interface TenantResolverOptions {
+    /** Host pattern containing exactly one `{tenant}` placeholder. */
+    pattern: string;
+    /** Optional override of the reserved set (must remain a superset of the default in production). */
+    reserved?: ReadonlySet<string>;
+}
+interface TenantResolver {
+    resolve(host: string | undefined): string | null;
+}
+declare const createTenantResolver: (opts: TenantResolverOptions) => TenantResolver;
+
+/**
+ * @module @kb-labs/gateway-auth/providers/email-password
+ *
+ * Built-in identity provider for the local email-password flow
+ * (ADR-0020, Phase 1.10). Implements `IIdentityProvider` exactly as a
+ * future Google/Okta provider would — `email-password` has no special
+ * status beyond being the one we ship.
+ *
+ * Two design notes worth keeping in mind:
+ *
+ * - **Constant-time response (CD-8).** Every not-ok path runs a real
+ *   bcrypt compare against a fixed dummy hash. Without this, a missing
+ *   user returns in microseconds while a wrong-password attempt takes
+ *   ~hundreds of milliseconds — a textbook user-enumeration timing
+ *   channel. The discriminated `reason` is for **logs only**; the HTTP
+ *   layer collapses it to a single opaque "invalid_credentials".
+ *
+ * - **No `setCredential` here.** This provider only *reads* credentials.
+ *   The activation flow writes the hash via the service layer, which
+ *   chooses the bcrypt cost from config. Keeping write logic out of
+ *   the provider means future Google/Okta providers don't carry a
+ *   meaningless `setCredential` method.
+ */
+
+interface EmailPasswordProviderOptions {
+    /**
+     * Narrow read port over users (DD-2). The gateway's `UsersStore`
+     * satisfies this structurally; the provider only ever reads.
+     */
+    users: IdentityUserPort;
+    /** Narrow read port over credentials (DD-2). */
+    credentials: IdentityCredentialPort;
+    /** The tenant this provider instance authenticates against. */
+    tenantId: string;
+    /** bcrypt cost used for the dummy compare timing. Should match the
+     *  cost used by the activation flow so dummy/real timings are similar. */
+    bcryptCost: number;
+}
+declare const createEmailPasswordProvider: (opts: EmailPasswordProviderOptions) => IIdentityProvider;
+
+/**
+ * @module @kb-labs/gateway-auth/providers/oidc
+ *
+ * Built-in generic OIDC redirect provider (ADR-0020, Step 5).
+ *
+ * Implements the authorization-code flow against any spec-compliant OIDC
+ * IdP (Google / Okta / Auth0 / Keycloak / Azure AD): `startAuthorization`
+ * builds the upstream authorize URL plus a per-attempt `nonce` (and optional
+ * PKCE `code_verifier`); `authenticate` exchanges the code at the token
+ * endpoint and verifies the returned ID token before returning the canonical
+ * identity. The gateway then does email→user→session as for any provider.
+ *
+ * Security guarantees this provider owns (not "quality of a custom" — these
+ * are the floor we promise):
+ *
+ * - **alg allowlist** — `jwtVerify(..., { algorithms: ['RS256','ES256'] })`.
+ *   `none` and HS* are rejected (alg-confusion / key-confusion). Same lesson
+ *   as pinning HS256 in jwt.ts: never let the token choose its own algorithm
+ *   class.
+ * - **iss / aud** — verified against the configured issuer and clientId.
+ * - **exp / nonce** — exp enforced by jose; nonce must echo the per-attempt
+ *   value we stashed in the state session (replay / token-injection guard).
+ * - **email_verified === true** — required unless `allowUnverifiedEmail`,
+ *   else an IdP that federates unverified emails becomes an account-takeover
+ *   vector.
+ * - **issuer https-only** — discovery / JWKS targets are admin-controlled but
+ *   we still refuse plaintext.
+ * - **secret hygiene** — `clientSecret` is read from an env var
+ *   (`clientSecretEnv`) by default; nothing secret is ever logged (no code /
+ *   id_token / access_token / client_secret in any log line).
+ *
+ * `fetch` is injected (DD-8) so the whole flow is testable against a locally
+ * signed token with a fake transport — no network, no global mocks. JWKS are
+ * fetched via the same injected `fetch` and verified with a local JWK set,
+ * with a single refetch on key rotation.
+ */
+
+declare const OidcConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oidc">;
+    id: z.ZodString;
+    issuer: z.ZodEffects<z.ZodString, string, string>;
+    clientId: z.ZodString;
+    /** Direct secret (discouraged — prefer clientSecretEnv). */
+    clientSecret: z.ZodOptional<z.ZodString>;
+    /** Name of the env var holding the secret (preferred). */
+    clientSecretEnv: z.ZodOptional<z.ZodString>;
+    /** OAuth scopes; `openid` is always included. Default `['openid','email']`. */
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Enable PKCE (S256). */
+    pkce: z.ZodOptional<z.ZodBoolean>;
+    /** Accept tokens whose email_verified is false (default false). */
+    allowUnverifiedEmail: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    type: z.ZodLiteral<"oidc">;
+    id: z.ZodString;
+    issuer: z.ZodEffects<z.ZodString, string, string>;
+    clientId: z.ZodString;
+    /** Direct secret (discouraged — prefer clientSecretEnv). */
+    clientSecret: z.ZodOptional<z.ZodString>;
+    /** Name of the env var holding the secret (preferred). */
+    clientSecretEnv: z.ZodOptional<z.ZodString>;
+    /** OAuth scopes; `openid` is always included. Default `['openid','email']`. */
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Enable PKCE (S256). */
+    pkce: z.ZodOptional<z.ZodBoolean>;
+    /** Accept tokens whose email_verified is false (default false). */
+    allowUnverifiedEmail: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    type: z.ZodLiteral<"oidc">;
+    id: z.ZodString;
+    issuer: z.ZodEffects<z.ZodString, string, string>;
+    clientId: z.ZodString;
+    /** Direct secret (discouraged — prefer clientSecretEnv). */
+    clientSecret: z.ZodOptional<z.ZodString>;
+    /** Name of the env var holding the secret (preferred). */
+    clientSecretEnv: z.ZodOptional<z.ZodString>;
+    /** OAuth scopes; `openid` is always included. Default `['openid','email']`. */
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Enable PKCE (S256). */
+    pkce: z.ZodOptional<z.ZodBoolean>;
+    /** Accept tokens whose email_verified is false (default false). */
+    allowUnverifiedEmail: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+type OidcProviderConfig = z.infer<typeof OidcConfigSchema>;
+declare function createOidcProvider(rawConfig: unknown, deps: IdentityProviderDeps): IRedirectIdentityProvider;
+
+/**
+ * @module @kb-labs/gateway-auth/provider-registry
+ *
+ * Tiny registry for `IIdentityProvider` instances (ADR-0020, Phase 1.11).
+ *
+ * Two invariants enforced beyond what a raw Map would give us:
+ * - Re-registering the same `id` throws — usually a bootstrap bug,
+ *   never intentional.
+ * - `list()` returns only the public `{ id, kind }` shape so the
+ *   `GET /auth/providers` route cannot accidentally serialise an
+ *   `authenticate` function over the wire.
+ */
+
+interface ProviderInfo {
+    id: string;
+    kind: IIdentityProvider['kind'];
+}
+declare class ProviderRegistry {
+    private readonly providers;
+    register(provider: IIdentityProvider): void;
+    get(id: string): IIdentityProvider | undefined;
+    has(id: string): boolean;
+    list(): ProviderInfo[];
+}
+
+/**
+ * @module @kb-labs/gateway-auth/provider-loader
+ *
+ * Config-driven loader for identity providers (ADR-0020, DD-3).
+ *
+ * This is the gateway-side analogue of the platform adapter loader
+ * (`core/runtime/src/loader.ts` notifier sub-channels): a type→factory
+ * map for the built-ins, plus dynamic `import()` of a package for any
+ * non-builtin `type`. Two deliberate departures from the platform
+ * loader:
+ *
+ * - **Fail-fast, not warn-skip.** A misconfigured *platform* adapter can
+ *   degrade gracefully; a misconfigured *auth door* must never boot
+ *   half-open. If a configured provider cannot be loaded, we throw.
+ * - **Gateway-owned (Pattern B).** Providers need gateway-domain ports
+ *   (users/credentials) and the tenant context, which don't exist until
+ *   gateway bootstrap — well after platform assembly. So the loader lives
+ *   here, not in core.
+ *
+ * The built-in `email-password` provider is the zero-config default: an
+ * empty/absent `providers` config registers it and nothing else. It has
+ * no special status beyond being the one we ship — it goes through the
+ * exact same factory path a third-party provider would.
+ */
+
+/**
+ * A single provider entry from `auth.providers` config. `type` is the
+ * discriminator (built-in name or package name); everything else is
+ * provider-specific and validated by the provider's own zod schema.
+ */
+interface ProviderConfigEntry {
+    type: string;
+    [key: string]: unknown;
+}
+type ProvidersConfig = Record<string, ProviderConfigEntry> | undefined;
+/**
+ * Built-in factories keyed by `type`. Anything not here is resolved as a
+ * package name. `oidc` is the generic OIDC redirect provider (Google / Okta /
+ * Auth0 / Keycloak / Azure AD); it owns its own zod config schema.
+ */
+declare const BUILTIN_FACTORIES: Record<string, IdentityProviderFactory>;
+/**
+ * Build a {@link ProviderRegistry} from the `auth.providers` config.
+ *
+ * @param config The `auth.providers` map (or undefined).
+ * @param deps Shared dependencies handed to every provider factory.
+ * @returns A populated registry. Throws (fail-fast) on any load error.
+ */
+declare function loadIdentityProviders(config: ProvidersConfig, deps: IdentityProviderDeps): Promise<ProviderRegistry>;
+
+/**
+ * @module @kb-labs/gateway-auth/oauth-state-store
+ *
+ * Per-attempt OAuth `state` storage (ADR-0020, DD-5).
+ *
+ * Between `GET /auth/oauth/:id/start` and the IdP callback we must hold a
+ * short-lived binding from the opaque `state` token to the flow context
+ * (which provider issued it, which tenant, where to return, and the
+ * per-attempt secrets like nonce / PKCE verifier). This is a thin,
+ * namespaced wrapper over `IKVStore` — a real abstraction, not a stub:
+ *
+ * - **Namespaced keys** (`oauth:state:{state}`) so it can share the same
+ *   KV as the rate limiter without collision.
+ * - **TTL** so abandoned flows self-clean.
+ * - **One-shot `consume`** (get → delete, gated on the delete result) so
+ *   a replayed callback cannot be processed twice. With a shared Redis KV
+ *   the gating on `delete()` is what provides the atomic single-winner
+ *   guarantee under concurrency.
+ *
+ * NOTE: in a multi-process / HA deployment this MUST be backed by a
+ * shared KV (Redis); an in-memory KV is per-process and a callback may
+ * land on a different worker than the one that issued the state. The
+ * bootstrap warns when a redirect provider is configured against an
+ * in-memory KV (see OAuth hardening, Step 4b).
+ */
+
+/**
+ * The flow context bound to a single `state` token. `session` carries the
+ * provider's per-attempt secrets (OIDC nonce, PKCE verifier) verbatim and
+ * is never logged.
+ */
+interface OAuthStateRecord {
+    /** The provider instance id that started this flow (mix-up guard). */
+    providerId: string;
+    /** The tenant the flow was started for (cross-tenant guard). */
+    tenantId: string;
+    /** Validated relative path to return to after success. */
+    returnTo: string;
+    /** Opaque per-attempt secrets the provider needs back at callback. */
+    session?: Record<string, unknown>;
+    /** Issue timestamp (ms). */
+    createdAt: number;
+}
+interface OAuthStateStoreOptions {
+    /** State TTL in milliseconds. Default 10 minutes. */
+    ttlMs?: number;
+}
+declare class OAuthStateStore {
+    private readonly kv;
+    private readonly ttlMs;
+    constructor(kv: IKVStore, opts?: OAuthStateStoreOptions);
+    private key;
+    /** Persist a state record with the configured TTL. */
+    put(state: string, record: OAuthStateRecord): Promise<void>;
+    /**
+     * One-shot read. Returns the record to the first caller and deletes it;
+     * concurrent / subsequent callers get `null`. The `delete` result gates
+     * the return so exactly one caller wins even under a shared KV.
+     */
+    consume(state: string): Promise<OAuthStateRecord | null>;
+}
+
+/**
+ * @module @kb-labs/gateway-auth/stub-pdp
+ *
+ * Stub `IPolicyDecisionPoint` (ADR-0020, Phase 1.12). Mock RBAC over
+ * the memberships store: tenant-admin gets every canonical permission,
+ * tenant-member gets none. Machine identities are temporarily allowed
+ * everything (matches the existing machine-token behaviour pre-RBAC).
+ *
+ * This module exists so the real handlers can call `policy.check(...)`
+ * and `enumeratePermissions(...)` from day one. The real RBAC + ReBAC
+ * engine (ClickUp 869def338) replaces this implementation; callers do
+ * not change.
+ *
+ * Closed-world: actions outside the canonical PERMISSIONS enum return
+ * `allow: false` even for tenant-admin. This is deliberate — until we
+ * have per-plugin permission registration, the central enum is the
+ * full universe of known actions.
+ */
+
+interface StubPDPOptions {
+    memberships: MembershipsStore;
+}
+declare const createStubPDP: (opts: StubPDPOptions) => IPolicyDecisionPoint;
+
+/**
+ * @module @kb-labs/gateway-auth/bootstrap-admin
+ *
+ * First-run admin provisioning (ADR-0020, Phase 1.14).
+ *
+ * On a fresh deployment the operator can't log in unless someone has
+ * already been provisioned — and we deliberately removed the public
+ * `/auth/register` for humans. `ensureBootstrapAdmin` reads bootstrap
+ * config from env and creates a single tenant-admin User on first
+ * start. Idempotent: subsequent runs see the existing User and do
+ * nothing.
+ *
+ * Conflict handling is conservative: if a User with the configured
+ * email already exists in the configured tenant but in a different
+ * status (e.g. someone manually `disabled` them and forgot the env
+ * was still set), we log a warning and **do not touch** the existing
+ * record. Silently re-activating or re-passwording is the kind of
+ * surprise we want to avoid on a production system.
+ */
+
+interface BootstrapConfig {
+    adminEmail: string;
+    adminPassword: string;
+    tenantId: string;
+}
+interface BootstrapAdminLogger {
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+interface EnsureBootstrapAdminOptions {
+    bootstrap: BootstrapConfig | undefined;
+    users: UsersStore;
+    credentials: CredentialsStore;
+    memberships: MembershipsStore;
+    bcryptCost: number;
+    logger: BootstrapAdminLogger;
+}
+declare const ensureBootstrapAdmin: (opts: EnsureBootstrapAdminOptions) => Promise<void>;
+
+/**
+ * @module @kb-labs/gateway-auth/user-auth-service
+ *
+ * Orchestration layer for the user authentication flow (ADR-0020,
+ * Phase 1.15).
+ *
+ * Pulls together every store + provider + jwt + policy and exposes the
+ * five operations the HTTP layer calls:
+ *
+ * - `login`
+ * - `refresh`     (CD-1 enforced here — disabled user revokes family)
+ * - `logout`
+ * - `changePassword` (revokes other families, keeps current)
+ * - `activate`    (consumes invite, auto-logs in)
+ *
+ * All not-ok paths throw `AuthError(code)`. The HTTP layer collapses
+ * most codes to opaque `invalid_credentials` for the caller; `code` is
+ * preserved for logs and tests.
+ */
+
+type AuthErrorCode = 'invalid_credentials' | 'unknown_provider' | 'invalid_refresh' | 'refresh_reuse' | 'user_disabled' | 'invalid_current_password' | 'weak_password' | 'invalid_invite' | 'unknown_invite';
+declare class AuthError extends Error {
+    readonly code: AuthErrorCode;
+    readonly reason?: string | undefined;
+    readonly name = "AuthError";
+    constructor(code: AuthErrorCode, reason?: string | undefined);
+}
+interface UserAuthServiceOptions {
+    users: UsersStore;
+    credentials: CredentialsStore;
+    memberships: MembershipsStore;
+    invites: InvitesStore;
+    sessions: SessionsStore;
+    providers: ProviderRegistry;
+    passwordPolicy: PasswordPolicy;
+    jwtConfig: JwtConfig;
+    accessTtlSec: number;
+    refreshTtlSec: number;
+    bcryptCost: number;
+    /** Override for tests. Defaults to Date.now. */
+    now?: () => number;
+}
+interface PublicUser {
+    userId: string;
+    email: string;
+    tenantId: string;
+}
+interface TokenInfo {
+    token: string;
+    expiresInSec: number;
+}
+interface SessionResult {
+    user: PublicUser;
+    access: TokenInfo;
+    refresh: TokenInfo;
+    csrf: string;
+    familyId: string;
+}
+interface LoginInput {
+    providerId: string;
+    input: unknown;
+}
+interface DeviceCtx {
+    userAgent?: string;
+    ip?: string;
+}
+interface ChangePasswordInput {
+    userId: string;
+    currentFamilyId: string;
+    currentPassword: string;
+    newPassword: string;
+}
+interface ActivateInput {
+    activationToken: string;
+    password: string;
+    deviceCtx: DeviceCtx;
+}
+declare const createUserAuthService: (opts: UserAuthServiceOptions) => {
+    login: (input: LoginInput, tenantId: string, deviceCtx: DeviceCtx) => Promise<SessionResult>;
+    refresh: (refreshToken: string) => Promise<SessionResult>;
+    logout: (refreshToken: string) => Promise<void>;
+    changePassword: (input: ChangePasswordInput) => Promise<void>;
+    activate: (input: ActivateInput) => Promise<SessionResult>;
+};
+
+export { type ActivateInput, type AddMembershipInput, AuthError, type AuthErrorCode, AuthService, BUILTIN_FACTORIES, type BootstrapAdminLogger, type BootstrapConfig, type ChangePasswordInput, type ClientRecord, type CreateInviteInput, type CreateInviteResult, type CreateSessionInput, type CreateSessionResult, type CreateUserInput, type Credential, CredentialsStore, type DeviceCtx, type EmailPasswordProviderOptions, type EnsureBootstrapAdminOptions, type GroupId, type InviteRecord, type InviteStatus, InvitesStore, type JwtConfig, type LoginInput, type Membership, MembershipsStore, type OAuthStateRecord, OAuthStateStore, type OAuthStateStoreOptions, type OidcProviderConfig, type PasswordPolicy, type PasswordPolicyLogger, type PasswordPolicyOptions, type ProviderConfigEntry, type ProviderInfo, ProviderRegistry, type ProvidersConfig, type PublicUser, RESERVED_SUBDOMAINS, type RateLimitConfig, type RateLimitResult, type RateLimiter, RefreshExpiredError, RefreshNotFoundError, RefreshReuseDetectedError, type RotateRefreshResult, type SessionFamily, type SessionResult, SessionsStore, type SessionsStoreOptions, type SetCredentialInput, type SignUserTokenOptions, type StubPDPOptions, type TenantResolver, type TenantResolverOptions, type TokenInfo, type User, type UserAccessPayload, type UserAuthServiceOptions, type UserRefreshPayload, type UserStatus, UsersStore, type ValidationResult, buildClientRecord, canonicalizeEmail, consumeRefreshToken, createEmailPasswordProvider, createOidcProvider, createPasswordPolicy, createRateLimiter, createStubPDP, createTenantResolver, createUserAuthService, ensureBootstrapAdmin, generateClientId, generateClientSecret, generateHostId, getClient, getClientByHandle, getClientByHostId, getPublicKey, isHandleTaken, issueCsrfToken, loadIdentityProviders, saveClient, savePublicKey, saveRefreshToken, signAccessToken, signRefreshToken, signUserAccessToken, signUserRefreshToken, verifyAccessToken, verifyClientSecret, verifyCsrfToken, verifyRefreshToken, verifyUserAccessToken, verifyUserRefreshToken };