wechat-oauth-service.ts

import { createHmac, timingSafeEqual } from "node:crypto";
import { AppError } from "../core/errors";

const WECHAT_AUTHORIZE_URL = "https://open.weixin.qq.com/connect/oauth2/authorize";
const WECHAT_ACCESS_TOKEN_URL = "https://api.weixin.qq.com/sns/oauth2/access_token";
const WECHAT_USERINFO_URL = "https://api.weixin.qq.com/sns/userinfo";
const STATE_TTL_MS = 10 * 60 * 1_000;
const SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1_000;

interface WeChatOAuthServiceOptions {
  appId?: string;
  appSecret?: string;
  publicBaseUrl?: string;
  oauthScope?: "snsapi_base" | "snsapi_userinfo";
  sessionSecret?: string;
}

interface SignedStatePayload {
  shareSlug: string;
  issuedAt: number;
}

interface SignedIdentitySessionPayload {
  platformUserId: string;
  displayName: string;
  issuedAt: number;
  expiresAt: number;
}

interface WeChatAccessTokenResponse {
  access_token?: string;
  expires_in?: number;
  refresh_token?: string;
  openid?: string;
  scope?: string;
  unionid?: string;
  errcode?: number;
  errmsg?: string;
}

interface WeChatUserInfoResponse {
  openid?: string;
  nickname?: string;
  unionid?: string;
  errcode?: number;
  errmsg?: string;
}

export interface WeChatIdentityProfile {
  platformUserId: string;
  displayName: string;
}

export class WeChatOAuthService {
  constructor(private readonly options: WeChatOAuthServiceOptions) {}

  isConfigured(): boolean {
    return Boolean(
      this.options.appId &&
      this.options.appSecret &&
      this.options.publicBaseUrl,
    );
  }

  buildAuthorizationUrl(shareSlug: string): string {
    this.assertConfigured();

    const url = new URL(WECHAT_AUTHORIZE_URL);
    url.searchParams.set("appid", this.options.appId as string);
    url.searchParams.set("redirect_uri", this.getRedirectUri());
    url.searchParams.set("response_type", "code");
    url.searchParams.set("scope", this.options.oauthScope ?? "snsapi_userinfo");
    url.searchParams.set("state", this.signPayload<SignedStatePayload>({
      shareSlug,
      issuedAt: Date.now(),
    }));
    return `${url.toString()}#wechat_redirect`;
  }

  verifyState(state: string): SignedStatePayload {
    this.assertConfigured();
    const payload = this.verifyPayload<SignedStatePayload>(
      state,
      "The WeChat sign-in link is invalid or expired.",
    );

    if (
      typeof payload.shareSlug !== "string" ||
      typeof payload.issuedAt !== "number" ||
      Date.now() - payload.issuedAt > STATE_TTL_MS
    ) {
      throw new AppError("WeChat OAuth state payload was invalid.", {
        statusCode: 400,
        userMessage: "The WeChat sign-in link is invalid or expired.",
      });
    }

    return payload;
  }

  async exchangeCodeForIdentity(code: string): Promise<WeChatIdentityProfile> {
    this.assertConfigured();

    const tokenUrl = new URL(WECHAT_ACCESS_TOKEN_URL);
    tokenUrl.searchParams.set("appid", this.options.appId as string);
    tokenUrl.searchParams.set("secret", this.options.appSecret as string);
    tokenUrl.searchParams.set("code", code);
    tokenUrl.searchParams.set("grant_type", "authorization_code");

    const tokenResponse = await fetch(tokenUrl.toString());
    if (!tokenResponse.ok) {
      throw new AppError("WeChat OAuth token exchange failed.", {
        statusCode: 502,
        userMessage: "WeChat sign-in failed. Try the join link again.",
      });
    }

    const tokenPayload = (await tokenResponse.json()) as WeChatAccessTokenResponse;
    if (tokenPayload.errcode || !tokenPayload.openid) {
      throw new AppError(`WeChat OAuth token exchange failed: ${tokenPayload.errmsg ?? "unknown error"}.`, {
        statusCode: 502,
        userMessage: "WeChat sign-in failed. Try the join link again.",
      });
    }

    const platformUserId = tokenPayload.unionid ?? tokenPayload.openid;
    const displayName = await this.resolveDisplayName(tokenPayload);

    return {
      platformUserId,
      displayName,
    };
  }

