@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/two-factor.js

@@ -0,0 +1,526 @@
+// src/core/auth/refresh-token.ts
+async function generateRefreshToken() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const raw = base64UrlEncode(bytes);
+  const hash = await hashToken(raw);
+  return { raw, hash };
+}
+async function hashToken(raw) {
+  const data = new TextEncoder().encode(raw);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return hexEncode(new Uint8Array(hashBuffer));
+}
+function base64UrlEncode(bytes) {
+  const binString = Array.from(bytes, (b) => String.fromCodePoint(b)).join("");
+  return btoa(binString).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function hexEncode(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/core/errors.ts
+var FortressError = class extends Error {
+  code;
+  statusCode;
+  retryAfter;
+  details;
+  /** RFC 6749 §5.2 / §4.1.2.1 machine code. Set by `Errors.oauth()`. */
+  oauthError;
+  /** Human-readable description for the OAuth `error_description` field. */
+  oauthDescription;
+  /** Optional URI for the OAuth `error_uri` field (§5.2). */
+  oauthErrorUri;
+  constructor(code, message, statusCode, options) {
+    super(message, { cause: options?.cause });
+    this.code = code;
+    this.statusCode = statusCode;
+    this.retryAfter = options?.retryAfter;
+    this.details = options?.details;
+    this.oauthError = options?.oauthError;
+    this.oauthDescription = options?.oauthDescription;
+    this.oauthErrorUri = options?.oauthErrorUri;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      ...this.details !== void 0 && { details: this.details }
+    };
+  }
+};
+var Errors = {
+  unauthorized: (message = "Unauthorized") => new FortressError("UNAUTHORIZED", message, 401),
+  tokenReuse: () => new FortressError("TOKEN_REUSE", "Token reuse detected", 401),
+  sessionIdleTimeout: () => new FortressError("SESSION_IDLE_TIMEOUT", "Session idle timeout exceeded", 401),
+  sessionAbsoluteTimeout: () => new FortressError("SESSION_ABSOLUTE_TIMEOUT", "Session absolute timeout exceeded", 401),
+  forbidden: (message = "Forbidden") => new FortressError("FORBIDDEN", message, 403),
+  badRequest: (message = "Bad request") => new FortressError("BAD_REQUEST", message, 400),
+  notFound: (message = "Not found") => new FortressError("NOT_FOUND", message, 404),
+  conflict: (message = "Conflict", options) => new FortressError("CONFLICT", message, 409, options),
+  unprocessable: (message = "Unprocessable entity", options) => new FortressError("UNPROCESSABLE_ENTITY", message, 422, options),
+  rateLimited: (retryAfter) => new FortressError("RATE_LIMITED", "Too many requests", 429, { retryAfter }),
+  database: (message = "Database error", cause) => new FortressError("DATABASE_ERROR", message, 500, { cause }),
+  serviceUnavailable: (message = "Service unavailable", options) => new FortressError("SERVICE_UNAVAILABLE", message, 503, options),
+  validationError: (issues) => new FortressError("VALIDATION_ERROR", "Validation failed", 422, { details: issues }),
+  /**
+   * RFC 6749 §5.2 / §4.1.2.1 OAuth error.
+   *
+   * The HTTP error mapper detects `oauthError` and emits the OAuth-spec
+   * JSON body `{ error, error_description, error_uri? }` instead of the
+   * default fortress `{ code, message }` shape, so strict OAuth clients
+   * (Moodle, openid-client, Spring Security, etc.) can switch behaviour
+   * on the machine-readable `error` field.
+   *
+   * Status is inferred from the OAuth code per the spec table:
+   * - `invalid_client` → 401
+   * - everything else → 400
+   */
+  oauth: (error, description, options) => {
+    const status = options?.status ?? (error === "invalid_client" ? 401 : 400);
+    const code = status === 401 ? "UNAUTHORIZED" : "BAD_REQUEST";
+    return new FortressError(code, description ?? error, status, {
+      oauthError: error,
+      oauthDescription: description,
+      oauthErrorUri: options?.errorUri,
+      cause: options?.cause
+    });
+  },
+  /**
+   * Reconstruct a {@link FortressError} from a JSON error body emitted by
+   * `errorToResponse`. Used by the in-process `fortress.call.*` client to
+   * convert non-2xx responses into typed throws that mirror what a direct
+   * service-method call would produce.
+   *
+   * Maps by HTTP status when the body doesn't carry a recognizable
+   * `{ code, message }` payload, so network errors and opaque upstream
+   * failures still become structured `FortressError`s.
+   */
+  fromHttpResponse: (status, body) => {
+    const payload = body && typeof body === "object" ? body : {};
+    const message = typeof payload.message === "string" ? payload.message : `HTTP ${status}`;
+    const code = typeof payload.code === "string" && isFortressErrorCode(payload.code) ? payload.code : statusToErrorCode(status);
+    return new FortressError(code, message, status, { details: payload.details });
+  }
+};
+function isFortressErrorCode(code) {
+  return code === "UNAUTHORIZED" || code === "TOKEN_REUSE" || code === "SESSION_IDLE_TIMEOUT" || code === "SESSION_ABSOLUTE_TIMEOUT" || code === "FORBIDDEN" || code === "BAD_REQUEST" || code === "NOT_FOUND" || code === "CONFLICT" || code === "UNPROCESSABLE_ENTITY" || code === "RATE_LIMITED" || code === "DATABASE_ERROR" || code === "VALIDATION_ERROR" || code === "SERVICE_UNAVAILABLE";
+}
+function statusToErrorCode(status) {
+  if (status === 401)
+    return "UNAUTHORIZED";
+  if (status === 403)
+    return "FORBIDDEN";
+  if (status === 404)
+    return "NOT_FOUND";
+  if (status === 409)
+    return "CONFLICT";
+  if (status === 422)
+    return "UNPROCESSABLE_ENTITY";
+  if (status === 429)
+    return "RATE_LIMITED";
+  if (status === 503)
+    return "SERVICE_UNAVAILABLE";
+  if (status >= 500)
+    return "DATABASE_ERROR";
+  return "BAD_REQUEST";
+}
+
+// src/plugins/two-factor/index.ts
+var ENCODER = new TextEncoder();
+var DECODER = new TextDecoder();
+var HEX_32_BYTE_KEY = /^[0-9a-f]{64}$/i;
+function decodeEncryptionKey(value) {
+  const trimmed = value.trim();
+  if (HEX_32_BYTE_KEY.test(trimmed))
+    return new Uint8Array(trimmed.match(/.{2}/g).map((byte) => Number.parseInt(byte, 16)));
+  try {
+    const normalized = trimmed.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    const raw = atob(padded);
+    const decoded = Uint8Array.from(raw, (char) => char.charCodeAt(0));
+    if (decoded.length === 32)
+      return decoded;
+  } catch {
+  }
+  return ENCODER.encode(value);
+}
+function base64UrlEncode2(value) {
+  return btoa(String.fromCharCode(...value)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlDecode(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "="));
+  return Uint8Array.from(raw, (char) => char.charCodeAt(0));
+}
+function toArrayBuffer(value) {
+  return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+}
+async function encryptSecret(keyPromise, secret, userId) {
+  const key = await keyPromise;
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: ENCODER.encode(userId) },
+    key,
+    ENCODER.encode(secret)
+  ));
+  return `v1.${base64UrlEncode2(iv)}.${base64UrlEncode2(ciphertext)}`;
+}
+async function decryptSecret(keyPromise, encrypted, userId) {
+  const [version, encodedIv, encodedCiphertext] = encrypted.split(".");
+  if (version !== "v1" || !encodedIv || !encodedCiphertext)
+    throw Errors.unauthorized("Two-factor enrolment uses an unsupported secret format; re-enrolment is required");
+  try {
+    const key = await keyPromise;
+    const iv = base64UrlDecode(encodedIv);
+    const ciphertext = base64UrlDecode(encodedCiphertext);
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: toArrayBuffer(iv), additionalData: ENCODER.encode(userId) },
+      key,
+      toArrayBuffer(ciphertext)
+    );
+    return DECODER.decode(plaintext);
+  } catch {
+    throw Errors.unauthorized("Unable to decrypt two-factor secret");
+  }
+}
+function generateSecret() {
+  const bytes = new Uint8Array(20);
+  crypto.getRandomValues(bytes);
+  return base32Encode(bytes);
+}
+function base32Encode(bytes) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  let bits = 0;
+  let value = 0;
+  let result = "";
+  for (const byte of bytes) {
+    value = value << 8 | byte;
+    bits += 8;
+    while (bits >= 5) {
+      result += alphabet[value >>> bits - 5 & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) {
+    result += alphabet[value << 5 - bits & 31];
+  }
+  return result;
+}
+var BASE32_PADDING = /=+$/;
+function base32Decode(encoded) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  const cleanInput = encoded.replace(BASE32_PADDING, "").toUpperCase();
+  let bits = 0;
+  let value = 0;
+  const output = [];
+  for (const char of cleanInput) {
+    const idx = alphabet.indexOf(char);
+    if (idx === -1)
+      continue;
+    value = value << 5 | idx;
+    bits += 5;
+    if (bits >= 8) {
+      output.push(value >>> bits - 8 & 255);
+      bits -= 8;
+    }
+  }
+  return new Uint8Array(output);
+}
+async function generateTOTPForCounter(secret, digits, counter) {
+  const counterBytes = new ArrayBuffer(8);
+  const view = new DataView(counterBytes);
+  view.setBigUint64(0, BigInt(counter));
+  const keyBytes = base32Decode(secret);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    keyBytes.buffer,
+    { name: "HMAC", hash: "SHA-1" },
+    false,
+    ["sign"]
+  );
+  const hmac = new Uint8Array(await crypto.subtle.sign("HMAC", key, counterBytes));
+  const offset = hmac.at(-1) & 15;
+  const code = ((hmac[offset] & 127) << 24 | (hmac[offset + 1] & 255) << 16 | (hmac[offset + 2] & 255) << 8 | hmac[offset + 3] & 255) % 10 ** digits;
+  return String(code).padStart(digits, "0");
+}
+async function generateTOTP(secret, period, digits, timeOffset = 0) {
+  const counter = Math.floor((Date.now() / 1e3 + timeOffset) / period);
+  return generateTOTPForCounter(secret, digits, counter);
+}
+async function verifyTOTPWithCounter(secret, code, period, digits) {
+  const currentCounter = Math.floor(Date.now() / 1e3 / period);
+  for (const counter of [currentCounter, currentCounter - 1, currentCounter + 1]) {
+    const expected = await generateTOTPForCounter(secret, digits, counter);
+    if (expected === code)
+      return counter;
+  }
+  return null;
+}
+async function verifyTOTP(secret, code, period, digits) {
+  return await verifyTOTPWithCounter(secret, code, period, digits) !== null;
+}
+function buildOtpauthUrl(secret, issuer, email, period, digits) {
+  const label = `${issuer}:${email}`;
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: "SHA1",
+    digits: String(digits),
+    period: String(period)
+  });
+  return `otpauth://totp/${encodeURIComponent(label)}?${params.toString()}`;
+}
+async function generateBackupCodes(count) {
+  const raw = [];
+  const hashes = [];
+  for (let i = 0; i < count; i++) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    const code = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    raw.push(code);
+    hashes.push(await hashToken(code));
+  }
+  return { raw, hashes };
+}
+function twoFactor(config) {
+  if (!config?.secretEncryptionKey)
+    throw Errors.badRequest("twoFactor requires secretEncryptionKey");
+  const keyBytes = decodeEncryptionKey(config.secretEncryptionKey);
+  if (keyBytes.length !== 32)
+    throw Errors.badRequest("twoFactor secretEncryptionKey must decode to exactly 32 bytes for AES-256-GCM");
+  const keyBuffer = keyBytes.buffer.slice(keyBytes.byteOffset, keyBytes.byteOffset + keyBytes.byteLength);
+  const encryptionKey = crypto.subtle.importKey("raw", keyBuffer, "AES-GCM", false, ["encrypt", "decrypt"]);
+  const issuer = config.totp?.issuer ?? "Fortress";
+  const period = config.totp?.period ?? 30;
+  const digits = config.totp?.digits ?? 6;
+  const backupCodeCount = config.backupCodes?.count ?? 10;
+  const trustedDeviceDays = config.trustedDeviceDays ?? 30;
+  const maxAttempts = config.maxAttempts ?? 5;
+  const failedAttemptCooldownSeconds = config.failedAttemptCooldownSeconds ?? 1;
+  async function verifyCode(db, userId, code, meta) {
+    const secretRecord = await db.findOne({
+      model: "two_factor_secret",
+      where: [{ field: "userId", operator: "=", value: userId }]
+    });
+    if (!secretRecord)
+      throw Errors.badRequest("Two-factor authentication is not set up");
+    const secret = await decryptSecret(encryptionKey, secretRecord.secret, userId);
+    const matchedCounter = await verifyTOTPWithCounter(secret, code, period, digits);
+    if (matchedCounter !== null) {
+      const previousCounter = secretRecord.lastUsedCounter;
+      if (previousCounter !== null && matchedCounter <= previousCounter)
+        throw Errors.unauthorized("Two-factor code has already been used");
+      const claimed2 = await db.update({
+        model: "two_factor_secret",
+        where: [
+          { field: "id", operator: "=", value: secretRecord.id },
+          previousCounter === null ? { field: "lastUsedCounter", operator: "isNull", value: null } : { field: "lastUsedCounter", operator: "=", value: previousCounter }
+        ],
+        data: { isEnabled: true, lastUsedCounter: matchedCounter }
+      });
+      if (!claimed2)
+        throw Errors.unauthorized("Two-factor code has already been used");
+      if (meta?.rememberDevice) {
+        const trusted = await generateRefreshToken();
+        const expiresAt = new Date(Date.now() + trustedDeviceDays * 24 * 60 * 60 * 1e3);
+        await db.create({
+          model: "trusted_device",
+          data: { userId, deviceHash: trusted.hash, expiresAt, lastUsedAt: /* @__PURE__ */ new Date() }
+        });
+        return trusted.raw;
+      }
+      return void 0;
+    }
+    const backupCodes = await db.findMany({
+      model: "backup_code",
+      where: [
+        { field: "userId", operator: "=", value: userId },
+        { field: "isUsed", operator: "=", value: false }
+      ]
+    });
+    const codeHash = await hashToken(code);
+    const matchingCode = backupCodes.find((backupCode) => backupCode.codeHash === codeHash);
+    if (!matchingCode)
+      throw Errors.unauthorized("Invalid two-factor code");
+    const claimed = await db.update({
+      model: "backup_code",
+      where: [
+        { field: "id", operator: "=", value: matchingCode.id },
+        { field: "isUsed", operator: "=", value: false }
+      ],
+      data: { isUsed: true }
+    });
+    if (!claimed)
+      throw Errors.unauthorized("Invalid two-factor code");
+    if (!secretRecord.isEnabled) {
+      await db.update({
+        model: "two_factor_secret",
+        where: [{ field: "id", operator: "=", value: secretRecord.id }],
+        data: { isEnabled: true }
+      });
+    }
+    if (meta?.rememberDevice) {
+      const trusted = await generateRefreshToken();
+      const expiresAt = new Date(Date.now() + trustedDeviceDays * 24 * 60 * 60 * 1e3);
+      await db.create({
+        model: "trusted_device",
+        data: { userId, deviceHash: trusted.hash, expiresAt, lastUsedAt: /* @__PURE__ */ new Date() }
+      });
+      return trusted.raw;
+    }
+    return void 0;
+  }
+  return {
+    name: "two-factor",
+    models: [
+      {
+        name: "two_factor_secret",
+        fields: {
+          id: { type: "number", required: true },
+          userId: { type: "number", required: true, unique: true, references: { model: "user", field: "id" } },
+          secret: { type: "string", required: true },
+          isEnabled: { type: "boolean", required: true },
+          lastUsedCounter: { type: "number" },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "backup_code",
+        fields: {
+          id: { type: "number", required: true },
+          userId: { type: "number", required: true, references: { model: "user", field: "id" } },
+          codeHash: { type: "string", required: true },
+          isUsed: { type: "boolean", required: true },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "trusted_device",
+        fields: {
+          id: { type: "number", required: true },
+          userId: { type: "number", required: true, references: { model: "user", field: "id" } },
+          deviceHash: { type: "string", required: true },
+          expiresAt: { type: "date", required: true },
+          lastUsedAt: { type: "date", required: true },
+          createdAt: { type: "date", required: true }
+        }
+      }
+    ],
+    hooks: {
+      postAuthGate: {
+        reason: "two-factor",
+        maxAttempts,
+        cooldownSeconds: failedAttemptCooldownSeconds,
+        async evaluate(ctx) {
+          const secret = await ctx.db.findOne({
+            model: "two_factor_secret",
+            where: [
+              { field: "userId", operator: "=", value: ctx.user.id },
+              { field: "isEnabled", operator: "=", value: true }
+            ]
+          });
+          if (!secret)
+            return;
+          if (ctx.meta?.trustedDeviceToken) {
+            const deviceHash = await hashToken(ctx.meta.trustedDeviceToken);
+            const trusted = await ctx.db.findOne({
+              model: "trusted_device",
+              where: [
+                { field: "userId", operator: "=", value: ctx.user.id },
+                { field: "deviceHash", operator: "=", value: deviceHash }
+              ]
+            });
+            if (trusted && trusted.expiresAt > /* @__PURE__ */ new Date()) {
+              await ctx.db.update({
+                model: "trusted_device",
+                where: [{ field: "id", operator: "=", value: trusted.id }],
+                data: { lastUsedAt: /* @__PURE__ */ new Date() }
+              });
+              return;
+            }
+          }
+          return { pluginData: { requires2FA: true } };
+        },
+        async verify(ctx, completion) {
+          if (typeof completion !== "string")
+            throw Errors.unauthorized("Invalid two-factor code");
+          const trustedDeviceToken = await verifyCode(ctx.db, ctx.user.id, completion, ctx.meta);
+          return trustedDeviceToken ? { trustedDeviceToken } : void 0;
+        }
+      }
+    },
+    methods: (ctx) => {
+      return {
+        async enable(userId) {
+          const user = await ctx.db.findOne({
+            model: "user",
+            where: [{ field: "id", operator: "=", value: userId }]
+          });
+          if (!user)
+            throw Errors.notFound("User not found");
+          const existing = await ctx.db.findOne({
+            model: "two_factor_secret",
+            where: [{ field: "userId", operator: "=", value: userId }]
+          });
+          if (existing?.isEnabled)
+            throw Errors.badRequest("Two-factor authentication is already enabled");
+          if (existing) {
+            await ctx.db.delete({
+              model: "two_factor_secret",
+              where: [{ field: "userId", operator: "=", value: userId }]
+            });
+            await ctx.db.delete({
+              model: "backup_code",
+              where: [{ field: "userId", operator: "=", value: userId }]
+            });
+          }
+          const secret = generateSecret();
+          const otpauthUrl = buildOtpauthUrl(secret, issuer, user.email, period, digits);
+          const { raw: backupCodesRaw, hashes } = await generateBackupCodes(backupCodeCount);
+          const encryptedSecret = await encryptSecret(encryptionKey, secret, userId);
+          await ctx.db.create({
+            model: "two_factor_secret",
+            data: { userId, secret: encryptedSecret, isEnabled: false, lastUsedCounter: null }
+          });
+          for (const hash of hashes) {
+            await ctx.db.create({
+              model: "backup_code",
+              data: { userId, codeHash: hash, isUsed: false }
+            });
+          }
+          return { secret, otpauthUrl, backupCodes: backupCodesRaw };
+        },
+        async confirmSetup(userId, code, meta) {
+          const trustedDeviceToken = await verifyCode(ctx.db, userId, code, meta);
+          return { verified: true, ...trustedDeviceToken ? { trustedDeviceToken } : {} };
+        },
+        async verify(continuationToken, code, meta) {
+          if (!ctx.auth)
+            throw Errors.badRequest("Auth service is unavailable");
+          return ctx.auth.completePendingAuth(continuationToken, code, meta);
+        },
+        async disable(userId) {
+          await ctx.db.delete({
+            model: "two_factor_secret",
+            where: [{ field: "userId", operator: "=", value: userId }]
+          });
+          await ctx.db.delete({
+            model: "backup_code",
+            where: [{ field: "userId", operator: "=", value: userId }]
+          });
+          await ctx.db.delete({
+            model: "trusted_device",
+            where: [{ field: "userId", operator: "=", value: userId }]
+          });
+        }
+      };
+    }
+  };
+}
+export {
+  generateTOTP,
+  twoFactor,
+  verifyTOTP
+};