@graphoria/server 0.1.0

package/src/authentication/jwt.ts

@@ -0,0 +1,220 @@
+import { timingSafeEqual } from "crypto";
+
+import { SignJWT, jwtVerify } from "jose";
+
+import type { JWTPayload } from "jose";
+import type { Env } from "../types/env";
+import type { SessionContext } from "../utils/sessionVariables";
+import type { TokenRepository } from "./tokenRepository";
+import type { TokenGenerationParameters, TokenOptions, TokenResponse, TokenService } from "./types";
+
+import { parseDurationToSeconds } from "./duration";
+import { createTokenRepository } from "./tokenRepository";
+import { logger } from "../logging";
+
+// Audience constants to distinguish token types
+const ACCESS_TOKEN_AUDIENCE = "access";
+const REFRESH_TOKEN_AUDIENCE = "refresh";
+
+// Timing-safe string comparison to prevent timing attacks
+const safeCompare = (a: string, b: string): boolean => {
+  try {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) return false;
+    return timingSafeEqual(bufA, bufB);
+  } catch {
+    return false;
+  }
+};
+
+export type { TokenGenerationParameters, TokenOptions, TokenResponse };
+
+export type JWTTokenPayload = JWTPayload &
+  TokenGenerationParameters & {
+    jti: string;
+  };
+
+const ALGORITHM = "HS256";
+const TYP = "JWT";
+
+export const createJWTService = (
+  env: Env,
+  tokenRepositoryOverride?: TokenRepository,
+): TokenService => {
+  const tokenRepository = tokenRepositoryOverride ?? createTokenRepository(env.cache.redisUrl);
+  const jwtSecret = new TextEncoder().encode(env.jwt.secret);
+
+  const createToken = async (
+    payload: TokenGenerationParameters,
+    options: TokenOptions = {},
+  ): Promise<string> => {
+    try {
+      const jwt = new SignJWT({ ...payload })
+        .setProtectedHeader({ alg: ALGORITHM, typ: TYP })
+        .setIssuedAt()
+        .setSubject(payload.sub)
+        .setExpirationTime(options.expiresIn || env.jwt.expiresIn)
+        .setJti(crypto.randomUUID()); // Add unique token ID
+
+      if (options.issuer) {
+        jwt.setIssuer(options.issuer);
+      }
+      if (options.audience) {
+        jwt.setAudience(options.audience);
+      }
+      if (options.notBefore) {
+        jwt.setNotBefore(options.notBefore);
+      }
+
+      return await jwt.sign(jwtSecret);
+    } catch (error) {
+      logger("auth").child({ strategy: "jwt" }).error({ err: error }, "token creation failed");
+      throw new Error("Token creation failed");
+    }
+  };
+
+  const verifyToken = async <T extends JWTTokenPayload = JWTTokenPayload>(
+    token: string,
+    options: TokenOptions = {},
+  ): Promise<T> => {
+    const { payload } = await jwtVerify(token, jwtSecret, {
+      issuer: options.issuer,
+      audience: options.audience,
+      algorithms: [ALGORITHM],
+      typ: TYP,
+    });
+
+    return payload as T;
+  };
+
+  const verifyTokenAndGetRole = async (
+    authHeader: string | null,
+    adminSecretHeader: string | null,
+  ): Promise<string> => {
+    // Use timing-safe comparison to prevent timing attacks
+    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
+      return env.superadmin.role;
+
+    if (!authHeader) return env.anonymousRole;
+
+    if (!authHeader.startsWith("Bearer ")) return env.anonymousRole;
+
+    const token = authHeader.substring(7); // Remove 'Bearer ' prefix
+
+    try {
+      const verifiedToken = await verifyToken(token);
+
+      return verifiedToken.role;
+    } catch {
+      return env.anonymousRole;
+    }
+  };
+
+  const verifyTokenAndGetSession = async (
+    authHeader: string | null,
+    adminSecretHeader: string | null,
+  ): Promise<SessionContext> => {
+    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
+      return { sub: "superadmin", role: env.superadmin.role };
+
+    if (!authHeader || !authHeader.startsWith("Bearer "))
+      return { sub: "anonymous", role: env.anonymousRole };
+
+    const token = authHeader.substring(7);
+
+    try {
+      const payload = await verifyToken(token, { audience: ACCESS_TOKEN_AUDIENCE });
+      if (await tokenRepository.isRevoked(payload.jti)) {
+        logger("auth").child({ strategy: "jwt" }).warn({ jti: payload.jti }, "token revoked");
+        return { sub: "anonymous", role: env.anonymousRole };
+      }
+      logger("auth")
+        .child({ strategy: "jwt" })
+        .debug({ sub: payload.sub, role: payload.role }, "token verified");
+      return {
+        sub: payload.sub,
+        role: payload.role,
+        jti: payload.jti,
+        claims: (payload.claims as Record<string, unknown>) ?? {},
+        iat: payload.iat,
+        exp: payload.exp,
+      };
+    } catch (error) {
+      logger("auth").child({ strategy: "jwt" }).debug({ err: error }, "token verification failed");
+      return { sub: "anonymous", role: env.anonymousRole };
+    }
+  };
+
+  const createTokenPair = async (
+    payload: TokenGenerationParameters,
+    options: TokenOptions = {},
+  ): Promise<TokenResponse> => {
+    const accessTokenExpiry = options.expiresIn || env.jwt.expiresIn;
+
+    // Access token - short lived, with "access" audience
+    const access_token = await createToken(payload, {
+      ...options,
+      expiresIn: accessTokenExpiry,
+      audience: ACCESS_TOKEN_AUDIENCE,
+    });
+
+    // Refresh token - longer lived, with "refresh" audience
+    const refresh_token = await createToken(payload, {
+      ...options,
+      expiresIn: env.jwt.rtExpiresIn,
+      audience: REFRESH_TOKEN_AUDIENCE,
+    });
+
+    return {
+      access_token,
+      refresh_token,
+      expires_in: parseDurationToSeconds(accessTokenExpiry),
+      role: payload.role,
+    };
+  };
+
+  const refreshAccessToken = async (refresh_token: string) => {
+    // Verify refresh token with correct audience
+    const payload = await verifyToken(refresh_token, {
+      audience: REFRESH_TOKEN_AUDIENCE,
+    });
+
+    if (await tokenRepository.isRevoked(payload.jti)) {
+      throw new Error("Token revoked");
+    }
+
+    // Check if this refresh token has already been used (token rotation)
+    const isAlreadyUsed = await tokenRepository.isTokenUsed(payload.jti);
+
+    if (isAlreadyUsed) {
+      // Token reuse detected - this could indicate token theft
+      // In a production system, you might want to revoke all tokens for this user
+      throw new Error("Token reuse detected");
+    }
+
+    // Mark this refresh token as used BEFORE issuing new tokens
+    await tokenRepository.saveJti(payload.jti, env.jwt.rtExpiresIn);
+
+    // Create new token pair with original subject, role, and claims
+    return createTokenPair(
+      {
+        sub: payload.sub,
+        role: payload.role,
+        claims: (payload.claims as Record<string, unknown>) ?? {},
+      },
+      { expiresIn: env.jwt.expiresIn },
+    );
+  };
+
+  return {
+    createToken,
+    verifyToken,
+    verifyTokenAndGetRole,
+    verifyTokenAndGetSession,
+    createTokenPair,
+    refreshAccessToken,
+    revoke: tokenRepository.revoke,
+    isRevoked: tokenRepository.isRevoked,
+  };
+};

