diff --git a/src/claim/runtime.test.ts b/src/claim/runtime.test.ts new file mode 100644 index 0000000..c6340c1 --- /dev/null +++ b/src/claim/runtime.test.ts @@ -0,0 +1,45 @@ +/** + * Tests for the claim-plane wiring helpers. + * + * `claimDeviceMid` exists because the billing gateway rejects every preview / + * claim call that arrives without a UUID `X-Device-Mid` (biz 3001 "parameter + * error", client.ts file header). A config with no `identity.deviceMid` used to + * reach the claim POST with the header omitted — the observed Android symptom + * was `[claim] claim: invalid_request (3001) — parameter error`, even though + * the marketing face could still enumerate the plan via its own fallback. + */ +import { describe, it, expect } from "bun:test"; +import { claimDeviceMid } from "./runtime.js"; +import type { ProxyConfig } from "../config/types.js"; + +const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/; + +function configWith(deviceMid?: string): ProxyConfig { + return { + identity: { + appVersion: "3.18.2", + sourceTitle: "cli", + refererOrigin: "https://zcode.z.ai", + ...(deviceMid !== undefined ? { deviceMid } : {}), + }, + } as ProxyConfig; +} + +describe("claimDeviceMid", () => { + it("uses the configured identity.deviceMid verbatim", () => { + expect(claimDeviceMid(configWith("0d2c62ae-717c-4d88-9bbe-24c28fd45ed6"))) + .toBe("0d2c62ae-717c-4d88-9bbe-24c28fd45ed6"); + }); + + it("treats a blank/whitespace value as unset", () => { + expect(claimDeviceMid(configWith(" "))).toMatch(UUID_V4); + }); + + it("falls back to a stable UUIDv4 when the config carries none", () => { + const first = claimDeviceMid(configWith()); + expect(first).toMatch(UUID_V4); + // Fingerprint stability: upstream risk engines require one device id per + // install — never randomize per call. + expect(claimDeviceMid(configWith())).toBe(first); + }); +}); diff --git a/src/claim/runtime.ts b/src/claim/runtime.ts index 1c57c26..ce770bf 100644 --- a/src/claim/runtime.ts +++ b/src/claim/runtime.ts @@ -41,6 +41,19 @@ function claimCaptchaRequired(config: ProxyConfig, resolveCredential: () => Prom .catch(() => true); } +/** + * Device identity for the claim plane. Configured value (YAML, or the + * `ZCODE_IDENTITY_DEVICE_MID` env NodeRunner injects on Android) first — the + * gateway answers biz 3001 "parameter error" to any billing call whose + * `X-Device-Mid` is missing or not a UUID (client.ts file header). The billing + * face has no fallback of its own, so a config without `identity.deviceMid` + * used to enumerate plans (marketing face falls back here) and then fail the + * claim POST with 3001 — hence the shared derived fallback. + */ +export function claimDeviceMid(config: ProxyConfig): string { + return config.identity.deviceMid?.trim() || stableMarketingDeviceMid(); +} + export function startAutoClaim(config: ProxyConfig, auth: AuthManager): ClaimScheduler { const scheduler = new ClaimScheduler({ // AuthManager first (fresh), then the encrypted store — on Android the @@ -59,8 +72,8 @@ export function startAutoClaim(config: ProxyConfig, auth: AuthManager): ClaimSch jwt, appVersion: config.identity.appVersion, platform: claimPlatform(), - deviceMid: config.identity.deviceMid, - marketingDeviceMid: config.identity.deviceMid ?? stableMarketingDeviceMid(), + deviceMid: claimDeviceMid(config), + marketingDeviceMid: claimDeviceMid(config), }), getCaptcha: async () => { const token = await getCaptchaToken(config.identity.appVersion); @@ -112,8 +125,8 @@ export async function runClaimCli(config: ProxyConfig, mode: "list" | "now"): Pr jwt, appVersion: config.identity.appVersion, platform: claimPlatform(), - deviceMid: config.identity.deviceMid, - marketingDeviceMid: config.identity.deviceMid ?? stableMarketingDeviceMid(), + deviceMid: claimDeviceMid(config), + marketingDeviceMid: claimDeviceMid(config), }); let plans: ClaimablePlan[]; diff --git a/src/config/loader.test.ts b/src/config/loader.test.ts index 8454241..2475141 100644 --- a/src/config/loader.test.ts +++ b/src/config/loader.test.ts @@ -23,6 +23,7 @@ beforeEach(() => { delete process.env.ZCODE_PROVIDER; delete process.env.ZCODE_SOURCE_TITLE; delete process.env.ZCODE_REFERER_ORIGIN; + delete process.env.ZCODE_IDENTITY_DEVICE_MID; delete process.env.ZCODE_ASYNC_ENABLED; delete process.env.ZCODE_ASYNC_ORIGIN; delete process.env.ZCODE_CLAIM_ENABLED; @@ -82,6 +83,35 @@ identity: `); expect(loadConfig(path).identity.deviceMid).toBe("0f1e2d3c-4b5a-4978-8796-a5b4c3d2e1f0"); }); + + // Android: NodeRunner injects the app-private UUID as an env var and never + // writes identity.deviceMid into config.yaml — the claim plane reads the + // resolved value, so dropping the env here made every claim POST hit biz + // 3001 "parameter error" (missing X-Device-Mid) on the app. + it("takes identity.deviceMid from ZCODE_IDENTITY_DEVICE_MID when YAML has none", () => { + const path = writeYaml(` +server: + port: 9090 +provider: zai +`); + process.env.ZCODE_IDENTITY_DEVICE_MID = "0d2c62ae-717c-4d88-9bbe-24c28fd45ed6"; + expect(loadConfig(path).identity.deviceMid).toBe("0d2c62ae-717c-4d88-9bbe-24c28fd45ed6"); + }); + + it("prefers ZCODE_IDENTITY_DEVICE_MID over YAML (blank env falls through)", () => { + const path = writeYaml(` +server: + port: 9090 +provider: zai +identity: + deviceMid: "0f1e2d3c-4b5a-4978-8796-a5b4c3d2e1f0" +`); + process.env.ZCODE_IDENTITY_DEVICE_MID = "11111111-2222-4333-8444-555555555555"; + expect(loadConfig(path).identity.deviceMid).toBe("11111111-2222-4333-8444-555555555555"); + + process.env.ZCODE_IDENTITY_DEVICE_MID = " "; + expect(loadConfig(path).identity.deviceMid).toBe("0f1e2d3c-4b5a-4978-8796-a5b4c3d2e1f0"); + }); }); describe("loadConfig", () => { diff --git a/src/config/loader.ts b/src/config/loader.ts index 8461f2c..5ac70b2 100644 --- a/src/config/loader.ts +++ b/src/config/loader.ts @@ -12,6 +12,7 @@ const ENV = { PROVIDER: "ZCODE_PROVIDER", SOURCE_TITLE: "ZCODE_SOURCE_TITLE", REFERER_ORIGIN: "ZCODE_REFERER_ORIGIN", + IDENTITY_DEVICE_MID: "ZCODE_IDENTITY_DEVICE_MID", ASYNC_ENABLED: "ZCODE_ASYNC_ENABLED", ASYNC_ORIGIN: "ZCODE_ASYNC_ORIGIN", ASYNC_MAX_RETRIES: "ZCODE_ASYNC_MAX_RETRIES", @@ -139,6 +140,7 @@ export function loadConfig(path: string): ProxyConfig { sourceTitleYaml: parsed?.identity?.sourceTitle, refererEnv: process.env[ENV.REFERER_ORIGIN], refererYaml: parsed?.identity?.refererOrigin, + deviceMidEnv: process.env[ENV.IDENTITY_DEVICE_MID], deviceMidYaml: parsed?.identity?.deviceMid, }); @@ -396,6 +398,7 @@ interface IdentityInputs { sourceTitleYaml?: string; refererEnv?: string; refererYaml?: string; + deviceMidEnv?: string; deviceMidYaml?: string; } @@ -408,7 +411,13 @@ function resolveIdentity(inp: IdentityInputs): ProxyIdentity { const refererOrigin = (inp.refererEnv ?? inp.refererYaml ?? DEFAULTS.REFERER_ORIGIN).trim() || DEFAULTS.REFERER_ORIGIN; - const deviceMid = typeof inp.deviceMidYaml === "string" ? inp.deviceMidYaml.trim() : ""; + // env > YAML (identity.ts applies the same order to the request headers, so + // both planes agree on one fingerprint). Android has no deviceMid to persist + // — NodeRunner injects ZCODE_IDENTITY_DEVICE_MID instead, and the claim plane + // reads this resolved value (a missing X-Device-Mid is rejected as biz 3001). + const deviceMid = [inp.deviceMidEnv, inp.deviceMidYaml] + .map((v) => (typeof v === "string" ? v.trim() : "")) + .find((v) => v.length > 0) ?? ""; return { appVersion: DEFAULT_APP_VERSION, sourceTitle, refererOrigin, ...(deviceMid ? { deviceMid } : {}) }; }