fix(auth): make oauthLoginParam opt-in so PAT/password logins stop hitting portal 5014

loginWithRetry unconditionally injected oauthLoginParam into every login.
Portals that don't implement OAuth authorization-code login (e.g.
ap-southeast-1-aws.api.singdata.com) reject any credential login carrying it
with business code 5014, breaking pure username/password profiles.

oauthLoginParam/PKCE are now gated behind an opt-in `oauth` flag (default
false) on loginWithPat/loginWithPassword; the authorizationCode exchange is
guarded by `pkce && data.authorizationCode`. Only loginWithBrowser mints
refresh tokens; runtime refresh stays a plain credential exchange. Keeps the
four login methods (PAT, password, browser OAuth, cookie) independent.

Rewrites token-store/token-refresh/login-oauth tests to seed persisted OAuth
tokens via TokenStore instead of assuming a password login returns an OAuth
token. Translates stray Chinese comments in pkce test, task.ts, poll.ts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: suibianwanwan

packages/clickzetta-sdk/src/auth/login.ts

@@ -95,22 +95,32 @@ async function loginWithRetry(
   baseUrl: string,
   body: Record<string, unknown>,
   instance: string,
+  oauth: boolean,
 ): Promise<AuthToken> {
   let lastError: Error | undefined
   // client.py:305 — one request id for the entire login attempt sequence
   const requestId = generateRequestId()
 
+  // The three login methods (PAT, password, browser OAuth) are independent.
+  // PAT and password logins are plain credential exchanges and must NOT carry
+  // `oauthLoginParam` — portals that don't implement OAuth authorization-code
+  // login reject the whole request (business code 5014, "missing required
+  // parameter or otherwise malformed"). `oauthLoginParam` is attached ONLY when
+  // the caller explicitly opts into the OAuth upgrade (`oauth === true`).
+  //
   // PKCE is generated once per login sequence; codeVerifier stays in memory
   // only and is never logged. codeChallenge is sent to the portal so the
   // gateway can later validate the matching verifier at /oauth2/token.
-  const pkce = generatePkce()
-  const loginBody = {
-    ...body,
-    oauthLoginParam: buildOauthLoginParam({
-      redirectUri: OAUTH_REDIRECT_URI,
-      codeChallenge: pkce.codeChallenge,
-    }),
-  }
+  const pkce = oauth ? generatePkce() : undefined
+  const loginBody = pkce
+    ? {
+        ...body,
+        oauthLoginParam: buildOauthLoginParam({
+          redirectUri: OAUTH_REDIRECT_URI,
+          codeChallenge: pkce.codeChallenge,
+        }),
+      }
+    : body
 
   for (let attempt = 0; attempt <= LOGIN_MAX_RETRIES; attempt++) {
     try {
@@ -128,9 +138,11 @@ async function loginWithRetry(
       } else {
         const data = resp.data
         // OAuth path: a non-empty authorizationCode means the portal opted
-        // into the code exchange. Swap the legacy token for the OAuth tokens
-        // while keeping the portal-issued instanceId/userId.
-        if (data.authorizationCode) {
+        // into the code exchange. Only reachable when we sent PKCE (oauth ===
+        // true); the guard keeps this correct even if a portal echoes a code
+        // for a plain credential login. Swap the legacy token for the OAuth
+        // tokens while keeping the portal-issued instanceId/userId.
+        if (pkce && data.authorizationCode) {
           const oauth = await exchangeAuthorizationCode(baseUrl, data.authorizationCode, pkce.codeVerifier, OAUTH_REDIRECT_URI)
           return {
             token: oauth.accessToken,
@@ -174,20 +186,23 @@ export async function loginWithPat(
   baseUrl: string,
   pat: string,
   instanceName: string,
+  oauth = false,
 ): Promise<AuthToken> {
-  return loginWithRetry(baseUrl, { accessToken: pat, instanceName }, instanceName)
+  return loginWithRetry(baseUrl, { accessToken: pat, instanceName }, instanceName, oauth)
 }
 
 export async function loginWithPassword(
   baseUrl: string,
   username: string,
   password: string,
   instanceName: string,
+  oauth = false,
 ): Promise<AuthToken> {
   return loginWithRetry(
     baseUrl,
     { username, password, instanceName },
     instanceName,
+    oauth,
   )
 }
 

packages/clickzetta-sdk/src/sql/poll.ts

@@ -260,7 +260,7 @@ export function coerceValue(value: string | null, typeCategory: string, timezone
     return value.toLowerCase() === "true"
   }
 
-  // 时间类型
+  // Temporal types
   // DATE: TEXT format is already "YYYY-MM-DD", return as ISO string.
   if (upper === "DATE") {
     return value.trim()
@@ -275,7 +275,7 @@ export function coerceValue(value: string | null, typeCategory: string, timezone
     return normaliseTimestampText(value, upper)
   }
 
-  // 二进制
+  // Binary types
   if (upper === "BINARY" || upper === "VARBINARY") {
     return hexToBytes(value)
   }

packages/clickzetta-sdk/src/studio/task.ts

@@ -319,7 +319,7 @@ export interface SaveCdcTaskParams {
 
 export interface CdcStartupPositionConfig {
   datasourceId: number | string
-  startupMode: number   // 2=指定时间, 3=指定文件
+  startupMode: number   // 2=specific time, 3=specific file
   startTimestamp?: string   // unix ms string, for startupMode=2
   file?: string             // binlog file, for startupMode=3
   pos?: string              // binlog offset, for startupMode=3
@@ -329,7 +329,7 @@ export interface CdcTaskStartParams {
   fileId: number
   updateBy: string
   workspace: string
-  startupMode?: number          // 0=无状态启动, 1=从上次保存状态恢复, 4=自定义起始位置
+  startupMode?: number          // 0=stateless start, 1=resume from last saved state, 4=custom start position
   engineType?: number           // 5=default
   snapshotTaskSwitch?: number   // 0=off, 1=on
   snapshotTaskPoolSize?: number // snapshot concurrency (default 1, only when snapshotTaskSwitch=1)

packages/clickzetta-sdk/src/types/index.ts

@@ -53,7 +53,7 @@ export interface AuthToken {
   userId: number
   expireTimeMs: number
   obtainedAt: number
-  refreshToken?: string // OAuth refresh token；传统登录模式下为 undefined
+  refreshToken?: string // OAuth refresh token; undefined for legacy (PAT/password) logins
   // OAuth issuer host (no protocol, e.g. "api.clickzetta.com") — the OIDC
   // authorization server that issued this token. OAuth `/oauth2/token` is ONLY
   // served by the issuer, NOT the region business host in `config.service`

packages/clickzetta-sdk/test/login-oauth.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { createHash } from "node:crypto"
 
-import { loginWithPassword } from "../src/auth/login.js"
+import { loginWithPassword, loginWithPat } from "../src/auth/login.js"
 
 function base64Url(input: Buffer): string {
   return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "")
@@ -13,8 +13,58 @@ afterEach(() => {
   globalThis.fetch = originalFetch
 })
 
-describe("OAuth login", () => {
-  test("loginWithPassword sends oauthLoginParam and exchanges authorizationCode", async () => {
+describe("login OAuth opt-in", () => {
+  test("password login stays a plain credential exchange by default (no oauthLoginParam)", async () => {
+    let loginPayload: Record<string, unknown> | undefined
+    let tokenExchangeCalls = 0
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = new URL(String(input))
+      if (url.pathname === "/clickzetta-portal/user/loginSingle" && init?.method === "POST") {
+        loginPayload = JSON.parse(String(init.body)) as Record<string, unknown>
+        return new Response(JSON.stringify({
+          code: 0,
+          data: { token: "legacy-token", userId: 7, instanceId: 9, expireTime: 123 },
+        }), { status: 200, headers: { "content-type": "application/json" } })
+      }
+      if (url.pathname === "/clickzetta-hornhub/oauth2/token") tokenExchangeCalls += 1
+      return new Response("not found", { status: 404 })
+    }) as typeof fetch
+
+    const token = await loginWithPassword("https://service.example.com", "user", "pass", "inst")
+
+    // The whole payload is just credentials — no OAuth upgrade fields leak in.
+    expect(loginPayload?.username).toBe("user")
+    expect(loginPayload?.password).toBe("pass")
+    expect(loginPayload?.instanceName).toBe("inst")
+    expect(loginPayload?.oauthLoginParam).toBeUndefined()
+    expect(token.token).toBe("legacy-token")
+    expect(token.refreshToken).toBeUndefined()
+    expect(tokenExchangeCalls).toBe(0)
+  })
+
+  test("PAT login stays a plain credential exchange by default (no oauthLoginParam)", async () => {
+    let loginPayload: Record<string, unknown> | undefined
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = new URL(String(input))
+      if (url.pathname === "/clickzetta-portal/user/loginSingle" && init?.method === "POST") {
+        loginPayload = JSON.parse(String(init.body)) as Record<string, unknown>
+        return new Response(JSON.stringify({
+          code: 0,
+          data: { token: "legacy-token", userId: 7, instanceId: 9, expireTime: 123 },
+        }), { status: 200, headers: { "content-type": "application/json" } })
+      }
+      return new Response("not found", { status: 404 })
+    }) as typeof fetch
+
+    const token = await loginWithPat("https://service.example.com", "my-pat", "inst")
+
+    expect(loginPayload?.accessToken).toBe("my-pat")
+    expect(loginPayload?.instanceName).toBe("inst")
+    expect(loginPayload?.oauthLoginParam).toBeUndefined()
+    expect(token.token).toBe("legacy-token")
+  })
+
+  test("explicit oauth opt-in sends oauthLoginParam and exchanges authorizationCode", async () => {
     let loginPayload: Record<string, unknown> | undefined
     let tokenPayload: URLSearchParams | undefined
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
@@ -44,12 +94,9 @@ describe("OAuth login", () => {
       return new Response("not found", { status: 404 })
     }) as typeof fetch
 
-    const token = await loginWithPassword("https://service.example.com", "user", "pass", "inst")
+    const token = await loginWithPassword("https://service.example.com", "user", "pass", "inst", true)
 
     const oauthLoginParam = loginPayload?.oauthLoginParam as Record<string, unknown>
-    expect(loginPayload?.username).toBe("user")
-    expect(loginPayload?.password).toBe("pass")
-    expect(loginPayload?.instanceName).toBe("inst")
     expect(oauthLoginParam.oauthLogin).toBe(true)
     expect(oauthLoginParam.clientId).toBe("official-cli")
     expect(oauthLoginParam.redirectUri).toBe("http://127.0.0.1/callback")
@@ -67,28 +114,21 @@ describe("OAuth login", () => {
     expect(token.expireTimeMs).toBe(900_000)
   })
 
-  test("loginWithPassword keeps legacy token when authorizationCode is absent", async () => {
+  test("oauth opt-in without a returned authorizationCode keeps the legacy token", async () => {
     let tokenExchangeCalls = 0
     globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
       const url = new URL(String(input))
       if (url.pathname === "/clickzetta-portal/user/loginSingle" && init?.method === "POST") {
         return new Response(JSON.stringify({
           code: 0,
-          data: {
-            token: "legacy-token",
-            userId: 7,
-            instanceId: 9,
-            expireTime: 123,
-          },
+          data: { token: "legacy-token", userId: 7, instanceId: 9, expireTime: 123 },
         }), { status: 200, headers: { "content-type": "application/json" } })
       }
-      if (url.pathname === "/clickzetta-hornhub/oauth2/token") {
-        tokenExchangeCalls += 1
-      }
+      if (url.pathname === "/clickzetta-hornhub/oauth2/token") tokenExchangeCalls += 1
       return new Response("not found", { status: 404 })
     }) as typeof fetch
 
-    const token = await loginWithPassword("https://service.example.com", "user", "pass", "inst")
+    const token = await loginWithPassword("https://service.example.com", "user", "pass", "inst", true)
 
     expect(token.token).toBe("legacy-token")
     expect(tokenExchangeCalls).toBe(0)

packages/clickzetta-sdk/test/pkce.test.ts

@@ -11,8 +11,8 @@ function base64Url(input: Buffer): string {
 const UNRESERVED = /^[A-Za-z0-9\-._~]+$/
 
 describe("generatePkce", () => {
-  // Property 1: PKCE 一致性 — codeChallenge == base64url(sha256(codeVerifier)),
-  // codeVerifier 长度 ∈ [43,128] 且仅含 unreserved 字符。
+  // Property 1: PKCE consistency — codeChallenge == base64url(sha256(codeVerifier)),
+  // codeVerifier length ∈ [43,128] and uses only unreserved characters.
   // Validates: Requirements 2.1, 2.2
   test("codeChallenge equals base64url(sha256(codeVerifier)) with no padding", () => {
     for (let i = 0; i < 100; i++) {
@@ -25,7 +25,7 @@ describe("generatePkce", () => {
     }
   })
 
-  // Property 1: codeVerifier 长度 ∈ [43,128] 且仅含 RFC 7636 unreserved 字符。
+  // Property 1: codeVerifier length ∈ [43,128] and uses only RFC 7636 unreserved characters.
   // Validates: Requirements 2.1
   test("codeVerifier length is within [43,128] and uses only unreserved characters", () => {
     for (let i = 0; i < 100; i++) {
@@ -36,7 +36,7 @@ describe("generatePkce", () => {
     }
   })
 
-  // Property 2: PKCE 唯一性 — 连续多次生成的 codeVerifier 互不相同。
+  // Property 2: PKCE uniqueness — consecutive generations produce distinct codeVerifier values.
   // Validates: Requirements 2.3
   test("multiple calls produce distinct codeVerifier values", () => {
     const verifiers = Array.from({ length: 100 }, () => generatePkce().codeVerifier)