@geekmidas/auth 0.0.3 → 0.0.5

package/src/jwt.ts

@@ -0,0 +1,106 @@
+import * as jose from 'jose';
+
+/**
+ * Standard JWT claims
+ */
+export interface JwtClaims {
+  sub?: string;
+  iss?: string;
+  aud?: string | string[];
+  exp?: number;
+  iat?: number;
+  nbf?: number;
+  jti?: string;
+}
+
+/**
+ * Configuration for JWT verification with a symmetric secret
+ */
+export interface JwtSecretConfig {
+  secret: string;
+  issuer?: string;
+  audience?: string | string[];
+  algorithms?: string[];
+}
+
+/**
+ * Configuration for JWT verification with JWKS
+ */
+export interface JwtJwksConfig {
+  jwksUri: string;
+  issuer?: string;
+  audience?: string | string[];
+  algorithms?: string[];
+}
+
+export type JwtConfig = JwtSecretConfig | JwtJwksConfig;
+
+/**
+ * Options for token extraction from requests
+ */
+export interface TokenExtractionOptions {
+  headerName?: string;
+  cookieName?: string;
+  tokenPrefix?: string;
+}
+
+export function isJwksConfig(config: JwtConfig): config is JwtJwksConfig {
+  return 'jwksUri' in config;
+}
+
+/**
+ * JWT Verifier with JWKS caching
+ */
+export class JwtVerifier<TClaims extends JwtClaims = JwtClaims> {
+  private jwks: jose.JWTVerifyGetKey | null = null;
+  private readonly verifyOptions: jose.JWTVerifyOptions;
+
+  constructor(private readonly config: JwtConfig) {
+    this.verifyOptions = {
+      issuer: config.issuer,
+      audience: config.audience,
+      algorithms:
+        config.algorithms ?? (isJwksConfig(config) ? undefined : ['HS256']),
+    };
+  }
+
+  async verify(token: string): Promise<TClaims> {
+    if (isJwksConfig(this.config)) {
+      if (!this.jwks) {
+        this.jwks = jose.createRemoteJWKSet(new URL(this.config.jwksUri));
+      }
+      const { payload } = await jose.jwtVerify(
+        token,
+        this.jwks,
+        this.verifyOptions,
+      );
+      return payload as unknown as TClaims;
+    }
+
+    const secret = new TextEncoder().encode(this.config.secret);
+    const { payload } = await jose.jwtVerify(token, secret, this.verifyOptions);
+    return payload as unknown as TClaims;
+  }
+
+  async verifyOrNull(token: string): Promise<TClaims | null> {
+    try {
+      return await this.verify(token);
+    } catch {
+      return null;
+    }
+  }
+
+  clearCache(): void {
+    this.jwks = null;
+  }
+}
+
+/**
+ * Decode a JWT without verification
+ * WARNING: This does NOT verify the token signature!
+ */
+export function decodeJwt<TClaims extends JwtClaims = JwtClaims>(
+  token: string,
+): TClaims {
+  return jose.decodeJwt(token) as unknown as TClaims;
+}

package/src/lambda/jwt.ts

