@rebasepro/server-core 0.7.0 → 0.9.0

package/{src/auth/api-keys/api-key-types.ts → dist/auth/api-keys/api-key-types.d.ts}

@@ -7,7 +7,6 @@
  *
  * @module
  */
-
 /**
  * A single permission entry scoping an API key to a collection and set of operations.
  *
@@ -19,7 +18,6 @@ export interface ApiKeyPermission {
     /** Allowed operations on the collection. */
     operations: ("read" | "write" | "delete")[];
 }
-
 /**
  * Full database row for an API key.
  * The `key_hash` is never exposed via the API — only stored for lookup.
@@ -43,7 +41,6 @@ export interface ApiKey {
     expires_at: string | null;
     revoked_at: string | null;
 }
-
 /**
  * Masked version of an API key, safe for API responses.
  * Omits `key_hash` and shows only the prefix.
@@ -63,7 +60,6 @@ export interface ApiKeyMasked {
     expires_at: string | null;
     revoked_at: string | null;
 }
-
 /**
  * Request body for creating a new API key.
  */
@@ -77,7 +73,6 @@ export interface CreateApiKeyRequest {
     /** ISO-8601 expiration timestamp. Omit for no expiration. */
     expires_at?: string | null;
 }
-
 /**
  * Request body for updating an existing API key.
  * All fields are optional — only provided fields are updated.
@@ -90,7 +85,6 @@ export interface UpdateApiKeyRequest {
     rate_limit?: number | null;
     expires_at?: string | null;
 }
-
 /**
  * Returned exactly once when a key is created.
  * The `key` field contains the full plaintext key — it is never stored

package/{src/auth/api-keys/index.ts → dist/auth/api-keys/index.d.ts}

@@ -6,32 +6,12 @@
  *
  * @module
  */
-
-// Types
-export type {
-    ApiKey,
-    ApiKeyMasked,
-    ApiKeyPermission,
-    ApiKeyWithSecret,
-    CreateApiKeyRequest,
-    UpdateApiKeyRequest
-} from "./api-key-types";
-
-// Store
+export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types";
 export { createApiKeyStore } from "./api-key-store";
 export type { ApiKeyStore } from "./api-key-store";
-
-// Middleware
 export { isApiKeyToken, validateApiKey } from "./api-key-middleware";
 export type { ApiKeyAuthOptions } from "./api-key-middleware";
-
-// Permission guard
-export {
-    httpMethodToOperation,
-    isOperationAllowed
-} from "./api-key-permission-guard";
+export { httpMethodToOperation, isOperationAllowed } from "./api-key-permission-guard";
 export type { ApiKeyOperation } from "./api-key-permission-guard";
-
-// Routes
 export { createApiKeyRoutes } from "./api-key-routes";
 export type { ApiKeyRouteOptions } from "./api-key-routes";

package/dist/auth/apple-oauth.d.ts