  createIdentitySession(identity: WeChatIdentityProfile): string {
    this.assertConfigured();
    return this.signPayload<SignedIdentitySessionPayload>({
      platformUserId: identity.platformUserId,
      displayName: identity.displayName,
      issuedAt: Date.now(),
      expiresAt: Date.now() + SESSION_TTL_MS,
    });
  }

  verifyIdentitySession(token: string): WeChatIdentityProfile {
    this.assertConfigured();
    const payload = this.verifyPayload<SignedIdentitySessionPayload>(
      token,
      "WeChat sign-in has expired. Open the join link again in WeChat.",
    );

    if (
      typeof payload.platformUserId !== "string" ||
      typeof payload.displayName !== "string" ||
      typeof payload.issuedAt !== "number" ||
      typeof payload.expiresAt !== "number" ||
      Date.now() > payload.expiresAt
    ) {
      throw new AppError("WeChat identity session payload was invalid.", {
        statusCode: 400,
        userMessage: "WeChat sign-in has expired. Open the join link again in WeChat.",
      });
    }

    return {
      platformUserId: payload.platformUserId,
      displayName: payload.displayName,
    };
  }

  private async resolveDisplayName(tokenPayload: WeChatAccessTokenResponse): Promise<string> {
    const defaultLabel = `WeChat User ${tokenPayload.openid?.slice(-4) ?? ""}`.trim();
    const scope = tokenPayload.scope ?? "";

    if (
      !scope.includes("snsapi_userinfo") ||
      !tokenPayload.access_token ||
      !tokenPayload.openid
    ) {
      return defaultLabel;
    }

    const userInfoUrl = new URL(WECHAT_USERINFO_URL);
    userInfoUrl.searchParams.set("access_token", tokenPayload.access_token);
    userInfoUrl.searchParams.set("openid", tokenPayload.openid);
    userInfoUrl.searchParams.set("lang", "en_US");

    const userInfoResponse = await fetch(userInfoUrl.toString());
    if (!userInfoResponse.ok) {
      return defaultLabel;
    }

    const userInfo = (await userInfoResponse.json()) as WeChatUserInfoResponse;
    if (userInfo.errcode || !userInfo.nickname) {
      return defaultLabel;
    }

    return userInfo.nickname;
  }

  private signPayload<T extends object>(payload: T): string {
    const encodedPayload = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
    return `${encodedPayload}.${this.createSignature(encodedPayload).toString("base64url")}`;
  }

  private verifyPayload<T>(value: string, userMessage: string): T {
    const [encodedPayload, signature] = value.split(".");
    if (!encodedPayload || !signature) {
      throw new AppError("Signed payload was malformed.", {
        statusCode: 400,
        userMessage,
      });
    }

    const expectedSignature = this.createSignature(encodedPayload);
    const actualSignature = this.decodeSignature(signature);

    if (
      expectedSignature.length !== actualSignature.length ||
      !timingSafeEqual(expectedSignature, actualSignature)
    ) {
      throw new AppError("Signed payload signature did not match.", {
        statusCode: 400,
        userMessage,
      });
    }

    try {
      return JSON.parse(Buffer.from(encodedPayload, "base64url").toString("utf8")) as T;
    } catch {
      throw new AppError("Signed payload could not be parsed.", {
        statusCode: 400,
        userMessage,
      });
    }
  }

  private createSignature(encodedPayload: string): Buffer {
    return createHmac("sha256", this.getSigningSecret())
      .update(encodedPayload)
      .digest();
  }

  private decodeSignature(signature: string): Buffer {
    try {
      return Buffer.from(signature, "base64url");
    } catch {
      throw new AppError("WeChat OAuth signature could not be decoded.", {
        statusCode: 400,
        userMessage: "The WeChat sign-in link is invalid or expired.",
      });
    }
  }

  private getRedirectUri(): string {
    return new URL("/auth/wechat/callback", ensureTrailingSlash(this.options.publicBaseUrl as string)).toString();
  }

  private getSigningSecret(): string {
    return this.options.sessionSecret ?? (this.options.appSecret as string);
  }

  private assertConfigured(): void {
    if (this.isConfigured()) {
      return;
    }

    throw new AppError("WeChat OAuth service is missing required configuration.", {
      statusCode: 500,
      userMessage: "WeChat sign-in is not configured on this server yet.",
    });
  }
}

function ensureTrailingSlash(value: string): string {
  return value.endsWith("/") ? value : `${value}/`;
}