@@ -0,0 +1,210 @@
+import type {
+  APIGatewayAuthorizerResult,
+  APIGatewayRequestAuthorizerEvent,
+  APIGatewayTokenAuthorizerEvent,
+  Context as LambdaContext,
+  PolicyDocument,
+} from 'aws-lambda';
+import {
+  type JwtClaims,
+  type JwtConfig,
+  JwtVerifier,
+  type TokenExtractionOptions,
+} from '../jwt';
+
+export {
+  JwtVerifier,
+  type JwtClaims,
+  type JwtConfig,
+  type TokenExtractionOptions,
+};
+
+function generatePolicy(
+  principalId: string,
+  effect: 'Allow' | 'Deny',
+  resource: string,
+  context?: Record<string, string | number | boolean>,
+): APIGatewayAuthorizerResult {
+  const policyDocument: PolicyDocument = {
+    Version: '2012-10-17',
+    Statement: [
+      {
+        Action: 'execute-api:Invoke',
+        Effect: effect,
+        Resource: resource,
+      },
+    ],
+  };
+
+  return {
+    principalId,
+    policyDocument,
+    context,
+  };
+}
+
+function getWildcardResource(methodArn: string): string {
+  const parts = methodArn.split('/');
+  return `${parts[0]}/${parts[1]}/*`;
+}
+
+export interface JwtAuthorizerOptions<TClaims extends JwtClaims = JwtClaims> {
+  config: JwtConfig;
+  extraction?: TokenExtractionOptions;
+  wildcardResource?: boolean;
+  getPrincipalId?: (claims: TClaims) => string;
+  getContext?: (
+    claims: TClaims,
+  ) => Record<string, string | number | boolean> | undefined;
+  authorize?: (claims: TClaims) => boolean | Promise<boolean>;
+}
+
+/**
+ * JWT Lambda Authorizer
+ *
+ * @example
+ * ```typescript
+ * const authorizer = new JwtAuthorizer({
+ *   config: {
+ *     jwksUri: 'https://auth.example.com/.well-known/jwks.json',
+ *     issuer: 'https://auth.example.com',
+ *   },
+ *   getContext: (claims) => ({ userId: claims.sub! }),
+ * });
+ *
+ * // TOKEN authorizer
+ * export const tokenHandler = authorizer.tokenHandler();
+ *
+ * // REQUEST authorizer
+ * export const requestHandler = authorizer.requestHandler();
+ * ```
+ */
+export class JwtAuthorizer<TClaims extends JwtClaims = JwtClaims> {
+  private readonly verifier: JwtVerifier<TClaims>;
+  private readonly extraction: TokenExtractionOptions;
+  private readonly wildcardResource: boolean;
+  private readonly getPrincipalId: (claims: TClaims) => string;
+  private readonly getContext?: (
+    claims: TClaims,
+  ) => Record<string, string | number | boolean> | undefined;
+  private readonly authorize?: (claims: TClaims) => boolean | Promise<boolean>;
+
+  constructor(options: JwtAuthorizerOptions<TClaims>) {
+    this.verifier = new JwtVerifier(options.config);
+    this.extraction = options.extraction ?? {};
+    this.wildcardResource = options.wildcardResource ?? true;
+    this.getPrincipalId = options.getPrincipalId ?? ((c) => c.sub ?? 'unknown');
+    this.getContext = options.getContext;
+    this.authorize = options.authorize;
+  }
+
+  /**
+   * Returns a TOKEN authorizer handler
+   */
+  tokenHandler() {
+    return async (
+      event: APIGatewayTokenAuthorizerEvent,
+      _context: LambdaContext,
+    ): Promise<APIGatewayAuthorizerResult> => {
+      const { authorizationToken, methodArn } = event;
+      const resource = this.wildcardResource
+        ? getWildcardResource(methodArn)
+        : methodArn;
+
+      const token = authorizationToken.startsWith('Bearer ')
+        ? authorizationToken.slice(7)
+        : authorizationToken;
+
+      try {
+        const claims = await this.verifier.verify(token);
+
+        if (this.authorize) {
+          const isAuthorized = await this.authorize(claims);
+          if (!isAuthorized) {
+            return generatePolicy('unauthorized', 'Deny', resource);
+          }
+        }
+
+        const principalId = this.getPrincipalId(claims);
+        const context = this.getContext?.(claims);
+
+        return generatePolicy(principalId, 'Allow', resource, context);
+      } catch {
+        return generatePolicy('unauthorized', 'Deny', resource);
+      }
+    };
+  }
+
+  /**
+   * Returns a REQUEST authorizer handler
+   */
+  requestHandler() {
+    const {
+      headerName = 'authorization',
+      cookieName,
+      tokenPrefix = 'Bearer ',
+    } = this.extraction;
+
+    const extractToken = (
+      event: APIGatewayRequestAuthorizerEvent,
+    ): string | null => {
+      const headers = event.headers ?? {};
+      const headerKey = Object.keys(headers).find(
+        (k) => k.toLowerCase() === headerName.toLowerCase(),
+      );
+      if (headerKey) {
+        const headerValue = headers[headerKey];
+        if (headerValue) {
+          if (tokenPrefix && headerValue.startsWith(tokenPrefix)) {
+            return headerValue.slice(tokenPrefix.length);
+          }
+          return headerValue;
+        }
+      }
+
+      if (cookieName) {
+        const cookieHeader = headers['cookie'] ?? headers['Cookie'] ?? '';
+        const match = cookieHeader.match(new RegExp(`${cookieName}=([^;]+)`));
+        if (match) {
+          return match[1];
+        }
+      }
+
+      return null;
+    };
+
+    return async (
+      event: APIGatewayRequestAuthorizerEvent,
+      _context: LambdaContext,
+    ): Promise<APIGatewayAuthorizerResult> => {
+      const methodArn = event.methodArn;
+      const resource = this.wildcardResource
+        ? getWildcardResource(methodArn)
+        : methodArn;
+
+      const token = extractToken(event);
+
+      if (!token) {
+        return generatePolicy('unauthorized', 'Deny', resource);
+      }
+
+      try {
+        const claims = await this.verifier.verify(token);
+
+        if (this.authorize) {
+          const isAuthorized = await this.authorize(claims);
+          if (!isAuthorized) {
+            return generatePolicy('unauthorized', 'Deny', resource);
+          }
+        }
+
+        const principalId = this.getPrincipalId(claims);
+        const context = this.getContext?.(claims);
+
+        return generatePolicy(principalId, 'Allow', resource, context);
+      } catch {
+        return generatePolicy('unauthorized', 'Deny', resource);
+      }
+    };
+  }
+}