package/src/authentication/paseto.ts

@@ -0,0 +1,256 @@
+import { timingSafeEqual } from "crypto";
+
+import { decrypt, encrypt, sign, verify } from "paseto-ts/v4";
+
+import type { Env } from "../types/env";
+import type { SessionContext } from "../utils/sessionVariables";
+import type { TokenRepository } from "./tokenRepository";
+import type { TokenGenerationParameters, TokenOptions, TokenResponse, TokenService } from "./types";
+
+import { parseDurationToSeconds, toPasetoDuration } from "./duration";
+import { createTokenRepository } from "./tokenRepository";
+import { logger } from "../logging";
+
+// Audience constants to distinguish token types
+const ACCESS_TOKEN_AUDIENCE = "access";
+const REFRESH_TOKEN_AUDIENCE = "refresh";
+
+// Timing-safe string comparison to prevent timing attacks
+const safeCompare = (a: string, b: string): boolean => {
+  try {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) return false;
+    return timingSafeEqual(bufA, bufB);
+  } catch {
+    return false;
+  }
+};
+
+type PasetoPayload = {
+  sub: string;
+  role: string;
+  claims?: Record<string, unknown>;
+  jti: string;
+  aud?: string;
+  iss?: string;
+  iat?: string;
+  exp?: string;
+  nbf?: string;
+};
+
+/**
+ * Convert PASETO ISO 8601 timestamp string to Unix epoch seconds
+ */
+const isoToEpoch = (iso: string | undefined): number | undefined => {
+  if (!iso) return undefined;
+  return Math.floor(new Date(iso).getTime() / 1000);
+};
+
+type PasetoMode = "local" | "public";
+
+export const createPASETOService = (
+  env: Env,
+  mode: PasetoMode,
+  tokenRepositoryOverride?: TokenRepository,
+): TokenService => {
+  const tokenRepository = tokenRepositoryOverride ?? createTokenRepository(env.cache.redisUrl);
+
+  // Token creation and verification functions based on mode
+  const createPasetoToken = async (
+    payload: Record<string, unknown>,
+    expiry: string,
+  ): Promise<string> => {
+    const pasetoPayload = {
+      ...payload,
+      exp: toPasetoDuration(expiry),
+    };
+
+    if (mode === "local") {
+      return encrypt(env.paseto.localKey!, pasetoPayload);
+    }
+    return sign(env.paseto.secretKey!, pasetoPayload);
+  };
+
+  const verifyPasetoToken = async (token: string): Promise<PasetoPayload> => {
+    if (mode === "local") {
+      const { payload } = await decrypt<PasetoPayload>(env.paseto.localKey!, token);
+      return payload;
+    }
+    const { payload } = await verify<PasetoPayload>(env.paseto.publicKey!, token);
+    return payload;
+  };
+
+  const createToken = async (
+    payload: TokenGenerationParameters,
+    options: TokenOptions = {},
+  ): Promise<string> => {
+    try {
+      const tokenPayload: Record<string, unknown> = {
+        sub: payload.sub,
+        role: payload.role,
+        jti: crypto.randomUUID(),
+      };
+
+      if (payload.claims) {
+        tokenPayload.claims = payload.claims;
+      }
+      if (options.audience) {
+        tokenPayload.aud = options.audience;
+      }
+      if (options.issuer) {
+        tokenPayload.iss = options.issuer;
+      }
+
+      const expiry = options.expiresIn || env.jwt.expiresIn;
+      return await createPasetoToken(tokenPayload, expiry);
+    } catch (error) {
+      logger("auth").child({ strategy: "paseto" }).error({ err: error }, "token creation failed");
+      throw new Error("Token creation failed");
+    }
+  };
+
+  const verifyToken = async <T = PasetoPayload>(
+    token: string,
+    options: TokenOptions = {},
+  ): Promise<T> => {
+    const payload = await verifyPasetoToken(token);
+
+    // Validate audience manually (PASETO doesn't auto-validate audience)
+    if (options.audience && payload.aud !== options.audience) {
+      throw new Error("Audience mismatch");
+    }
+
+    if (options.issuer && payload.iss !== options.issuer) {
+      throw new Error("Issuer mismatch");
+    }
+
+    return payload as T;
+  };
+
+  const verifyTokenAndGetRole = async (
+    authHeader: string | null,
+    adminSecretHeader: string | null,
+  ): Promise<string> => {
+    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
+      return env.superadmin.role;
+
+    if (!authHeader) return env.anonymousRole;
+
+    if (!authHeader.startsWith("Bearer ")) return env.anonymousRole;
+
+    const token = authHeader.substring(7);
+
+    try {
+      const payload = await verifyPasetoToken(token);
+      return payload.role;
+    } catch {
+      return env.anonymousRole;
+    }
+  };
+
+  const verifyTokenAndGetSession = async (
+    authHeader: string | null,
+    adminSecretHeader: string | null,
+  ): Promise<SessionContext> => {
+    if (env.admin.secret && adminSecretHeader && safeCompare(adminSecretHeader, env.admin.secret))
+      return { sub: "superadmin", role: env.superadmin.role };
+
+    if (!authHeader || !authHeader.startsWith("Bearer "))
+      return { sub: "anonymous", role: env.anonymousRole };
+
+    const token = authHeader.substring(7);
+
+    try {
+      const payload = await verifyPasetoToken(token);
+      // Enforce access-token audience on the bearer path
+      if (payload.aud && payload.aud !== ACCESS_TOKEN_AUDIENCE) {
+        throw new Error("Audience mismatch");
+      }
+      if (await tokenRepository.isRevoked(payload.jti)) {
+        logger("auth").child({ strategy: "paseto" }).warn({ jti: payload.jti }, "token revoked");
+        return { sub: "anonymous", role: env.anonymousRole };
+      }
+      logger("auth")
+        .child({ strategy: "paseto" })
+        .debug({ sub: payload.sub, role: payload.role }, "token verified");
+      return {
+        sub: payload.sub,
+        role: payload.role,
+        jti: payload.jti,
+        claims: payload.claims ?? {},
+        iat: isoToEpoch(payload.iat),
+        exp: isoToEpoch(payload.exp),
+      };
+    } catch (error) {
+      logger("auth")
+        .child({ strategy: "paseto" })
+        .debug({ err: error }, "token verification failed");
+      return { sub: "anonymous", role: env.anonymousRole };
+    }
+  };
+
+  const createTokenPair = async (
+    payload: TokenGenerationParameters,
+    options: TokenOptions = {},
+  ): Promise<TokenResponse> => {
+    const accessTokenExpiry = options.expiresIn || env.jwt.expiresIn;
+
+    const access_token = await createToken(payload, {
+      ...options,
+      expiresIn: accessTokenExpiry,
+      audience: ACCESS_TOKEN_AUDIENCE,
+    });
+
+    const refresh_token = await createToken(payload, {
+      ...options,
+      expiresIn: env.jwt.rtExpiresIn,
+      audience: REFRESH_TOKEN_AUDIENCE,
+    });
+
+    return {
+      access_token,
+      refresh_token,
+      expires_in: parseDurationToSeconds(accessTokenExpiry),
+      role: payload.role,
+    };
+  };
+
+  const refreshAccessToken = async (refresh_token: string): Promise<TokenResponse> => {
+    const payload = await verifyToken<PasetoPayload>(refresh_token, {
+      audience: REFRESH_TOKEN_AUDIENCE,
+    });
+
+    if (await tokenRepository.isRevoked(payload.jti)) {
+      throw new Error("Token revoked");
+    }
+
+    const isAlreadyUsed = await tokenRepository.isTokenUsed(payload.jti);
+
+    if (isAlreadyUsed) {
+      throw new Error("Token reuse detected");
+    }
+
+    await tokenRepository.saveJti(payload.jti, env.jwt.rtExpiresIn);
+
+    return createTokenPair(
+      {
+        sub: payload.sub,
+        role: payload.role,
+        claims: payload.claims ?? {},
+      },
+      { expiresIn: env.jwt.expiresIn },
+    );
+  };
+
+  return {
+    createToken,
+    verifyToken,
+    verifyTokenAndGetRole,
+    verifyTokenAndGetSession,
+    createTokenPair,
+    refreshAccessToken,
+    revoke: tokenRepository.revoke,
+    isRevoked: tokenRepository.isRevoked,
+  };
+};

