@oneunit/auth 2.0.0

package/src/errors.ts

@@ -0,0 +1,76 @@
+import type { AuthErrorOptions } from "./types.js";
+
+export class AuthError extends Error {
+  override readonly name: string;
+  readonly code: string;
+  readonly status: number;
+  override readonly cause?: unknown;
+
+  constructor(message: string, { code = "AUTH_ERROR", status = 401, cause }: AuthErrorOptions = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.status = status;
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+    Error.captureStackTrace?.(this, this.constructor);
+  }
+
+  toJSON(): { name: string; message: string; code: string; status: number } {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      status: this.status,
+    };
+  }
+}
+
+export class InvalidTokenError extends AuthError {
+  constructor(message = "Invalid or expired token", options: AuthErrorOptions = {}) {
+    super(message, { code: "INVALID_TOKEN", status: 401, ...options });
+  }
+}
+
+export class TokenExpiredError extends AuthError {
+  constructor(message = "Token has expired", options: AuthErrorOptions = {}) {
+    super(message, { code: "TOKEN_EXPIRED", status: 401, ...options });
+  }
+}
+
+export class UnauthorizedError extends AuthError {
+  constructor(message = "Unauthorized", options: AuthErrorOptions = {}) {
+    super(message, { code: "UNAUTHORIZED", status: 401, ...options });
+  }
+}
+
+export class ForbiddenError extends AuthError {
+  constructor(message = "Forbidden", options: AuthErrorOptions = {}) {
+    super(message, { code: "FORBIDDEN", status: 403, ...options });
+  }
+}
+
+export class ConfigurationError extends AuthError {
+  constructor(message = "Invalid authentication configuration", options: AuthErrorOptions = {}) {
+    super(message, { code: "CONFIGURATION_ERROR", status: 500, ...options });
+  }
+}
+
+export class OAuthError extends AuthError {
+  constructor(message = "OAuth authentication failed", options: AuthErrorOptions = {}) {
+    super(message, { code: "OAUTH_ERROR", status: 401, ...options });
+  }
+}
+
+export class ProviderError extends AuthError {
+  constructor(message = "Identity provider error", options: AuthErrorOptions = {}) {
+    super(message, { code: "PROVIDER_ERROR", status: 502, ...options });
+  }
+}
+
+export class ValidationError extends AuthError {
+  constructor(message = "Validation failed", options: AuthErrorOptions = {}) {
+    super(message, { code: "VALIDATION_ERROR", status: 400, ...options });
+  }
+}

package/src/index.ts

@@ -0,0 +1,124 @@
+export {
+  AuthError,
+  InvalidTokenError,
+  TokenExpiredError,
+  UnauthorizedError,
+  ForbiddenError,
+  ConfigurationError,
+  OAuthError,
+  ProviderError,
+  ValidationError,
+} from "./errors.js";
+
+export {
+  encode,
+  decode,
+  decodeUnsafe,
+  encodeAccessToken,
+  encodeRefreshToken,
+} from "./jwt.js";
+
+export {
+  RBAC,
+  createRBAC,
+  defineRoles,
+  matchPermission,
+} from "./rbac.js";
+
+export {
+  hashPassword,
+  verifyPassword,
+  needsRehash,
+} from "./password.js";
+
+export {
+  OAuth,
+  createOAuth,
+  createMemoryStateStore,
+} from "./oauth.js";
+
+export {
+  createProvider,
+  getProvider,
+  builtinProviders,
+  pkceVerifier,
+  pkceChallenge,
+  google,
+  github,
+  instagram,
+  facebook,
+  twitter,
+  discord,
+  apple,
+  linkedin,
+  microsoft,
+  reddit,
+  twitch,
+  slack,
+  spotify,
+  tiktok,
+} from "./providers.js";
+
+export {
+  Auth,
+  auth,
+  createAuth,
+  createMemoryRefreshStore,
+} from "./auth.js";
+
+export {
+  expressAdapter,
+  fastifyAdapter,
+  koaAdapter,
+  uwsAdapter,
+  snapshotUwsRequest,
+  createAdapters,
+} from "./adapters.js";
+
+export {
+  parseExpiresIn,
+  isValidExpiresIn,
+  randomToken,
+  randomState,
+  extractBearerToken,
+} from "./utils.js";
+
+export type {
+  AuthErrorOptions,
+  JwtSignOptions,
+  JwtVerifyOptions,
+  JwtPayload,
+  Secret,
+  RoleDefinition,
+  RBACOptions,
+  AuthSubject,
+  PasswordOptions,
+  OAuthProfile,
+  OAuthTokens,
+  OAuthProviderConfig,
+  OAuthProvider,
+  ProviderDefinition,
+  StateStore,
+  OAuthOptions,
+  OAuthAuthorizeOptions,
+  UserRecord,
+  UserStore,
+  RefreshRecord,
+  RefreshStore,
+  LoginOptions,
+  LoginResult,
+  AuthOptions,
+  RequestLike,
+  ExtractTokenOptions,
+  UwsHttpResponse,
+  UwsHttpRequest,
+  UwsRequestSnapshot,
+  UwsHandler,
+  ExpressRequestLike,
+  ExpressResponseLike,
+  ExpressNext,
+  KoaContextLike,
+  FastifyLike,
+  FastifyRequestLike,
+  FastifyReplyLike,
+} from "./types.js";