package/src/lambda/oidc.ts

@@ -0,0 +1,203 @@
+import type {
+  APIGatewayAuthorizerResult,
+  APIGatewayRequestAuthorizerEvent,
+  APIGatewayTokenAuthorizerEvent,
+  Context as LambdaContext,
+  PolicyDocument,
+} from 'aws-lambda';
+import {
+  type OidcClaims,
+  type OidcConfig,
+  OidcVerifier,
+  type TokenExtractionOptions,
+} from '../oidc';
+
+export {
+  OidcVerifier,
+  type OidcClaims,
+  type OidcConfig,
+  type TokenExtractionOptions,
+};
+
+function generatePolicy(
+  principalId: string,
+  effect: 'Allow' | 'Deny',
+  resource: string,
+  context?: Record<string, string | number | boolean>,
+): APIGatewayAuthorizerResult {
+  const policyDocument: PolicyDocument = {
+    Version: '2012-10-17',
+    Statement: [
+      {
+        Action: 'execute-api:Invoke',
+        Effect: effect,
+        Resource: resource,
+      },
+    ],
+  };
+
+  return {
+    principalId,
+    policyDocument,
+    context,
+  };
+}
+
+function getWildcardResource(methodArn: string): string {
+  const parts = methodArn.split('/');
+  return `${parts[0]}/${parts[1]}/*`;
+}
+
+export interface OidcAuthorizerOptions<
+  TClaims extends OidcClaims = OidcClaims,
+> {
+  config: OidcConfig;
+  extraction?: TokenExtractionOptions;
+  wildcardResource?: boolean;
+  getPrincipalId?: (claims: TClaims) => string;
+  getContext?: (
+    claims: TClaims,
+  ) => Record<string, string | number | boolean> | undefined;
+  authorize?: (claims: TClaims) => boolean | Promise<boolean>;
+}
+
+/**
+ * OIDC Lambda Authorizer
+ *
+ * @example
+ * ```typescript
+ * const authorizer = new OidcAuthorizer({
+ *   config: {
+ *     issuer: 'https://auth.example.com',
+ *     audience: 'my-api',
+ *   },
+ *   getContext: (claims) => ({ userId: claims.sub! }),
+ * });
+ *
+ * export const tokenHandler = authorizer.tokenHandler();
+ * export const requestHandler = authorizer.requestHandler();
+ * ```
+ */
+export class OidcAuthorizer<TClaims extends OidcClaims = OidcClaims> {
+  private readonly verifier: OidcVerifier<TClaims>;
+  private readonly extraction: TokenExtractionOptions;
+  private readonly wildcardResource: boolean;
+  private readonly getPrincipalId: (claims: TClaims) => string;
+  private readonly getContext?: (
+    claims: TClaims,
+  ) => Record<string, string | number | boolean> | undefined;
+  private readonly authorize?: (claims: TClaims) => boolean | Promise<boolean>;
+
+  constructor(options: OidcAuthorizerOptions<TClaims>) {
+    this.verifier = new OidcVerifier(options.config);
+    this.extraction = options.extraction ?? {};
+    this.wildcardResource = options.wildcardResource ?? true;
+    this.getPrincipalId = options.getPrincipalId ?? ((c) => c.sub ?? 'unknown');
+    this.getContext = options.getContext;
+    this.authorize = options.authorize;
+  }
+
+  tokenHandler() {
+    return async (
+      event: APIGatewayTokenAuthorizerEvent,
+      _context: LambdaContext,
+    ): Promise<APIGatewayAuthorizerResult> => {
+      const { authorizationToken, methodArn } = event;
+      const resource = this.wildcardResource
+        ? getWildcardResource(methodArn)
+        : methodArn;
+
+      const token = authorizationToken.startsWith('Bearer ')
+        ? authorizationToken.slice(7)
+        : authorizationToken;
+
+      try {
+        const claims = await this.verifier.verify(token);
+
+        if (this.authorize) {
+          const isAuthorized = await this.authorize(claims);
+          if (!isAuthorized) {
+            return generatePolicy('unauthorized', 'Deny', resource);
+          }
+        }
+
+        const principalId = this.getPrincipalId(claims);
+        const context = this.getContext?.(claims);
+
+        return generatePolicy(principalId, 'Allow', resource, context);
+      } catch {
+        return generatePolicy('unauthorized', 'Deny', resource);
+      }
+    };
+  }
+
+  requestHandler() {
+    const {
+      headerName = 'authorization',
+      cookieName,
+      tokenPrefix = 'Bearer ',
+    } = this.extraction;
+
+    const extractToken = (
+      event: APIGatewayRequestAuthorizerEvent,
+    ): string | null => {
+      const headers = event.headers ?? {};
+      const headerKey = Object.keys(headers).find(
+        (k) => k.toLowerCase() === headerName.toLowerCase(),
+      );
+      if (headerKey) {
+        const headerValue = headers[headerKey];
+        if (headerValue) {
+          if (tokenPrefix && headerValue.startsWith(tokenPrefix)) {
+            return headerValue.slice(tokenPrefix.length);
+          }
+          return headerValue;
+        }
+      }
+
+      if (cookieName) {
+        const cookieHeader = headers['cookie'] ?? headers['Cookie'] ?? '';
+        const match = cookieHeader.match(new RegExp(`${cookieName}=([^;]+)`));
+        if (match) {
+          return match[1];
+        }
+      }
+
+      return null;
+    };
+
+    return async (
+      event: APIGatewayRequestAuthorizerEvent,
+      _context: LambdaContext,
+    ): Promise<APIGatewayAuthorizerResult> => {
+      const methodArn = event.methodArn;
+      const resource = this.wildcardResource
+        ? getWildcardResource(methodArn)
+        : methodArn;
+
+      const token = extractToken(event);
+
+      if (!token) {
+        return generatePolicy('unauthorized', 'Deny', resource);
+      }
+
+      try {
+        const claims = await this.verifier.verify(token);
+
+        if (this.authorize) {
+          const isAuthorized = await this.authorize(claims);
+          if (!isAuthorized) {
+            return generatePolicy('unauthorized', 'Deny', resource);
+          }
+        }
+
+        const principalId = this.getPrincipalId(claims);
+        const context = this.getContext?.(claims);
+
+        return generatePolicy(principalId, 'Allow', resource, context);
+      } catch {
+        return generatePolicy('unauthorized', 'Deny', resource);
+      }
+    };
+  }
+}

