dsh-config-manager 0.1.78 → 0.1.80

package/src/sync/risk.ts

@@ -9,8 +9,16 @@
  *    本模块只做分流，`SECTION_RISK_TIER` 是注册表的派生视图（保留给既有调用方）；
  *  - 双向 conflict 分区永远进 review（无论风险与 firstSync 与否）；
  *  - firstSync=true 时所有非 skip 项一律进 review（安全第一：人工确认后才开启自动）；
- *  - firstSync=false 时按风险等级分流：低风险且 useRemote/keepLocal 进 autoApply；
- *    中风险、high、双向冲突 → review；skip 或无变化 → skipped。
+ *  - firstSync=false 时按风险等级分流：决策明确（useRemote / keepLocal / **merge** 即三方精细
+    合并成功）且「风险等级 ≤ maxAutoTier」的分区进 autoApply；超过阈值的、high、双向冲突 → review；
+    skip 或无变化 → skipped。
+ *  - 'merge' 与 useRemote/keepLocal 同等对待：它的 merged 是双方改动的合并结果（不是单侧原值）。
+ *
+ * maxAutoTier（真·自动同步，2026-10）：
+ *  - 缺省 'low' = 改造前的口径（只有低风险分区自动落盘），既有调用方（预览/UI）行为不变；
+ *  - 自动同步按用户配置传 'medium' ⇒ plugins / mcp 的中风险改动也自动落盘。
+ *    这是用户拍板的产品决策：不改这条，「同步所有更改」就只是句口号（中风险分区永远停在待确认）。
+ *  - **high 永远不参与自动应用**：类型上就只允许 low|medium，杜绝「传 high 顺手放行全部」。
  */
 import type { MergePlan, MergeSectionResult } from './merge.ts';
 import type { SectionId } from '../schema/types.ts';
@@ -48,6 +56,21 @@ export interface ClassifyOptions {
    * 调用方在 SyncEngine 中维护 firstSyncCompleted 标志。
    */
   firstSync: boolean;
+  /**
+   * 允许自动落盘的最高风险等级（缺省 'low' = 改造前的行为）。
+   *
+   * 只有自动同步路径会传 'medium'（用户在配置里显式选的，缺省也是 medium）；
+   * high 在类型层面就被排除 —— 那不是「配置项」，是安全边界。
+   */
+  maxAutoTier?: 'low' | 'medium';
+}
+
+/** 风险等级序（用于「等级 ≤ 阈值」比较；high 永不满足自动应用，因为阈值上限就是 medium）。 */
+const TIER_RANK: Readonly<Record<RiskTier, number>> = { low: 0, medium: 1, high: 2 };
+
+/** 该风险等级是否在允许自动落盘的阈值之内。 */
+export function tierWithinAutoApply(tier: RiskTier, maxAutoTier: 'low' | 'medium'): boolean {
+  return TIER_RANK[tier] <= TIER_RANK[maxAutoTier];
 }
 
 /** 自动应用三组结果（互斥：同一 sectionId 只出现在一组） */
@@ -65,6 +88,7 @@ export function classifyMergePlan(plan: MergePlan, opts: ClassifyOptions): SyncA
   const autoApply: MergeSectionResult[] = [];
   const review: MergeSectionResult[] = [];
   const skipped: MergeSectionResult[] = [];