@@ -0,0 +1,30 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates an Apple Sign In OAuth Provider integration.
+ *
+ * Apple requires a client secret that is a signed JWT, regenerated on each
+ * token exchange (valid up to 6 months). This provider handles that automatically.
+ *
+ * Required Apple Developer configuration:
+ * - Services ID (clientId)
+ * - Key ID from the private key registered with Apple
+ * - Team ID from Apple Developer account
+ * - Private key (.p8 file contents) downloaded from Apple Developer portal
+ */
+export declare function createAppleProvider(config: {
+    clientId: string;
+    teamId: string;
+    keyId: string;
+    /** The raw PEM contents of the .p8 private key file */
+    privateKey: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+    user?: {
+        name?: {
+            firstName?: string;
+            lastName?: string;
+        };
+        email?: string;
+    };
+}>;

package/{src/auth/auth-hooks.ts → dist/auth/auth-hooks.d.ts}

@@ -36,22 +36,14 @@
  * };
  * ```
  */
-
-import {
-    hashPassword as defaultHashPassword,
-    verifyPassword as defaultVerifyPassword,
-    validatePasswordStrength as defaultValidatePasswordStrength
-} from "./password";
 import type { PasswordValidationResult } from "./password";
 import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
 import type { EmailService, EmailConfig } from "../email";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
-
 /**
  * Authentication method identifier for lifecycle hooks.
  */
 export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset" | "anonymous" | "magic-link" | "mfa";
-
 /**
  * Hook specific parts of the built-in Rebase auth implementation.
  *
@@ -59,8 +51,6 @@ export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-
  * that is not provided.
  */
 export interface AuthHooks {
-    // ─── Password Operations ──────────────────────────────────────────────
-
     /**
      * Hash a cleartext password for storage.
      *
@@ -70,7 +60,6 @@ export interface AuthHooks {
      * @returns The hashed password string (format is implementation-defined).
      */
     hashPassword?(password: string): Promise<string>;
-
     /**
      * Verify a cleartext password against a stored hash.
      *
@@ -81,7 +70,6 @@ export interface AuthHooks {
      * @returns `true` if the password matches the hash.
      */
     verifyPassword?(password: string, storedHash: string): Promise<boolean>;
-
     /**
      * Validate password strength before hashing.
      *
@@ -91,9 +79,6 @@ export interface AuthHooks {
      * @returns Validation result with `valid` flag and error messages.
      */
     validatePasswordStrength?(password: string): PasswordValidationResult;
-
-    // ─── Credential Resolution ────────────────────────────────────────────
-
     /**
      * Override the complete credential verification during email/password login.
      *
@@ -107,9 +92,6 @@ export interface AuthHooks {
      * Default: `getUserByEmail(email)` + `verifyPassword(password, user.passwordHash)`.
      */
     verifyCredentials?(email: string, password: string, repo: AuthRepository): Promise<UserData | null>;
-
-    // ─── Lifecycle Hooks ──────────────────────────────────────────────────
-
     /**
      * Called after any successful authentication event (login, register,
      * OAuth, token refresh, password reset).
@@ -120,7 +102,6 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     onAuthenticated?(user: UserData, method: AuthMethod): Promise<void>;
-
     /**
      * Called before a new user is created (registration or admin creation).
      *
@@ -130,7 +111,6 @@ export interface AuthHooks {
      * Default: passthrough (returns data unchanged).
      */
     beforeUserCreate?(data: CreateUserData): Promise<CreateUserData>;
-
     /**
      * Called after a new user is created.
      *
@@ -140,9 +120,6 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserCreate?(user: UserData): Promise<void>;
-
-    // ─── Extended Lifecycle Hooks ─────────────────────────────────────────
-
     /**
      * Pre-login validation. Called before credential verification.
      *
@@ -150,7 +127,6 @@ export interface AuthHooks {
      * IP-based restrictions, etc.).
      */
     beforeLogin?(email: string, method: AuthMethod): Promise<void>;
-
     /**
      * Post-logout cleanup.
      *
@@ -160,7 +136,6 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterLogout?(userId: string): Promise<void>;
-
     /**
      * Called after successful MFA verification.
      *
@@ -169,7 +144,6 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     onMfaVerified?(userId: string, factorId: string): Promise<void>;
-
     /**
      * Customize JWT access token claims before signing.
      *
@@ -181,7 +155,6 @@ export interface AuthHooks {
      * @returns Modified claims to include in the JWT.
      */
     customizeAccessToken?(claims: Record<string, unknown>, user: UserData): Promise<Record<string, unknown>>;
-
     /**
      * Transform the auth response before sending it to the client.
      *
@@ -190,18 +163,14 @@ export interface AuthHooks {
      * response and returns a (potentially enriched) response.
      *
      * Use cases:
-     * - Inject tokens from external auth systems (Firebase Custom Tokens, etc.)
+     * - Inject tokens from external auth systems (custom provider tokens, etc.)
      * - Add project-specific metadata to the response
      * - Enrich the user object with data from external sources
      *
      * The hook runs in the request path — keep it fast.
      * Heavy work should be offloaded to `onAuthenticated` (fire-and-forget).
      */
-    transformAuthResponse?(
-        response: AuthResponsePayload,
-        context: TransformAuthResponseContext
-    ): Promise<AuthResponsePayload>;
-
+    transformAuthResponse?(response: AuthResponsePayload, context: TransformAuthResponseContext): Promise<AuthResponsePayload>;
     /**
      * Called after a successful password reset.
      *
@@ -210,7 +179,6 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     onPasswordReset?(userId: string): Promise<void>;
-
     /**
      * Called before a user is deleted.
      *
@@ -218,7 +186,6 @@ export interface AuthHooks {
      * subscriptions, pending transactions, etc.).
      */
     beforeUserDelete?(userId: string): Promise<void>;
-
     /**
      * Called after a user is deleted.
      *
@@ -227,42 +194,33 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserDelete?(userId: string): Promise<void>;
-
     /**
      * Optional hook to customize or override the default user creation flow via the admin panel/REST API.
      * When provided, this replaces the built-in password generation, hashing, and invitation email logic.
      */
-    onAdminCreateUser?(
-        values: Record<string, unknown>,
-        ctx: {
-            authRepo: AuthRepository;
-            emailService?: EmailService;
-            emailConfig?: EmailConfig;
-            hashPassword: (password: string) => Promise<string>;
-        }
-    ): Promise<{
+    onAdminCreateUser?(values: Record<string, unknown>, ctx: {
+        authRepo: AuthRepository;
+        emailService?: EmailService;
+        emailConfig?: EmailConfig;
+        hashPassword: (password: string) => Promise<string>;
+    }): Promise<{
         values: Record<string, unknown>;
         temporaryPassword?: string;
         invitationSent?: boolean;
     }>;
-
     /**
      * Optional hook to customize or override the default password reset flow via the admin panel.
      * When provided, this replaces the built-in password reset token generation, hashing, and email logic.
      */
-    onAdminResetPassword?(
-        userId: string,
-        ctx: {
-            authRepo: AuthRepository;
-            emailService?: EmailService;
-            emailConfig?: EmailConfig;
-        }
-    ): Promise<{
+    onAdminResetPassword?(userId: string, ctx: {
+        authRepo: AuthRepository;
+        emailService?: EmailService;
+        emailConfig?: EmailConfig;
+    }): Promise<{
         temporaryPassword?: string;
         invitationSent?: boolean;
     }>;
 }
-
 /**
  * Resolved auth hooks — password operations are guaranteed to exist,
  * all other hooks are passed through as-is (optional).
@@ -273,10 +231,7 @@ export interface AuthHooks {
  * Consumers should use the resolved object exclusively —
  * never access the raw `AuthHooks` directly.
  */
-export type ResolvedAuthHooks =
-    Required<Pick<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">>
-    & Omit<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">;
-
+export type ResolvedAuthHooks = Required<Pick<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">> & Omit<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">;
 /**
  * Merge user-provided hooks with the built-in defaults to produce
  * a complete set of resolved hooks.
@@ -284,17 +239,4 @@ export type ResolvedAuthHooks =
  * This is the single point where defaults are applied — all consumers
  * call this once and use the resolved hooks throughout.
  */
-export function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthHooks {
-    return {
-        ...hooks,
-
-        hashPassword: hooks?.hashPassword
-            ?? defaultHashPassword,
-
-        verifyPassword: hooks?.verifyPassword
-            ?? defaultVerifyPassword,
-
-        validatePasswordStrength: hooks?.validatePasswordStrength
-            ?? defaultValidatePasswordStrength
-    };
-}
+export declare function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthHooks;

package/dist/auth/bitbucket-oauth.d.ts

@@ -0,0 +1,11 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Bitbucket OAuth Provider integration (OAuth 2.0 consumer).
+ */
+export declare function createBitbucketProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/builtin-auth-adapter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * RebaseBuiltinAuthAdapter
+ *
+ * Wraps Rebase's existing built-in JWT auth system (routes, middleware, user/role
+ * management) into the `AuthAdapter` interface. This is the default adapter used
+ * when the user passes a plain `RebaseAuthConfig` object.
+ *
+ * This is NOT a rewrite — it delegates to the existing `createAuthRoutes()`,
+ * `createResetPasswordRoute()`, and `verifyAccessToken()` functions. The goal is to
+ * present the same functionality through the pluggable `AuthAdapter` contract.
+ */
+import type { AuthAdapter } from "@rebasepro/types";
+import type { AuthRepository, OAuthProvider } from "./interfaces";
+import type { AuthHooks } from "./auth-hooks";
+import type { EmailService, EmailConfig } from "../email";
+/**
+ * Configuration for the built-in Rebase auth adapter.
+ *
+ * This mirrors the existing `RebaseAuthConfig` — users pass this and
+ * server-core auto-wraps it in a `RebaseBuiltinAuthAdapter`.
+ */
+export interface BuiltinAuthAdapterConfig {
+    /** The bootstrapper-provided auth repository (users, roles, tokens). */
+    authRepository: AuthRepository;
+    /** Email service for password resets, verification, etc. */
+    emailService?: EmailService;
+    /** Email configuration. */
+    emailConfig?: EmailConfig;
+    /** Whether to allow new user registration. */
+    allowRegistration?: boolean;
+    /** Whether to expose the authenticated email→minimal-profile lookup route. */
+    allowUserLookup?: boolean;
+    /** Default role to assign to new users. */
+    defaultRole?: string;
+    /** OAuth providers to register. */
+    oauthProviders?: OAuthProvider<unknown>[];
+    /** Static service key for server-to-server auth. */
+    serviceKey?: string;
+    /** Auth hooks for customizing password, credentials, lifecycle, etc. */
+    authHooks?: AuthHooks;
+    /** The parsed auth config from the collection (if `auth` is an object, not just `true`). */
+    collectionAuthConfig?: import("@rebasepro/types").AuthCollectionConfig;
+    /** Enable magic link (passwordless email) login. Requires email service. */
+    enableMagicLink?: boolean;
+    /** Opt-in httpOnly cookie mode for refresh tokens. */
+    cookieAuth?: import("./routes").CookieAuthConfig;
+}
+/**
+ * Create the built-in Rebase auth adapter.
+ *
+ * This wraps the existing auth infrastructure (JWT, OAuth, user/role management)
+ * into the `AuthAdapter` interface. It's used internally by `initializeRebaseBackend()`
+ * when the user passes a plain `RebaseAuthConfig` object.
+ */
+export declare function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): AuthAdapter;

package/dist/auth/cookie-utils.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from "hono";
+import type { AuthResponsePayload } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types";
+import type { CookieAuthConfig } from "./routes";
+/**
+ * Cookie auth helpers for httpOnly refresh tokens.
+ */
+export declare function getCookieSettings(config: CookieAuthConfig | undefined): {
+    name: string;
+    path: string;
+    sameSite: "Strict" | "Lax" | "None";
+    domain: string | undefined;
+    secure: boolean | undefined;
+};
+/**
+ * Set the refresh token as an httpOnly cookie on the response.
+ */
+export declare function setRefreshCookie(c: Context<HonoEnv>, refreshToken: string, config: CookieAuthConfig | undefined): void;
+/**
+ * Clear the refresh token cookie.
+ */
+export declare function clearRefreshCookie(c: Context<HonoEnv>, config: CookieAuthConfig | undefined): void;
+/**
+ * Read the refresh token from the request — cookie first, then body fallback.
+ */
+export declare function readRefreshToken(c: Context<HonoEnv>, body: {
+    refreshToken?: string;
+}, config: CookieAuthConfig | undefined): string | undefined;
+/**
+ * Redact the refresh token from the response body when cookie mode is active.
+ */
+export declare function redactRefreshToken(response: AuthResponsePayload, c: Context<HonoEnv>, refreshToken: string, config: CookieAuthConfig | undefined): AuthResponsePayload;

package/{src/auth/crypto-utils.ts → dist/auth/crypto-utils.d.ts}

@@ -3,9 +3,6 @@
  *
  * @module
  */
-
-import { timingSafeEqual } from "crypto";
-
 /**
  * Constant-time string comparison to prevent timing attacks.
  *
@@ -16,16 +13,4 @@ import { timingSafeEqual } from "crypto";
  * @param b - Second string to compare.
  * @returns `true` if the strings are identical, `false` otherwise.
  */
-export function safeCompare(a: string, b: string): boolean {
-    const maxLen = Math.max(a.length, b.length);
-    const bufA = Buffer.alloc(maxLen);
-    const bufB = Buffer.alloc(maxLen);
-    bufA.write(a);
-    bufB.write(b);
-    try {
-        const isEqual = timingSafeEqual(bufA, bufB);
-        return isEqual && a.length === b.length;
-    } catch {
-        return false;
-    }
-}
+export declare function safeCompare(a: string, b: string): boolean;

package/dist/auth/custom-auth-adapter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Custom Auth Adapter Factory
+ *
+ * Provides a minimal-config way for users with existing auth systems
+ * to plug into Rebase. Only `verifyRequest` is required — everything
+ * else is optional.
+ *
+ * @example
+ * ```ts
+ * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ *
+ * const auth = createCustomAuthAdapter({
+ *   verifyRequest: async (request) => {
+ *     const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+ *     if (!token) return null;
+ *     const decoded = jwt.verify(token, MY_SECRET);
+ *     return {
+ *       uid: decoded.sub,
+ *       email: decoded.email,
+ *       displayName: decoded.name,
+ *       roles: decoded.roles || [],
+ *       isAdmin: decoded.roles?.includes("admin") ?? false,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+import type { AuthAdapter, CustomAuthAdapterOptions } from "@rebasepro/types";
+/**
+ * Create a custom auth adapter from minimal options.
+ *
+ * This is the recommended entry point for users who already have their own
+ * auth system and just need to tell Rebase how to extract the user from
+ * incoming requests.
+ *
+ * @param options - Configuration options. Only `verifyRequest` is required.
+ * @returns A fully-formed `AuthAdapter` ready for `initializeRebaseBackend()`.
+ */
+export declare function createCustomAuthAdapter(options: CustomAuthAdapterOptions): AuthAdapter;

package/dist/auth/discord-oauth.d.ts

@@ -0,0 +1,14 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Discord OAuth2 Provider integration.
+ *
+ * Uses the authorization code flow. Requires the "identify" and "email"
+ * scopes to retrieve the user's email and profile information.
+ */
+export declare function createDiscordProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/facebook-oauth.d.ts

@@ -0,0 +1,14 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Facebook / Meta OAuth Provider integration.
+ *
+ * Uses the authorization code flow to exchange a code for an access token,
+ * then fetches user profile from the Facebook Graph API.
+ */
+export declare function createFacebookProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/github-oauth.d.ts

@@ -0,0 +1,15 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a GitHub OAuth Provider integration.
+ *
+ * Flow: Frontend receives an authorization `code` via the GitHub OAuth redirect.
+ * This provider exchanges the code for an access token, then fetches the user's
+ * profile and primary email from the GitHub API.
+ */
+export declare function createGitHubProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/gitlab-oauth.d.ts

@@ -0,0 +1,13 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a GitLab OAuth Provider integration.
+ * Works with both GitLab.com and self-hosted instances.
+ */
+export declare function createGitLabProvider(config: {
+    clientId: string;
+    clientSecret: string;
+    baseUrl?: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/google-oauth.d.ts

@@ -0,0 +1,47 @@
+import type { OAuthProvider } from "./interfaces";
+export interface GoogleUserInfo {
+    googleId: string;
+    email: string;
+    displayName: string | null;
+    photoUrl: string | null;
+    emailVerified: boolean;
+}
+export interface GoogleProviderConfig {
+    clientId: string;
+    /**
+     * The OAuth 2.0 client secret from Google Cloud Console.
+     *
+     * Required for the **authorization code flow** (Path 3), where the
+     * frontend sends an authorization `code` and the backend exchanges it
+     * server-side for tokens. This is the most secure flow because tokens
+     * never touch the browser.
+     *
+     * When omitted, only ID-token and access-token verification are available
+     * (Paths 1 & 2), which rely on the frontend obtaining tokens directly.
+     */
+    clientSecret?: string;
+}
+/**
+ * Creates a Google OAuth Provider integration.
+ *
+ * Supports three verification paths:
+ *
+ * **Path 1 – ID Token** (One Tap / Sign In With Google button):
+ *   Frontend sends `idToken`. Backend verifies cryptographically using
+ *   Google's public keys. No secret required.
+ *
+ * **Path 2 – Access Token** (popup via `initTokenClient`):
+ *   Frontend sends `accessToken`. Backend validates by calling Google's
+ *   userinfo endpoint. No secret required.
+ *
+ * **Path 3 – Authorization Code** (most secure, requires `clientSecret`):
+ *   Frontend sends `code` + `redirectUri`. Backend exchanges the code
+ *   server-side for an ID token using `clientId` + `clientSecret`, then
+ *   verifies the ID token. Tokens never touch the browser.
+ */
+export declare function createGoogleProvider(config: GoogleProviderConfig | string): OAuthProvider<{
+    idToken?: string;
+    accessToken?: string;
+    code?: string;
+    redirectUri?: string;
+}>;