@guren/server 1.0.0-rc.9 → 1.0.0

package/dist/api-token-BSSCLlFW.d.ts

@@ -0,0 +1,541 @@
+import { MiddlewareHandler, Context } from 'hono';
+
+type SessionData = Record<string, unknown>;
+interface SessionStore {
+    /**
+     * Read a session by its opaque identifier.
+     * Returns undefined when the session does not exist or has expired.
+     */
+    read(id: string): Promise<SessionData | undefined>;
+    /**
+     * Persist a session using upsert semantics for the given opaque identifier.
+     */
+    write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
+    /**
+     * Destroy a session. Implementations must treat repeated calls as safe.
+     */
+    destroy(id: string): Promise<void>;
+}
+declare class MemorySessionStore implements SessionStore {
+    private readonly now;
+    private readonly store;
+    constructor(now?: () => number);
+    read(id: string): Promise<SessionData | undefined>;
+    write(id: string, data: SessionData, ttlSeconds: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+}
+interface SessionOptions {
+    cookieName?: string;
+    cookiePath?: string;
+    cookieDomain?: string;
+    cookieSecure?: boolean;
+    cookieSameSite?: 'Strict' | 'Lax' | 'None';
+    cookieHttpOnly?: boolean;
+    cookieMaxAgeSeconds?: number;
+    ttlSeconds?: number;
+    store?: SessionStore;
+}
+interface Session {
+    readonly id: string;
+    readonly isNew: boolean;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+    forget(key: string): void;
+    flush(): void;
+    all(): SessionData;
+    regenerate(): void;
+    invalidate(): void;
+    flash(key: string, value: unknown): void;
+    getFlash<T = unknown>(key: string): T | undefined;
+    reflash(): void;
+    keep(...keys: string[]): void;
+}
+interface CreateSessionMiddlewareOptions extends SessionOptions {
+}
+declare function createSessionMiddleware(options?: CreateSessionMiddlewareOptions): MiddlewareHandler;
+declare function getSessionFromContext<T extends Session = Session>(ctx: {
+    get: (key: string) => unknown;
+}): T | undefined;
+
+type AuthCredentials = Record<string, unknown>;
+interface Authenticatable {
+    getAuthIdentifier(): unknown;
+    getAuthPassword(): string | null | undefined;
+    getRememberToken?(): string | null | undefined;
+    setRememberToken?(token: string | null): void | Promise<void>;
+}
+interface Guard<User = Authenticatable> {
+    check(): Promise<boolean>;
+    guest(): Promise<boolean>;
+    user<T = User>(): Promise<T | null>;
+    id(): Promise<unknown>;
+    login<T = User>(user: T, remember?: boolean): Promise<void>;
+    logout(): Promise<void>;
+    attempt(credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
+    validate(credentials: AuthCredentials): Promise<User | null>;
+    session<T extends Session = Session>(): T | undefined;
+}
+interface UserProvider<User = Authenticatable> {
+    retrieveById(identifier: unknown): Promise<User | null>;
+    retrieveByCredentials(credentials: AuthCredentials): Promise<User | null>;
+    validateCredentials(user: User, credentials: AuthCredentials): Promise<boolean>;
+    getId(user: User): unknown;
+    setRememberToken?(user: User, token: string | null): Promise<void> | void;
+    getRememberToken?(user: User): Promise<string | null> | string | null;
+    /**
+     * Strip fields that must never leave the auth layer (password hashes,
+     * remember tokens, model `hidden` fields) from a user record before it
+     * is cached or handed to application code via guard.user().
+     */
+    sanitize?(user: User): User;
+}
+interface GuardContext {
+    ctx: Context;
+    session: Session | undefined;
+    manager: AuthManagerContract;
+}
+type GuardFactory<User = Authenticatable> = (context: GuardContext) => Guard<User>;
+interface ProviderFactory<User = Authenticatable> {
+    (manager: AuthManagerContract): UserProvider<User>;
+}
+interface AuthManagerOptions {
+    defaultGuard?: string;
+}
+interface AttachContextOptions {
+    guard?: string;
+}
+interface AuthContext<User = Authenticatable> {
+    check(): Promise<boolean>;
+    guest(): Promise<boolean>;
+    user<T = User>(): Promise<T | null>;
+    userOrFail<T = User>(): Promise<T>;
+    id(): Promise<unknown>;
+    login<T = User>(user: T, remember?: boolean): Promise<void>;
+    attempt(credentials: AuthCredentials, remember?: boolean): Promise<boolean>;
+    logout(): Promise<void>;
+    guard<T = User>(name?: string): Guard<T>;
+    session<T extends Session = Session>(): T | undefined;
+}
+interface AuthManagerContract {
+    registerGuard<User = Authenticatable>(name: string, factory: GuardFactory<User>): void;
+    registerProvider<User = Authenticatable>(name: string, factory: ProviderFactory<User>): void;
+    getProvider<User = Authenticatable>(name: string): UserProvider<User>;
+    createGuard<User = Authenticatable>(name: string, context: GuardContext): Guard<User>;
+    guardNames(): string[];
+    setDefaultGuard(name: string): void;
+    getDefaultGuard(): string;
+    createAuthContext(ctx: Context, options?: AttachContextOptions): AuthContext;
+}
+
+interface OAuthProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    authorizeUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    scopes?: string[];
+    tokenAuthMethod?: 'client_secret_post' | 'client_secret_basic';
+    userInfoMethod?: 'GET' | 'POST';
+    mapProfile?: (raw: Record<string, unknown>, token: OAuthTokenResult) => OAuthUserProfile;
+}
+interface OAuthTokenResult {
+    accessToken: string;
+    tokenType?: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    scope?: string;
+    raw: Record<string, unknown>;
+}
+interface OAuthUserProfile {
+    id: string;
+    email?: string;
+    name?: string;
+    avatar?: string;
+    token: OAuthTokenResult;
+    raw: Record<string, unknown>;
+}
+interface OAuthStatePayload {
+    provider: string;
+    redirectTo?: string;
+    expiresAt: Date;
+}
+interface OAuthStateStore {
+    store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
+    find(stateHash: string): Promise<OAuthStatePayload | null>;
+    delete(stateHash: string): Promise<void>;
+}
+interface OAuthStateConfig {
+    expiresIn?: number;
+    stateLength?: number;
+    hashAlgorithm?: 'sha256' | 'sha512';
+}
+interface OAuthAuthorizeOptions {
+    scope?: string[];
+    redirectTo?: string;
+    state?: string;
+    extraParams?: Record<string, string>;
+}
+interface OAuthCallbackPayload {
+    code: string;
+    state: string;
+}
+interface OAuthManagerOptions {
+    stateStore?: OAuthStateStore;
+    stateConfig?: OAuthStateConfig;
+}
+declare class MemoryOAuthStateStore implements OAuthStateStore {
+    private readonly states;
+    private readonly maxEntries;
+    constructor(options?: {
+        maxEntries?: number;
+    });
+    store(stateHash: string, payload: OAuthStatePayload): Promise<void>;
+    private sweepExpired;
+    find(stateHash: string): Promise<OAuthStatePayload | null>;
+    delete(stateHash: string): Promise<void>;
+    clear(): void;
+}
+declare class OAuthManager {
+    private readonly providers;
+    private readonly stateStore;
+    private readonly stateConfig;
+    constructor(options?: OAuthManagerOptions);
+    registerProvider(name: string, config: OAuthProviderConfig): void;
+    providerNames(): string[];
+    getProvider(name: string): OAuthProviderConfig;
+    authorize(providerName: string, options?: OAuthAuthorizeOptions): Promise<{
+        url: string;
+        state: string;
+        expiresAt: Date;
+    }>;
+    user(providerName: string, payload: OAuthCallbackPayload): Promise<OAuthUserProfile>;
+}
+declare function createOAuthManager(options?: OAuthManagerOptions): OAuthManager;
+declare function createOAuthState(provider: string, store: OAuthStateStore, config?: OAuthStateConfig, redirectTo?: string, fixedState?: string): Promise<{
+    state: string;
+    expiresAt: Date;
+}>;
+declare function verifyOAuthState(state: string, provider: string, store: OAuthStateStore, config?: OAuthStateConfig): Promise<OAuthStatePayload | null>;
+declare function buildOAuthAuthorizeUrl(provider: OAuthProviderConfig, state: string, options?: {
+    scope?: string[];
+    extraParams?: Record<string, string>;
+}): string;
+declare function exchangeOAuthCode(provider: OAuthProviderConfig, code: string): Promise<OAuthTokenResult>;
+declare function fetchOAuthUserProfile(provider: OAuthProviderConfig, token: OAuthTokenResult): Promise<OAuthUserProfile>;
+interface OAuthProviderFactoryInput {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+}
+declare function createGitHubOAuthProviderConfig(input: OAuthProviderFactoryInput): OAuthProviderConfig;
+declare function createGoogleOAuthProviderConfig(input: OAuthProviderFactoryInput): OAuthProviderConfig;
+declare function createDiscordOAuthProviderConfig(input: OAuthProviderFactoryInput): OAuthProviderConfig;
+declare function buildOAuthRedirectUrl(baseUrl: string, token: string, email?: string): string;
+declare function parseOAuthRedirectUrl(url: string): {
+    token: string | null;
+    email: string | null;
+};
+
+/**
+ * API token data stored in the backing store.
+ */
+interface ApiToken {
+    id: string;
+    name: string;
+    hashedToken: string;
+    userId: string | number;
+    abilities: string[];
+    lastUsedAt: Date | null;
+    expiresAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Store interface for API tokens.
+ * Implement this for database-backed storage.
+ */
+interface ApiTokenStore {
+    /**
+     * Store a new API token.
+     */
+    store(token: ApiToken): Promise<void>;
+    /**
+     * Find a token by its hashed value.
+     */
+    findByHashedToken(hashedToken: string): Promise<ApiToken | null>;
+    /**
+     * Find all tokens for a user.
+     */
+    findByUserId(userId: string | number): Promise<ApiToken[]>;
+    /**
+     * Delete a token by its ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Delete all tokens for a user.
+     */
+    deleteForUser(userId: string | number): Promise<void>;
+    /**
+     * Update the last used timestamp.
+     */
+    updateLastUsed(id: string, timestamp: Date): Promise<void>;
+}
+/**
+ * In-memory token store for testing.
+ * Do NOT use in production - tokens will be lost on restart.
+ */
+declare class MemoryApiTokenStore implements ApiTokenStore {
+    private tokens;
+    private byHash;
+    store(token: ApiToken): Promise<void>;
+    findByHashedToken(hashedToken: string): Promise<ApiToken | null>;
+    findByUserId(userId: string | number): Promise<ApiToken[]>;
+    delete(id: string): Promise<void>;
+    deleteForUser(userId: string | number): Promise<void>;
+    updateLastUsed(id: string, timestamp: Date): Promise<void>;
+    /**
+     * Clear all tokens (useful for testing).
+     */
+    clear(): void;
+    /**
+     * Get the number of stored tokens.
+     */
+    get size(): number;
+}
+/**
+ * Configuration for API token creation.
+ */
+interface CreateApiTokenOptions {
+    /**
+     * Human-readable name for the token.
+     */
+    name: string;
+    /**
+     * User ID the token belongs to.
+     */
+    userId: string | number;
+    /**
+     * Token abilities/scopes.
+     * @default ['*'] (all abilities)
+     */
+    abilities?: string[];
+    /**
+     * Token expiration time in milliseconds from now.
+     * @default null (never expires)
+     */
+    expiresIn?: number | null;
+    /**
+     * Token byte length (before encoding).
+     * @default 32
+     */
+    tokenLength?: number;
+}
+/**
+ * Result of creating an API token.
+ */
+interface CreateApiTokenResult {
+    /**
+     * The full token to give to the user.
+     * Format: {id}|{plainToken}
+     * This is the ONLY time the plain token is available.
+     */
+    plainTextToken: string;
+    /**
+     * The token record (without the plain token).
+     */
+    token: ApiToken;
+}
+/**
+ * Create a new API token.
+ *
+ * @example
+ * ```ts
+ * const { plainTextToken, token } = await createApiToken(store, {
+ *   name: 'My App Token',
+ *   userId: user.id,
+ *   abilities: ['read', 'write'],
+ *   expiresIn: 30 * 24 * 60 * 60 * 1000, // 30 days
+ * })
+ *
+ * // Return plainTextToken to user - this is the only time it's available
+ * return ctx.json({ token: plainTextToken })
+ * ```
+ */
+declare function createApiToken(store: ApiTokenStore, options: CreateApiTokenOptions): Promise<CreateApiTokenResult>;
+/**
+ * Parse a plain text token into its components.
+ */
+declare function parseApiToken(plainTextToken: string): {
+    id: string;
+    token: string;
+} | null;
+/**
+ * Verify an API token and return the associated user ID.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyApiToken(plainTextToken, store)
+ *
+ * if (!result) {
+ *   return ctx.json({ error: 'Invalid token' }, 401)
+ * }
+ *
+ * console.log(`User ${result.userId} authenticated with abilities:`, result.abilities)
+ * ```
+ */
+declare function verifyApiToken(plainTextToken: string, store: ApiTokenStore, options?: {
+    updateLastUsed?: boolean;
+}): Promise<{
+    token: ApiToken;
+    userId: string | number;
+    abilities: string[];
+} | null>;
+/**
+ * Check if a token has a specific ability.
+ */
+declare function tokenCan(token: ApiToken | {
+    abilities: string[];
+}, ability: string): boolean;
+/**
+ * Check if a token has all specified abilities.
+ */
+declare function tokenCanAll(token: ApiToken | {
+    abilities: string[];
+}, abilities: string[]): boolean;
+/**
+ * Check if a token has any of the specified abilities.
+ */
+declare function tokenCanAny(token: ApiToken | {
+    abilities: string[];
+}, abilities: string[]): boolean;
+/**
+ * Revoke (delete) an API token.
+ *
+ * @example
+ * ```ts
+ * await revokeApiToken(tokenId, store)
+ * ```
+ */
+declare function revokeApiToken(id: string, store: ApiTokenStore): Promise<void>;
+/**
+ * Revoke all API tokens for a user.
+ *
+ * @example
+ * ```ts
+ * // Revoke all tokens when user changes password
+ * await revokeAllApiTokens(user.id, store)
+ * ```
+ */
+declare function revokeAllApiTokens(userId: string | number, store: ApiTokenStore): Promise<void>;
+/**
+ * Get all API tokens for a user.
+ *
+ * @example
+ * ```ts
+ * const tokens = await getUserApiTokens(user.id, store)
+ * // Returns tokens without the plain text (only metadata)
+ * ```
+ */
+declare function getUserApiTokens(userId: string | number, store: ApiTokenStore): Promise<ApiToken[]>;
+/**
+ * Context key for storing the authenticated token.
+ */
+declare const API_TOKEN_KEY = "guren:api-token";
+/**
+ * Options for the bearer token middleware.
+ */
+interface BearerTokenMiddlewareOptions {
+    /**
+     * Token store implementation.
+     */
+    store: ApiTokenStore;
+    /**
+     * Function to load the user from the user ID.
+     */
+    loadUser?: (userId: string | number) => Promise<unknown>;
+    /**
+     * Required abilities for this route.
+     * If not specified, any valid token is accepted.
+     */
+    abilities?: string[];
+    /**
+     * Custom handler when authentication fails.
+     */
+    onUnauthorized?: (ctx: Context) => Response | Promise<Response>;
+    /**
+     * Custom handler when token lacks required abilities.
+     */
+    onForbidden?: (ctx: Context, required: string[]) => Response | Promise<Response>;
+    /**
+     * Header name to extract the token from.
+     * @default 'Authorization'
+     */
+    headerName?: string;
+    /**
+     * Whether to update the token's lastUsedAt timestamp.
+     * @default true
+     */
+    updateLastUsed?: boolean;
+}
+/**
+ * Create middleware that authenticates requests using Bearer tokens.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * app.use('/api/*', createBearerTokenMiddleware({ store }))
+ *
+ * // With ability requirement
+ * router.delete('/api/posts/:id', [PostController, 'destroy'],
+ *   createBearerTokenMiddleware({
+ *     store,
+ *     abilities: ['posts:delete'],
+ *   })
+ * )
+ *
+ * // With user loading
+ * app.use('/api/*', createBearerTokenMiddleware({
+ *   store,
+ *   loadUser: async (userId) => User.find(userId),
+ * }))
+ * ```
+ */
+declare function createBearerTokenMiddleware(options: BearerTokenMiddlewareOptions): MiddlewareHandler;
+/**
+ * Get the authenticated API token from the request context.
+ *
+ * @example
+ * ```ts
+ * router.get('/api/me', async (ctx) => {
+ *   const { token, userId, abilities } = getApiToken(ctx)!
+ *   return ctx.json({ userId, tokenName: token.name, abilities })
+ * })
+ * ```
+ */
+declare function getApiToken(ctx: Context): {
+    token: ApiToken;
+    userId: string | number;
+    abilities: string[];
+} | null;
+/**
+ * Get the authenticated API token from the request context, or throw.
+ *
+ * @throws {AuthenticationException} When no token is present in the context.
+ *
+ * @example
+ * ```ts
+ * router.get('/api/me', async (ctx) => {
+ *   const { token, userId, abilities } = getApiTokenOrFail(ctx)
+ *   return ctx.json({ userId, tokenName: token.name, abilities })
+ * })
+ * ```
+ */
+declare function getApiTokenOrFail(ctx: Context): {
+    token: ApiToken;
+    userId: string | number;
+    abilities: string[];
+};
+
+export { revokeAllApiTokens as $, type Authenticatable as A, type BearerTokenMiddlewareOptions as B, type CreateSessionMiddlewareOptions as C, buildOAuthAuthorizeUrl as D, buildOAuthRedirectUrl as E, createApiToken as F, type GuardFactory as G, createBearerTokenMiddleware as H, createDiscordOAuthProviderConfig as I, createGitHubOAuthProviderConfig as J, createGoogleOAuthProviderConfig as K, createOAuthManager as L, MemoryApiTokenStore as M, createOAuthState as N, type OAuthStateStore as O, type ProviderFactory as P, createSessionMiddleware as Q, exchangeOAuthCode as R, type SessionStore as S, fetchOAuthUserProfile as T, type UserProvider as U, getApiToken as V, getApiTokenOrFail as W, getSessionFromContext as X, getUserApiTokens as Y, parseApiToken as Z, parseOAuthRedirectUrl as _, type AuthCredentials as a, revokeApiToken as a0, tokenCan as a1, tokenCanAll as a2, tokenCanAny as a3, verifyApiToken as a4, verifyOAuthState as a5, type AuthManagerContract as b, type AuthManagerOptions as c, type GuardContext as d, type Guard as e, type AttachContextOptions as f, type AuthContext as g, type SessionData as h, type ApiTokenStore as i, type ApiToken as j, type OAuthStatePayload as k, OAuthManager as l, API_TOKEN_KEY as m, type CreateApiTokenOptions as n, type CreateApiTokenResult as o, MemoryOAuthStateStore as p, MemorySessionStore as q, type OAuthAuthorizeOptions as r, type OAuthCallbackPayload as s, type OAuthManagerOptions as t, type OAuthProviderConfig as u, type OAuthProviderFactoryInput as v, type OAuthStateConfig as w, type OAuthTokenResult as x, type OAuthUserProfile as y, type Session as z };