+  const maxAutoTier = opts.maxAutoTier ?? 'low';
   for (const r of plan.sections) {
     // 跳过：决策为 skip（远端缺且本地未改 / 完全无变化）
     if (r.decision === 'skip') {
@@ -87,11 +111,11 @@ export function classifyMergePlan(plan: MergePlan, opts: ClassifyOptions): SyncA
       review.push(r);
       continue;
     }
-    if (tier === 'low') {
-      // 低风险且决策明确（useRemote / keepLocal）→ 自动应用
+    if (tierWithinAutoApply(tier, maxAutoTier)) {
+      // 决策明确（useRemote / keepLocal / merge）且等级在阈值内 → 自动应用
       autoApply.push(r);
     } else {
-      // medium / high → 待审
+      // 超过阈值（缺省阈值下即 medium / high）→ 待审
       review.push(r);
     }
   }

package/src/sync/s3/messages.ts

@@ -39,6 +39,13 @@ export const s3Zh = {
   'sync.s3.providerNoteKodo': '七牛 Kodo S3 兼容（region 必填，如 cn-east-1；endpoint 可覆盖）',
   'sync.s3.unknownSignatureDialect': '未知签名方言: {id}',
   'sync.s3.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}',
+  // ---- cloud-sync 借鉴项 ①②：条件写并发保护 + 连通性探针 ----
+  'sync.s3.concurrentWrite': '远端索引已被其它设备更新（HTTP {status}）：本次写入已中止，请重新同步后再试',
+  'sync.s3.probeOk': '连接正常（远端 {count} 份快照）',
+  'sync.s3.probeRegionRedirect': '端点把请求重定向到区域 {region}：请把 region 改成该值后重试',
+  'sync.s3.probeRedirectNoRegion': '端点返回了重定向（HTTP {status}）但没有给出区域：请核对 endpoint 与 region',
+  'sync.s3.probeBucketMissing': '桶不存在或无权访问（HTTP 404）：请核对 bucket 名与 endpoint',
+  'sync.s3.probeAccessDenied': '访问被拒绝（HTTP 403）：请核对 AccessKey、密钥与桶权限',
 } as const;
 
 export const s3En: Record<keyof typeof s3Zh, string> = {
@@ -67,6 +74,12 @@ export const s3En: Record<keyof typeof s3Zh, string> = {
   'sync.s3.providerNoteKodo': 'Qiniu Kodo S3-compatible (region required, e.g. cn-east-1; endpoint can be overridden)',
   'sync.s3.unknownSignatureDialect': 'Unknown signature dialect: {id}',
   'sync.s3.blobHashInvalid': 'Malformed content hash; refusing to write to the blob store: {hash}',
+  'sync.s3.concurrentWrite': 'The remote index was updated by another device (HTTP {status}): this write was aborted, please sync again',
+  'sync.s3.probeOk': 'Connection OK ({count} remote snapshots)',
+  'sync.s3.probeRegionRedirect': 'The endpoint redirects to region {region}: set region to that value and retry',
+  'sync.s3.probeRedirectNoRegion': 'The endpoint returned a redirect (HTTP {status}) without a region: check endpoint and region',
+  'sync.s3.probeBucketMissing': 'Bucket not found or not accessible (HTTP 404): check the bucket name and endpoint',
+  'sync.s3.probeAccessDenied': 'Access denied (HTTP 403): check the AccessKey, secret, and bucket permissions',
 };
 
 /** 插值：{param} → 形参值；缺参原样保留（与 core/messages.ts 同口径）。 */

package/src/sync/s3/s3-conditional-write.test.ts

@@ -0,0 +1,330 @@
+/**
+ * S3 兼容系通道：本轮借鉴项的**针对性**单测（不重复 s3-transport.test.ts 的既有契约）。
+ *  - ① 条件写：索引 ETag → if-match；索引缺失且远端无内容 → if-none-match: *；
+ *    索引 PUT 412 → conflict；409 **带条件头** → conflict；
+ *    409 **不带条件头** → 绝不走并发写冲突那条路径（isConcurrentWrite 只认带条件头的 409）；
+ *  - ② 探针：HEAD 回 301/307/308 + x-amz-bucket-region → 抛错且文案里带可执行的 region；
+ *    404 / 403 各自文案；HEAD 200 时读索引回报快照数。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { S3Transport, S3TransportError } from './s3-transport.ts';
+import type { S3RequestFn, S3Response, S3TransportOptions } from './s3-transport.ts';
+import { SyncTransportError } from '../transport.ts';
+import type { SyncSnapshot } from '../transport.ts';
+import { s3Msg } from './messages.ts';
+
+const ENDPOINT = 'https://minio.example.com:9000';
+const BUCKET = 'demo-bucket';
+const PREFIX = 'dsh-config-manager';
+const ACCESS_KEY_ID = 'AKIAIOSFODNN7EXAMPLE';
+const SECRET = 'wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY';
+const BASE_OBJECT = ENDPOINT + '/' + BUCKET + '/' + PREFIX;
+const INDEX_URL = BASE_OBJECT + '/index.json';
+const BLOBS_INDEX_URL = BASE_OBJECT + '/blobs-index.json';
+const SNAPSHOT_URL = BASE_OBJECT + '/snap-001.json';
+
+interface S3Call { method: string; url: string; headers: Record<string, string>; body?: string }
+
+function res(status: number, bodyText = '', headers?: Record<string, string>): S3Response {
+  return {
+    status,
+    ok: status >= 200 && status < 300,
+    ...(headers !== undefined ? { headers } : {}),
+    async text() { return bodyText; },
+  };
+}
+
+function record(calls: S3Call[], handler: (m: S3Call) => S3Response): S3RequestFn {
+  return async (method, url, opts = {}) => {
+    const rec: S3Call = { method, url, headers: opts.headers ?? {}, ...(opts.body !== undefined ? { body: opts.body } : {}) };
+    calls.push(rec);
+    return handler(rec);
+  };
+}
+
+function makeOptions(request: S3RequestFn, overrides: Partial<S3TransportOptions> = {}): S3TransportOptions {
+  return {
+    provider: 'minio',
+    endpoint: ENDPOINT,
+    region: 'us-east-1',
+    bucket: BUCKET,
+    accessKeyId: ACCESS_KEY_ID,
+    credentials: { getSecretAccessKey: async () => SECRET },
+    pathStyle: true,
+    request,
+    now: () => new Date('2026-10-18T10:00:00.000Z'),
+    ...overrides,
+  };
+}
+
+function sampleSnapshot(overrides: Partial<SyncSnapshot> = {}): SyncSnapshot {
+  return {
+    id: 'snap-001',
+    createdAt: '2026-10-18T10:00:00.000Z',
+    manifest: {
+      schemaVersion: 1,
+      dshVersion: '1.2.3',
+      platform: 'win32',
+      sectionIds: ['settings', 'providers'],
+      containsSecrets: false,
+    },
+    sections: {
+      settings: { version: 1, namespaces: { general: { value: { theme: 'dark' }, revision: 1, secrets: [] } } },
+      providers: { version: 1, providers: { deepseek: { route: '/v1' } } },
+    },
+    ...overrides,
+  };
+}
+
+const putIndexCalls = (calls: S3Call[]): S3Call[] => calls.filter((c) => c.method === 'PUT' && c.url === INDEX_URL);
+
+/* ---------------- ① 条件写 ---------------- */
+
+test('条件写①：索引 GET 回 ETag → 索引 PUT 带 if-match（小写头）钉住该 ETag', async () => {
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, '[]', { etag: '"v1-s3"' });
+    if (m.method === 'PUT' && m.url === SNAPSHOT_URL) return res(200, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(200, '');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await t.upload(sampleSnapshot());
+
+  const puts = putIndexCalls(calls);
+  assert.equal(puts.length, 1, '索引只 PUT 一次');
+  assert.equal(puts[0]!.headers['if-match'], '"v1-s3"', '有 ETag 时必须用 if-match');
+  assert.equal(puts[0]!.headers['if-none-match'], undefined);
+});
+
+test('条件写①：索引 404 且远端无内容（blobs-index 404）→ 索引 PUT 带 if-none-match: *', async () => {
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(404, '');
+    if (m.method === 'GET' && m.url === BLOBS_INDEX_URL) return res(404, '');
+    if (m.method === 'PUT' && m.url === SNAPSHOT_URL) return res(200, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(200, '');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await t.upload(sampleSnapshot());
+
+  const puts = putIndexCalls(calls);
+  assert.equal(puts.length, 1);
+  assert.equal(puts[0]!.headers['if-none-match'], '*', '首推（远端无内容）必须用 if-none-match: * 防两设备同时首推');
+  assert.equal(puts[0]!.headers['if-match'], undefined);
+});
+
+test('条件写①：索引 PUT 回 412（带条件头）→ 抛 conflict，文案来自 sync.s3.concurrentWrite', async () => {
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, '[]', { etag: '"v1-s3"' });
+    if (m.method === 'PUT' && m.url === SNAPSHOT_URL) return res(200, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(412, 'PreconditionFailed');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await assert.rejects(
+    () => t.upload(sampleSnapshot()),
+    (err: unknown) => {
+      assert.ok(err instanceof S3TransportError);
+      assert.ok(err instanceof SyncTransportError, '统一错误基类（上层按 kind 分流）');
+      assert.equal(err.kind, 'conflict');
+      assert.equal(err.retryable, false);
+      assert.equal(err.status, 412);
+      assert.equal(err.message, s3Msg('sync.s3.concurrentWrite', { status: '412', url: INDEX_URL }));
+      return true;
+    },
+  );
+});
+
+test('条件写①：索引 PUT 回 409 且**带了条件头** → 仍判 conflict（S3 兼容端点的并发写语义）', async () => {
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, '[]', { etag: '"v1-s3"' });
+    if (m.method === 'PUT' && m.url === SNAPSHOT_URL) return res(200, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(409, 'Conflict');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await assert.rejects(
+    () => t.upload(sampleSnapshot()),
+    (err: unknown) => {
+      assert.ok(err instanceof S3TransportError);
+      assert.equal(err.kind, 'conflict');
+      assert.equal(err.status, 409);
+      assert.equal(err.message, s3Msg('sync.s3.concurrentWrite', { status: '409', url: INDEX_URL }));
+      return true;
+    },
+  );
+});
+
+test('回归：索引 PUT 回 409 但**没带条件头** → 不得被当成并发写冲突（SSE/无条件写场景）', async () => {
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    // 服务端不返回 ETag、索引又存在（非 404）⇒ 条件头为空 ⇒ 无条件写
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, '[]');
+    if (m.method === 'PUT' && m.url === SNAPSHOT_URL) return res(200, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(409, 'Conflict');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await assert.rejects(
+    () => t.upload(sampleSnapshot()),
+    (err: unknown) => {
+      assert.ok(err instanceof S3TransportError);
+      assert.equal(err.status, 409);
+      const put = putIndexCalls(calls)[0]!;
+      assert.equal(Object.keys(put.headers).filter((k) => k === 'if-match' || k === 'if-none-match').length, 0,
+        '本用例前提：这一 PUT 确实没带条件头');
+      assert.notEqual(
+        err.message,
+        s3Msg('sync.s3.concurrentWrite', { status: '409', url: INDEX_URL }),
+        '无条件的 409 另有含义，绝不能套用「远端被其它设备改过」的并发写文案',
+      );
+      assert.equal(
+        err.message,
+        s3Msg('sync.s3.requestFailed', { method: 'PUT', url: INDEX_URL, status: '409', err: 'Conflict' }),
+        '应走通用请求失败文案（isConcurrentWrite 只认带条件头的 409）',
+      );
+      return true;
+    },
+  );
+});
+
+test('条件写①（删除路径）：delete 读 index 拿 ETag → 写回剩余索引的 PUT 带 if-match；412 → conflict', async () => {
+  const meta = {
+    id: 'snap-001',
+    createdAt: '2026-10-18T09:00:00.000Z',
+    sections: {},
+    manifest: { schemaVersion: 1, dshVersion: '1', platform: 'win32', sectionIds: [], containsSecrets: false },
+  };
+  const make = (putStatus: number) => new S3Transport(makeOptions(record([], (m) => {
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, JSON.stringify([meta]), { etag: '"v1-del"' });
+    if (m.method === 'DELETE' && m.url === SNAPSHOT_URL) return res(204, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(putStatus, putStatus === 412 ? 'PreconditionFailed' : '');
+    if (m.method === 'GET' && m.url === BLOBS_INDEX_URL) return res(404, '');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, JSON.stringify([meta]), { etag: '"v1-del"' });
+    if (m.method === 'DELETE' && m.url === SNAPSHOT_URL) return res(204, '');
+    if (m.method === 'PUT' && m.url === INDEX_URL) return res(200, '');
+    if (m.method === 'GET' && m.url === BLOBS_INDEX_URL) return res(404, '');
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+  await t.delete('snap-001');
+  const put = putIndexCalls(calls)[0]!;
+  assert.equal(put.headers['if-match'], '"v1-del"', '删除路径的索引写回同样是条件写');
+  assert.equal(put.body, '[]');
+
+  await assert.rejects(
+    () => make(412).delete('snap-001'),
+    (err: unknown) => {
+      assert.ok(err instanceof S3TransportError);
+      assert.equal(err.kind, 'conflict');
+      assert.equal(err.status, 412);
+      assert.equal(err.message, s3Msg('sync.s3.concurrentWrite', { status: '412', url: INDEX_URL }));
+      return true;
+    },
+  );
+});
+
+/* ---------------- ② 探针 ---------------- */
+
+test('② 探针：HEAD 回 301 + x-amz-bucket-region: cn-hangzhou → 抛错且文案含该 region', async () => {
+  const calls: S3Call[] = [];
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'HEAD') return res(301, '', { 'x-amz-bucket-region': 'cn-hangzhou' });
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  await assert.rejects(
+    () => t.probe(),
+    (err: unknown) => {
+      assert.ok(err instanceof S3TransportError);
+      assert.equal(err.status, 301);
+      assert.equal(err.kind, 'client');
+      assert.equal(err.message, s3Msg('sync.s3.probeRegionRedirect', { region: 'cn-hangzhou' }));
+      assert.match(err.message, /cn-hangzhou/, '文案必须给出可执行的 region 提示');
+      return true;
+    },
+  );
+  assert.equal(calls.length, 1, '301 应立即抛错，不再读索引');
+});
+
+test('② 探针：region 头缺失 / 大写形态 → 分别走「无 region 提示」与正常解析', async () => {
+  const callsA: S3Call[] = [];
+  const tA = new S3Transport(makeOptions(record(callsA, (m) => (m.method === 'HEAD' ? res(307, '') : res(500, '')))));
+  await assert.rejects(
+    () => tA.probe(),
+    (err: unknown) => {
+      assert.equal((err as S3TransportError).message, s3Msg('sync.s3.probeRedirectNoRegion', { status: '307' }));
+      assert.equal((err as S3TransportError).status, 307);
+      return true;
+    },
+  );
+
+  const callsB: S3Call[] = [];
+  const tB = new S3Transport(makeOptions(record(callsB, (m) => {
+    if (m.method === 'HEAD') return res(308, '', { 'X-Amz-Bucket-Region': 'ap-guangzhou' });
+    return res(500, '');
+  })));
+  await assert.rejects(
+    () => tB.probe(),
+    (err: unknown) => {
+      assert.equal((err as S3TransportError).message, s3Msg('sync.s3.probeRegionRedirect', { region: 'ap-guangzhou' }));
+      return true;
+    },
+  );
+});
+
+test('② 探针：HEAD 404 → 桶不存在文案（kind=notfound）；HEAD 403 → 权限文案（kind=auth）', async () => {
+  const mk = (status: number): S3Transport => new S3Transport(makeOptions(record([], (m) => {
+    if (m.method === 'HEAD') return res(status, '');
+    return res(500, '');
+  })));
+
+  await assert.rejects(
+    () => mk(404).probe(),
+    (err: unknown) => {
+      assert.equal((err as S3TransportError).message, s3Msg('sync.s3.probeBucketMissing'));
+      assert.equal((err as S3TransportError).kind, 'notfound');
+      assert.equal((err as S3TransportError).status, 404);
+      return true;
+    },
+  );
+  await assert.rejects(
+    () => mk(403).probe(),
+    (err: unknown) => {
+      assert.equal((err as S3TransportError).message, s3Msg('sync.s3.probeAccessDenied'));
+      assert.equal((err as S3TransportError).kind, 'auth');
+      assert.equal((err as S3TransportError).status, 403);
+      return true;
+    },
+  );
+});
+
+test('② 探针：HEAD 200 + index 有 1 条 → snapshotCount=1、message 带计数、零写入', async () => {
+  const calls: S3Call[] = [];
+  const meta = {
+    id: 'snap-a',
+    createdAt: '2026-10-18T08:00:00.000Z',
+    sections: {},
+    manifest: { schemaVersion: 1, dshVersion: '1', platform: 'win32', sectionIds: [], containsSecrets: false },
+  };
+  const t = new S3Transport(makeOptions(record(calls, (m) => {
+    if (m.method === 'HEAD') return res(200, '');
+    if (m.method === 'GET' && m.url === INDEX_URL) return res(200, JSON.stringify([meta]));
+    return res(500, 'unexpected ' + m.method + ' ' + m.url);
+  })));
+
+  const result = await t.probe();
+  assert.equal(result.snapshotCount, 1);
+  assert.equal(result.message, s3Msg('sync.s3.probeOk', { count: '1' }));
+  assert.equal(calls.filter((c) => c.method === 'PUT' || c.method === 'DELETE').length, 0, '探针零写入');
+});

package/src/sync/s3/s3-transport.test.ts

@@ -291,7 +291,8 @@ test('阿里云 OSS 变体：请求头走 OSS4（x-oss-date / x-oss-content-sha2
   assert.equal(call.headers['x-oss-date'], '20261005T014910Z');
   assert.equal(call.headers['x-oss-content-sha256'], 'UNSIGNED-PAYLOAD');
   assert.equal(call.headers['x-amz-date'], undefined);
-  assert.match(call.headers['authorization'] ?? '', /^OSS4-HMAC-SHA256 Credential=.*\/cn-hangzhou\/oss\/aliyun_v4_request, AdditionalHeaders=, Signature=[a-f0-9]{64}$/);
+  // 官方 SDK 格式：无空格、空 AdditionalHeaders 省略（issue #109：写成 ", AdditionalHeaders=, Signature=" 会被 OSS 拒绝）
+  assert.match(call.headers['authorization'] ?? '', /^OSS4-HMAC-SHA256 Credential=.*\/cn-hangzhou\/oss\/aliyun_v4_request,Signature=[a-f0-9]{64}$/);
 });
 
 test('密钥纪律：错误消息里的响应体被脱敏（密钥绝不出现），且目标对象不含任何密钥', async () => {

package/src/sync/s3/s3-transport.ts

@@ -37,7 +37,7 @@ import {
   isEncryptedSections, sectionsEqual, SyncTransportError, withSyncRetry,
 } from '../transport.ts';
 import type {
-  SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
+  SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions,
 } from '../transport.ts';
 import { signRequest } from './sigv4.ts';
 import type { SigV4DialectId } from './sigv4.ts';
@@ -57,6 +57,21 @@ const ERR_BODY_MAX = 500;
 const BLOB_HASH_RE = /^[a-f0-9]{64}$/;
 const REDACTED = '[REDACTED]';
 
+/**
+ * 条件写头（cloud-sync 借鉴项 ①）：有 ETag → If-Match（远端必须仍是我读到的那一版）；
+ * 索引本来就不存在 → If-None-Match: *（防两设备同时首推）；服务端不给 ETag → 空（无条件写，不改既有行为）。
+ */
+function conditionalHeaders(etag: string | undefined, indexMissing: boolean): Record<string, string> {
+  if (etag !== undefined) return { 'if-match': etag };
+  return indexMissing ? { 'if-none-match': '*' } : {};
+}
+
+/** 条件写失败判定：412 恒是；409 仅在**确实带了条件头**时才算（无条件的 409 另有含义，不吞）。 */
+function isConcurrentWrite(status: number, headers: Record<string, string>): boolean {
+  if (status === 412) return true;
+  return status === 409 && Object.keys(headers).length > 0;
+}
+
 /** 请求选项：headers / body / 覆盖默认超时（ms；0 = 不超时） */
 export interface S3RequestOptions {
   headers?: Record<string, string>;
@@ -258,7 +273,7 @@ export class S3Transport implements SyncTransport {
     const secret = await this.secretOnce();
     const meta = computeSnapshotMeta(snapshot);
     // audit-sync sync-N1 覆盖面补全（t66，来自 t22 的 C7）：upload 也是写路径，**不接受 404 = 空集合**。
-    const { entries: idxBefore, missing: indexMissing } = await this.readIndexDetailed(secret);
+    const { entries: idxBefore, missing: indexMissing, etag: idxEtag } = await this.readIndexDetailed(secret);
     if (indexMissing && await this.remoteHasPriorContent(secret)) {
       // 索引 404 只是**缺信息**：远端已有历史内容时按空索引读改写，会把权威索引 PUT 成只有本条目
       // → 其余快照从列表整体消失，随后 delete + GC 会回收仍被现存快照文件引用的 blob（不可恢复）。
@@ -281,7 +296,13 @@ export class S3Transport implements SyncTransport {
     const merged = idxBefore.filter((m) => m.id !== snapshot.id);
     merged.push(meta);
     merged.sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
-    const putIdx = await this.send('PUT', indexKey(this.target.prefix), { body: JSON.stringify(merged), secret });
+    const condHeaders = conditionalHeaders(idxEtag, indexMissing);
+    const putIdx = await this.send('PUT', indexKey(this.target.prefix), {
+      body: JSON.stringify(merged),
+      secret,
+      headers: condHeaders,
+    });
+    if (isConcurrentWrite(putIdx.res.status, condHeaders)) throw this.concurrentWrite(putIdx.url, putIdx.res.status);
     if (!putIdx.res.ok) {
       throw new S3TransportError(await this.failText('PUT', putIdx.url, putIdx.res, secret), classifyHttpStatus(putIdx.res.status));
     }
@@ -318,7 +339,7 @@ export class S3Transport implements SyncTransport {
     // index.json 覆盖成 []（其余快照从列表消失）并让 blob GC 删掉仍被引用的会话 blob —— 一律中止。
     // audit-sync sync-N1（P0）：与 WebDAV 同型 —— 写路径**不接受 404 = 空集合**。索引真缺失时
     // 「远端一条快照都没有」是缺信息而非事实，沿用空索引会覆盖 index.json 并用空引用集回收 blob。
-    const { entries: idx, missing: indexMissing } = await this.readIndexDetailed(secret);
+    const { entries: idx, missing: indexMissing, etag: idxEtag } = await this.readIndexDetailed(secret);
     const del = await this.send('DELETE', snapshotKey(this.target.prefix, id), { secret });
     if (!del.res.ok && del.res.status !== 404) {
       throw new S3TransportError(await this.failText('DELETE', del.url, del.res, secret), classifyHttpStatus(del.res.status));
@@ -328,7 +349,13 @@ export class S3Transport implements SyncTransport {
     if (indexMissing) return;
     const remaining = idx.filter((m) => m.id !== id);
     if (remaining.length === idx.length && del.res.status === 404) return; // 对象与索引都没有 → 静默成功
-    const putIdx = await this.send('PUT', indexKey(this.target.prefix), { body: JSON.stringify(remaining), secret });
+    const condHeaders = conditionalHeaders(idxEtag, false);
+    const putIdx = await this.send('PUT', indexKey(this.target.prefix), {
+      body: JSON.stringify(remaining),
+      secret,
+      headers: condHeaders,
+    });
+    if (isConcurrentWrite(putIdx.res.status, condHeaders)) throw this.concurrentWrite(putIdx.url, putIdx.res.status);
     if (!putIdx.res.ok) {
       throw new S3TransportError(await this.failText('PUT', putIdx.url, putIdx.res, secret), classifyHttpStatus(putIdx.res.status));
     }
@@ -337,6 +364,46 @@ export class S3Transport implements SyncTransport {
 
   /* ---------------- 内部实现 ---------------- */
 
+  /** 条件写失败：远端索引在本次读取之后被别人改过 —— 中止写入让用户重跑（cloud-sync 借鉴项 ①）。 */
+  private concurrentWrite(url: string, status: number): S3TransportError {
+    return new S3TransportError(
+      this.o.msg('sync.s3.concurrentWrite', { status: String(status), url }),
+      { kind: 'conflict', retryable: false, status },
+    );
+  }
+
+  /**
+   * 连通性探针（cloud-sync 借鉴项 ②）：HEAD 桶证明端点/凭据/桶可达，再读一次索引回报快照数。
+   * 重定向（301/307/308）时读 x-amz-bucket-region 直接把「region 该填什么」告诉用户 ——
+   * 这是 S3 兼容端点最常见的失败原因（AWS/OSS/COS/Kodo 各自的 region 值不同）。
+   */
+  async probe(): Promise<SyncProbeResult> {
+    const secret = await this.secretOnce();
+    const bucket = await this.send('HEAD', '', { secret });
+    const status = bucket.res.status;
+    if (status === 301 || status === 307 || status === 308) {
+      const region = bucket.res.headers?.['x-amz-bucket-region'] ?? bucket.res.headers?.['X-Amz-Bucket-Region'];
+      throw new S3TransportError(
+        region !== undefined && region !== ''
+          ? this.o.msg('sync.s3.probeRegionRedirect', { region })
+          : this.o.msg('sync.s3.probeRedirectNoRegion', { status: String(status) }),
+        { kind: 'client', retryable: false, status },
+      );
+    }
+    if (status === 404) {
+      throw new S3TransportError(this.o.msg('sync.s3.probeBucketMissing'), { kind: 'notfound', retryable: false, status });
+    }
+    if (status === 403) {
+      throw new S3TransportError(this.o.msg('sync.s3.probeAccessDenied'), { kind: 'auth', retryable: false, status });
+    }
+    if (!bucket.res.ok) {
+      throw new S3TransportError(await this.failText('HEAD', bucket.url, bucket.res, secret), classifyHttpStatus(status));
+    }
+    const { entries, missing } = await this.readIndexDetailed(secret);
+    const count = missing ? 0 : entries.length;
+    return { message: this.o.msg('sync.s3.probeOk', { count: String(count) }), snapshotCount: count };
+  }
+
   private assertSafeId(id: string): void {
     if (typeof id !== 'string' || !SAFE_ID_RE.test(id) || RESERVED_IDS.has(id)) {
       throw new S3TransportError(this.o.msg('sync.s3.invalidSnapshotId', { id: JSON.stringify(id) }));
@@ -356,10 +423,15 @@ export class S3Transport implements SyncTransport {
   private async send(
     method: string,
     key: string,
-    opts: { body?: string; secret: string },
+    opts: { body?: string; secret: string; headers?: Record<string, string> },
   ): Promise<{ res: S3Response; url: string }> {
     const url = objectUrl(this.target, key);
-    const headers: Record<string, string> = { 'content-type': 'application/json' };
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      // 条件写头（if-match / if-none-match）从这里注入（cloud-sync 借鉴项 ①）；
+      // 签名在注入之后计算，因此条件头也进 SignedHeaders。
+      ...(opts.headers ?? {}),
+    };
     if (opts.body !== undefined) headers['content-length'] = String(Buffer.byteLength(opts.body, 'utf8'));
     const signed = signRequest({
       method,
@@ -440,13 +512,19 @@ export class S3Transport implements SyncTransport {
    * 读索引的**带缺失标志**版本（audit-sync sync-N1，与 WebDAV 同型）：
    * 404 → `missing = true`（缺信息，不是事实）；其它非 2xx / 非法 → 抛错（F2 语义）。
    */
-  private async readIndexDetailed(secret: string): Promise<{ entries: SyncSnapshotMeta[]; missing: boolean }> {
+  private async readIndexDetailed(secret: string): Promise<{ entries: SyncSnapshotMeta[]; missing: boolean; etag?: string }> {
     const sent = await this.send('GET', indexKey(this.target.prefix), { secret });
     if (sent.res.status === 404) return { entries: [], missing: true };
     if (!sent.res.ok) {
       throw new S3TransportError(await this.failText('GET', sent.url, sent.res, secret), classifyHttpStatus(sent.res.status));
     }
-    return { entries: this.parseIndex(await sent.res.text(), sent.url, secret), missing: false };
+    // ETag 是条件写的前置条件（cloud-sync 借鉴项 ①）；服务端没给就退化为无条件写，绝不判成失败。
+    const etag = sent.res.headers?.['etag'];
+    return {
+      entries: this.parseIndex(await sent.res.text(), sent.url, secret),
+      missing: false,
+      ...(typeof etag === 'string' && etag !== '' ? { etag } : {}),
+    };
   }
 
   private parseIndex(raw: string, url: string, secret: string): SyncSnapshotMeta[] {

package/src/sync/s3/sigv4.test.ts

@@ -156,7 +156,10 @@ test('OSS4 方言：algorithm/头名/UNSIGNED-PAYLOAD/AdditionalHeaders/scope
   assert.equal(out.headers['x-oss-content-sha256'], UNSIGNED_PAYLOAD, 'OSS4 只支持 UNSIGNED-PAYLOAD');
   assert.equal(out.headers['x-amz-date'], undefined, 'OSS4 不得出现 AWS 头名');
   assert.equal(out.credentialScope, '20261005/cn-hangzhou/oss/aliyun_v4_request');
-  assert.match(out.authorization, /^OSS4-HMAC-SHA256 Credential=LTAIEXAMPLE\/20261005\/cn-hangzhou\/oss\/aliyun_v4_request, AdditionalHeaders=, Signature=[a-f0-9]{64}$/);
+  // 官方 Go/PHP SDK 的格式：逗号后无空格，AdditionalHeaders 为空时整段省略（issue #109）
+  assert.match(out.authorization, /^OSS4-HMAC-SHA256 Credential=LTAIEXAMPLE\/20261005\/cn-hangzhou\/oss\/aliyun_v4_request,Signature=[a-f0-9]{64}$/);
+  assert.equal(out.authorization.includes(', '), false, 'OSS4 授权头不得有逗号后的空格');
+  assert.equal(out.authorization.includes('AdditionalHeaders='), false, '没有附加头时不得写空的 AdditionalHeaders=');
   assert.equal(out.stringToSign.split('\n')[0], 'OSS4-HMAC-SHA256');
   // 规范化头只含 content-type 与 x-oss-*（host 默认不参与）
   assert.equal(out.canonicalRequest.split('\n')[3], 'content-type:application/json');

package/src/sync/s3/sigv4.ts

@@ -269,8 +269,17 @@ export function signRequest(input: SigV4RequestInput): SigV4RequestOutput {
     dialect,
   });
   const signature = createHmac('sha256', signingKey).update(stringToSign, 'utf8').digest('hex');
-  const authorization = dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
-    + ', ' + dialect.headerListLabel + '=' + headerList + ', Signature=' + signature;
+  // 授权头序列化按方言分两套（issue #109 实证）：
+  //  - AWS：AWS4-HMAC-SHA256 Credential=<ak>/<scope>, SignedHeaders=<list>, Signature=<sig>
+  //  - OSS4：官方 Go/PHP SDK 的格式是**逗号后不带空格**，且 AdditionalHeaders 为空时**整段省略**；
+  //    写成 ", AdditionalHeaders=, Signature=" 会被 OSS 判成 Authorization header value is empty.
+  //    （HTTP 400 InvalidArgument，错误码 EC 0002-00000209，真机逐一比对过两种格式）。
+  const authorization = dialect.headerListLabel === 'AdditionalHeaders'
+    ? dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
+      + (headerList === '' ? '' : ',' + dialect.headerListLabel + '=' + headerList)
+      + ',Signature=' + signature
+    : dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
+      + ', ' + dialect.headerListLabel + '=' + headerList + ', Signature=' + signature;
 
   return {
     headers: { ...all, authorization },