package/src/authentication/tokenRepository.ts

@@ -0,0 +1,75 @@
+import { RedisClient as ValkeyClient } from "bun";
+
+import { parseDurationToMs } from "./duration";
+import { logger } from "../logging";
+
+export type TokenRepository = {
+  saveJti(jti: string, expiresIn: string): Promise<void>;
+  isTokenUsed(jti: string): Promise<boolean>;
+  revoke(jti: string): Promise<void>;
+  isRevoked(jti: string): Promise<boolean>;
+};
+
+export type TokenRepositoryClient = {
+  hset(key: string, fields: Record<string, string>): Promise<unknown>;
+  hmget(key: string, fields: string[]): Promise<(string | null)[]>;
+  expire(key: string, seconds: number): Promise<unknown>;
+};
+
+export const createTokenRepositoryWithClient = (client: TokenRepositoryClient): TokenRepository => {
+  const log = logger("token-repository");
+
+  const saveJti = async (jti: string, expiresIn: string) => {
+    try {
+      await client.hset(jti, { isUsed: "true" });
+      await client.expire(jti, parseDurationToMs(expiresIn) / 1000);
+    } catch (error) {
+      log.error({ err: error }, "failed to save JTI");
+      throw new Error("Token storage unavailable");
+    }
+  };
+
+  const isTokenUsed = async (jti: string): Promise<boolean> => {
+    try {
+      const [isUsed] = await client.hmget(jti, ["isUsed"]);
+      return isUsed === "true";
+    } catch (error) {
+      log.error({ err: error }, "failed to check JTI usage, failing closed");
+      return true;
+    }
+  };
+
+  const revoke = async (jti: string) => {
+    try {
+      const [isUsed] = await client.hmget(jti, ["isUsed"]);
+      if (isUsed !== "true") return;
+      await client.hset(jti, { isRevoked: "true" });
+    } catch (error) {
+      log.error({ err: error }, "failed to revoke JTI");
+      throw new Error("Token revocation failed");
+    }
+  };
+
+  const isRevoked = async (jti: string): Promise<boolean> => {
+    try {
+      const [isRevoked] = await client.hmget(jti, ["isRevoked"]);
+      return isRevoked === "true";
+    } catch (error) {
+      log.error({ err: error }, "failed to check revocation, failing closed");
+      return true;
+    }
+  };
+
+  return {
+    saveJti,
+    isTokenUsed,
+    revoke,
+    isRevoked,
+  };
+};
+
+export const createTokenRepository = (redisUrl: string): TokenRepository =>
+  // Bun's RedisClient exposes the same hset/hmget/expire surface we need but
+  // its declared types are wider than TokenRepositoryClient. The cast is the
+  // structural-typing bridge and is intentional.
+  createTokenRepositoryWithClient(new ValkeyClient(redisUrl) as unknown as TokenRepositoryClient);