package/src/jwt.ts

@@ -0,0 +1,159 @@
+import jwt from "jsonwebtoken";
+import type { Algorithm, JwtHeader, SignOptions, VerifyOptions } from "jsonwebtoken";
+import { AuthError, InvalidTokenError, TokenExpiredError, ValidationError } from "./errors.js";
+import type { JwtPayload, JwtSignOptions, JwtVerifyOptions, Secret } from "./types.js";
+import { isValidExpiresIn, parseExpiresIn } from "./utils.js";
+
+const DEFAULT_ALGORITHM: Algorithm = "HS256";
+const DEFAULT_EXPIRES_IN = 60 * 60 * 24;
+
+function normalizeSecret(secret: Secret | undefined): Secret {
+  if (typeof secret === "string" && secret.length > 0) {
+    return secret;
+  }
+  if (Buffer.isBuffer(secret) && secret.length > 0) {
+    return secret;
+  }
+  throw new ValidationError("A non-empty secret is required to sign or verify tokens");
+}
+
+function signOptions({
+  expiresIn,
+  subject,
+  audience,
+  issuer,
+  jwtid,
+  notBefore,
+  header,
+  algorithm = DEFAULT_ALGORITHM,
+  keyid,
+}: JwtSignOptions = {}): SignOptions {
+  const options: SignOptions = { algorithm: algorithm as Algorithm };
+
+  if (expiresIn !== undefined && expiresIn !== null) {
+    // Resolve the TTL here so an unparsable value fails loudly instead of being
+    // silently defaulted by parseExpiresIn while jsonwebtoken rejects it later.
+    if (!isValidExpiresIn(expiresIn)) {
+      throw new ValidationError(
+        `Invalid expiresIn: ${JSON.stringify(expiresIn)}. Use seconds or a timespan like "15m", "7d".`,
+      );
+    }
+    options.expiresIn = (typeof expiresIn === "number"
+      ? parseExpiresIn(expiresIn)
+      : expiresIn) as SignOptions["expiresIn"];
+  }
+
+  if (subject !== undefined) options.subject = String(subject);
+  if (audience !== undefined) options.audience = audience;
+  if (issuer !== undefined) options.issuer = issuer;
+  if (jwtid !== undefined) options.jwtid = jwtid;
+  if (notBefore !== undefined) options.notBefore = notBefore as SignOptions["notBefore"];
+  if (keyid !== undefined) options.keyid = keyid;
+  if (header !== undefined) options.header = header as unknown as JwtHeader;
+
+  return options;
+}
+
+export function encode(payload: object = {}, secret: Secret, options: JwtSignOptions = {}): string {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new ValidationError("Token payload must be an object");
+  }
+
+  const {
+    expiresInSeconds,
+    expiresIn = expiresInSeconds ?? DEFAULT_EXPIRES_IN,
+    subject,
+    ...rest
+  } = options;
+
+  try {
+    const signPayload = { ...(payload as Record<string, unknown>) };
+    if (subject !== undefined && signPayload.sub === undefined) {
+      signPayload.sub = String(subject);
+    }
+    return jwt.sign(signPayload, normalizeSecret(secret), signOptions({ expiresIn, ...rest }));
+  } catch (error) {
+    if (error instanceof AuthError) {
+      throw error;
+    }
+    throw new InvalidTokenError(error instanceof Error ? error.message : "Failed to sign token", { cause: error });
+  }
+}
+
+export function decode(token: string, secret: Secret, options: JwtVerifyOptions = {}): JwtPayload {
+  if (!token || typeof token !== "string") {
+    throw new InvalidTokenError("Token is required");
+  }
+
+  const {
+    algorithms = [DEFAULT_ALGORITHM],
+    audience,
+    issuer,
+    subject,
+    clockTolerance,
+    ignoreExpiration = false,
+    complete = false,
+  } = options;
+
+  try {
+    const verifyOptions: VerifyOptions = {
+      algorithms: algorithms as Algorithm[],
+      audience: audience as VerifyOptions["audience"],
+      issuer,
+      subject,
+      clockTolerance,
+      ignoreExpiration,
+      complete,
+    };
+    return jwt.verify(token, normalizeSecret(secret), verifyOptions) as JwtPayload;
+  } catch (error) {
+    if (error instanceof AuthError) {
+      throw error;
+    }
+    if (error instanceof Error && error.name === "TokenExpiredError") {
+      throw new TokenExpiredError("Token has expired", { cause: error });
+    }
+    throw new InvalidTokenError("Invalid or expired token", { cause: error });
+  }
+}
+
+export function decodeUnsafe(token: string, options: { complete?: boolean } = {}): unknown {
+  if (!token || typeof token !== "string") {
+    return null;
+  }
+  return jwt.decode(token, { complete: options.complete === true }) ?? null;
+}
+
+function withTyp(payload: object, typ: string, options: JwtSignOptions & { secret: Secret } = { secret: "" }): string {
+  const next: Record<string, unknown> = { ...(payload as Record<string, unknown>), typ };
+  const subject = options.subject ?? next.sub ?? next.userId;
+  if (subject !== undefined && next.sub === undefined) {
+    next.sub = String(subject);
+  }
+  return encode(next, options.secret, {
+    expiresIn: options.expiresIn,
+    audience: options.audience,
+    issuer: options.issuer,
+    jwtid: options.jwtid,
+    algorithm: options.algorithm,
+    header: options.header,
+  });
+}
+
+export function encodeAccessToken(payload: object, secret: Secret, options: JwtSignOptions = {}): string {
+  return withTyp(payload, "access", {
+    ...options,
+    secret,
+    expiresIn: options.expiresIn ?? "15m",
+  });
+}
+
+export function encodeRefreshToken(payload: object, secret: Secret, options: JwtSignOptions = {}): string {
+  return withTyp(payload, "refresh", {
+    ...options,
+    secret,
+    expiresIn: options.expiresIn ?? "7d",
+  });
+}
+
+export { jwt };

