@forinda/kickjs-auth 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,496 @@
+import { AppAdapter, AdapterMiddleware, Container } from '@forinda/kickjs-core';
+
+declare const AUTH_META: {
+    readonly AUTHENTICATED: symbol;
+    readonly PUBLIC: symbol;
+    readonly ROLES: symbol;
+    readonly STRATEGY: symbol;
+};
+/**
+ * The authenticated user object attached to the request.
+ * Extend this via module augmentation for your app's user shape.
+ *
+ * @example
+ * ```ts
+ * declare module '@forinda/kickjs-auth' {
+ *   interface AuthUser {
+ *     id: string
+ *     email: string
+ *     roles: string[]
+ *   }
+ * }
+ * ```
+ */
+interface AuthUser {
+    [key: string]: any;
+}
+/**
+ * Abstract authentication strategy. Implement this to support any
+ * auth mechanism: JWT, API keys, OAuth, sessions, SAML, etc.
+ *
+ * @example
+ * ```ts
+ * class SessionStrategy implements AuthStrategy {
+ *   name = 'session'
+ *   async validate(req) {
+ *     const session = req.session
+ *     if (!session?.userId) return null
+ *     return { id: session.userId, roles: session.roles }
+ *   }
+ * }
+ * ```
+ */
+interface AuthStrategy {
+    /** Unique name for this strategy (e.g., 'jwt', 'api-key', 'session') */
+    name: string;
+    /**
+     * Extract and validate credentials from the request.
+     * Return the authenticated user, or null if authentication fails.
+     *
+     * @param req - Express request object
+     * @returns The authenticated user, or null
+     */
+    validate(req: any): Promise<AuthUser | null> | AuthUser | null;
+}
+interface AuthAdapterOptions {
+    /**
+     * Authentication strategies to use, in order of precedence.
+     * The first strategy that returns a user wins.
+     *
+     * @example
+     * ```ts
+     * new AuthAdapter({
+     *   strategies: [
+     *     new JwtStrategy({ secret: process.env.JWT_SECRET! }),
+     *     new ApiKeyStrategy({ keys: { 'sk-123': { name: 'CI bot', roles: ['api'] } } }),
+     *   ],
+     * })
+     * ```
+     */
+    strategies: AuthStrategy[];
+    /**
+     * Default behavior for routes without @Authenticated or @Public.
+     * - `'protected'` — all routes require auth unless marked @Public (default)
+     * - `'open'` — all routes are public unless marked @Authenticated
+     */
+    defaultPolicy?: 'protected' | 'open';
+    /**
+     * Custom handler for unauthorized requests.
+     * Default: responds with 401 JSON error.
+     */
+    onUnauthorized?: (req: any, res: any) => void;
+    /**
+     * Custom handler for forbidden requests (role mismatch).
+     * Default: responds with 403 JSON error.
+     */
+    onForbidden?: (req: any, res: any) => void;
+}
+
+/**
+ * Mark a controller or method as requiring authentication.
+ * When applied to a controller, all methods require auth unless overridden with @Public.
+ *
+ * Optionally specify which strategy to use (defaults to trying all registered strategies).
+ *
+ * @example
+ * ```ts
+ * @Controller('/users')
+ * @Authenticated()        // All routes require auth
+ * class UserController {
+ *   @Get('/')
+ *   list(ctx) { ... }     // Protected
+ *
+ *   @Get('/public-count')
+ *   @Public()              // Override: this route is open
+ *   count(ctx) { ... }
+ * }
+ *
+ * // Strategy-specific:
+ * @Authenticated('api-key')
+ * @Get('/webhook')
+ * webhook(ctx) { ... }
+ * ```
+ */
+declare function Authenticated(strategy?: string): ClassDecorator & MethodDecorator;
+/**
+ * Mark a method as publicly accessible, bypassing authentication.
+ * Use inside an @Authenticated controller to exempt specific routes.
+ *
+ * @example
+ * ```ts
+ * @Controller('/auth')
+ * @Authenticated()
+ * class AuthController {
+ *   @Post('/login')
+ *   @Public()              // No auth required
+ *   login(ctx) { ... }
+ *
+ *   @Get('/me')            // Auth required (inherits from controller)
+ *   me(ctx) { ... }
+ * }
+ * ```
+ */
+declare function Public(): MethodDecorator;
+/**
+ * Require specific roles to access a route.
+ * The authenticated user must have at least one of the specified roles.
+ * Implies @Authenticated — no need to add both.
+ *
+ * The user object must have a `roles` property (string array).
+ *
+ * @example
+ * ```ts
+ * @Get('/admin/dashboard')
+ * @Roles('admin', 'superadmin')
+ * dashboard(ctx) { ... }
+ *
+ * @Delete('/:id')
+ * @Roles('admin')
+ * deleteUser(ctx) { ... }
+ * ```
+ */
+declare function Roles(...roles: string[]): MethodDecorator;
+
+/** DI token to resolve the current authenticated user from the container */
+declare const AUTH_USER: unique symbol;
+/**
+ * Authentication adapter — plugs into the KickJS lifecycle to protect
+ * routes based on @Authenticated, @Public, and @Roles decorators.
+ *
+ * Supports multiple strategies (JWT, API key, custom) with first-match semantics.
+ *
+ * @example
+ * ```ts
+ * import { AuthAdapter, JwtStrategy, ApiKeyStrategy } from '@forinda/kickjs-auth'
+ *
+ * bootstrap({
+ *   modules: [...],
+ *   adapters: [
+ *     new AuthAdapter({
+ *       strategies: [
+ *         new JwtStrategy({ secret: process.env.JWT_SECRET! }),
+ *         new ApiKeyStrategy({ keys: { 'sk-123': { name: 'Bot', roles: ['api'] } } }),
+ *       ],
+ *       defaultPolicy: 'protected', // secure by default
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare class AuthAdapter implements AppAdapter {
+    private options;
+    name: string;
+    private strategies;
+    private defaultPolicy;
+    private onUnauthorized;
+    private onForbidden;
+    private routeControllers;
+    constructor(options: AuthAdapterOptions);
+    onRouteMount(controllerClass: any, mountPath: string): void;
+    middleware(): AdapterMiddleware[];
+    beforeStart(app: any, _container: Container): void;
+    private createAuthMiddleware;
+    private authenticate;
+    private resolveHandler;
+    private pathMatches;
+    private isAuthRequired;
+    private getRequiredRoles;
+    private getStrategyName;
+}
+
+interface JwtStrategyOptions {
+    /** JWT secret key for HS256 or public key for RS256 */
+    secret: string | Buffer;
+    /**
+     * Algorithm (default: 'HS256').
+     * Common values: 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512'
+     */
+    algorithms?: string[];
+    /** Where to read the token from (default: 'header') */
+    tokenFrom?: 'header' | 'query' | 'cookie';
+    /** Header name (default: 'authorization') */
+    headerName?: string;
+    /** Query parameter name when tokenFrom='query' (default: 'token') */
+    queryParam?: string;
+    /** Cookie name when tokenFrom='cookie' (default: 'jwt') */
+    cookieName?: string;
+    /** Token prefix in header (default: 'Bearer') */
+    headerPrefix?: string;
+    /**
+     * Transform the decoded JWT payload into your AuthUser shape.
+     * By default, returns the payload as-is.
+     *
+     * @example
+     * ```ts
+     * mapPayload: (payload) => ({
+     *   id: payload.sub,
+     *   email: payload.email,
+     *   roles: payload.roles || [],
+     * })
+     * ```
+     */
+    mapPayload?: (payload: any) => AuthUser;
+}
+/**
+ * JWT authentication strategy.
+ * Validates Bearer tokens using `jsonwebtoken`.
+ *
+ * Requires `jsonwebtoken` as a peer dependency:
+ * ```bash
+ * pnpm add jsonwebtoken @types/jsonwebtoken
+ * ```
+ *
+ * @example
+ * ```ts
+ * new JwtStrategy({
+ *   secret: process.env.JWT_SECRET!,
+ *   mapPayload: (payload) => ({
+ *     id: payload.sub,
+ *     email: payload.email,
+ *     roles: payload.roles ?? ['user'],
+ *   }),
+ * })
+ * ```
+ */
+declare class JwtStrategy implements AuthStrategy {
+    name: string;
+    private jwt;
+    private options;
+    constructor(options: JwtStrategyOptions);
+    private ensureJwt;
+    validate(req: any): Promise<AuthUser | null>;
+    private extractToken;
+}
+
+interface ApiKeyUser {
+    /** Display name for the API key holder */
+    name: string;
+    /** Roles granted to this API key */
+    roles?: string[];
+    /** Additional metadata */
+    [key: string]: any;
+}
+interface ApiKeyStrategyOptions {
+    /**
+     * Map of API keys to their associated users.
+     * Keys are the raw API key strings.
+     *
+     * @example
+     * ```ts
+     * keys: {
+     *   'sk-live-abc123': { name: 'Production Bot', roles: ['api', 'write'] },
+     *   'sk-test-xyz789': { name: 'Test Runner', roles: ['api'] },
+     * }
+     * ```
+     */
+    keys?: Record<string, ApiKeyUser>;
+    /**
+     * Async function to validate an API key.
+     * Use when keys are stored in a database or external service.
+     * Takes precedence over the static `keys` map.
+     *
+     * @example
+     * ```ts
+     * validate: async (key) => {
+     *   const row = await db.apiKeys.findUnique({ where: { key } })
+     *   if (!row || row.revokedAt) return null
+     *   return { name: row.name, roles: row.roles }
+     * }
+     * ```
+     */
+    validate?: (key: string) => Promise<AuthUser | null> | AuthUser | null;
+    /**
+     * Where to read the API key from (default: 'header').
+     * Checks all specified locations in order.
+     */
+    from?: Array<'header' | 'query'>;
+    /** Header name (default: 'x-api-key') */
+    headerName?: string;
+    /** Query parameter name (default: 'api_key') */
+    queryParam?: string;
+}
+/**
+ * API key authentication strategy.
+ * Validates keys from headers or query parameters against a static map
+ * or async validator function.
+ *
+ * @example
+ * ```ts
+ * // Static keys
+ * new ApiKeyStrategy({
+ *   keys: {
+ *     'sk-prod-123': { name: 'CI Bot', roles: ['api'] },
+ *   },
+ * })
+ *
+ * // Database lookup
+ * new ApiKeyStrategy({
+ *   validate: async (key) => {
+ *     const record = await db.apiKeys.findByKey(key)
+ *     return record ? { name: record.name, roles: record.roles } : null
+ *   },
+ * })
+ * ```
+ */
+declare class ApiKeyStrategy implements AuthStrategy {
+    name: string;
+    private options;
+    constructor(options: ApiKeyStrategyOptions);
+    validate(req: any): Promise<AuthUser | null>;
+    private extractKey;
+}
+
+/** Supported OAuth providers with pre-configured endpoints */
+type OAuthProvider = 'google' | 'github' | 'discord' | 'microsoft' | 'custom';
+/** Provider-specific endpoint configuration */
+interface OAuthEndpoints {
+    authorizeUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string;
+    /** Scopes to request (space-separated or array) */
+    scopes?: string[] | string;
+}
+interface OAuthStrategyOptions {
+    /** OAuth provider preset or 'custom' for manual endpoint config */
+    provider: OAuthProvider;
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+    /** Callback URL for the OAuth flow (e.g. 'http://localhost:3000/auth/google/callback') */
+    callbackUrl: string;
+    /** Custom endpoints (required when provider is 'custom') */
+    endpoints?: OAuthEndpoints;
+    /** Override default scopes for the provider */
+    scopes?: string[];
+    /**
+     * Transform the provider's user profile into your AuthUser.
+     * Called after successfully exchanging the code for a token and fetching user info.
+     *
+     * @example
+     * ```ts
+     * mapProfile: (profile) => ({
+     *   id: profile.id,
+     *   email: profile.email,
+     *   name: profile.name,
+     *   avatar: profile.picture,
+     *   roles: ['user'],
+     * })
+     * ```
+     */
+    mapProfile?: (profile: any, tokens: OAuthTokens) => AuthUser | Promise<AuthUser>;
+}
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    expiresIn?: number;
+    scope?: string;
+}
+/**
+ * Built-in OAuth 2.0 strategy with pre-configured providers.
+ * No Passport dependency — KickJS handles the entire OAuth flow.
+ *
+ * Supports: Google, GitHub, Discord, Microsoft, or any custom OAuth 2.0 provider.
+ *
+ * This strategy validates the callback request (the one with `?code=...`),
+ * exchanges the code for tokens, fetches the user profile, and returns it.
+ *
+ * You need two routes:
+ * 1. **Redirect** — sends user to provider's login page
+ * 2. **Callback** — receives the code and authenticates
+ *
+ * @example
+ * ```ts
+ * import { OAuthStrategy } from '@forinda/kickjs-auth'
+ *
+ * const googleAuth = new OAuthStrategy({
+ *   provider: 'google',
+ *   clientId: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *   callbackUrl: 'http://localhost:3000/auth/google/callback',
+ *   mapProfile: (profile) => ({
+ *     id: profile.id,
+ *     email: profile.email,
+ *     name: profile.name,
+ *     avatar: profile.picture,
+ *     roles: ['user'],
+ *   }),
+ * })
+ *
+ * // In your controller:
+ * @Get('/auth/google')
+ * @Public()
+ * loginWithGoogle(ctx: RequestContext) {
+ *   return ctx.res.redirect(googleAuth.getAuthorizationUrl())
+ * }
+ *
+ * @Get('/auth/google/callback')
+ * @Public()
+ * async googleCallback(ctx: RequestContext) {
+ *   const user = await googleAuth.validate(ctx.req)
+ *   if (!user) return ctx.res.status(401).json({ error: 'Auth failed' })
+ *   const token = issueJwt(user)
+ *   return ctx.json({ token, user })
+ * }
+ * ```
+ */
+declare class OAuthStrategy implements AuthStrategy {
+    name: string;
+    private options;
+    private endpoints;
+    constructor(options: OAuthStrategyOptions);
+    /**
+     * Get the authorization URL to redirect the user to the OAuth provider.
+     * Pass an optional `state` parameter for CSRF protection.
+     */
+    getAuthorizationUrl(state?: string): string;
+    /**
+     * Validate the callback request — exchange the authorization code for
+     * tokens and fetch the user profile.
+     */
+    validate(req: any): Promise<AuthUser | null>;
+    /** Exchange authorization code for access/refresh tokens */
+    private exchangeCode;
+    /** Fetch user profile from the provider's userinfo endpoint */
+    private fetchUserInfo;
+}
+
+/**
+ * Bridge that wraps any Passport.js strategy into a KickJS AuthStrategy.
+ * This lets you use the full Passport ecosystem (500+ strategies) without
+ * changing your KickJS auth setup.
+ *
+ * Requires `passport` as a dependency in your project:
+ * ```bash
+ * pnpm add passport
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { Strategy as GoogleStrategy } from 'passport-google-oauth20'
+ * import { PassportBridge } from '@forinda/kickjs-auth'
+ *
+ * const google = new PassportBridge('google', new GoogleStrategy({
+ *   clientID: process.env.GOOGLE_CLIENT_ID!,
+ *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *   callbackURL: '/auth/google/callback',
+ * }, (accessToken, refreshToken, profile, done) => {
+ *   // Find or create user from profile
+ *   const user = await findOrCreateUser(profile)
+ *   done(null, user)
+ * }))
+ *
+ * new AuthAdapter({
+ *   strategies: [jwtStrategy, google],
+ * })
+ * ```
+ */
+declare class PassportBridge implements AuthStrategy {
+    name: string;
+    private passportStrategy;
+    constructor(name: string, passportStrategy: any);
+    validate(req: any): Promise<AuthUser | null>;
+}
+
+export { AUTH_META, AUTH_USER, ApiKeyStrategy, type ApiKeyStrategyOptions, type ApiKeyUser, AuthAdapter, type AuthAdapterOptions, type AuthStrategy, type AuthUser, Authenticated, JwtStrategy, type JwtStrategyOptions, type OAuthEndpoints, type OAuthProvider, OAuthStrategy, type OAuthStrategyOptions, type OAuthTokens, PassportBridge, Public, Roles };