package/src/authentication/types.ts

@@ -0,0 +1,78 @@
+import type { SessionContext } from "../utils/sessionVariables";
+
+// ============================================================================
+// Token Strategy
+// ============================================================================
+
+export type TokenStrategy = "jwt" | "paseto_local" | "paseto_public";
+
+// ============================================================================
+// Shared Token Types
+// ============================================================================
+
+export type TokenGenerationParameters = {
+  sub: string;
+  role: string;
+  claims?: Record<string, unknown>;
+};
+
+export type TokenPayload = {
+  sub: string;
+  role: string;
+  claims?: Record<string, unknown>;
+  jti: string;
+  aud?: string | string[];
+  iss?: string;
+  iat?: number;
+  exp?: number;
+  nbf?: number;
+  [key: string]: unknown;
+};
+
+export type TokenOptions = {
+  expiresIn?: string;
+  issuer?: string;
+  audience?: string;
+  notBefore?: string | number;
+};
+
+export type TokenResponse = {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number; // seconds until access_token expires
+  role: string;
+};
+
+// ============================================================================
+// Token Service Interface
+// ============================================================================
+
+export type TokenService = {
+  createToken(payload: TokenGenerationParameters, options?: TokenOptions): Promise<string>;
+
+  verifyToken<T extends TokenPayload = TokenPayload>(
+    token: string,
+    options?: TokenOptions,
+  ): Promise<T>;
+
+  verifyTokenAndGetRole(
+    authHeader: string | null,
+    adminSecretHeader: string | null,
+  ): Promise<string>;
+
+  verifyTokenAndGetSession(
+    authHeader: string | null,
+    adminSecretHeader: string | null,
+  ): Promise<SessionContext>;
+
+  createTokenPair(
+    payload: TokenGenerationParameters,
+    options?: TokenOptions,
+  ): Promise<TokenResponse>;
+
+  refreshAccessToken(refresh_token: string): Promise<TokenResponse>;
+
+  revoke(jti: string): Promise<void>;
+
+  isRevoked(jti: string): Promise<boolean>;
+};

