@xiashe/sdk 0.1.22 → 0.1.24

package/alipayWallet.mjs

@@ -41,6 +41,8 @@ const SAFE_OFFICIAL_FAILURE_CODES = new Set([
   'SELLER_ID_EMPTY',
   'TRADE_STATUS_INVALID'
 ]);
+const SAFE_OFFICIAL_FIELD_VALUE = /^[A-Za-z][A-Za-z0-9_.:-]{2,127}$/;
+const SAFE_OFFICIAL_ERROR_MESSAGE = /^(?!.*(?:https?:\/\/|payment[-_ ]?needed|payment[-_ ]?proof|seller_signature|authorization\s*:|runtimeToken|client[_ -]?session|(?:access|refresh)[_-]?token|credential|\b[A-Za-z0-9_-]{80,}\b)).{1,240}$/i;
 
 const OFFICIAL_ERROR_DIAGNOSES = {
   PAYMENT_NEEDED_REJECTED: {
@@ -142,6 +144,52 @@ function safeDiagnostic(value) {
   return SENSITIVE_OUTPUT.test(text) ? 'protocol_payload_processed' : 'official_wallet_response_received';
 }
 
+function explicitJsonString(output, fields) {
+  for (const field of fields) {
+    const match = output.match(new RegExp(`"${field}"\\s*:\\s*("(?:\\\\.|[^"\\\\])*")`, 'i'));
+    if (!match) continue;
+    try {
+      const value = JSON.parse(match[1]);
+      if (typeof value === 'string') return value;
+    } catch {
+      // Do not fall back to arbitrary vendor text: it can carry protocol data.
+    }
+  }
+  return null;
+}
+
+/**
+ * The official client may include Payment-Needed, Payment-Proof, credentials,
+ * or mutable diagnostic text. Persist only explicit, bounded support fields.
+ */
+function safeOfficialDiagnostic(stdout, stderr) {
+  const output = `${stdout}\n${stderr}`;
+  const pick = (fields) => {
+    const value = explicitJsonString(output, fields);
+    return value && SAFE_OFFICIAL_FIELD_VALUE.test(value) ? value : null;
+  };
+  const code = pick(['errorCode', 'error_code', 'previous_error', 'code']);
+  const message = explicitJsonString(output, ['errorMsg', 'subMsg', 'error_message', 'message']);
+  return {
+    code,
+    subCode: pick(['subCode', 'sub_code']),
+    requestId: pick(['requestId', 'request_id']),
+    traceId: pick(['traceId', 'trace_id']),
+    // For known downstream codes, our normalized recovery text is safer and
+    // more useful than arbitrary vendor prose. TRADE_PROGRESS_FAILED is the
+    // one generic wallet-creation code where the official short message adds
+    // context without exposing protocol material.
+    ...(code?.toUpperCase() === 'TRADE_PROGRESS_FAILED' && message && SAFE_OFFICIAL_ERROR_MESSAGE.test(message.trim())
+      ? { message: safeText(message, 240) }
+      : {})
+  };
+}
+
+function safeRuntimeVersion(stdout, stderr) {
+  const match = `${stdout}\n${stderr}`.match(/\balipay-bot(?:-cli)?\s+v?(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)/i);
+  return match?.[1] || null;
+}
+
 function normalizeResourceUrl(value) {
   let url;
   try {
@@ -340,10 +388,10 @@ function walletFailureCode(stdout, stderr, exitCode) {
  * credentials, URLs, trade identifiers, or PayGuard internals.
  */
 function safeOfficialFailureCode(stdout, stderr) {
-  const output = `${stdout}\n${stderr}`;
-  const candidates = [
-    ...output.matchAll(/(?:"(?:errorCode|code|sub_code|previous_error)"|\b(?:errorCode|code|sub_code|previous_error)\b)\s*[:=]\s*["']?([A-Z][A-Z0-9_]{2,80})/ig)
-  ].map((match) => match[1].toUpperCase());
+  const official = safeOfficialDiagnostic(stdout, stderr);
+  const candidates = [official.code, official.subCode]
+    .filter(Boolean)
+    .map((candidate) => candidate.toUpperCase());
   return candidates.find((candidate) => SAFE_OFFICIAL_FAILURE_CODES.has(candidate)) || null;
 }
 
@@ -358,12 +406,17 @@ function safeMerchantDiagnosticCode(stdout, stderr) {
 }
 
 function paymentFailureDiagnosis(failureCode, stdout, stderr) {
+  const official = safeOfficialDiagnostic(stdout, stderr);
   const officialCode = safeOfficialFailureCode(stdout, stderr);
   const merchantDiagnostic = safeMerchantDiagnosticCode(stdout, stderr);
   const base = {
     code: failureCode,
     stage: 'official_wallet_trade_creation',
-    nextStep: '不要重复付款；保留诊断代码和本次 attemptId 以便定位。'
+    nextStep: '不要重复付款；保留诊断代码和本次 attemptId 以便定位。',
+    ...(official.subCode ? { officialSubCode: official.subCode } : {}),
+    ...(official.requestId ? { officialRequestId: official.requestId } : {}),
+    ...(official.traceId ? { officialTraceId: official.traceId } : {}),
+    ...(official.message ? { officialMessage: official.message } : {})
   };
   if (officialCode && OFFICIAL_ERROR_DIAGNOSES[officialCode]) {
     return {
@@ -435,6 +488,10 @@ function paymentFailureUserVisible(diagnosis) {
     `诊断代码：${diagnosis.code}`,
     `失败阶段：${diagnosis.stage}`,
     ...(diagnosis.officialCode ? [`官方返回代码：${diagnosis.officialCode}`] : []),
+    ...(diagnosis.officialSubCode ? [`官方子码：${diagnosis.officialSubCode}`] : []),
+    ...(diagnosis.officialMessage ? [`官方消息：${diagnosis.officialMessage}`] : []),
+    ...(diagnosis.officialRequestId ? [`官方请求标识：${diagnosis.officialRequestId}`] : []),
+    ...(diagnosis.officialTraceId ? [`官方追踪标识：${diagnosis.officialTraceId}`] : []),
     ...(diagnosis.merchantDiagnostic ? [`商家验证诊断：${diagnosis.merchantDiagnostic}`] : []),
     `下一步：${diagnosis.nextStep}`
   ];
@@ -480,7 +537,7 @@ async function fetchPaymentNeeded(resourceUrl, options = {}) {
     if (!paymentNeeded) {
       throw new AlipayWalletError('ALIPAY_RESOURCE_PAYMENT_NEEDED_MISSING', '支付资源未返回有效的支付宝付款请求。');
     }
-    return { paymentNeeded };
+    return { paymentNeeded, responseStatus: response.status };
   } catch (error) {
     if (error instanceof AlipayWalletError) throw error;
     if (error?.name === 'AbortError') {
@@ -492,6 +549,102 @@ async function fetchPaymentNeeded(resourceUrl, options = {}) {
   }
 }
 
+/**
+ * Validate only the public shape of a 402 bill in memory. This is deliberately
+ * not a wallet call and never returns the bill, its signature, or any payment
+ * credentials to the caller.
+ */
+function validatePaymentNeededShape(paymentNeeded) {
+  let bill;
+  try {
+    bill = JSON.parse(Buffer.from(String(paymentNeeded), 'base64url').toString('utf8'));
+  } catch {
+    return {
+      ok: false,
+      checks: [{ id: 'payment_needed_encoding', ok: false }]
+    };
+  }
+  const protocol = bill?.protocol && typeof bill.protocol === 'object' ? bill.protocol : {};
+  const method = bill?.method && typeof bill.method === 'object' ? bill.method : {};
+  const sellerId = safeText(protocol.seller_unique_id, 80);
+  const methodSellerId = safeText(method.seller_id, 80);
+  const amount = safeText(protocol.amount, 32);
+  const payBefore = safeText(protocol.pay_before, 80);
+  const checks = [
+    {
+      id: 'payment_needed_encoding',
+      ok: true
+    },
+    {
+      id: 'protocol_fields',
+      ok: Boolean(
+        safeText(protocol.out_trade_no, 200) &&
+        /^\d+(?:\.\d{1,2})?$/.test(amount) && Number(amount) > 0 &&
+        safeText(protocol.currency, 16).toUpperCase() === 'CNY' &&
+        safeText(protocol.resource_id, 1_000) &&
+        payBefore && Number.isFinite(Date.parse(payBefore)) &&
+        safeText(protocol.seller_signature, 8_000) &&
+        safeText(protocol.seller_sign_type, 32).toUpperCase() === 'RSA2' &&
+        /^2088\d{8,}$/.test(sellerId)
+      )
+    },
+    {
+      id: 'merchant_fields',
+      ok: Boolean(
+        safeText(method.seller_name, 160) &&
+        /^2088\d{8,}$/.test(methodSellerId) &&
+        safeText(method.seller_app_id, 80) &&
+        safeText(method.goods_name, 160) &&
+        safeText(method.seller_unique_id_key, 80) === 'seller_id' &&
+        safeText(method.service_id, 160)
+      )
+    },
+    {
+      id: 'seller_identity_consistency',
+      ok: Boolean(sellerId && sellerId === methodSellerId)
+    }
+  ];
+  return { ok: checks.every((check) => check.ok), checks };
+}
+
+/**
+ * Read-only seller-resource preflight. It proves that this exact resource
+ * produces a structurally valid 402 bill, but never opens the wallet or
+ * attempts to create a trade.
+ */
+export async function preflightAlipay402Resource(input, options = {}) {
+  const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
+  const resource = await fetchPaymentNeeded(resourceUrl, options);
+  if (resource.alreadyPaid) {
+    return {
+      ok: true,
+      status: 'resource_already_available',
+      provider: 'alipay-agent-payment',
+      walletInvoked: false,
+      message: '该资源已可访问，无需再次创建付款账单。',
+      checks: [{ id: 'resource_access', ok: true }]
+    };
+  }
+  const validation = validatePaymentNeededShape(resource.paymentNeeded);
+  return {
+    ok: validation.ok,
+    status: validation.ok ? 'payment_needed_ready' : 'payment_needed_invalid',
+    provider: 'alipay-agent-payment',
+    walletInvoked: false,
+    resourceStatus: resource.responseStatus,
+    message: validation.ok
+      ? '虾舍已为该资源签发字段结构有效的支付宝 402 账单；尚未调用钱包或创建交易，且未验证支付宝端服务状态、已登记公钥或账单签名。'
+      : '虾舍资源返回了 402，但账单结构不符合支付宝 AI收要求；未调用钱包。',
+    validationScope: {
+      billFields: true,
+      sellerSignatureVerifiedByAlipay: false,
+      merchantServiceVerifiedByAlipay: false,
+      transactionCreationVerified: false
+    },
+    checks: validation.checks
+  };
+}
+
 function publicPaymentResult(state, status, diagnostic, options = {}) {
   const commandFailed = options.commandFailed === true;
   const failureCode = options.failureCode || 'official_cli_nonzero_exit';
@@ -505,6 +658,7 @@ function publicPaymentResult(state, status, diagnostic, options = {}) {
     walletInvoked: true,
     message: failed ? paymentFailureMessage(failureCode) : paymentMessage(status),
     diagnostic,
+    ...(options.merchantResource ? { merchantResource: options.merchantResource } : {}),
     ...(failed && diagnosis ? { userVisible: paymentFailureUserVisible(diagnosis), diagnosis } : {}),
     ...(!failed && options.userVisible ? { userVisible: options.userVisible } : {}),
     ...(options.officialMedia ? { officialMedia: options.officialMedia } : {}),
@@ -531,11 +685,15 @@ export async function checkAlipayWallet(options = {}) {
 /** Checks that the official buyer CLI is present, without querying wallet state. */
 export async function getAlipayWalletBridgeInfo(options = {}) {
   const { stdout, stderr } = await runOfficialCli(['--version'], options);
+  const runtimeVersion = safeRuntimeVersion(stdout, stderr);
   return {
     ok: true,
-    state: 'available',
+    state: 'runtime_available',
     provider: 'alipay-agent-payment',
-    message: '支付宝官方付款桥已可用；付款时将由支付宝 App 请求确认。',
+    message: '已找到支付宝官方钱包程序；这只表示程序可执行，尚未检查钱包授权或交易资格。',
+    walletStateChecked: false,
+    transactionCreationVerified: false,
+    ...(runtimeVersion ? { runtimeVersion } : {}),
     diagnostic: safeDiagnostic(stdout || stderr)
   };
 }
@@ -566,6 +724,11 @@ export async function payAlipay402Resource(input, options = {}) {
     return publicPaymentResult(state, 'completed', 'resource_already_available');
   }
 
+  const billValidation = validatePaymentNeededShape(resource.paymentNeeded);
+  if (!billValidation.ok) {
+    throw new AlipayWalletError('ALIPAY_PAYMENT_NEEDED_INVALID', '虾舍返回的支付宝付款账单结构无效；未调用钱包或创建交易。');
+  }
+
   const paths = statePaths(resourceUrl, options);
   await ensurePrivateDirectory(paths.directory);
   await writePrivateFile(paths.paymentNeededPath, resource.paymentNeeded);
@@ -576,6 +739,10 @@ export async function payAlipay402Resource(input, options = {}) {
     sessionId: randomUUID(),
     paymentNeededPath: paths.paymentNeededPath,
     queryCredential: null,
+    merchantResource: {
+      paymentNeededReceived: true,
+      billShapeValidated: true
+    },
     status: 'started',
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString()
@@ -618,7 +785,8 @@ export async function payAlipay402Resource(input, options = {}) {
     userVisible: ['pending_confirmation', 'completed'].includes(status)
       ? userVisibleWalletOutput(walletInvocation.stdout, walletInvocation.stderr)
       : null,
-    officialMedia
+    officialMedia,
+    merchantResource: state.merchantResource
   });
 }
 
@@ -701,6 +869,7 @@ export async function diagnoseAlipay402Resource(input, options = {}) {
     walletInvoked: state.status !== 'started',
     queryAvailable: Boolean(state.queryCredential?.value),
     diagnostic: state.lastWalletDiagnostic || 'payment_state_recorded',
+    merchantResource: state.merchantResource || null,
     ...(state.lastFailureCode ? { failureCode: state.lastFailureCode } : {}),
     ...(state.lastDiagnosis ? {
       diagnosis: state.lastDiagnosis,

package/index.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
 
-export const VERSION = '0.1.22';
+export const VERSION = '0.1.24';
 
 export const DEFAULTS = {
   cn: {
@@ -1362,6 +1362,7 @@ export {
   AlipayWalletError,
   checkAlipayWallet,
   getAlipayWalletBridgeInfo,
+  preflightAlipay402Resource,
   payAlipay402Resource,
   queryAlipay402Resource,
   diagnoseAlipay402Resource

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "main": "index.mjs",
   "exports": {