package/dist/index.js

@@ -0,0 +1,487 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import "reflect-metadata";
+
+// src/types.ts
+import "reflect-metadata";
+var AUTH_META = {
+  AUTHENTICATED: /* @__PURE__ */ Symbol("auth:authenticated"),
+  PUBLIC: /* @__PURE__ */ Symbol("auth:public"),
+  ROLES: /* @__PURE__ */ Symbol("auth:roles"),
+  STRATEGY: /* @__PURE__ */ Symbol("auth:strategy")
+};
+
+// src/decorators.ts
+import "reflect-metadata";
+function Authenticated(strategy) {
+  return (target, propertyKey) => {
+    if (propertyKey) {
+      Reflect.defineMetadata(AUTH_META.AUTHENTICATED, true, target.constructor, propertyKey);
+      if (strategy) {
+        Reflect.defineMetadata(AUTH_META.STRATEGY, strategy, target.constructor, propertyKey);
+      }
+    } else {
+      Reflect.defineMetadata(AUTH_META.AUTHENTICATED, true, target);
+      if (strategy) {
+        Reflect.defineMetadata(AUTH_META.STRATEGY, strategy, target);
+      }
+    }
+  };
+}
+__name(Authenticated, "Authenticated");
+function Public() {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(AUTH_META.PUBLIC, true, target.constructor, propertyKey);
+  };
+}
+__name(Public, "Public");
+function Roles(...roles) {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(AUTH_META.AUTHENTICATED, true, target.constructor, propertyKey);
+    Reflect.defineMetadata(AUTH_META.ROLES, roles, target.constructor, propertyKey);
+  };
+}
+__name(Roles, "Roles");
+
+// src/adapter.ts
+import "reflect-metadata";
+import { Logger, HttpStatus, METADATA } from "@forinda/kickjs-core";
+var log = Logger.for("AuthAdapter");
+var AUTH_USER = /* @__PURE__ */ Symbol("AuthUser");
+var AuthAdapter = class {
+  static {
+    __name(this, "AuthAdapter");
+  }
+  options;
+  name = "AuthAdapter";
+  strategies;
+  defaultPolicy;
+  onUnauthorized;
+  onForbidden;
+  // Collected route metadata for auth resolution
+  routeControllers = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.options = options;
+    this.strategies = options.strategies;
+    this.defaultPolicy = options.defaultPolicy ?? "protected";
+    this.onUnauthorized = options.onUnauthorized ?? ((_req, res) => {
+      res.status(HttpStatus.UNAUTHORIZED).json({
+        statusCode: HttpStatus.UNAUTHORIZED,
+        error: "Unauthorized",
+        message: "Authentication required"
+      });
+    });
+    this.onForbidden = options.onForbidden ?? ((_req, res) => {
+      res.status(HttpStatus.FORBIDDEN).json({
+        statusCode: HttpStatus.FORBIDDEN,
+        error: "Forbidden",
+        message: "Insufficient permissions"
+      });
+    });
+  }
+  onRouteMount(controllerClass, mountPath) {
+    this.routeControllers.set(mountPath, controllerClass);
+  }
+  middleware() {
+    return [
+      {
+        handler: this.createAuthMiddleware(),
+        phase: "beforeRoutes"
+      }
+    ];
+  }
+  beforeStart(app, _container) {
+    const strategyNames = this.strategies.map((s) => s.name).join(", ");
+    log.info(`Auth enabled [${strategyNames}] (default: ${this.defaultPolicy})`);
+  }
+  // ── Core Auth Middleware ─────────────────────────────────────────────
+  createAuthMiddleware() {
+    return async (req, res, next) => {
+      const { controllerClass, handlerName } = this.resolveHandler(req);
+      const authRequired = this.isAuthRequired(controllerClass, handlerName);
+      if (!authRequired) {
+        return next();
+      }
+      const strategyName = this.getStrategyName(controllerClass, handlerName);
+      const user = await this.authenticate(req, strategyName);
+      if (!user) {
+        return this.onUnauthorized(req, res);
+      }
+      req.user = user;
+      const requiredRoles = this.getRequiredRoles(controllerClass, handlerName);
+      if (requiredRoles && requiredRoles.length > 0) {
+        const userRoles = user.roles ?? [];
+        const hasRole = requiredRoles.some((role) => userRoles.includes(role));
+        if (!hasRole) {
+          return this.onForbidden(req, res);
+        }
+      }
+      next();
+    };
+  }
+  // ── Strategy Execution ──────────────────────────────────────────────
+  async authenticate(req, strategyName) {
+    const strategies = strategyName ? this.strategies.filter((s) => s.name === strategyName) : this.strategies;
+    for (const strategy of strategies) {
+      try {
+        const user = await strategy.validate(req);
+        if (user) return user;
+      } catch (err) {
+        log.debug(`Strategy ${strategy.name} failed: ${err.message}`);
+      }
+    }
+    return null;
+  }
+  // ── Metadata Resolution ─────────────────────────────────────────────
+  resolveHandler(req) {
+    const route = req.route;
+    if (!route) {
+      return {
+        controllerClass: void 0,
+        handlerName: void 0
+      };
+    }
+    for (const [mountPath, controllerClass] of this.routeControllers) {
+      if (req.baseUrl?.startsWith(mountPath) || req.path?.startsWith(mountPath)) {
+        const routes = Reflect.getMetadata(METADATA.ROUTES, controllerClass) ?? [];
+        const matched = routes.find((r) => r.method === req.method && this.pathMatches(r.path, req.route?.path ?? req.path));
+        if (matched) {
+          return {
+            controllerClass,
+            handlerName: matched.handlerName
+          };
+        }
+      }
+    }
+    return {
+      controllerClass: void 0,
+      handlerName: void 0
+    };
+  }
+  pathMatches(routePath, requestPath) {
+    const norm = /* @__PURE__ */ __name((p) => p.replace(/\/+$/, "") || "/", "norm");
+    return norm(routePath) === norm(requestPath);
+  }
+  isAuthRequired(controllerClass, handlerName) {
+    if (!controllerClass) {
+      return this.defaultPolicy === "protected";
+    }
+    if (handlerName) {
+      const isPublic = Reflect.getMetadata(AUTH_META.PUBLIC, controllerClass, handlerName);
+      if (isPublic) return false;
+      const methodAuth = Reflect.getMetadata(AUTH_META.AUTHENTICATED, controllerClass, handlerName);
+      if (methodAuth !== void 0) return methodAuth;
+    }
+    const classAuth = Reflect.getMetadata(AUTH_META.AUTHENTICATED, controllerClass);
+    if (classAuth !== void 0) return classAuth;
+    return this.defaultPolicy === "protected";
+  }
+  getRequiredRoles(controllerClass, handlerName) {
+    if (!controllerClass || !handlerName) return void 0;
+    return Reflect.getMetadata(AUTH_META.ROLES, controllerClass, handlerName);
+  }
+  getStrategyName(controllerClass, handlerName) {
+    if (!controllerClass) return void 0;
+    if (handlerName) {
+      const methodStrategy = Reflect.getMetadata(AUTH_META.STRATEGY, controllerClass, handlerName);
+      if (methodStrategy) return methodStrategy;
+    }
+    return Reflect.getMetadata(AUTH_META.STRATEGY, controllerClass);
+  }
+};
+
+// src/strategies/jwt.strategy.ts
+var JwtStrategy = class {
+  static {
+    __name(this, "JwtStrategy");
+  }
+  name = "jwt";
+  jwt;
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async ensureJwt() {
+    if (this.jwt) return;
+    try {
+      const mod = await import("jsonwebtoken");
+      this.jwt = mod.default ?? mod;
+    } catch {
+      throw new Error('JwtStrategy requires "jsonwebtoken" package. Install: pnpm add jsonwebtoken');
+    }
+  }
+  async validate(req) {
+    await this.ensureJwt();
+    const token = this.extractToken(req);
+    if (!token) return null;
+    try {
+      const payload = this.jwt.verify(token, this.options.secret, {
+        algorithms: this.options.algorithms ?? [
+          "HS256"
+        ]
+      });
+      return this.options.mapPayload ? this.options.mapPayload(payload) : payload;
+    } catch {
+      return null;
+    }
+  }
+  extractToken(req) {
+    const from = this.options.tokenFrom ?? "header";
+    if (from === "header") {
+      const headerName = this.options.headerName ?? "authorization";
+      const prefix = this.options.headerPrefix ?? "Bearer";
+      const header = req.headers?.[headerName] ?? req.headers?.[headerName.toLowerCase()];
+      if (!header || typeof header !== "string") return null;
+      if (!header.startsWith(`${prefix} `)) return null;
+      return header.slice(prefix.length + 1);
+    }
+    if (from === "query") {
+      const param = this.options.queryParam ?? "token";
+      return req.query?.[param] ?? null;
+    }
+    if (from === "cookie") {
+      const cookieName = this.options.cookieName ?? "jwt";
+      return req.cookies?.[cookieName] ?? null;
+    }
+    return null;
+  }
+};
+
+// src/strategies/api-key.strategy.ts
+var ApiKeyStrategy = class {
+  static {
+    __name(this, "ApiKeyStrategy");
+  }
+  name = "api-key";
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async validate(req) {
+    const key = this.extractKey(req);
+    if (!key) return null;
+    if (this.options.validate) {
+      return this.options.validate(key);
+    }
+    if (this.options.keys) {
+      const user = this.options.keys[key];
+      return user ?? null;
+    }
+    return null;
+  }
+  extractKey(req) {
+    const sources = this.options.from ?? [
+      "header"
+    ];
+    for (const source of sources) {
+      if (source === "header") {
+        const headerName = this.options.headerName ?? "x-api-key";
+        const value = req.headers?.[headerName] ?? req.headers?.[headerName.toLowerCase()];
+        if (value && typeof value === "string") return value;
+      }
+      if (source === "query") {
+        const param = this.options.queryParam ?? "api_key";
+        const value = req.query?.[param];
+        if (value && typeof value === "string") return value;
+      }
+    }
+    return null;
+  }
+};
+
+// src/strategies/oauth.strategy.ts
+import { Logger as Logger2 } from "@forinda/kickjs-core";
+var log2 = Logger2.for("OAuthStrategy");
+var PROVIDER_ENDPOINTS = {
+  google: {
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    userInfoUrl: "https://www.googleapis.com/oauth2/v2/userinfo",
+    scopes: [
+      "openid",
+      "email",
+      "profile"
+    ]
+  },
+  github: {
+    authorizeUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    userInfoUrl: "https://api.github.com/user",
+    scopes: [
+      "read:user",
+      "user:email"
+    ]
+  },
+  discord: {
+    authorizeUrl: "https://discord.com/api/oauth2/authorize",
+    tokenUrl: "https://discord.com/api/oauth2/token",
+    userInfoUrl: "https://discord.com/api/users/@me",
+    scopes: [
+      "identify",
+      "email"
+    ]
+  },
+  microsoft: {
+    authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    userInfoUrl: "https://graph.microsoft.com/v1.0/me",
+    scopes: [
+      "openid",
+      "email",
+      "profile"
+    ]
+  }
+};
+var OAuthStrategy = class {
+  static {
+    __name(this, "OAuthStrategy");
+  }
+  name;
+  options;
+  endpoints;
+  constructor(options) {
+    this.options = options;
+    this.name = `oauth-${options.provider}`;
+    if (options.provider === "custom") {
+      if (!options.endpoints) {
+        throw new Error('OAuthStrategy: "endpoints" required when provider is "custom"');
+      }
+      this.endpoints = options.endpoints;
+    } else {
+      this.endpoints = {
+        ...PROVIDER_ENDPOINTS[options.provider],
+        ...options.endpoints ?? {}
+      };
+    }
+    if (options.scopes) {
+      this.endpoints.scopes = options.scopes;
+    }
+  }
+  /**
+  * Get the authorization URL to redirect the user to the OAuth provider.
+  * Pass an optional `state` parameter for CSRF protection.
+  */
+  getAuthorizationUrl(state) {
+    const scopes = Array.isArray(this.endpoints.scopes) ? this.endpoints.scopes.join(" ") : this.endpoints.scopes ?? "";
+    const params = new URLSearchParams({
+      client_id: this.options.clientId,
+      redirect_uri: this.options.callbackUrl,
+      response_type: "code",
+      scope: scopes,
+      ...state ? {
+        state
+      } : {}
+    });
+    return `${this.endpoints.authorizeUrl}?${params.toString()}`;
+  }
+  /**
+  * Validate the callback request — exchange the authorization code for
+  * tokens and fetch the user profile.
+  */
+  async validate(req) {
+    const code = req.query?.code;
+    if (!code) return null;
+    try {
+      const tokens = await this.exchangeCode(code);
+      if (!tokens) return null;
+      const profile = await this.fetchUserInfo(tokens.accessToken);
+      if (!profile) return null;
+      if (this.options.mapProfile) {
+        return this.options.mapProfile(profile, tokens);
+      }
+      return profile;
+    } catch (err) {
+      log2.error({
+        err
+      }, `OAuth ${this.options.provider} callback failed`);
+      return null;
+    }
+  }
+  /** Exchange authorization code for access/refresh tokens */
+  async exchangeCode(code) {
+    const body = new URLSearchParams({
+      client_id: this.options.clientId,
+      client_secret: this.options.clientSecret,
+      code,
+      grant_type: "authorization_code",
+      redirect_uri: this.options.callbackUrl
+    });
+    const response = await fetch(this.endpoints.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    if (!response.ok) {
+      log2.error(`Token exchange failed: ${response.status} ${response.statusText}`);
+      return null;
+    }
+    const data = await response.json();
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      tokenType: data.token_type ?? "Bearer",
+      expiresIn: data.expires_in,
+      scope: data.scope
+    };
+  }
+  /** Fetch user profile from the provider's userinfo endpoint */
+  async fetchUserInfo(accessToken) {
+    const response = await fetch(this.endpoints.userInfoUrl, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json"
+      }
+    });
+    if (!response.ok) {
+      log2.error(`User info fetch failed: ${response.status} ${response.statusText}`);
+      return null;
+    }
+    return response.json();
+  }
+};
+
+// src/strategies/passport.bridge.ts
+var PassportBridge = class {
+  static {
+    __name(this, "PassportBridge");
+  }
+  name;
+  passportStrategy;
+  constructor(name, passportStrategy) {
+    this.name = name;
+    this.passportStrategy = passportStrategy;
+  }
+  validate(req) {
+    return new Promise((resolve) => {
+      const strategy = Object.create(this.passportStrategy);
+      strategy.success = (user) => resolve(user ?? null);
+      strategy.fail = () => resolve(null);
+      strategy.error = () => resolve(null);
+      strategy.pass = () => resolve(null);
+      strategy.redirect = () => resolve(null);
+      try {
+        strategy.authenticate(req, {});
+      } catch {
+        resolve(null);
+      }
+    });
+  }
+};
+export {
+  AUTH_META,
+  AUTH_USER,
+  ApiKeyStrategy,
+  AuthAdapter,
+  Authenticated,
+  JwtStrategy,
+  OAuthStrategy,
+  PassportBridge,
+  Public,
+  Roles
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/types.ts","../src/decorators.ts","../src/adapter.ts","../src/strategies/jwt.strategy.ts","../src/strategies/api-key.strategy.ts","../src/strategies/oauth.strategy.ts","../src/strategies/passport.bridge.ts"],"sourcesContent":["import 'reflect-metadata'\n\n// Types & interfaces\nexport { AUTH_META, type AuthUser, type AuthStrategy, type AuthAdapterOptions } from './types'\n\n// Decorators\nexport { Authenticated, Public, Roles } from './decorators'\n\n// Adapter\nexport { AuthAdapter, AUTH_USER } from './adapter'\n\n// Built-in strategies\nexport {\n  JwtStrategy,\n  ApiKeyStrategy,\n  OAuthStrategy,\n  PassportBridge,\n  type JwtStrategyOptions,\n  type ApiKeyStrategyOptions,\n  type ApiKeyUser,\n  type OAuthStrategyOptions,\n  type OAuthProvider,\n  type OAuthEndpoints,\n  type OAuthTokens,\n} from './strategies'\n","import 'reflect-metadata'\n\n// ── Auth Metadata Keys ──────────────────────────────────────────────────\n\nexport const AUTH_META = {\n  AUTHENTICATED: Symbol('auth:authenticated'),\n  PUBLIC: Symbol('auth:public'),\n  ROLES: Symbol('auth:roles'),\n  STRATEGY: Symbol('auth:strategy'),\n} as const\n\n// ── AuthUser ────────────────────────────────────────────────────────────\n\n/**\n * The authenticated user object attached to the request.\n * Extend this via module augmentation for your app's user shape.\n *\n * @example\n * ```ts\n * declare module '@forinda/kickjs-auth' {\n *   interface AuthUser {\n *     id: string\n *     email: string\n *     roles: string[]\n *   }\n * }\n * ```\n */\nexport interface AuthUser {\n  [key: string]: any\n}\n\n// ── AuthStrategy Interface ──────────────────────────────────────────────\n\n/**\n * Abstract authentication strategy. Implement this to support any\n * auth mechanism: JWT, API keys, OAuth, sessions, SAML, etc.\n *\n * @example\n * ```ts\n * class SessionStrategy implements AuthStrategy {\n *   name = 'session'\n *   async validate(req) {\n *     const session = req.session\n *     if (!session?.userId) return null\n *     return { id: session.userId, roles: session.roles }\n *   }\n * }\n * ```\n */\nexport interface AuthStrategy {\n  /** Unique name for this strategy (e.g., 'jwt', 'api-key', 'session') */\n  name: string\n\n  /**\n   * Extract and validate credentials from the request.\n   * Return the authenticated user, or null if authentication fails.\n   *\n   * @param req - Express request object\n   * @returns The authenticated user, or null\n   */\n  validate(req: any): Promise<AuthUser | null> | AuthUser | null\n}\n\n// ── AuthAdapter Options ─────────────────────────────────────────────────\n\nexport interface AuthAdapterOptions {\n  /**\n   * Authentication strategies to use, in order of precedence.\n   * The first strategy that returns a user wins.\n   *\n   * @example\n   * ```ts\n   * new AuthAdapter({\n   *   strategies: [\n   *     new JwtStrategy({ secret: process.env.JWT_SECRET! }),\n   *     new ApiKeyStrategy({ keys: { 'sk-123': { name: 'CI bot', roles: ['api'] } } }),\n   *   ],\n   * })\n   * ```\n   */\n  strategies: AuthStrategy[]\n\n  /**\n   * Default behavior for routes without @Authenticated or @Public.\n   * - `'protected'` — all routes require auth unless marked @Public (default)\n   * - `'open'` — all routes are public unless marked @Authenticated\n   */\n  defaultPolicy?: 'protected' | 'open'\n\n  /**\n   * Custom handler for unauthorized requests.\n   * Default: responds with 401 JSON error.\n   */\n  onUnauthorized?: (req: any, res: any) => void\n\n  /**\n   * Custom handler for forbidden requests (role mismatch).\n   * Default: responds with 403 JSON error.\n   */\n  onForbidden?: (req: any, res: any) => void\n}\n","import 'reflect-metadata'\nimport { AUTH_META } from './types'\n\n/**\n * Mark a controller or method as requiring authentication.\n * When applied to a controller, all methods require auth unless overridden with @Public.\n *\n * Optionally specify which strategy to use (defaults to trying all registered strategies).\n *\n * @example\n * ```ts\n * @Controller('/users')\n * @Authenticated()        // All routes require auth\n * class UserController {\n *   @Get('/')\n *   list(ctx) { ... }     // Protected\n *\n *   @Get('/public-count')\n *   @Public()              // Override: this route is open\n *   count(ctx) { ... }\n * }\n *\n * // Strategy-specific:\n * @Authenticated('api-key')\n * @Get('/webhook')\n * webhook(ctx) { ... }\n * ```\n */\nexport function Authenticated(strategy?: string): ClassDecorator & MethodDecorator {\n  return (target: any, propertyKey?: string | symbol) => {\n    if (propertyKey) {\n      Reflect.defineMetadata(AUTH_META.AUTHENTICATED, true, target.constructor, propertyKey)\n      if (strategy) {\n        Reflect.defineMetadata(AUTH_META.STRATEGY, strategy, target.constructor, propertyKey)\n      }\n    } else {\n      Reflect.defineMetadata(AUTH_META.AUTHENTICATED, true, target)\n      if (strategy) {\n        Reflect.defineMetadata(AUTH_META.STRATEGY, strategy, target)\n      }\n    }\n  }\n}\n\n/**\n * Mark a method as publicly accessible, bypassing authentication.\n * Use inside an @Authenticated controller to exempt specific routes.\n *\n * @example\n * ```ts\n * @Controller('/auth')\n * @Authenticated()\n * class AuthController {\n *   @Post('/login')\n *   @Public()              // No auth required\n *   login(ctx) { ... }\n *\n *   @Get('/me')            // Auth required (inherits from controller)\n *   me(ctx) { ... }\n * }\n * ```\n */\nexport function Public(): MethodDecorator {\n  return (target: any, propertyKey: string | symbol) => {\n    Reflect.defineMetadata(AUTH_META.PUBLIC, true, target.constructor, propertyKey)\n  }\n}\n\n/**\n * Require specific roles to access a route.\n * The authenticated user must have at least one of the specified roles.\n * Implies @Authenticated — no need to add both.\n *\n * The user object must have a `roles` property (string array).\n *\n * @example\n * ```ts\n * @Get('/admin/dashboard')\n * @Roles('admin', 'superadmin')\n * dashboard(ctx) { ... }\n *\n * @Delete('/:id')\n * @Roles('admin')\n * deleteUser(ctx) { ... }\n * ```\n */\nexport function Roles(...roles: string[]): MethodDecorator {\n  return (target: any, propertyKey: string | symbol) => {\n    Reflect.defineMetadata(AUTH_META.AUTHENTICATED, true, target.constructor, propertyKey)\n    Reflect.defineMetadata(AUTH_META.ROLES, roles, target.constructor, propertyKey)\n  }\n}\n","import 'reflect-metadata'\nimport {\n  Logger,\n  HttpStatus,\n  METADATA,\n  type AppAdapter,\n  type AdapterMiddleware,\n  type Container,\n  type RouteDefinition,\n} from '@forinda/kickjs-core'\n\nimport { AUTH_META, type AuthAdapterOptions, type AuthStrategy, type AuthUser } from './types'\n\nconst log = Logger.for('AuthAdapter')\n\n/** DI token to resolve the current authenticated user from the container */\nexport const AUTH_USER = Symbol('AuthUser')\n\n/**\n * Authentication adapter — plugs into the KickJS lifecycle to protect\n * routes based on @Authenticated, @Public, and @Roles decorators.\n *\n * Supports multiple strategies (JWT, API key, custom) with first-match semantics.\n *\n * @example\n * ```ts\n * import { AuthAdapter, JwtStrategy, ApiKeyStrategy } from '@forinda/kickjs-auth'\n *\n * bootstrap({\n *   modules: [...],\n *   adapters: [\n *     new AuthAdapter({\n *       strategies: [\n *         new JwtStrategy({ secret: process.env.JWT_SECRET! }),\n *         new ApiKeyStrategy({ keys: { 'sk-123': { name: 'Bot', roles: ['api'] } } }),\n *       ],\n *       defaultPolicy: 'protected', // secure by default\n *     }),\n *   ],\n * })\n * ```\n */\nexport class AuthAdapter implements AppAdapter {\n  name = 'AuthAdapter'\n  private strategies: AuthStrategy[]\n  private defaultPolicy: 'protected' | 'open'\n  private onUnauthorized: (req: any, res: any) => void\n  private onForbidden: (req: any, res: any) => void\n\n  // Collected route metadata for auth resolution\n  private routeControllers = new Map<string, any>()\n\n  constructor(private options: AuthAdapterOptions) {\n    this.strategies = options.strategies\n    this.defaultPolicy = options.defaultPolicy ?? 'protected'\n\n    this.onUnauthorized =\n      options.onUnauthorized ??\n      ((_req, res) => {\n        res.status(HttpStatus.UNAUTHORIZED).json({\n          statusCode: HttpStatus.UNAUTHORIZED,\n          error: 'Unauthorized',\n          message: 'Authentication required',\n        })\n      })\n\n    this.onForbidden =\n      options.onForbidden ??\n      ((_req, res) => {\n        res.status(HttpStatus.FORBIDDEN).json({\n          statusCode: HttpStatus.FORBIDDEN,\n          error: 'Forbidden',\n          message: 'Insufficient permissions',\n        })\n      })\n  }\n\n  onRouteMount(controllerClass: any, mountPath: string): void {\n    this.routeControllers.set(mountPath, controllerClass)\n  }\n\n  middleware(): AdapterMiddleware[] {\n    return [\n      {\n        handler: this.createAuthMiddleware(),\n        phase: 'beforeRoutes',\n      },\n    ]\n  }\n\n  beforeStart(app: any, _container: Container): void {\n    const strategyNames = this.strategies.map((s) => s.name).join(', ')\n    log.info(`Auth enabled [${strategyNames}] (default: ${this.defaultPolicy})`)\n  }\n\n  // ── Core Auth Middleware ─────────────────────────────────────────────\n\n  private createAuthMiddleware() {\n    return async (req: any, res: any, next: any) => {\n      // Find which controller + method handles this route\n      const { controllerClass, handlerName } = this.resolveHandler(req)\n\n      // Determine if this route needs auth\n      const authRequired = this.isAuthRequired(controllerClass, handlerName)\n      if (!authRequired) {\n        return next()\n      }\n\n      // Determine which strategy to use\n      const strategyName = this.getStrategyName(controllerClass, handlerName)\n\n      // Try to authenticate\n      const user = await this.authenticate(req, strategyName)\n      if (!user) {\n        return this.onUnauthorized(req, res)\n      }\n\n      // Attach user to request\n      req.user = user\n\n      // Check roles if required\n      const requiredRoles = this.getRequiredRoles(controllerClass, handlerName)\n      if (requiredRoles && requiredRoles.length > 0) {\n        const userRoles: string[] = (user as any).roles ?? []\n        const hasRole = requiredRoles.some((role) => userRoles.includes(role))\n        if (!hasRole) {\n          return this.onForbidden(req, res)\n        }\n      }\n\n      next()\n    }\n  }\n\n  // ── Strategy Execution ──────────────────────────────────────────────\n\n  private async authenticate(req: any, strategyName?: string): Promise<AuthUser | null> {\n    const strategies = strategyName\n      ? this.strategies.filter((s) => s.name === strategyName)\n      : this.strategies\n\n    for (const strategy of strategies) {\n      try {\n        const user = await strategy.validate(req)\n        if (user) return user\n      } catch (err: any) {\n        log.debug(`Strategy ${strategy.name} failed: ${err.message}`)\n      }\n    }\n\n    return null\n  }\n\n  // ── Metadata Resolution ─────────────────────────────────────────────\n\n  private resolveHandler(req: any): { controllerClass: any; handlerName: string | undefined } {\n    // Express 5 stores matched route info\n    const route = req.route\n    if (!route) {\n      return { controllerClass: undefined, handlerName: undefined }\n    }\n\n    // Try to find the controller from our collected route mounts\n    for (const [mountPath, controllerClass] of this.routeControllers) {\n      if (req.baseUrl?.startsWith(mountPath) || req.path?.startsWith(mountPath)) {\n        const routes: RouteDefinition[] =\n          Reflect.getMetadata(METADATA.ROUTES, controllerClass) ?? []\n        const matched = routes.find(\n          (r) => r.method === req.method && this.pathMatches(r.path, req.route?.path ?? req.path),\n        )\n        if (matched) {\n          return { controllerClass, handlerName: matched.handlerName }\n        }\n      }\n    }\n\n    return { controllerClass: undefined, handlerName: undefined }\n  }\n\n  private pathMatches(routePath: string, requestPath: string): boolean {\n    // Normalize trailing slashes and compare\n    const norm = (p: string) => p.replace(/\\/+$/, '') || '/'\n    return norm(routePath) === norm(requestPath)\n  }\n\n  private isAuthRequired(controllerClass: any, handlerName?: string): boolean {\n    if (!controllerClass) {\n      // No controller found — apply default policy\n      return this.defaultPolicy === 'protected'\n    }\n\n    // Method-level @Public always wins\n    if (handlerName) {\n      const isPublic = Reflect.getMetadata(AUTH_META.PUBLIC, controllerClass, handlerName)\n      if (isPublic) return false\n\n      // Method-level @Authenticated\n      const methodAuth = Reflect.getMetadata(AUTH_META.AUTHENTICATED, controllerClass, handlerName)\n      if (methodAuth !== undefined) return methodAuth\n    }\n\n    // Class-level @Authenticated\n    const classAuth = Reflect.getMetadata(AUTH_META.AUTHENTICATED, controllerClass)\n    if (classAuth !== undefined) return classAuth\n\n    // Default policy\n    return this.defaultPolicy === 'protected'\n  }\n\n  private getRequiredRoles(controllerClass: any, handlerName?: string): string[] | undefined {\n    if (!controllerClass || !handlerName) return undefined\n    return Reflect.getMetadata(AUTH_META.ROLES, controllerClass, handlerName)\n  }\n\n  private getStrategyName(controllerClass: any, handlerName?: string): string | undefined {\n    if (!controllerClass) return undefined\n\n    // Method-level strategy\n    if (handlerName) {\n      const methodStrategy = Reflect.getMetadata(AUTH_META.STRATEGY, controllerClass, handlerName)\n      if (methodStrategy) return methodStrategy\n    }\n\n    // Class-level strategy\n    return Reflect.getMetadata(AUTH_META.STRATEGY, controllerClass)\n  }\n}\n","import type { AuthStrategy, AuthUser } from '../types'\n\nexport interface JwtStrategyOptions {\n  /** JWT secret key for HS256 or public key for RS256 */\n  secret: string | Buffer\n\n  /**\n   * Algorithm (default: 'HS256').\n   * Common values: 'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512'\n   */\n  algorithms?: string[]\n\n  /** Where to read the token from (default: 'header') */\n  tokenFrom?: 'header' | 'query' | 'cookie'\n\n  /** Header name (default: 'authorization') */\n  headerName?: string\n\n  /** Query parameter name when tokenFrom='query' (default: 'token') */\n  queryParam?: string\n\n  /** Cookie name when tokenFrom='cookie' (default: 'jwt') */\n  cookieName?: string\n\n  /** Token prefix in header (default: 'Bearer') */\n  headerPrefix?: string\n\n  /**\n   * Transform the decoded JWT payload into your AuthUser shape.\n   * By default, returns the payload as-is.\n   *\n   * @example\n   * ```ts\n   * mapPayload: (payload) => ({\n   *   id: payload.sub,\n   *   email: payload.email,\n   *   roles: payload.roles || [],\n   * })\n   * ```\n   */\n  mapPayload?: (payload: any) => AuthUser\n}\n\n/**\n * JWT authentication strategy.\n * Validates Bearer tokens using `jsonwebtoken`.\n *\n * Requires `jsonwebtoken` as a peer dependency:\n * ```bash\n * pnpm add jsonwebtoken @types/jsonwebtoken\n * ```\n *\n * @example\n * ```ts\n * new JwtStrategy({\n *   secret: process.env.JWT_SECRET!,\n *   mapPayload: (payload) => ({\n *     id: payload.sub,\n *     email: payload.email,\n *     roles: payload.roles ?? ['user'],\n *   }),\n * })\n * ```\n */\nexport class JwtStrategy implements AuthStrategy {\n  name = 'jwt'\n  private jwt: any\n  private options: JwtStrategyOptions\n\n  constructor(options: JwtStrategyOptions) {\n    this.options = options\n  }\n\n  private async ensureJwt(): Promise<void> {\n    if (this.jwt) return\n    try {\n      const mod: any = await import('jsonwebtoken')\n      this.jwt = mod.default ?? mod\n    } catch {\n      throw new Error('JwtStrategy requires \"jsonwebtoken\" package. Install: pnpm add jsonwebtoken')\n    }\n  }\n\n  async validate(req: any): Promise<AuthUser | null> {\n    await this.ensureJwt()\n\n    const token = this.extractToken(req)\n    if (!token) return null\n\n    try {\n      const payload = this.jwt.verify(token, this.options.secret, {\n        algorithms: this.options.algorithms ?? ['HS256'],\n      })\n\n      return this.options.mapPayload ? this.options.mapPayload(payload) : payload\n    } catch {\n      return null\n    }\n  }\n\n  private extractToken(req: any): string | null {\n    const from = this.options.tokenFrom ?? 'header'\n\n    if (from === 'header') {\n      const headerName = this.options.headerName ?? 'authorization'\n      const prefix = this.options.headerPrefix ?? 'Bearer'\n      const header = req.headers?.[headerName] ?? req.headers?.[headerName.toLowerCase()]\n      if (!header || typeof header !== 'string') return null\n      if (!header.startsWith(`${prefix} `)) return null\n      return header.slice(prefix.length + 1)\n    }\n\n    if (from === 'query') {\n      const param = this.options.queryParam ?? 'token'\n      return req.query?.[param] ?? null\n    }\n\n    if (from === 'cookie') {\n      const cookieName = this.options.cookieName ?? 'jwt'\n      return req.cookies?.[cookieName] ?? null\n    }\n\n    return null\n  }\n}\n","import type { AuthStrategy, AuthUser } from '../types'\n\nexport interface ApiKeyUser {\n  /** Display name for the API key holder */\n  name: string\n  /** Roles granted to this API key */\n  roles?: string[]\n  /** Additional metadata */\n  [key: string]: any\n}\n\nexport interface ApiKeyStrategyOptions {\n  /**\n   * Map of API keys to their associated users.\n   * Keys are the raw API key strings.\n   *\n   * @example\n   * ```ts\n   * keys: {\n   *   'sk-live-abc123': { name: 'Production Bot', roles: ['api', 'write'] },\n   *   'sk-test-xyz789': { name: 'Test Runner', roles: ['api'] },\n   * }\n   * ```\n   */\n  keys?: Record<string, ApiKeyUser>\n\n  /**\n   * Async function to validate an API key.\n   * Use when keys are stored in a database or external service.\n   * Takes precedence over the static `keys` map.\n   *\n   * @example\n   * ```ts\n   * validate: async (key) => {\n   *   const row = await db.apiKeys.findUnique({ where: { key } })\n   *   if (!row || row.revokedAt) return null\n   *   return { name: row.name, roles: row.roles }\n   * }\n   * ```\n   */\n  validate?: (key: string) => Promise<AuthUser | null> | AuthUser | null\n\n  /**\n   * Where to read the API key from (default: 'header').\n   * Checks all specified locations in order.\n   */\n  from?: Array<'header' | 'query'>\n\n  /** Header name (default: 'x-api-key') */\n  headerName?: string\n\n  /** Query parameter name (default: 'api_key') */\n  queryParam?: string\n}\n\n/**\n * API key authentication strategy.\n * Validates keys from headers or query parameters against a static map\n * or async validator function.\n *\n * @example\n * ```ts\n * // Static keys\n * new ApiKeyStrategy({\n *   keys: {\n *     'sk-prod-123': { name: 'CI Bot', roles: ['api'] },\n *   },\n * })\n *\n * // Database lookup\n * new ApiKeyStrategy({\n *   validate: async (key) => {\n *     const record = await db.apiKeys.findByKey(key)\n *     return record ? { name: record.name, roles: record.roles } : null\n *   },\n * })\n * ```\n */\nexport class ApiKeyStrategy implements AuthStrategy {\n  name = 'api-key'\n  private options: ApiKeyStrategyOptions\n\n  constructor(options: ApiKeyStrategyOptions) {\n    this.options = options\n  }\n\n  async validate(req: any): Promise<AuthUser | null> {\n    const key = this.extractKey(req)\n    if (!key) return null\n\n    // Async validator takes precedence\n    if (this.options.validate) {\n      return this.options.validate(key)\n    }\n\n    // Static key lookup\n    if (this.options.keys) {\n      const user = this.options.keys[key]\n      return user ?? null\n    }\n\n    return null\n  }\n\n  private extractKey(req: any): string | null {\n    const sources = this.options.from ?? ['header']\n\n    for (const source of sources) {\n      if (source === 'header') {\n        const headerName = this.options.headerName ?? 'x-api-key'\n        const value = req.headers?.[headerName] ?? req.headers?.[headerName.toLowerCase()]\n        if (value && typeof value === 'string') return value\n      }\n\n      if (source === 'query') {\n        const param = this.options.queryParam ?? 'api_key'\n        const value = req.query?.[param]\n        if (value && typeof value === 'string') return value\n      }\n    }\n\n    return null\n  }\n}\n","import { Logger } from '@forinda/kickjs-core'\nimport type { AuthStrategy, AuthUser } from '../types'\n\nconst log = Logger.for('OAuthStrategy')\n\n/** Supported OAuth providers with pre-configured endpoints */\nexport type OAuthProvider = 'google' | 'github' | 'discord' | 'microsoft' | 'custom'\n\n/** Provider-specific endpoint configuration */\nexport interface OAuthEndpoints {\n  authorizeUrl: string\n  tokenUrl: string\n  userInfoUrl: string\n  /** Scopes to request (space-separated or array) */\n  scopes?: string[] | string\n}\n\n/** Pre-configured OAuth provider endpoints */\nconst PROVIDER_ENDPOINTS: Record<Exclude<OAuthProvider, 'custom'>, OAuthEndpoints> = {\n  google: {\n    authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',\n    tokenUrl: 'https://oauth2.googleapis.com/token',\n    userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',\n    scopes: ['openid', 'email', 'profile'],\n  },\n  github: {\n    authorizeUrl: 'https://github.com/login/oauth/authorize',\n    tokenUrl: 'https://github.com/login/oauth/access_token',\n    userInfoUrl: 'https://api.github.com/user',\n    scopes: ['read:user', 'user:email'],\n  },\n  discord: {\n    authorizeUrl: 'https://discord.com/api/oauth2/authorize',\n    tokenUrl: 'https://discord.com/api/oauth2/token',\n    userInfoUrl: 'https://discord.com/api/users/@me',\n    scopes: ['identify', 'email'],\n  },\n  microsoft: {\n    authorizeUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',\n    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',\n    userInfoUrl: 'https://graph.microsoft.com/v1.0/me',\n    scopes: ['openid', 'email', 'profile'],\n  },\n}\n\nexport interface OAuthStrategyOptions {\n  /** OAuth provider preset or 'custom' for manual endpoint config */\n  provider: OAuthProvider\n\n  /** OAuth client ID */\n  clientId: string\n\n  /** OAuth client secret */\n  clientSecret: string\n\n  /** Callback URL for the OAuth flow (e.g. 'http://localhost:3000/auth/google/callback') */\n  callbackUrl: string\n\n  /** Custom endpoints (required when provider is 'custom') */\n  endpoints?: OAuthEndpoints\n\n  /** Override default scopes for the provider */\n  scopes?: string[]\n\n  /**\n   * Transform the provider's user profile into your AuthUser.\n   * Called after successfully exchanging the code for a token and fetching user info.\n   *\n   * @example\n   * ```ts\n   * mapProfile: (profile) => ({\n   *   id: profile.id,\n   *   email: profile.email,\n   *   name: profile.name,\n   *   avatar: profile.picture,\n   *   roles: ['user'],\n   * })\n   * ```\n   */\n  mapProfile?: (profile: any, tokens: OAuthTokens) => AuthUser | Promise<AuthUser>\n}\n\nexport interface OAuthTokens {\n  accessToken: string\n  refreshToken?: string\n  tokenType: string\n  expiresIn?: number\n  scope?: string\n}\n\n/**\n * Built-in OAuth 2.0 strategy with pre-configured providers.\n * No Passport dependency — KickJS handles the entire OAuth flow.\n *\n * Supports: Google, GitHub, Discord, Microsoft, or any custom OAuth 2.0 provider.\n *\n * This strategy validates the callback request (the one with `?code=...`),\n * exchanges the code for tokens, fetches the user profile, and returns it.\n *\n * You need two routes:\n * 1. **Redirect** — sends user to provider's login page\n * 2. **Callback** — receives the code and authenticates\n *\n * @example\n * ```ts\n * import { OAuthStrategy } from '@forinda/kickjs-auth'\n *\n * const googleAuth = new OAuthStrategy({\n *   provider: 'google',\n *   clientId: process.env.GOOGLE_CLIENT_ID!,\n *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,\n *   callbackUrl: 'http://localhost:3000/auth/google/callback',\n *   mapProfile: (profile) => ({\n *     id: profile.id,\n *     email: profile.email,\n *     name: profile.name,\n *     avatar: profile.picture,\n *     roles: ['user'],\n *   }),\n * })\n *\n * // In your controller:\n * @Get('/auth/google')\n * @Public()\n * loginWithGoogle(ctx: RequestContext) {\n *   return ctx.res.redirect(googleAuth.getAuthorizationUrl())\n * }\n *\n * @Get('/auth/google/callback')\n * @Public()\n * async googleCallback(ctx: RequestContext) {\n *   const user = await googleAuth.validate(ctx.req)\n *   if (!user) return ctx.res.status(401).json({ error: 'Auth failed' })\n *   const token = issueJwt(user)\n *   return ctx.json({ token, user })\n * }\n * ```\n */\nexport class OAuthStrategy implements AuthStrategy {\n  name: string\n  private options: OAuthStrategyOptions\n  private endpoints: OAuthEndpoints\n\n  constructor(options: OAuthStrategyOptions) {\n    this.options = options\n    this.name = `oauth-${options.provider}`\n\n    if (options.provider === 'custom') {\n      if (!options.endpoints) {\n        throw new Error('OAuthStrategy: \"endpoints\" required when provider is \"custom\"')\n      }\n      this.endpoints = options.endpoints\n    } else {\n      this.endpoints = {\n        ...PROVIDER_ENDPOINTS[options.provider],\n        ...(options.endpoints ?? {}),\n      }\n    }\n\n    // Override scopes if provided\n    if (options.scopes) {\n      this.endpoints.scopes = options.scopes\n    }\n  }\n\n  /**\n   * Get the authorization URL to redirect the user to the OAuth provider.\n   * Pass an optional `state` parameter for CSRF protection.\n   */\n  getAuthorizationUrl(state?: string): string {\n    const scopes = Array.isArray(this.endpoints.scopes)\n      ? this.endpoints.scopes.join(' ')\n      : (this.endpoints.scopes ?? '')\n\n    const params = new URLSearchParams({\n      client_id: this.options.clientId,\n      redirect_uri: this.options.callbackUrl,\n      response_type: 'code',\n      scope: scopes,\n      ...(state ? { state } : {}),\n    })\n\n    return `${this.endpoints.authorizeUrl}?${params.toString()}`\n  }\n\n  /**\n   * Validate the callback request — exchange the authorization code for\n   * tokens and fetch the user profile.\n   */\n  async validate(req: any): Promise<AuthUser | null> {\n    const code = req.query?.code\n    if (!code) return null\n\n    try {\n      // Exchange code for tokens\n      const tokens = await this.exchangeCode(code)\n      if (!tokens) return null\n\n      // Fetch user profile\n      const profile = await this.fetchUserInfo(tokens.accessToken)\n      if (!profile) return null\n\n      // Map profile to AuthUser\n      if (this.options.mapProfile) {\n        return this.options.mapProfile(profile, tokens)\n      }\n\n      return profile\n    } catch (err: any) {\n      log.error({ err }, `OAuth ${this.options.provider} callback failed`)\n      return null\n    }\n  }\n\n  /** Exchange authorization code for access/refresh tokens */\n  private async exchangeCode(code: string): Promise<OAuthTokens | null> {\n    const body = new URLSearchParams({\n      client_id: this.options.clientId,\n      client_secret: this.options.clientSecret,\n      code,\n      grant_type: 'authorization_code',\n      redirect_uri: this.options.callbackUrl,\n    })\n\n    const response = await fetch(this.endpoints.tokenUrl, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/x-www-form-urlencoded',\n        Accept: 'application/json',\n      },\n      body: body.toString(),\n    })\n\n    if (!response.ok) {\n      log.error(`Token exchange failed: ${response.status} ${response.statusText}`)\n      return null\n    }\n\n    const data: any = await response.json()\n\n    return {\n      accessToken: data.access_token,\n      refreshToken: data.refresh_token,\n      tokenType: data.token_type ?? 'Bearer',\n      expiresIn: data.expires_in,\n      scope: data.scope,\n    }\n  }\n\n  /** Fetch user profile from the provider's userinfo endpoint */\n  private async fetchUserInfo(accessToken: string): Promise<any | null> {\n    const response = await fetch(this.endpoints.userInfoUrl, {\n      headers: {\n        Authorization: `Bearer ${accessToken}`,\n        Accept: 'application/json',\n      },\n    })\n\n    if (!response.ok) {\n      log.error(`User info fetch failed: ${response.status} ${response.statusText}`)\n      return null\n    }\n\n    return response.json()\n  }\n}\n","import type { AuthStrategy, AuthUser } from '../types'\n\n/**\n * Bridge that wraps any Passport.js strategy into a KickJS AuthStrategy.\n * This lets you use the full Passport ecosystem (500+ strategies) without\n * changing your KickJS auth setup.\n *\n * Requires `passport` as a dependency in your project:\n * ```bash\n * pnpm add passport\n * ```\n *\n * @example\n * ```ts\n * import { Strategy as GoogleStrategy } from 'passport-google-oauth20'\n * import { PassportBridge } from '@forinda/kickjs-auth'\n *\n * const google = new PassportBridge('google', new GoogleStrategy({\n *   clientID: process.env.GOOGLE_CLIENT_ID!,\n *   clientSecret: process.env.GOOGLE_CLIENT_SECRET!,\n *   callbackURL: '/auth/google/callback',\n * }, (accessToken, refreshToken, profile, done) => {\n *   // Find or create user from profile\n *   const user = await findOrCreateUser(profile)\n *   done(null, user)\n * }))\n *\n * new AuthAdapter({\n *   strategies: [jwtStrategy, google],\n * })\n * ```\n */\nexport class PassportBridge implements AuthStrategy {\n  name: string\n  private passportStrategy: any\n\n  constructor(name: string, passportStrategy: any) {\n    this.name = name\n    this.passportStrategy = passportStrategy\n  }\n\n  validate(req: any): Promise<AuthUser | null> {\n    return new Promise((resolve) => {\n      // Passport strategies call done(err, user, info)\n      // We wrap the authenticate flow manually without needing passport.initialize()\n      const strategy = Object.create(this.passportStrategy)\n\n      strategy.success = (user: any) => resolve(user ?? null)\n      strategy.fail = () => resolve(null)\n      strategy.error = () => resolve(null)\n      strategy.pass = () => resolve(null)\n      strategy.redirect = () => resolve(null)\n\n      try {\n        strategy.authenticate(req, {})\n      } catch {\n        resolve(null)\n      }\n    })\n  }\n}\n"],"mappings":"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","names":["AUTH_META","AUTHENTICATED","Symbol","PUBLIC","ROLES","STRATEGY","Authenticated","strategy","target","propertyKey","Reflect","defineMetadata","AUTH_META","AUTHENTICATED","STRATEGY","Public","PUBLIC","Roles","roles","ROLES","Logger","HttpStatus","METADATA","log","Logger","for","AUTH_USER","Symbol","AuthAdapter","name","strategies","defaultPolicy","onUnauthorized","onForbidden","routeControllers","Map","options","_req","res","status","HttpStatus","UNAUTHORIZED","json","statusCode","error","message","FORBIDDEN","onRouteMount","controllerClass","mountPath","set","middleware","handler","createAuthMiddleware","phase","beforeStart","app","_container","strategyNames","map","s","join","info","req","next","handlerName","resolveHandler","authRequired","isAuthRequired","strategyName","getStrategyName","user","authenticate","requiredRoles","getRequiredRoles","length","userRoles","roles","hasRole","some","role","includes","filter","strategy","validate","err","debug","route","undefined","baseUrl","startsWith","path","routes","Reflect","getMetadata","METADATA","ROUTES","matched","find","r","method","pathMatches","routePath","requestPath","norm","p","replace","isPublic","AUTH_META","PUBLIC","methodAuth","AUTHENTICATED","classAuth","ROLES","methodStrategy","STRATEGY","JwtStrategy","name","jwt","options","ensureJwt","mod","default","Error","validate","req","token","extractToken","payload","verify","secret","algorithms","mapPayload","from","tokenFrom","headerName","prefix","headerPrefix","header","headers","toLowerCase","startsWith","slice","length","param","queryParam","query","cookieName","cookies","ApiKeyStrategy","name","options","validate","req","key","extractKey","keys","user","sources","from","source","headerName","value","headers","toLowerCase","param","queryParam","query","Logger","log","Logger","for","PROVIDER_ENDPOINTS","google","authorizeUrl","tokenUrl","userInfoUrl","scopes","github","discord","microsoft","OAuthStrategy","name","options","endpoints","provider","Error","getAuthorizationUrl","state","Array","isArray","join","params","URLSearchParams","client_id","clientId","redirect_uri","callbackUrl","response_type","scope","toString","validate","req","code","query","tokens","exchangeCode","profile","fetchUserInfo","accessToken","mapProfile","err","error","body","client_secret","clientSecret","grant_type","response","fetch","method","headers","Accept","ok","status","statusText","data","json","access_token","refreshToken","refresh_token","tokenType","token_type","expiresIn","expires_in","Authorization","PassportBridge","name","passportStrategy","validate","req","Promise","resolve","strategy","Object","create","success","user","fail","error","pass","redirect","authenticate"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@forinda/kickjs-auth",
+  "version": "1.1.0",
+  "description": "Pluggable authentication for KickJS — JWT, API key, and custom strategies",
+  "keywords": [
+    "kickjs",
+    "auth",
+    "authentication",
+    "jwt",
+    "api-key",
+    "guard",
+    "middleware",
+    "typescript",
+    "decorators",
+    "strategy-pattern"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs-core": "1.1.0"
+  },
+  "peerDependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jsonwebtoken": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/node": "^24.5.2",
+    "jsonwebtoken": "^9.0.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}