package/src/cli/seedAuth.ts

@@ -0,0 +1,51 @@
+import type { SeedAuthArgs } from "./seedAuthArgs";
+
+import { loadConfiguration } from "../configuration";
+import { insertAuthUser } from "../databases";
+import { instantiateDatabasesConnections } from "../singletons/databases";
+import { ConfigurationZod } from "../types/zod/configuration";
+import { parseSeedAuthArgs } from "./seedAuthArgs";
+import { logger } from "../logging";
+
+export const runSeedAuth = async (args: SeedAuthArgs): Promise<void> => {
+  const rawConfig = await loadConfiguration(args.config);
+  const configuration = ConfigurationZod.parse(rawConfig);
+
+  if (!configuration.auth?.enabled) {
+    throw new Error("auth.enabled must be true in the configuration to seed an auth user");
+  }
+
+  await instantiateDatabasesConnections([configuration.auth.databaseEntity]);
+
+  await insertAuthUser(configuration.auth, {
+    username: args.user,
+    password: args.password,
+    role: args.role,
+    claims: args.claims,
+  });
+};
+
+export const seedAuthCommand = async (argv: string[]): Promise<void> => {
+  const log = logger("cli");
+  let args: SeedAuthArgs;
+  try {
+    args = parseSeedAuthArgs(argv);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log.error({ err: error }, `seed-auth: ${msg}`);
+    console.error(
+      "Usage: graphoria seed-auth --user <name> --password <pwd> --role <role> --config <path> [--claims <json>]",
+    );
+    process.exit(2);
+  }
+
+  try {
+    await runSeedAuth(args);
+    log.info({ user: args.user, role: args.role }, "seeded auth user");
+    process.exit(0);
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    log.error({ err: error }, `seed-auth failed: ${msg}`);
+    process.exit(1);
+  }
+};