dsh-config-manager 0.1.69 → 0.1.71

package/lib/sync/s3/sigv4.js

@@ -0,0 +1,196 @@
+/**
+ * 手写 SigV4 签名（AWS SigV4 / 阿里云 OSS4），零第三方依赖（node:crypto 足够）。
+ *
+ * 为什么手写：竞品 \`@dickpy/dsh-cloud-sync\` v0.20.9（零依赖、lib 2610 行）证明五家 S3 兼容
+ * 对象存储共用同一套「派生密钥 → 规范化请求 → 待签字符串 → HMAC」流程，差异只在**方言参数**：
+ *  - AWS S3 / MinIO / 腾讯云 COS / 七牛 Kodo：\`AWS4-HMAC-SHA256\` + \`x-amz-date\` +
+ *    \`x-amz-content-sha256\`（载荷 SHA-256 十六进制）+ scope 终止符 \`aws4_request\`，
+ *    授权头里用 \`SignedHeaders=host;x-amz-date;...\`（**全部**已发头参与规范化）；
+ *  - 阿里云 OSS：\`OSS4-HMAC-SHA256\` + \`x-oss-date\` + \`x-oss-content-sha256: UNSIGNED-PAYLOAD\`
+ *    + 派生密钥前缀 \`aliyun_v4\` + 终止符 \`aliyun_v4_request\`，授权头里用
+ *    \`AdditionalHeaders=<可选头>\`，且**只有** \`content-type\`/\`content-md5\`/\`x-oss-*\` 参与规范化头
+ *    （\`host\` 默认不参与）。依据 = 阿里云《在 Header 中包含 V4 签名》+ 官方 SDK
+ *    \`aliyun-oss-java-sdk\` 的 \`OSSV4Signer\`（2026-10 读码确证）。
+ *  因此本文件把「同一实现 + 方言参数表」落成 \`SigV4Dialect\`：新增同类厂商只加一行参数。
+ *
+ * 纪律：
+ *  - 纯函数 + 可注入时间（\`now\`），同一输入两次签名**逐字相同**（单测钉住）；
+ *  - secretAccessKey 只在内存里参与 HMAC，绝不写入返回值之外的任何地方，也绝不进日志；
+ *  - 不做任何 I/O：请求头的注入与发送由通道层（s3-transport）负责。
+ */
+import { createHash, createHmac } from 'node:crypto';
+/** 「不校验载荷」的载荷哈希字面量（OSS4 目前只支持该取值）。 */
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+/** AWS SigV4（S3 / MinIO / COS / Kodo 共用）。 */
+export const AWS_SIG_V4 = {
+    id: 'aws4',
+    algorithm: 'AWS4-HMAC-SHA256',
+    dateHeader: 'x-amz-date',
+    contentShaHeader: 'x-amz-content-sha256',
+    secretKeyPrefix: 'AWS4',
+    terminator: 'aws4_request',
+    headerSelection: 'all',
+    payloadHash: 'sha256',
+    headerListLabel: 'SignedHeaders',
+};
+/** 阿里云 OSS4（OSS 原生 V4；与 AWS 同构但头名/前缀/终止符/载荷形态不同）。 */
+export const OSS_SIG_V4 = {
+    id: 'oss4',
+    algorithm: 'OSS4-HMAC-SHA256',
+    dateHeader: 'x-oss-date',
+    contentShaHeader: 'x-oss-content-sha256',
+    secretKeyPrefix: 'aliyun_v4',
+    terminator: 'aliyun_v4_request',
+    headerSelection: 'oss-default',
+    payloadHash: 'unsigned',
+    headerListLabel: 'AdditionalHeaders',
+};
+/** 方言查表（非法 id 抛错：绝不静默回落成 AWS，否则 OSS 会以「签名不对」的形式失败）。 */
+export function sigV4Dialect(id) {
+    if (id === 'aws4')
+        return AWS_SIG_V4;
+    if (id === 'oss4')
+        return OSS_SIG_V4;
+    throw new Error('未知签名方言: ' + String(id));
+}
+/** SHA-256 十六进制小写。 */
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** HMAC-SHA256（返回 Buffer，供逐层派生密钥）。 */
+export function hmacSha256(key, data) {
+    return createHmac('sha256', key).update(data, 'utf8').digest();
+}
+/**
+ * 逐层派生签名密钥：prefix+secret → date → region → service → terminator（RFC/厂商文档同构）。
+ * AWS：AWS4+SK → dateStamp → region → service → aws4_request；
+ * OSS：aliyun_v4+SK → dateStamp → region → oss → aliyun_v4_request。
+ */
+export function deriveSigningKey(params) {
+    const kDate = hmacSha256(params.dialect.secretKeyPrefix + params.secretAccessKey, params.dateStamp);
+    const kRegion = hmacSha256(kDate, params.region);
+    const kService = hmacSha256(kRegion, params.service);
+    return hmacSha256(kService, params.dialect.terminator);
+}
+/** 签名时刻格式 \`YYYYMMDDTHHMMSSZ\`（UTC）。 */
+export function formatAmzDate(date) {
+    const iso = date.toISOString(); // 2026-10-05T01:49:10.000Z
+    const datePart = iso.slice(0, 10).split('-').join('');
+    const timePart = iso.slice(11, 19).split(':').join('');
+    return datePart + 'T' + timePart + 'Z';
+}
+/** 签名日期段 \`YYYYMMDD\`（UTC）。 */
+export function formatDateStamp(amzDate) {
+    return amzDate.slice(0, 8);
+}
+/**
+ * URI 编码（RFC 3986 未保留字符集 A-Za-z0-9-_.~ 之外一律 %XX 大写）。
+ * \`encodeSlash=false\` 时保留路径分隔符（规范化 URI 用），其余场景（查询串）编码它。
+ */
+export function uriEncode(value, encodeSlash) {
+    const bytes = Buffer.from(value, 'utf8');
+    let out = '';
+    for (const byte of bytes) {
+        const ch = String.fromCharCode(byte);
+        const unreserved = (byte >= 0x41 && byte <= 0x5a) || (byte >= 0x61 && byte <= 0x7a)
+            || (byte >= 0x30 && byte <= 0x39) || ch === '-' || ch === '_' || ch === '.' || ch === '~';
+        if (unreserved)
+            out += ch;
+        else if (ch === '/' && !encodeSlash)
+            out += '/';
+        else
+            out += '%' + byte.toString(16).toUpperCase().padStart(2, '0');
+    }
+    return out;
+}
+/** 安全百分号解码（非法转义原样返回，绝不抛错）。 */
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** 规范化 URI：先解码再逐段编码（避免 URL 归一化后的二次编码），保留分隔符。 */
+export function canonicalUri(pathname) {
+    const path = pathname === '' ? '/' : pathname;
+    return path.split('/').map((seg) => uriEncode(safeDecode(seg), true)).join('/');
+}
+/** 规范化查询串：按「编码后的键、编码后的值」字典序排序，空值写成 \`key=\`。 */
+export function canonicalQueryString(searchParams) {
+    const pairs = [];
+    for (const [rawKey, rawValue] of searchParams) {
+        pairs.push({ key: uriEncode(rawKey, true), value: uriEncode(rawValue, true) });
+    }
+    pairs.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : (a.value < b.value ? -1 : a.value > b.value ? 1 : 0)));
+    return pairs.map((p) => p.key + '=' + p.value).join('&');
+}
+/** 头值归一：去首尾空白 + 内部连续空白折叠成单空格（SigV4 要求）。 */
+function trimHeaderValue(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+/** 该头是否按方言参与规范化头集合。 */
+function participates(name, dialect, additional) {
+    if (dialect.headerSelection === 'all')
+        return true;
+    // OSS4：content-type / content-md5 / x-oss-* 默认参与；其余必须是显式附加头
+    return name === 'content-type' || name === 'content-md5' || name.startsWith('x-oss-') || additional.includes(name);
+}
+/**
+ * 计算一次请求的 SigV4 签名并返回待注入的头。
+ * 幂等且无副作用：同一输入（含同一 now）两次调用逐字相同。
+ */
+export function signRequest(input) {
+    const dialect = input.dialect;
+    const url = new URL(input.url);
+    const amzDate = formatAmzDate(input.now ?? new Date());
+    const dateStamp = formatDateStamp(amzDate);
+    const payloadHash = dialect.payloadHash === 'unsigned'
+        ? UNSIGNED_PAYLOAD
+        : sha256Hex(input.body ?? new Uint8Array(0));
+    const additional = (input.additionalSignedHeaders ?? []).map((h) => h.toLowerCase());
+    const all = { host: url.host };
+    for (const [key, value] of Object.entries(input.headers ?? {}))
+        all[key.toLowerCase()] = value;
+    all[dialect.dateHeader] = amzDate;
+    if (input.includeContentShaHeader !== false)
+        all[dialect.contentShaHeader] = payloadHash;
+    const names = Object.keys(all).filter((n) => participates(n, dialect, additional)).sort();
+    const canonicalHeaderBlock = names.map((n) => n + ':' + trimHeaderValue(all[n] ?? '') + '\n').join('');
+    // AWS：SignedHeaders = 参与规范化的全部头；OSS4：AdditionalHeaders = 仅显式附加的可选头
+    const headerList = dialect.headerSelection === 'all'
+        ? names.join(';')
+        : additional.filter((n) => names.includes(n)).sort().join(';');
+    const canonicalRequest = [
+        input.method.toUpperCase(),
+        canonicalUri(url.pathname),
+        canonicalQueryString(url.searchParams),
+        canonicalHeaderBlock,
+        headerList,
+        payloadHash,
+    ].join('\n');
+    const credentialScope = [dateStamp, input.region, input.service, dialect.terminator].join('/');
+    const stringToSign = [dialect.algorithm, amzDate, credentialScope, sha256Hex(canonicalRequest)].join('\n');
+    const signingKey = deriveSigningKey({
+        secretAccessKey: input.secretAccessKey,
+        dateStamp,
+        region: input.region,
+        service: input.service,
+        dialect,
+    });
+    const signature = createHmac('sha256', signingKey).update(stringToSign, 'utf8').digest('hex');
+    const authorization = dialect.algorithm + ' Credential=' + input.accessKeyId + '/' + credentialScope
+        + ', ' + dialect.headerListLabel + '=' + headerList + ', Signature=' + signature;
+    return {
+        headers: { ...all, authorization },
+        authorization,
+        canonicalRequest,
+        stringToSign,
+        credentialScope,
+        signature,
+        signedHeaders: headerList,
+        payloadHash,
+    };
+}
+//# sourceMappingURL=sigv4.js.map

package/lib/sync/sync-config.d.ts

@@ -1,14 +1,21 @@
 import type { MsgFunc } from '../core/messages.ts';
+import { SYNC_CHANNELS } from '../utils/shared-constants.ts';
+import { S3_COMPAT_PROVIDERS, GIST_PROVIDER, CLOUD_SYNC_PROVIDERS } from '../utils/shared-constants.ts';
+import type { S3CompatProvider, GistProvider, CloudSyncProvider } from '../utils/shared-constants.ts';
+import type { SigV4DialectId } from './s3/sigv4.ts';
 export declare const SYNC_CONFIG_FILE = "sync-config.json";
 /**
- * 同步通道枚举（**唯一声明处**，t32）：所有「有哪些通道 / 通道列表 / 通道判定」的唯一事实源。
+ * 同步通道枚举（**唯一事实源**，t32）：所有「有哪些通道 / 通道列表 / 通道判定」的唯一来源。
+ *
+ * 声明处 = `src/utils/shared-constants.ts`（**零依赖**：client 半可运行时 import 而不带进
+ * node 模块）；本文件 re-export，宿主侧沿用既有 import 路径即可。
  *
  * 为什么要单一来源：此前 SyncTransportType 在 sync-config / ui-prefs / client sync-api /
  * client sync-view 各自声明一遍，通道数组也在 autosync-scheduler 里写了两遍 ——「改一处漏一处」
- * 的表现是某个通道**静默**不再排期 / 不再落盘，而不是报错。新增通道只改这里：typecheck 会在
+ * 的表现是某个通道**静默**不再排期 / 不再落盘，而不是报错。新增通道只改声明处：typecheck 会在
  * 所有 Record<SyncTransportType, X> 的构造处与穷尽检查处报错。
  */
-export declare const SYNC_CHANNELS: readonly ['git', 'webdav'];
+export { SYNC_CHANNELS };
 /** 同步通道类型（由 SYNC_CHANNELS 派生；host 侧与 client 半统一引用）。 */
 export type SyncTransportType = (typeof SYNC_CHANNELS)[number];
 /** 通道值守卫（用于请求体 / localStorage / 磁盘 JSON 的原始输入校验）。 */
@@ -48,6 +55,10 @@ export interface FullSyncConfig {
     transport: SyncTransportType;
     git?: GitConfig;
     webdav?: WebDavConfig;
+    /** 云端点通道 s3（活动兼容商；只有非密字段 + 密钥标记，绝无密钥值） */
+    s3?: S3ChannelConfig;
+    /** 云端点通道 gist（只有非密字段 + 密钥标记，绝无 token 值） */
+    gist?: GistChannelConfig;
 }
 /** 持久化的同步通道配置：可辨识联合（schemaVersion 恒 2） */
 export type SyncConfig = {
@@ -58,6 +69,14 @@ export type SyncConfig = {
     schemaVersion: 2;
     transport: 'webdav';
     webdav: WebDavConfig;
+} | {
+    schemaVersion: 2;
+    transport: 's3';
+    s3: S3ChannelConfig;
+} | {
+    schemaVersion: 2;
+    transport: 'gist';
+    gist: GistChannelConfig;
 };
 /** git 通道守卫 */
 export declare function isGitConfig(cfg: SyncConfig): cfg is Extract<SyncConfig, {
@@ -67,6 +86,14 @@ export declare function isGitConfig(cfg: SyncConfig): cfg is Extract<SyncConfig,
 export declare function isWebDavConfig(cfg: SyncConfig): cfg is Extract<SyncConfig, {
     transport: 'webdav';
 }>;
+/** s3 通道守卫（provider 在 cfg.s3.provider：s3 / oss / cos / minio / kodo） */
+export declare function isS3Config(cfg: SyncConfig): cfg is Extract<SyncConfig, {
+    transport: 's3';
+}>;
+/** gist 通道守卫 */
+export declare function isGistConfig(cfg: SyncConfig): cfg is Extract<SyncConfig, {
+    transport: 'gist';
+}>;
 /**
  * 读取同步通道配置；文件不存在/损坏/不支持 schema → null（视为未配置，UI 显示空表单）。
  * 兼容旧文件：缺 schemaVersion 字段视为 v1（git 通道）。
@@ -89,7 +116,7 @@ export declare function readSyncConfigFor(dir: string, channel: SyncTransportTyp
  * - 另一通道之前配置过 → 一并保留（切换通道不丢失另一通道的 repoUrl/url）；
  * - 覆盖旧值；未配置过的字段不写入。
  */
-export declare function writeSyncConfig(dir: string, cfg: SyncConfig): Promise<void>;
+export declare function writeSyncConfig(dir: string, cfg: SyncConfig, secrets?: CloudSecretWriter): Promise<void>;
 /** 断开单条通道配置的结果（供路由层决定凭据/自动同步/UI 偏好怎么收尾）。 */
 export interface ClearSyncChannelResult {
     /** 该通道之前是否有配置；false = 本来就没配（幂等成功，不算失败） */
@@ -127,3 +154,222 @@ export declare function validateRepoUrl(repoUrl: string, msg?: MsgFunc): string
  * （username[:password]@）的地址，引导用户把口令放 DSH credentials，避免凭据经 URL 泄漏进出入口/日志。
  */
 export declare function validateWebDavUrl(url: string, msg?: MsgFunc): string | null;
+/** 云端点通道配置文件名（与 sync-config.json 并列，互不影响）。 */
+export declare const CLOUD_SYNC_CONFIG_FILE = "sync-cloud-config.json";
+/** 云端点配置 schema 版本。 */
+export declare const CLOUD_SYNC_CONFIG_SCHEMA_VERSION = 1;
+/**
+ * S3 兼容系通道枚举（**唯一声明处已迁到零依赖的 `utils/shared-constants.ts` 的 S3_COMPAT_PROVIDERS**，t88）：
+ * 五家共用同一份 SigV4 实现，差异只有 endpoint / region / 寻址风格 / 签名方言
+ * （见 src/sync/s3/s3-providers.ts 的变体表）。
+ */
+export { S3_COMPAT_PROVIDERS, GIST_PROVIDER, CLOUD_SYNC_PROVIDERS };
+export type { S3CompatProvider, GistProvider, CloudSyncProvider };
+/** 通道值守卫（请求体 / 磁盘 JSON 的原始输入校验）。 */
+export declare function isCloudSyncProvider(value: unknown): value is CloudSyncProvider;
+/** 是否 S3 兼容系通道。 */
+export declare function isS3CompatProvider(value: unknown): value is S3CompatProvider;
+/** 是否 Gist 通道。 */
+export declare function isGistProvider(value: unknown): value is GistProvider;
+/**
+/**
+ * 取某云端点通道的密钥槽位引用（不涉及任何值）。
+ *
+ * 表本身在零依赖的 utils/shared-constants.ts（**唯一声明处**，t88）：客户端要显示同一个名字
+ * （cloudSecretRefName()），两侧各写一份时「宿主改名、界面还提示旧名」不会红。
+ * 命名与既有 syncPasswordRef 同族：DSH_CONFIG_MANAGER_SYNC_<CHANNEL>_<KIND>。
+ */
+export declare function cloudSecretRef(provider: CloudSyncProvider): string;
+/**
+ * 密钥**只写**端口：故意不提供 get()——宿主只能写、只能问「有没有」，
+ * 通道实现与 UI 都不可能把值回读出来（这是「只写不回读」的结构性保证，不靠纪律）。
+ */
+export interface CloudSecretWriter {
+    /** 写入密钥值（仅内存传递；不落盘、不进日志、不回传） */
+    set(ref: string, value: string): Promise<void>;
+    /** 只问「该槽位有没有值」（绝不返回值本身） */
+    has(ref: string): Promise<boolean>;
+}
+/** S3 兼容系通道的非密配置（值里绝不含 AccessKey Secret）。 */
+export interface CloudS3ChannelConfig {
+    /** 对象存储端点（http(s)，不含凭据、不含桶名；如 https://s3.us-east-1.amazonaws.com） */
+    endpoint: string;
+    /** V4 签名作用域里的 region（如 us-east-1 / cn-hangzhou / ap-guangzhou） */
+    region: string;
+    /** 桶名 */
+    bucket: string;
+    /** 对象键前缀（缺省 dsh-config-manager） */
+    prefix?: string;
+    /** AccessKey ID（标识符，可回显；**不是**密钥） */
+    accessKeyId: string;
+    /** path-style 寻址开关（缺省取变体默认：MinIO true，其余 false） */
+    pathStyle?: boolean;
+    /**
+     * 显式覆盖变体默认签名方言（缺省 = provider 变体默认；'aws4' = AWS SigV4，'oss4' = 阿里云 OSS4）。
+     * 非法的值在解析期被忽略（回落变体默认）—— 该字段是高级覆盖，不是配置错误来源。
+     */
+    dialectId?: SigV4DialectId;
+    /** 密钥是否已在 DSH credentials 里（**只回标记，不回值**） */
+    secretStored?: boolean;
+}
+/** Gist 通道的非密配置（值里绝不含 token）。 */
+export interface CloudGistChannelConfig {
+    /** 目标 gist id（十六进制串） */
+    gistId: string;
+    /** GitHub API 根（缺省 https://api.github.com；GitHub Enterprise 可改） */
+    apiBaseUrl?: string;
+    /** gist 内文件名前缀（缺省 dsh-sync） */
+    filePrefix?: string;
+    /** token 是否已在 DSH credentials 里（**只回标记，不回值**） */
+    secretStored?: boolean;
+}
+/**
+ * s3 通道（SYNC_CHANNELS 的 's3'）的配置 = 具体兼容商的非密配置 + provider 身份。
+ * 密钥值绝不在此（只在 DSH credentials 的 cloudSecretRef(provider) 槽位）。
+ */
+export interface S3ChannelConfig extends CloudS3ChannelConfig {
+    /** 具体 S3 兼容商（s3 / oss / cos / minio / kodo） */
+    provider: S3CompatProvider;
+}
+/** gist 通道（SYNC_CHANNELS 的 'gist'）的配置：非密字段；token 只在 DSH credentials。 */
+export type GistChannelConfig = CloudGistChannelConfig;
+/**
+ * 每个云端点**通道**当前选用的 provider（保存即选定；断开即移除）。
+ * s3 通道 → 五家兼容商之一；gist 通道 → 恒 'gist'。
+ * 与 savedProviders 的分工：savedProviders 是「切换 provider 时能自动回填」的记忆，
+ * 本字段回答「这条通道现在用哪一个」。
+ */
+export interface CloudActiveProviders {
+    s3?: S3CompatProvider;
+    gist?: GistProvider;
+}
+/** 按通道分别保存的非密配置（照 cloud-sync 的 savedProviders 模式）。 */
+export interface CloudSavedProviders {
+    s3?: CloudS3ChannelConfig;
+    oss?: CloudS3ChannelConfig;
+    cos?: CloudS3ChannelConfig;
+    minio?: CloudS3ChannelConfig;
+    kodo?: CloudS3ChannelConfig;
+    gist?: CloudGistChannelConfig;
+}
+/** 磁盘上的云端点配置（读侧恒归一为该形态；损坏/不支持的版本 → null）。 */
+export interface CloudSyncConfig {
+    schemaVersion: number;
+    savedProviders: CloudSavedProviders;
+    /** 每条云端点通道当前选用的 provider（缺省 = 旧文件，读侧按「唯一已保存者」推断） */
+    active?: CloudActiveProviders;
+}
+/** 某通道读出来的配置（按 provider 收窄的联合）。 */
+export type CloudChannelConfig = {
+    provider: S3CompatProvider;
+    config: CloudS3ChannelConfig;
+} | {
+    provider: GistProvider;
+    config: CloudGistChannelConfig;
+};
+/** S3 兼容系通道的回传视图：**只带 secretStored 标记，绝不带密钥值**。 */
+export interface CloudS3ChannelView {
+    provider: S3CompatProvider;
+    endpoint: string;
+    region: string;
+    bucket: string;
+    prefix: string;
+    accessKeyId: string;
+    pathStyle: boolean;
+    /** 密钥已在 credentials 里（只回布尔） */
+    secretStored: boolean;
+}
+/** Gist 通道的回传视图：**只带 secretStored 标记，绝不带 token 值**。 */
+export interface CloudGistChannelView {
+    provider: GistProvider;
+    gistId: string;
+    apiBaseUrl: string;
+    filePrefix: string;
+    secretStored: boolean;
+}
+/** 回传 UI 的通道视图（按 provider 收窄的联合） */
+export type CloudChannelView = CloudS3ChannelView | CloudGistChannelView;
+/** 写入入参（表单原样；字段按 provider 各自校验）。 */
+export interface CloudChannelWriteInput {
+    endpoint?: string;
+    region?: string;
+    bucket?: string;
+    prefix?: string;
+    accessKeyId?: string;
+    pathStyle?: boolean;
+    /** 显式覆盖签名方言（可缺省；仅 'aws4' | 'oss4' 被接受） */
+    dialectId?: SigV4DialectId;
+    gistId?: string;
+    apiBaseUrl?: string;
+    filePrefix?: string;
+    /** 明文密钥：**只写**（提供即写入 credentials）；缺省 = 只更新非密字段，已有密钥不动 */
+    secret?: string;
+}
+/**
+ * 云端点配置的**稳定错误码**（不是用户文案）。
+ * 与 \`validateRepoUrl\` 返回 \`'repoUrl is required'\` 同口径：码由路由/UI 层映射进字典，
+ * 因此本模块不产生任何用户可见字符串。
+ */
+export type CloudConfigIssueCode = 'cloud.providerUnknown' | 'cloud.endpointRequired' | 'cloud.endpointInvalid' | 'cloud.endpointUserinfo' | 'cloud.regionRequired' | 'cloud.bucketRequired' | 'cloud.bucketInvalid' | 'cloud.prefixInvalid' | 'cloud.accessKeyIdRequired' | 'cloud.gistIdRequired' | 'cloud.gistIdInvalid' | 'cloud.apiBaseUrlInvalid' | 'cloud.secretWriterRequired';
+/** 配置校验失败：携带稳定错误码（无用户文案），由上层映射成字典键。 */
+export declare class CloudConfigError extends Error {
+    readonly code: CloudConfigIssueCode;
+    constructor(code: CloudConfigIssueCode, detail?: string);
+}
+/** 端点校验（http(s)、无 userinfo、无 query/hash）；返回错误码或 null。 */
+export declare function validateCloudEndpoint(endpoint: string): CloudConfigIssueCode | null;
+/** region 校验：非空、无空白。 */
+export declare function validateCloudRegion(region: string): CloudConfigIssueCode | null;
+/** 桶名校验。 */
+export declare function validateCloudBucket(bucket: string): CloudConfigIssueCode | null;
+/** 对象键前缀校验（可缺省 = 根前缀；不得以 / 开头、不得含 .. / 反斜杠 / 空段）。 */
+export declare function validateCloudPrefix(prefix: string): CloudConfigIssueCode | null;
+/** gist id 校验。 */
+export declare function validateGistId(gistId: string): CloudConfigIssueCode | null;
+/** GitHub API 根校验（http(s)、无 userinfo）。 */
+export declare function validateCloudApiBaseUrl(url: string): CloudConfigIssueCode | null;
+/** 按通道校验写入入参；返回首个错误码或 null。 */
+export declare function validateCloudChannelInput(provider: CloudSyncProvider, input: CloudChannelWriteInput): CloudConfigIssueCode | null;
+/**
+ * 读取云端点配置；文件不存在/损坏/schema 不支持 → null（视为未配置）。
+ * **绝不回读密钥值**：只认非密白名单字段 + \`secretStored\` 标记。
+ */
+export declare function readCloudSyncConfig(dir: string): Promise<CloudSyncConfig | null>;
+/** 读取单条云端点通道的配置；该通道未配置/非法 → null。 */
+export declare function readCloudChannelConfig(dir: string, provider: CloudSyncProvider): Promise<CloudChannelConfig | null>;
+/** 已配置的云端点通道清单（供 UI 回填 / 断开时判断是否还剩别的通道）。 */
+export declare function listCloudConfiguredProviders(dir: string): Promise<CloudSyncProvider[]>;
+/** 组装 S3 兼容系回传视图（**只带标记、不带值**）。 */
+export declare function s3ChannelView(provider: S3CompatProvider, config: CloudS3ChannelConfig, secretStored: boolean): CloudS3ChannelView;
+/** 组装 Gist 回传视图（**只带标记、不带值**）。 */
+export declare function gistChannelView(config: CloudGistChannelConfig, secretStored: boolean): CloudGistChannelView;
+/** 组装回传视图（按 provider 分派到具名视图构造器）。 */
+export declare function cloudChannelView(channel: CloudChannelConfig, secretStored: boolean): CloudChannelView;
+/**
+ * 保存某云端点通道的配置（自动创建目录；恒写 schemaVersion=1 的 savedProviders）。
+ * - 只写当前通道的条目，其它通道原样保留（切换通道不丢失已填的 endpoint/bucket）；
+ * - 密钥**只写**：提供 input.secret 时经注入的 \`CloudSecretWriter\` 写进 credentials 槽位，
+ *   文件里只留 \`secretStored: true\`（值绝不落文件、绝不回传）；
+ * - 未提供 secret 时只更新非密字段（已有密钥不动，标记按 \`has()\` 现算）。
+ */
+export declare function writeCloudChannelConfig(dir: string, provider: CloudSyncProvider, input: CloudChannelWriteInput, secrets?: CloudSecretWriter): Promise<CloudChannelView>;
+/**
+ * 断开某云端点通道：删掉该通道的配置条目；一条不剩则删除整个文件。
+ * 幂等：本来没配置 → removed=false 且**不写文件**。
+ * 密钥槽位不在这里清除（凭据归凭据层），与 \`clearSyncChannel\` 同口径。
+ */
+export declare function clearCloudChannelConfig(dir: string, provider: CloudSyncProvider): Promise<{
+    removed: boolean;
+    hasRemaining: boolean;
+}>;
+/**
+ * s3 通道当前选用的兼容商：
+ *  - 有 active.s3 → 用它（且必须仍有已保存配置）；
+ *  - 旧文件（无 active）→ 只有**唯一一家**已保存时据此推断，多家并存时为 null（不猜）。
+ */
+export declare function readActiveS3Provider(dir: string): Promise<S3CompatProvider | null>;
+/**
+ * 当前仍配置的通道清单（git/webdav 命名空间 ∪ 云端点已保存的 provider），顺序 = SYNC_CHANNELS。
+ * 供路由层判断「还有没有其他通道可用」与断开后回落活动通道。
+ */
+export declare function listConfiguredChannels(dir: string): Promise<SyncTransportType[]>;