package/src/oidc.ts

@@ -0,0 +1,156 @@
+import * as jose from 'jose';
+import type { JwtClaims, TokenExtractionOptions } from './jwt';
+
+export type { TokenExtractionOptions };
+
+/**
+ * Standard OIDC claims (extends JWT claims)
+ */
+export interface OidcClaims extends JwtClaims {
+  nonce?: string;
+  auth_time?: number;
+  at_hash?: string;
+  c_hash?: string;
+  azp?: string;
+}
+
+/**
+ * Standard OIDC user info claims
+ */
+export interface OidcUserInfo {
+  sub: string;
+  name?: string;
+  given_name?: string;
+  family_name?: string;
+  middle_name?: string;
+  nickname?: string;
+  preferred_username?: string;
+  profile?: string;
+  picture?: string;
+  website?: string;
+  email?: string;
+  email_verified?: boolean;
+  gender?: string;
+  birthdate?: string;
+  zoneinfo?: string;
+  locale?: string;
+  phone_number?: string;
+  phone_number_verified?: boolean;
+  address?: {
+    formatted?: string;
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+  };
+  updated_at?: number;
+}
+
+/**
+ * OIDC Discovery document
+ */
+export interface OidcDiscovery {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint?: string;
+  jwks_uri: string;
+  scopes_supported?: string[];
+  response_types_supported: string[];
+  claims_supported?: string[];
+}
+
+/**
+ * Configuration for OIDC verification
+ */
+export interface OidcConfig {
+  issuer: string;
+  audience: string | string[];
+  cacheDiscovery?: boolean;
+}
+
+/**
+ * OIDC Verifier with auto-discovery and caching
+ */
+export class OidcVerifier<
+  TClaims extends OidcClaims = OidcClaims,
+  TUserInfo extends OidcUserInfo = OidcUserInfo,
+> {
+  private discovery: OidcDiscovery | null = null;
+  private jwks: jose.JWTVerifyGetKey | null = null;
+  private readonly discoveryUrl: string;
+
+  constructor(private readonly config: OidcConfig) {
+    this.discoveryUrl = config.issuer.endsWith('/')
+      ? `${config.issuer}.well-known/openid-configuration`
+      : `${config.issuer}/.well-known/openid-configuration`;
+  }
+
+  async getDiscovery(): Promise<OidcDiscovery> {
+    if (this.discovery && this.config.cacheDiscovery !== false) {
+      return this.discovery;
+    }
+
+    const response = await fetch(this.discoveryUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch OIDC discovery: ${response.statusText}`);
+    }
+
+    this.discovery = (await response.json()) as OidcDiscovery;
+    return this.discovery;
+  }
+
+  private async getJwks(): Promise<jose.JWTVerifyGetKey> {
+    if (this.jwks && this.config.cacheDiscovery !== false) {
+      return this.jwks;
+    }
+
+    const disc = await this.getDiscovery();
+    this.jwks = jose.createRemoteJWKSet(new URL(disc.jwks_uri));
+    return this.jwks;
+  }
+
+  async verify(token: string): Promise<TClaims> {
+    const key = await this.getJwks();
+    const { payload } = await jose.jwtVerify(token, key, {
+      issuer: this.config.issuer,
+      audience: this.config.audience,
+    });
+    return payload as unknown as TClaims;
+  }
+
+  async verifyOrNull(token: string): Promise<TClaims | null> {
+    try {
+      return await this.verify(token);
+    } catch {
+      return null;
+    }
+  }
+
+  async fetchUserInfo(token: string): Promise<TUserInfo | null> {
+    try {
+      const disc = await this.getDiscovery();
+      if (!disc.userinfo_endpoint) {
+        return null;
+      }
+
+      const response = await fetch(disc.userinfo_endpoint, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      if (!response.ok) {
+        return null;
+      }
+
+      return (await response.json()) as TUserInfo;
+    } catch {
+      return null;
+    }
+  }
+
+  clearCache(): void {
+    this.discovery = null;
+    this.jwks = null;
+  }
+}