@nubase/backend 0.1.0 → 0.1.4

package/dist/index.d.mts

@@ -1,23 +1,382 @@
 import * as hono from 'hono';
-import { Context } from 'hono';
+import { Context, Hono } from 'hono';
 import { RequestSchema, InferRequestParams, InferRequestBody, InferResponseBody } from '@nubase/core';
+import { ContentfulStatusCode } from 'hono/utils/http-status';
 
-type TypedHandlerContext<T extends RequestSchema> = {
+/**
+ * Represents an authenticated user on the backend.
+ * Generic type allows applications to define their own user shape.
+ */
+interface BackendUser {
+    id: number | string;
+}
+/**
+ * Token payload that can be embedded in JWTs.
+ * Applications can extend this with additional claims.
+ */
+interface TokenPayload {
+    /** User identifier */
+    userId: number | string;
+    /** Token issued at timestamp */
+    iat?: number;
+    /** Token expiration timestamp */
+    exp?: number;
+}
+/**
+ * Result of token verification.
+ */
+type VerifyTokenResult<TUser extends BackendUser> = {
+    valid: true;
+    user: TUser;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Authentication level for routes.
+ */
+type AuthLevel = "required" | "optional" | "none";
+/**
+ * BackendAuthController interface.
+ *
+ * This is the core abstraction for backend authentication in Nubase applications.
+ * Applications implement this interface to provide their own authentication logic.
+ *
+ * The controller handles:
+ * - Token extraction from requests (cookies, headers)
+ * - Token verification and user lookup
+ * - Token creation for login flows
+ *
+ * Future extensibility:
+ * - Token refresh
+ * - Token revocation (logout, security)
+ * - Two-factor authentication verification
+ * - Social login / SSO token validation
+ * - Session management
+ *
+ * @template TUser - The user type returned after authentication
+ * @template TTokenPayload - Additional claims to include in tokens
+ */
+interface BackendAuthController<TUser extends BackendUser = BackendUser, TTokenPayload extends TokenPayload = TokenPayload> {
+    /**
+     * Extract the authentication token from a request.
+     * Typically looks in cookies or Authorization header.
+     *
+     * @param ctx - Hono context
+     * @returns The token string or null if not present
+     */
+    extractToken(ctx: Context): string | null;
+    /**
+     * Verify a token and return the authenticated user.
+     *
+     * @param token - The token to verify
+     * @returns Verification result with user or error
+     */
+    verifyToken(token: string): Promise<VerifyTokenResult<TUser>>;
+    /**
+     * Create a new authentication token for a user.
+     * Used during login to generate the JWT.
+     *
+     * @param user - The user to create a token for
+     * @param additionalPayload - Optional additional claims
+     * @returns The signed token string
+     */
+    createToken(user: TUser, additionalPayload?: Partial<TTokenPayload>): Promise<string>;
+    /**
+     * Set the authentication token in the response.
+     * Typically sets an HttpOnly cookie.
+     *
+     * @param ctx - Hono context
+     * @param token - The token to set
+     */
+    setTokenInResponse(ctx: Context, token: string): void;
+    /**
+     * Clear the authentication token from the response.
+     * Used during logout.
+     *
+     * @param ctx - Hono context
+     */
+    clearTokenFromResponse(ctx: Context): void;
+    /**
+     * Validate user credentials during login.
+     * Looks up the user by username and verifies the password.
+     *
+     * @param username - The username to look up
+     * @param password - The plain text password to verify
+     * @returns The user if credentials are valid, null otherwise
+     */
+    validateCredentials(username: string, password: string): Promise<TUser | null>;
+    /**
+     * Refresh an existing token.
+     * Returns a new token if the old one is valid but near expiration.
+     *
+     * @param token - The current token
+     * @returns New token or null if refresh not possible
+     */
+    refreshToken?(token: string): Promise<string | null>;
+    /**
+     * Revoke a token (e.g., for logout or security).
+     * Implementations may track revoked tokens in a blacklist.
+     *
+     * @param token - The token to revoke
+     */
+    revokeToken?(token: string): Promise<void>;
+    /**
+     * Verify a two-factor authentication code.
+     *
+     * @param userId - The user's ID
+     * @param code - The 2FA code to verify
+     * @returns Whether the code is valid
+     */
+    verify2FA?(userId: number | string, code: string): Promise<boolean>;
+    /**
+     * Check if a user requires 2FA.
+     *
+     * @param user - The user to check
+     * @returns Whether 2FA is required
+     */
+    requires2FA?(user: TUser): boolean;
+    /**
+     * Validate an external OAuth/SSO token.
+     *
+     * @param provider - The OAuth provider (google, github, etc.)
+     * @param token - The external token
+     * @returns The user if valid, null otherwise
+     */
+    validateExternalToken?(provider: string, token: string): Promise<TUser | null>;
+    /**
+     * Link an external OAuth provider to a user account.
+     *
+     * @param userId - The user's ID
+     * @param provider - The OAuth provider
+     * @param externalId - The external provider's user ID
+     */
+    linkExternalProvider?(userId: number | string, provider: string, externalId: string): Promise<void>;
+    /**
+     * Create a server-side session (for SSO session sync).
+     *
+     * @param user - The user to create a session for
+     * @returns The session ID
+     */
+    createSession?(user: TUser): Promise<string>;
+    /**
+     * Invalidate a session.
+     *
+     * @param sessionId - The session to invalidate
+     */
+    invalidateSession?(sessionId: string): Promise<void>;
+}
+
+/**
+ * Options for creating auth handlers.
+ */
+interface CreateAuthHandlersOptions<TUser extends BackendUser = BackendUser> {
+    /**
+     * The auth controller instance.
+     */
+    controller: BackendAuthController<TUser>;
+}
+/**
+ * Auth handlers returned by createAuthHandlers.
+ */
+interface AuthHandlers {
+    /**
+     * Login handler - validates credentials and sets auth cookie.
+     * Expects JSON body: { username: string, password: string }
+     * Returns: { user: { id, email, username } }
+     */
+    login: (ctx: Context) => Promise<Response>;
+    /**
+     * Logout handler - clears the auth cookie.
+     * Returns: { success: true }
+     */
+    logout: (ctx: Context) => Promise<Response>;
+    /**
+     * Get current user handler - returns the authenticated user or undefined.
+     * Returns: { user?: { id, email, username } }
+     */
+    getMe: (ctx: Context) => Promise<Response>;
+    /**
+     * Pre-configured Hono router with all auth routes.
+     * Mount this at /auth to get /auth/login, /auth/logout, /auth/me
+     */
+    routes: Hono;
+}
+/**
+ * Create standard authentication handlers from a BackendAuthController.
+ *
+ * This utility reduces boilerplate by providing pre-built handlers for
+ * login, logout, and get-current-user endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { createAuthHandlers, createAuthMiddleware } from "@nubase/backend";
+ *
+ * const authController = new MyBackendAuthController();
+ * const authHandlers = createAuthHandlers({ controller: authController });
+ *
+ * const app = new Hono();
+ * app.use("*", createAuthMiddleware({ controller: authController }));
+ *
+ * // Option 1: Register routes individually
+ * app.post("/auth/login", authHandlers.login);
+ * app.post("/auth/logout", authHandlers.logout);
+ * app.get("/auth/me", authHandlers.getMe);
+ *
+ * // Option 2: Mount the pre-configured router
+ * app.route("/auth", authHandlers.routes);
+ * ```
+ */
+declare function createAuthHandlers<TUser extends BackendUser = BackendUser>(options: CreateAuthHandlersOptions<TUser>): AuthHandlers;
+
+/**
+ * Context key for storing the authenticated user.
+ * Use `c.get('user')` to retrieve the user in handlers.
+ */
+declare const AUTH_USER_KEY = "user";
+/**
+ * Context key for storing the auth controller instance.
+ */
+declare const AUTH_CONTROLLER_KEY = "authController";
+/**
+ * Variables added to Hono context by auth middleware.
+ */
+interface AuthVariables<TUser extends BackendUser = BackendUser> {
+    user: TUser | null;
+    authController: BackendAuthController<TUser>;
+}
+/**
+ * Options for the auth middleware.
+ */
+interface AuthMiddlewareOptions<TUser extends BackendUser = BackendUser> {
+    /**
+     * The auth controller instance to use for token verification.
+     */
+    controller: BackendAuthController<TUser>;
+    /**
+     * Default auth level for all routes.
+     * Can be overridden per-route using createHttpHandler's auth option.
+     * @default "none"
+     */
+    defaultAuthLevel?: AuthLevel;
+}
+/**
+ * Create an authentication middleware for Hono.
+ *
+ * This middleware:
+ * 1. Extracts the token from the request
+ * 2. Verifies the token using the provided controller
+ * 3. Sets the user in the context (or null if not authenticated)
+ * 4. Makes the controller available in context for handlers
+ *
+ * @example
+ * ```typescript
+ * const authController = new QuestlogBackendAuthController();
+ * const app = new Hono();
+ *
+ * // Apply to all routes
+ * app.use('*', createAuthMiddleware({ controller: authController }));
+ *
+ * // Access user in handlers
+ * app.get('/me', (c) => {
+ *   const user = c.get('user');
+ *   if (!user) return c.json({ error: 'Unauthorized' }, 401);
+ *   return c.json({ user });
+ * });
+ * ```
+ */
+declare function createAuthMiddleware<TUser extends BackendUser = BackendUser>(options: AuthMiddlewareOptions<TUser>): hono.MiddlewareHandler<{
+    Variables: AuthVariables<TUser>;
+}, string, {}, Response>;
+/**
+ * Middleware to require authentication.
+ * Returns 401 if user is not authenticated.
+ *
+ * @example
+ * ```typescript
+ * // Protect a single route
+ * app.get('/protected', requireAuth(), (c) => {
+ *   const user = c.get('user')!; // User is guaranteed to exist
+ *   return c.json({ message: `Hello ${user.username}` });
+ * });
+ *
+ * // Protect a group of routes
+ * const protected = app.basePath('/api/admin');
+ * protected.use('*', requireAuth());
+ * ```
+ */
+declare function requireAuth<TUser extends BackendUser = BackendUser>(): hono.MiddlewareHandler<{
+    Variables: AuthVariables<TUser>;
+}, string, {}, Response>;
+/**
+ * Helper to get the authenticated user from context.
+ * Returns null if not authenticated.
+ */
+declare function getUser<TUser extends BackendUser = BackendUser>(c: Context): TUser | null;
+/**
+ * Helper to get the auth controller from context.
+ */
+declare function getAuthController<TUser extends BackendUser = BackendUser>(c: Context): BackendAuthController<TUser>;
+
+/**
+ * Custom HTTP error class that allows handlers to throw errors with specific status codes.
+ * Use this to return proper HTTP error responses instead of generic 500 errors.
+ *
+ * @example
+ * throw new HttpError(401, "Invalid username or password");
+ * throw new HttpError(404, "Resource not found");
+ * throw new HttpError(403, "Access denied");
+ */
+declare class HttpError extends Error {
+    statusCode: ContentfulStatusCode;
+    constructor(statusCode: ContentfulStatusCode, message: string);
+}
+/**
+ * URL Parameter Coercion System (Backend)
+ *
+ * **The Problem:**
+ * URL path parameters always arrive as strings from HTTP requests,
+ * but schemas expect typed values (numbers, booleans).
+ *
+ * **The Solution:**
+ * We use the schema's `toZodWithCoercion()` method which leverages Zod's
+ * built-in coercion to automatically convert string values to expected types.
+ *
+ * **Example:**
+ * - URL: `/tickets/37` → params: { id: "37" }
+ * - Schema expects: { id: number }
+ * - toZodWithCoercion() converts: { id: 37 }
+ */
+/**
+ * Context provided to typed handlers.
+ *
+ * @template T - The request schema type
+ * @template TUser - The user type (when auth is required/optional)
+ */
+type TypedHandlerContext<T extends RequestSchema, TUser extends BackendUser | null = null> = {
     params: InferRequestParams<T>;
     body: InferRequestBody<T>;
     ctx: Context;
+    /**
+     * The authenticated user.
+     * - When auth is 'required': TUser (guaranteed to exist)
+     * - When auth is 'optional': TUser | null
+     * - When auth is 'none': not present (null)
+     */
+    user: TUser;
 };
-type TypedHandler<T extends RequestSchema> = (context: TypedHandlerContext<T>) => Promise<InferResponseBody<T>>;
+/**
+ * Handler function type for typed HTTP handlers.
+ */
+type TypedHandler<T extends RequestSchema, TUser extends BackendUser | null = null> = (context: TypedHandlerContext<T, TUser>) => Promise<InferResponseBody<T>>;
 declare function createTypedHandler<T extends RequestSchema>(schema: T, handler: TypedHandler<T>): ReturnType<typeof createTypedHandlerInternal>;
 declare function createTypedHandler<T extends RequestSchema>(endpointRef: T, // Can be apiEndpoints.ticketsGetTickets
 handler: TypedHandler<T>): ReturnType<typeof createTypedHandlerInternal>;
-declare function createTypedHandlerInternal<T extends RequestSchema>(schema: T, handler: TypedHandler<T>): (c: Context) => Promise<(Response & hono.TypedResponse<{
+declare function createTypedHandlerInternal<T extends RequestSchema, TUser extends BackendUser | null = null>(schema: T, handler: TypedHandler<T, TUser>, options?: {
+    auth?: AuthLevel;
+}): (c: Context) => Promise<(Response & hono.TypedResponse<any, 200 | 201, "json">) | (Response & hono.TypedResponse<{
     error: string;
-    details: string;
-}, 400, "json">) | (Response & hono.TypedResponse<any, 200 | 201, "json">) | (Response & hono.TypedResponse<{
-    error: string;
-    details: string;
-}, 500, "json">)>;
+}, 401 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | -1, "json">)>;
 type TypedRouteDefinition<T extends RequestSchema> = {
     schema: T;
     handler: TypedHandler<T>;
@@ -25,10 +384,139 @@ type TypedRouteDefinition<T extends RequestSchema> = {
 type TypedRoutes = Record<string, TypedRouteDefinition<any>>;
 declare function createTypedRoutes<T extends TypedRoutes>(routes: T): Record<string, (c: Context) => Promise<(Response & hono.TypedResponse<any, 200 | 201, "json">) | (Response & hono.TypedResponse<{
     error: string;
-    details: string;
-}, 400, "json">) | (Response & hono.TypedResponse<{
-    error: string;
-    details: string;
-}, 500, "json">)>>;
+}, 401 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 | -1, "json">)>>;
+/**
+ * A handler created by createHttpHandler with endpoint metadata attached.
+ * This allows registerHandlers to auto-register routes based on the endpoint's path and method.
+ */
+type HttpHandler = ((c: Context) => Promise<Response>) & {
+    __endpoint: RequestSchema;
+};
+/**
+ * Options for createHttpHandler.
+ */
+type CreateHttpHandlerOptions<T extends RequestSchema, TAuth extends AuthLevel = "none", TUser extends BackendUser = BackendUser> = {
+    /**
+     * The endpoint schema defining request/response types.
+     */
+    endpoint: T;
+    /**
+     * Authentication level for this route.
+     * - 'required': Request must be authenticated. Returns 401 if not. User is guaranteed in handler.
+     * - 'optional': Authentication is optional. User may be null in handler.
+     * - 'none': No authentication check. User is always null. (default)
+     */
+    auth?: TAuth;
+    /**
+     * The handler function.
+     * When auth is 'required', user is guaranteed to be non-null.
+     * When auth is 'optional', user may be null.
+     * When auth is 'none', user is null.
+     */
+    handler: TypedHandler<T, TAuth extends "required" ? TUser : TAuth extends "optional" ? TUser | null : null>;
+};
+/**
+ * Create a typed HTTP handler with optional authentication.
+ *
+ * @example
+ * ```typescript
+ * // No auth (default)
+ * export const handleGetPublicData = createHttpHandler({
+ *   endpoint: apiEndpoints.getPublicData,
+ *   handler: async ({ body }) => {
+ *     return { data: 'public' };
+ *   },
+ * });
+ *
+ * // Required auth - user is guaranteed
+ * export const handleGetProfile = createHttpHandler({
+ *   endpoint: apiEndpoints.getProfile,
+ *   auth: 'required',
+ *   handler: async ({ body, user }) => {
+ *     // user is guaranteed to exist here
+ *     return { userId: user.id };
+ *   },
+ * });
+ *
+ * // Optional auth - user may be null
+ * export const handleGetContent = createHttpHandler({
+ *   endpoint: apiEndpoints.getContent,
+ *   auth: 'optional',
+ *   handler: async ({ body, user }) => {
+ *     if (user) {
+ *       return { content: 'personalized', userId: user.id };
+ *     }
+ *     return { content: 'generic' };
+ *   },
+ * });
+ * ```
+ */
+declare function createHttpHandler<T extends RequestSchema, TAuth extends AuthLevel = "none", TUser extends BackendUser = BackendUser>(options: CreateHttpHandlerOptions<T, TAuth, TUser>): HttpHandler;
+/**
+ * A record of handlers to be registered with registerHandlers.
+ */
+type HttpHandlers = Record<string, HttpHandler>;
+/**
+ * Register multiple HTTP handlers with a Hono app.
+ * Automatically extracts path and method from each handler's endpoint metadata.
+ *
+ * @example
+ * ```typescript
+ * // In dashboard.ts
+ * export const dashboardHandlers = {
+ *   getRevenueChart: createHttpHandler({
+ *     endpoint: apiEndpoints.getRevenueChart,
+ *     auth: "required",
+ *     handler: async () => ({ ... }),
+ *   }),
+ *   getBrowserStats: createHttpHandler({
+ *     endpoint: apiEndpoints.getBrowserStats,
+ *     auth: "required",
+ *     handler: async () => ({ ... }),
+ *   }),
+ * };
+ *
+ * // In index.ts
+ * registerHandlers(app, dashboardHandlers);
+ * // Automatically registers:
+ * // app.get("/dashboard/revenue-chart", handler)
+ * // app.get("/dashboard/browser-stats", handler)
+ * ```
+ */
+declare function registerHandlers<TApp extends {
+    get: any;
+    post: any;
+    put: any;
+    patch: any;
+    delete: any;
+}>(app: TApp, handlers: HttpHandlers): void;
+
+/**
+ * Parse a cookie header string into a key-value object.
+ *
+ * @param cookieHeader - The Cookie header string (e.g., "name=value; other=123")
+ * @returns An object mapping cookie names to their values
+ *
+ * @example
+ * ```typescript
+ * const cookies = parseCookies("session=abc123; theme=dark");
+ * // { session: "abc123", theme: "dark" }
+ * ```
+ */
+declare function parseCookies(cookieHeader: string): Record<string, string>;
+/**
+ * Get a specific cookie value from a cookie header string.
+ *
+ * @param cookieHeader - The Cookie header string
+ * @param name - The cookie name to retrieve
+ * @returns The cookie value or null if not found
+ *
+ * @example
+ * ```typescript
+ * const session = getCookie("session=abc123; theme=dark", "session");
+ * // "abc123"
+ * ```
+ */
+declare function getCookie(cookieHeader: string, name: string): string | null;
 
-export { type TypedHandler, type TypedHandlerContext, type TypedRouteDefinition, type TypedRoutes, createTypedHandler, createTypedRoutes };
+export { AUTH_CONTROLLER_KEY, AUTH_USER_KEY, type AuthHandlers, type AuthLevel, type AuthMiddlewareOptions, type AuthVariables, type BackendAuthController, type BackendUser, type CreateAuthHandlersOptions, type CreateHttpHandlerOptions, HttpError, type HttpHandler, type HttpHandlers, type TokenPayload, type TypedHandler, type TypedHandlerContext, type TypedRouteDefinition, type TypedRoutes, type VerifyTokenResult, createAuthHandlers, createAuthMiddleware, createHttpHandler, createTypedHandler, createTypedRoutes, getAuthController, getCookie, getUser, parseCookies, registerHandlers, requireAuth };