package/src/oauth.ts

@@ -0,0 +1,226 @@
+import { OAuthError, ValidationError } from "./errors.js";
+import { builtinProviders, createProvider, getProvider, pkceVerifier } from "./providers.js";
+import type {
+  OAuthAuthorizeOptions,
+  OAuthOptions,
+  OAuthProfile,
+  OAuthProvider,
+  OAuthProviderConfig,
+  OAuthStateRecord,
+  OAuthTokens,
+  StateStore,
+} from "./types.js";
+import { randomState, timingSafeEqualString } from "./utils.js";
+
+interface ProviderEntry {
+  provider: OAuthProvider;
+  config: OAuthProviderConfig;
+}
+
+export class OAuth {
+  providers = new Map<string, ProviderEntry>();
+  defaultRedirectUri: string | null;
+  stateStore: StateStore;
+
+  constructor(options: OAuthOptions = {}) {
+    this.defaultRedirectUri = options.redirectUri ?? null;
+    this.stateStore = options.stateStore ?? createMemoryStateStore();
+
+    const configured = options.providers ?? {};
+    for (const [id, config] of Object.entries(configured)) {
+      this.use(id, config);
+    }
+  }
+
+  use(id: string, config: OAuthProviderConfig = {}): this {
+    const provider: OAuthProvider = (config.provider as OAuthProvider | undefined) ??
+      (id in builtinProviders
+        ? getProvider(id)
+        : createProvider({
+          id,
+          authorizationUrl: String(config.authorizationUrl ?? ""),
+          tokenUrl: String(config.tokenUrl ?? ""),
+          ...config,
+        }));
+
+    const entry: ProviderEntry = {
+      provider,
+      config: {
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        redirectUri: config.redirectUri ?? this.defaultRedirectUri ?? undefined,
+        scopes: config.scopes,
+        pkce: config.pkce,
+        extraAuthParams: config.extraAuthParams,
+        extraTokenParams: config.extraTokenParams,
+        userInfoHeaders: config.userInfoHeaders,
+        tokenAuthMethod: config.tokenAuthMethod,
+      },
+    };
+
+    this.providers.set(id, entry);
+    // Also expose the provider under its own id when registered via an alias,
+    // but never overwrite an entry that was configured explicitly.
+    if (provider.id && provider.id !== id && !this.providers.has(provider.id)) {
+      this.providers.set(provider.id, entry);
+    }
+
+    return this;
+  }
+
+  list(): string[] {
+    return [...new Set([...this.providers.values()].map((entry) => entry.provider.id))];
+  }
+
+  get(id: string): ProviderEntry {
+    const entry = this.providers.get(id);
+    if (!entry) {
+      throw new ValidationError(`OAuth provider "${id}" is not configured`);
+    }
+    return entry;
+  }
+
+  async authorize(id: string, options: OAuthAuthorizeOptions = {}): Promise<{
+    url: string;
+    state: string;
+    provider: string;
+    codeVerifier?: string;
+  }> {
+    const { provider, config } = this.get(id);
+    const state = options.state ?? randomState();
+    const redirectUri = options.redirectUri ?? config.redirectUri;
+    const codeVerifier = provider.pkce || config.pkce ? (options.codeVerifier ?? pkceVerifier()) : undefined;
+
+    const authorization = provider.createAuthorizationUrl(config, {
+      state,
+      redirectUri,
+      codeVerifier,
+      extraParams: options.extraParams,
+    });
+
+    await this.stateStore.set(state, {
+      provider: id,
+      redirectUri,
+      codeVerifier: authorization.codeVerifier ?? codeVerifier,
+      createdAt: Date.now(),
+      metadata: options.metadata ?? {},
+    } satisfies OAuthStateRecord, options.ttlSeconds ?? 600);
+
+    return {
+      url: authorization.url,
+      state,
+      provider: id,
+      codeVerifier: authorization.codeVerifier ?? codeVerifier,
+    };
+  }
+
+  async callback(id: string, params: string | Record<string, string> = {}): Promise<{
+    provider: string;
+    tokens: OAuthTokens;
+    profile: OAuthProfile;
+    state: OAuthStateRecord | null;
+  }> {
+    const query = normalizeCallbackParams(params);
+    if (query.error) {
+      throw new OAuthError(query.error_description || query.error);
+    }
+
+    if (!query.code) {
+      throw new ValidationError("OAuth callback is missing authorization code");
+    }
+
+    const { provider, config } = this.get(id);
+    let stored: OAuthStateRecord | null = null;
+
+    if (query.state) {
+      stored = (await this.stateStore.get(query.state)) as OAuthStateRecord | null;
+      if (!stored) {
+        throw new OAuthError("Invalid or expired OAuth state");
+      }
+      if (stored.provider && stored.provider !== id) {
+        throw new OAuthError("OAuth provider mismatch");
+      }
+      await this.stateStore.delete(query.state);
+    } else if (config.pkce || provider.pkce) {
+      throw new OAuthError("OAuth state is required");
+    }
+
+    const tokens = await provider.exchangeCode(config, {
+      code: query.code,
+      redirectUri: stored?.redirectUri ?? config.redirectUri,
+      codeVerifier: stored?.codeVerifier ?? query.codeVerifier,
+    });
+
+    const profile = await provider.fetchProfile(config, tokens);
+
+    return {
+      provider: id,
+      tokens,
+      profile: {
+        ...profile,
+        provider: profile.provider ?? id,
+      },
+      state: stored,
+    };
+  }
+
+  async verifyState(state: string, expected?: string): Promise<boolean> {
+    const stored = await this.stateStore.get(state) as OAuthStateRecord | null;
+    if (!stored) {
+      return false;
+    }
+    if (expected && !timingSafeEqualString(stored.provider, expected)) {
+      return false;
+    }
+    return true;
+  }
+}
+
+function normalizeCallbackParams(params: string | Record<string, string>): Record<string, string> {
+  if (typeof params === "string") {
+    const trimmed = params.trim();
+    // Accepts a full URL ("https://host/cb?code=..."), a path with a query
+    // ("/cb?code=..." or "cb?code=..."), a leading "?code=...", or a bare query
+    // string ("code=..."). Only the bare form needs special handling: the URL
+    // constructor reads it as a path, and reading it as a query string is the
+    // only way to find the code.
+    const isBareQuery = trimmed !== "" && !trimmed.includes("?") && !trimmed.includes("://") && !trimmed.startsWith("/");
+    if (isBareQuery) {
+      return Object.fromEntries(new URLSearchParams(trimmed));
+    }
+    const url = trimmed.includes("://") ? new URL(trimmed) : new URL(trimmed, "http://localhost");
+    return Object.fromEntries(url.searchParams.entries());
+  }
+  return params ?? {};
+}
+
+export function createMemoryStateStore(): StateStore {
+  const store = new Map<string, { value: unknown; expiresAt: number }>();
+
+  return {
+    async set(key, value, ttlSeconds = 600) {
+      store.set(key, {
+        value,
+        expiresAt: Date.now() + ttlSeconds * 1000,
+      });
+    },
+    async get(key) {
+      const entry = store.get(key);
+      if (!entry) {
+        return null;
+      }
+      if (entry.expiresAt <= Date.now()) {
+        store.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    async delete(key) {
+      store.delete(key);
+    },
+  };
+}
+
+export function createOAuth(options: OAuthOptions = {}): OAuth {
+  return new OAuth(options);
+}

package/src/password.ts

@@ -0,0 +1,111 @@
+import { randomBytes, scrypt as scryptCallback, timingSafeEqual } from "node:crypto";
+import { ValidationError } from "./errors.js";
+import type { PasswordOptions } from "./types.js";
+
+function scrypt(
+  password: string,
+  salt: Buffer,
+  keyLength: number,
+  options: { N: number; r: number; p: number },
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scryptCallback(password, salt, keyLength, options, (error, derivedKey) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve(derivedKey);
+    });
+  });
+}
+
+const DEFAULT_KEY_LENGTH = 64;
+const DEFAULT_SALT_BYTES = 16;
+const DEFAULT_COST = 16384;
+const DEFAULT_BLOCK_SIZE = 8;
+const DEFAULT_PARALLELISM = 1;
+const PREFIX = "scrypt";
+
+function toBuffer(value: string | Buffer): Buffer {
+  return Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8");
+}
+
+export async function hashPassword(password: string, options: PasswordOptions = {}): Promise<string> {
+  if (typeof password !== "string" || password.length === 0) {
+    throw new ValidationError("Password must be a non-empty string");
+  }
+
+  const saltBytes = options.saltBytes ?? DEFAULT_SALT_BYTES;
+  const keyLength = options.keyLength ?? DEFAULT_KEY_LENGTH;
+  const N = options.cost ?? DEFAULT_COST;
+  const r = options.blockSize ?? DEFAULT_BLOCK_SIZE;
+  const p = options.parallelism ?? DEFAULT_PARALLELISM;
+  const salt = options.salt ? toBuffer(options.salt) : randomBytes(saltBytes);
+  const key = await scrypt(password, salt, keyLength, { N, r, p });
+
+  return [
+    PREFIX,
+    N,
+    r,
+    p,
+    keyLength,
+    salt.toString("base64url"),
+    key.toString("base64url"),
+  ].join("$");
+}
+
+export async function verifyPassword(password: string, storedHash: string): Promise<boolean> {
+  if (typeof password !== "string" || typeof storedHash !== "string") {
+    return false;
+  }
+
+  const parts = storedHash.split("$");
+  if (parts.length !== 7 || parts[0] !== PREFIX) {
+    return false;
+  }
+
+  const [, nRaw, rRaw, pRaw, lengthRaw, saltB64, hashB64] = parts;
+  const N = Number.parseInt(nRaw, 10);
+  const r = Number.parseInt(rRaw, 10);
+  const p = Number.parseInt(pRaw, 10);
+  const keyLength = Number.parseInt(lengthRaw, 10);
+
+  if (![N, r, p, keyLength].every(Number.isFinite)) {
+    return false;
+  }
+
+  try {
+    const salt = Buffer.from(saltB64, "base64url");
+    const expected = Buffer.from(hashB64, "base64url");
+    const actual = await scrypt(password, salt, keyLength, { N, r, p });
+    if (actual.length !== expected.length) {
+      return false;
+    }
+    return timingSafeEqual(actual, expected);
+  } catch {
+    return false;
+  }
+}
+
+export function needsRehash(storedHash: string, options: PasswordOptions = {}): boolean {
+  if (typeof storedHash !== "string") {
+    return true;
+  }
+
+  const parts = storedHash.split("$");
+  if (parts.length !== 7 || parts[0] !== PREFIX) {
+    return true;
+  }
+
+  const N = Number.parseInt(parts[1], 10);
+  const r = Number.parseInt(parts[2], 10);
+  const p = Number.parseInt(parts[3], 10);
+  const keyLength = Number.parseInt(parts[4], 10);
+
+  return (
+    N !== (options.cost ?? DEFAULT_COST) ||
+    r !== (options.blockSize ?? DEFAULT_BLOCK_SIZE) ||
+    p !== (options.parallelism ?? DEFAULT_PARALLELISM) ||
+    keyLength !== (options.keyLength ?? DEFAULT_KEY_LENGTH)
+  );
+}