feat(api): bind encrypted workspaces to accounts and devices

packages/core/README.md

@@ -92,7 +92,6 @@ ws.onmessage = async (m) => {
 | `itemId` | 重试和续传必须复用同一个 id |
 | `fromFrame` | 上传断点续传:从第 k 帧开始产出(字节与完整加密完全相同)。仅支持 `Blob` / `Uint8Array` |
 | `ts`, `dev` | 覆盖时间戳和设备名 |
-| `label` | 仅 raw 模式:`X-WD-Label` |
 
 **GATED 的判断**:来源长度已知时创建计划时就确定;来源是流时,要产出第 0 帧之后 `plan.gated` 和 `frame0Headers` 才确定,请在拿到第 0 帧后再读取。
 

packages/core/src/constants.ts

@@ -13,6 +13,7 @@ export const Flags = {
   Snapshot: 2,
   Gated: 4,
   Enc: 8,
+  Control: 16,
 } as const;
 
 /** 档位 padding 的明文长度(protocol §6)。 */

packages/core/src/frame.ts

@@ -49,7 +49,7 @@ export interface Envelope {
 export function parseEnvelope(data: Uint8Array): Envelope {
   if (data.length < HEADER_SIZE || data[0] !== 1) throw new IntegrityError('bad_envelope');
   const flags = data[1] as number;
-  if ((flags & 0xf0) !== 0) throw new IntegrityError('bad_envelope');
+  if ((flags & 0xe0) !== 0) throw new IntegrityError('bad_envelope');
   const payloadLength = readU32(data, 22);
   if (data.length !== HEADER_SIZE + payloadLength) throw new IntegrityError('bad_envelope');
 
@@ -109,7 +109,7 @@ export interface SealParams {
  */
 export async function sealFrame(itemKey: CryptoKey, channelId: Uint8Array, p: SealParams): Promise<Bytes> {
   if ((p.flags & Flags.Enc) === 0) throw new RangeError('enc 帧必须带 ENC 标志');
-  if ((p.flags & 0xf0) !== 0) throw new RangeError('保留标志位必须为 0');
+  if ((p.flags & 0xe0) !== 0) throw new RangeError('保留标志位必须为 0');
 
   const plaintext = padPlaintext(p.data);
   const header = concat(new Uint8Array([1, p.flags]), p.itemId, writeU32(p.index), writeU32(plaintext.length + TAG_SIZE));

packages/core/src/internal.ts

@@ -7,7 +7,7 @@ import { Labels } from './constants.js';
 import { utf8, type Bytes } from './bytes.js';
 
 export { encodeEnvelope, frameAad, frameIv, padPlaintext, parseEnvelope, sealFrame, tierFor, unpadPlaintext } from './frame.js';
-export { encodeMeta, decodeFirstFrame, planEncItem, planRawItem } from './item.js';
+export { encodeMeta, decodeFirstFrame, planItem } from './item.js';
 export { deriveChannelKeys, deriveItemKey, deriveOwnerToken, sha256 } from './kdf.js';
 
 async function hkdfBytes(ikm: Uint8Array, salt: Uint8Array, label: string): Promise<Bytes> {

packages/core/src/item.ts

@@ -1,4 +1,4 @@
-import { Flags, MAX_FRAME_DATA, RAW_MAX_PAYLOAD, type ItemKind } from './constants.js';
+import { Flags, MAX_FRAME_DATA, type ItemKind } from './constants.js';
 import { concat, readU16, toBytes, tryDecodeUtf8, utf8, writeU16, toBase64Url, type Bytes } from './bytes.js';
 import { IntegrityError, LimitError } from './errors.js';
 
@@ -14,6 +14,10 @@ export interface ItemMeta {
   ts: number;
   /** 设备名。 */
   dev?: string;
+  /** WebDrop 频道中的 thread ID,加密元数据。 */
+  threadId?: string;
+  /** 文件所在的虚拟文件夹 ID,加密元数据。 */
+  folderId?: string;
 }
 
 const KINDS: readonly ItemKind[] = ['text', 'json', 'file', 'manifest', 'other'];
@@ -26,6 +30,8 @@ export function encodeMeta(meta: ItemMeta): Bytes {
   if (meta.size !== undefined) o.size = meta.size;
   o.ts = meta.ts;
   if (meta.dev !== undefined) o.dev = meta.dev;
+  if (meta.threadId !== undefined) o.thread_id = meta.threadId;
+  if (meta.folderId !== undefined) o.folder_id = meta.folderId;
 
   const json = utf8(JSON.stringify(o));
   if (json.length > 0xffff) throw new LimitError('条目元数据过大');
@@ -64,6 +70,12 @@ export function decodeFirstFrame(data: Uint8Array): { meta: ItemMeta; content: B
     if (typeof v !== 'string') throw new IntegrityError('bad_meta');
     meta[key] = v;
   }
+  for (const [wire, key] of [['thread_id', 'threadId'], ['folder_id', 'folderId']] as const) {
+    const v = o[wire];
+    if (v === undefined) continue;
+    if (typeof v !== 'string' || v.length > 80) throw new IntegrityError('bad_meta');
+    meta[key] = v;
+  }
   if (o.size !== undefined) {
     if (typeof o.size !== 'number' || !Number.isSafeInteger(o.size) || o.size < 0) throw new IntegrityError('bad_meta');
     meta.size = o.size;
@@ -76,6 +88,7 @@ export function decodeFirstFrame(data: Uint8Array): { meta: ItemMeta; content: B
 export type ContentSource = Uint8Array | Blob | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
 
 export interface PlanOptions {
+  control?: boolean;
   /** 指定条目 id(重试、续传时必须复用同一个);默认随机生成。 */
   itemId?: Uint8Array;
   /** 作为频道的「最新快照」。快照必须是单帧,所以内容不能超过一帧。 */
@@ -109,7 +122,7 @@ export interface ItemPlan {
    * 要等第 0 帧产出之后才确定,所以请在拿到第 0 帧之后再读取它和 frame0Headers。
    */
   readonly gated: boolean;
-  /** 第 0 帧要带的附加请求头(X-WD-Max-Downloads / X-WD-Label)。 */
+  /** 第 0 帧要带的附加请求头(X-WD-Max-Downloads)。 */
   frame0Headers: Record<string, string>;
   /** 按序产出加密后的帧。同一个计划只能迭代一次。 */
   frames: AsyncGenerator<EncodedFrame, void, void>;
@@ -256,11 +269,12 @@ function resolveGating(opts: PlanOptions, fitsInOneFrame: boolean | undefined):
  * enc 模式:把内容加密成一个条目(protocol §7)。
  * 小内容单帧、非 GATED;放不下就拆成多帧并标记 GATED。第 0 帧携带元数据。
  */
-export function planEncItem(
+export function planItem(
   seal: (p: { flags: number; itemId: Uint8Array; index: number; data: Uint8Array }) => Promise<Bytes>,
   source: ContentSource,
   meta: ItemMeta,
   opts: PlanOptions = {},
+  encrypted = true,
 ): ItemPlan {
   const idBytes: Bytes = opts.itemId ? toBytes(opts.itemId) : newItemId();
   const maxData = opts.maxFrameData ?? MAX_FRAME_DATA;
@@ -281,9 +295,10 @@ export function planEncItem(
   if (opts.maxDownloads !== undefined) frame0Headers['X-WD-Max-Downloads'] = String(opts.maxDownloads);
 
   const snapshot = opts.snapshot === true;
+  if (opts.control && (snapshot || gated)) throw new RangeError('控制条目必须是非快照的单帧');
 
   async function* frames(): AsyncGenerator<EncodedFrame, void, void> {
-    const base = (gatedNow: boolean) => (gatedNow ? Flags.Gated : 0) | (snapshot ? Flags.Snapshot : 0) | Flags.Enc;
+    const base = (gatedNow: boolean) => (gatedNow ? Flags.Gated : 0) | (snapshot ? Flags.Snapshot : 0) | (opts.control ? Flags.Control : 0) | (encrypted ? Flags.Enc : 0);
     const emit = async (index: number, last: boolean, data: Uint8Array, gatedNow: boolean): Promise<EncodedFrame> => ({
       index,
       final: last,
@@ -326,42 +341,3 @@ export function planEncItem(
   return { itemId: toBase64Url(idBytes), idBytes, get gated() { return gated; }, frame0Headers, frames: frames() };
 }
 
-/**
- * raw 模式:负载原样,没有加密、没有元数据。单帧放不下时拆成 GATED 多帧。
- * 注意 raw 内容对服务端完全可见。
- */
-export function planRawItem(
-  build: (p: { flags: number; itemId: Uint8Array; index: number; payload: Uint8Array }) => Bytes,
-  source: ContentSource,
-  opts: PlanOptions & { label?: string } = {},
-): ItemPlan {
-  const idBytes: Bytes = opts.itemId ? toBytes(opts.itemId) : newItemId();
-  const cap = Math.min(opts.maxFrameData ?? RAW_MAX_PAYLOAD, RAW_MAX_PAYLOAD);
-  const snapshot = opts.snapshot === true;
-
-  const size = source instanceof Uint8Array ? source.length : typeof Blob !== 'undefined' && source instanceof Blob ? source.size : undefined;
-  let gated = resolveGating(opts, size === undefined ? undefined : size <= cap);
-
-  const frame0Headers: Record<string, string> = {};
-  if (opts.maxDownloads !== undefined) frame0Headers['X-WD-Max-Downloads'] = String(opts.maxDownloads);
-  if (opts.label !== undefined) frame0Headers['X-WD-Label'] = opts.label;
-
-  async function* frames(): AsyncGenerator<EncodedFrame, void, void> {
-    let index = 0;
-    for await (const chunk of rechunk(source, cap, cap)) {
-      if (index === 0) {
-        if (chunk.last && opts.gated !== true && opts.maxDownloads === undefined) gated = false;
-        else if (!chunk.last) {
-          if (snapshot) throw new LimitError('快照必须是单帧,内容超过了一帧');
-          gated = true;
-        }
-      }
-      const flags = (gated ? Flags.Gated : 0) | (snapshot ? Flags.Snapshot : 0) | (chunk.last ? Flags.Final : 0);
-      yield { index, final: chunk.last, bytes: build({ flags, itemId: idBytes, index, payload: chunk.data }) };
-      index++;
-    }
-  }
-
-  return { itemId: toBase64Url(idBytes), idBytes, get gated() { return gated; }, frame0Headers, frames: frames() };
-}
-

packages/core/src/reader.ts

@@ -14,7 +14,7 @@ export interface ReaderContext {
   itemKey(itemId: Uint8Array): Promise<CryptoKey>;
 }
 
-export type ReceivedKind = ItemKind | 'raw';
+export type ReceivedKind = ItemKind;
 
 export interface ReceivedItem {
   itemId: string;
@@ -124,7 +124,7 @@ export class ItemReader {
     if (isEncFrame !== (this.#ctx.mode === 'enc')) throw new IntegrityError('wrong_mode');
     if (this.#done.has(itemId)) return [];
 
-    const itemFlags = env.flags & (Flags.Gated | Flags.Snapshot);
+    const itemFlags = env.flags & (Flags.Gated | Flags.Snapshot | Flags.Control);
     const gated = (env.flags & Flags.Gated) !== 0;
     const isFinal = (env.flags & Flags.Final) !== 0;
     // 非 GATED 条目必须是单帧且 FINAL(协议规则,服务端也强制)
@@ -156,7 +156,7 @@ export class ItemReader {
 
     let meta = state?.meta;
     let content = data;
-    if (this.#ctx.mode === 'enc' && env.frameIndex === 0) {
+    if (env.frameIndex === 0) {
       const first = decodeFirstFrame(data);
       meta = first.meta;
       content = first.content;
@@ -179,7 +179,7 @@ export class ItemReader {
     const item: ReceivedItem = {
       itemId,
       seq,
-      kind: this.#ctx.mode === 'raw' ? 'raw' : (state.meta?.kind ?? 'other'),
+      kind: state.meta?.kind ?? 'other',
       snapshot: (itemFlags & Flags.Snapshot) !== 0,
       gated,
       complete,

packages/core/src/session.ts

@@ -4,7 +4,7 @@ import { CapabilityError, IntegrityError, LimitError, LinkError, ModeMismatchErr
 import { encodeEnvelope, sealFrame } from './frame.js';
 import { deriveChannelKeys, deriveItemKey, deriveOwnerToken, sha256, type ChannelKeys } from './kdf.js';
 import { buildLink, parseLink, type ParsedLink } from './link.js';
-import { planEncItem, planRawItem, type ContentSource, type ItemMeta, type ItemPlan, type PlanOptions } from './item.js';
+import { planItem, type ContentSource, type ItemMeta, type ItemPlan, type PlanOptions } from './item.js';
 import { ItemReader, type ReaderContext } from './reader.js';
 import { decryptItemStream, type DecryptStreamOptions, type ItemDecodeResult } from './stream.js';
 
@@ -12,6 +12,9 @@ export type AuthRole = 'read' | 'write' | 'owner';
 
 /** 频道设置,字段名与 API 一致(snake_case)。 */
 export interface ChannelSettings {
+  join_policy?: 'open' | 'invite';
+  allow_guests?: boolean;
+  name?: string;
   seats?: number;
   members_can_upload?: boolean;
   delete_policy?: 'owner_only' | 'own' | 'anyone';
@@ -56,8 +59,10 @@ export interface PlanItemOptions extends PlanOptions {
   ts?: number;
   /** 覆盖设备名。默认使用 session.deviceName。 */
   dev?: string;
-  /** 仅 raw 模式:条目标签,作为 X-WD-Label 随第 0 帧发送(明文,服务端可见)。enc 模式下忽略,名字放在加密的元数据里。 */
-  label?: string;
+  /** Workspace thread ID, encoded only in encrypted item metadata. */
+  threadId?: string;
+  /** Virtual folder ID for files, encoded only in encrypted item metadata. */
+  folderId?: string;
 }
 
 export interface FileMetaOverrides {
@@ -255,22 +260,17 @@ export class ChannelSession {
 
   #meta(kind: ItemMeta['kind'], opts: PlanItemOptions, extra: Partial<ItemMeta> = {}): ItemMeta {
     const meta: ItemMeta = { kind, ts: opts.ts ?? Date.now(), ...extra };
+    if (opts.threadId !== undefined) meta.threadId = opts.threadId;
+    if (opts.folderId !== undefined) meta.folderId = opts.folderId;
     const dev = opts.dev ?? this.deviceName;
     if (dev !== undefined) meta.dev = dev;
     return meta;
   }
 
   #plan(source: ContentSource, meta: ItemMeta, opts: PlanItemOptions): ItemPlan {
-    if (this.mode === 'enc') {
-      return planEncItem(
-        async (p) => sealFrame(await this.itemKey(p.itemId), this.idBytes, p),
-        source,
-        meta,
-        opts,
-      );
-    }
-    // raw:没有元数据,内容原样放进负载
-    return planRawItem((p) => encodeEnvelope(p.flags, p.itemId, p.index, p.payload), source, opts);
+    return planItem(async (p) => this.mode === 'enc'
+      ? sealFrame(await this.itemKey(p.itemId), this.idBytes, p)
+      : encodeEnvelope(p.flags, p.itemId, p.index, p.data), source, meta, opts, this.mode === 'enc');
   }
 
   encryptBytes(content: Uint8Array, meta: Partial<ItemMeta> & { kind?: ItemMeta['kind'] } = {}, opts: PlanItemOptions = {}): ItemPlan {
@@ -331,11 +331,16 @@ export class ChannelSession {
   // ───────────────────────── 设备名(protocol §10) ─────────────────────────
 
   /**
-   * 加密设备名,作为 PUT /seats/me 的请求体。格式:iv(12) ‖ AES-GCM(K_label, 名称) ‖ tag(16),
+   * 加密设备名,作为席位名称 PUT 请求体。格式:iv(12) ‖ AES-GCM(K_label, 名称) ‖ tag(16),
    * AAD = "WD1L" ‖ channel_id ‖ endpoint_hash。raw 模式下设备名是明文 UTF-8。
+   * @param opts.endpointHash 指定目标席位;所有者可给其他终端重命名。
    * @param opts.iv 仅用于测试向量,真实使用必须让库随机生成。
    */
-  async sealLabel(name: string, opts: { iv?: Uint8Array } = {}): Promise<Bytes> {
+  async sealLabel(name: string, opts: { iv?: Uint8Array; endpointHash?: Uint8Array | string } = {}): Promise<Bytes> {
+    const endpointHash = typeof opts.endpointHash === 'string'
+      ? fromBase64Url(opts.endpointHash, 32)
+      : opts.endpointHash ?? this.endpointHash;
+    if (!endpointHash || endpointHash.length !== 32) throw new RangeError('终端标识必须是 32 字节');
     const plain = utf8(name);
     if (this.mode === 'raw') {
       if (plain.length > MAX_LABEL_BYTES) throw new LimitError('设备名过长');
@@ -347,7 +352,7 @@ export class ChannelSession {
     }
     const iv = opts.iv ?? randomBytes(LABEL_IV_SIZE);
     const sealed = await globalThis.crypto.subtle.encrypt(
-      { name: 'AES-GCM', iv: iv as Bytes, additionalData: this.#labelAad(this.endpointHash), tagLength: 128 },
+      { name: 'AES-GCM', iv: iv as Bytes, additionalData: this.#labelAad(endpointHash), tagLength: 128 },
       (this.#keys as ChannelKeys).labelKey,
       plain,
     );

packages/core/src/stream.ts

@@ -57,13 +57,15 @@ class ByteQueue {
 async function* bytesOf(source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array, void, void> {
   if (typeof ReadableStream !== 'undefined' && source instanceof ReadableStream) {
     const reader = source.getReader();
+    let finished = false;
     try {
       for (;;) {
         const { done, value } = await reader.read();
-        if (done) return;
+        if (done) { finished = true; return; }
         yield value;
       }
     } finally {
+      if (!finished) await reader.cancel().catch(() => {});
       reader.releaseLock();
     }
   }
@@ -136,21 +138,19 @@ export async function* decryptItemFrames(
     if (finalSeen) throw new IntegrityError('frame_after_final');
     if (env.frameIndex !== expected) throw new IntegrityError('gap');
 
-    const itemFlags = env.flags & (Flags.Gated | Flags.Snapshot);
+    const itemFlags = env.flags & (Flags.Gated | Flags.Snapshot | Flags.Control);
     if (flagsMask === undefined) flagsMask = itemFlags;
     else if (flagsMask !== itemFlags) throw new IntegrityError('flags_changed');
 
     let data: Bytes;
     if (ctx.mode === 'enc') {
       data = await openFrame(await ctx.itemKey(env.itemId), ctx.channelId, env);
-      if (env.frameIndex === 0) {
-        const first = decodeFirstFrame(data);
-        meta = first.meta;
-        data = first.content;
-      }
     } else {
       data = env.payload;
     }
+    if (env.frameIndex === 0) {
+      const first = decodeFirstFrame(data); meta = first.meta; data = first.content;
+    }
 
     expected++;
     if ((env.flags & Flags.Final) !== 0) finalSeen = true;
@@ -190,7 +190,8 @@ export function decryptItemStream(
         controller.error(e);
       }
     },
-    async cancel() {
+    async cancel(reason) {
+      reject(reason ?? new DOMException('解密已取消', 'AbortError'));
       await gen.return({ complete: false, nextIndex: opts.fromIndex ?? 0, meta: undefined });
     },
   });

packages/core/test/e2e.test.ts

@@ -30,7 +30,9 @@ const exe = process.env.WEBDROP_SERVER ?? join(root, 'out', 'win-x64', 'webdrop.
 const linuxExe = join(root, 'out', 'linux-x64', 'webdrop');
 const dll = process.env.WEBDROP_SERVER_DLL ?? join(root, 'src', 'WebDrop.Api', 'bin', 'Debug', 'net10.0', 'webdrop.dll');
 
-const command: [string, string[]] | undefined = existsSync(exe)
+const command: [string, string[]] | undefined = !process.env.WEBDROP_SERVER && existsSync(dll)
+  ? ['dotnet', [dll]]
+  : existsSync(exe)
   ? [exe, []]
   : existsSync(linuxExe)
     ? [linuxExe, []]
@@ -41,6 +43,10 @@ const command: [string, string[]] | undefined = existsSync(exe)
 let proc: ChildProcess | undefined;
 let dataDir = '';
 let base = '';
+let accountToken = '';
+function headersFor(session: ChannelSession, role: AuthRole): Record<string, string> {
+  return { ...session.authHeaders(role), ...(session.role === 'owner' ? { 'X-WD-Account': accountToken } : {}) };
+}
 
 beforeAll(async () => {
   if (!command) return;
@@ -69,6 +75,16 @@ beforeAll(async () => {
     });
     proc!.on('exit', (code) => reject(new Error(`服务端提前退出,代码 ${code}`)));
   });
+  const verifier = crypto.getRandomValues(new Uint8Array(32));
+  const keys = await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+  const pubkey = await crypto.subtle.exportKey('jwk', keys.publicKey);
+  const encoded = (value: Uint8Array) => Buffer.from(value).toString('base64');
+  const registered = await fetch(`${base}/api/v1/accounts`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({
+    username: 'core_e2e', salt: encoded(crypto.getRandomValues(new Uint8Array(16))), verifier: encoded(verifier), vault: encoded(new Uint8Array(28)), public_key: JSON.stringify(pubkey),
+  }) });
+  expect(registered.status).toBe(204);
+  const session = await fetch(`${base}/api/v1/accounts/session`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'core_e2e', verifier: encoded(verifier) }) });
+  expect(session.status).toBe(200); accountToken = ((await session.json()) as { token: string }).token;
 }, 30_000);
 
 afterAll(async () => {
@@ -85,7 +101,7 @@ async function createChannel(opts: Parameters<typeof ChannelSession.create>[0] =
   const created = await ChannelSession.create(opts);
   const res = await fetch(api('/channels'), {
     method: 'POST',
-    headers: { ...created.request.headers, 'Content-Type': 'application/json' },
+    headers: { ...created.request.headers, 'X-WD-Account': accountToken, 'Content-Type': 'application/json' },
     body: JSON.stringify(created.request.body),
   });
   expect(res.status).toBe(201);
@@ -95,7 +111,7 @@ async function createChannel(opts: Parameters<typeof ChannelSession.create>[0] =
 }
 
 async function joinChannel(session: ChannelSession, role: AuthRole = 'read') {
-  const res = await fetch(api(`/channels/${session.id}/seats`), { method: 'POST', headers: session.authHeaders(role) });
+  const res = await fetch(api(`/channels/${session.id}/seats`), { method: 'POST', headers: headersFor(session, role) });
   expect(res.status, await res.clone().text()).toBe(200);
 }
 
@@ -105,7 +121,7 @@ async function send(session: ChannelSession, plan: ItemPlan, role: AuthRole) {
   for await (const frame of plan.frames) {
     const res = await fetch(api(`/channels/${session.id}/frames`), {
       method: 'POST',
-      headers: { ...session.authHeaders(role), 'Content-Type': 'application/octet-stream', ...(first ? plan.frame0Headers : {}) },
+      headers: { ...headersFor(session, role), 'Content-Type': 'application/octet-stream', ...(first ? plan.frame0Headers : {}) },
       body: frame.bytes,
     });
     expect(res.status, await res.clone().text()).toBeLessThan(300);
@@ -116,16 +132,17 @@ async function send(session: ChannelSession, plan: ItemPlan, role: AuthRole) {
 }
 
 async function readLog(session: ChannelSession, role: AuthRole, from = 0) {
-  const res = await fetch(api(`/channels/${session.id}/log?from=${from}`), { headers: session.authHeaders(role) });
+  const res = await fetch(api(`/channels/${session.id}/log?from=${from}`), { headers: headersFor(session, role) });
   expect(res.status).toBe(200);
   return parseLogRecords(new Uint8Array(await res.arrayBuffer()));
 }
 
 /** 连接 WebSocket(凭据放在子协议里),收集事件直到满足 until。 */
 function subscribe(session: ChannelSession, role: AuthRole, until: (events: ItemEvent[]) => boolean, from = 0) {
-  const h = session.authHeaders(role);
+  const h = headersFor(session, role);
   const protocols = ['wd.v1', `wd.role.${role}`, `wd.ep.${h['X-WD-Endpoint']!}`];
   if (h.Authorization) protocols.push(`wd.auth.${h.Authorization.replace('Bearer ', '')}`);
+  if (session.role === 'owner') protocols.push(`wd.account.${accountToken.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`);
 
   const ws = new WebSocket(`${base.replace('http', 'ws')}/api/v1/channels/${session.id}/ws?from=${from}`, protocols);
   ws.binaryType = 'arraybuffer';
@@ -227,7 +244,7 @@ suite('端到端(真实服务端)', () => {
     const frame = (await collectFrames(again))[0]!;
     const res = await fetch(api(`/channels/${owner.id}/frames`), {
       method: 'POST',
-      headers: { ...owner.authHeaders('owner'), 'Content-Type': 'application/octet-stream' },
+      headers: { ...headersFor(owner, 'owner'), 'Content-Type': 'application/octet-stream' },
       body: frame.bytes,
     });
     expect(res.status).toBe(200);
@@ -239,7 +256,7 @@ suite('端到端(真实服务端)', () => {
     const marker = 'UNIQUE-PLAINTEXT-MARKER-7f3a9c';
     await send(owner, owner.encryptText(marker), 'owner');
 
-    const res = await fetch(api(`/channels/${owner.id}/log`), { headers: owner.authHeaders('owner') });
+    const res = await fetch(api(`/channels/${owner.id}/log`), { headers: headersFor(owner, 'owner') });
     const wire = new Uint8Array(await res.arrayBuffer());
     expect(new TextDecoder('latin1').decode(wire)).not.toContain(marker);
     expect(new TextDecoder('latin1').decode(wire)).not.toContain('"kind"');
@@ -260,7 +277,7 @@ suite('端到端(真实服务端)', () => {
     expect(log.map((r) => r.kind)).toEqual(['announce']);
 
     // 流式下载 + 流式解密
-    const res = await fetch(api(`/channels/${owner.id}/items/${plan.itemId}/frames`), { headers: member.authHeaders('read') });
+    const res = await fetch(api(`/channels/${owner.id}/items/${plan.itemId}/frames`), { headers: headersFor(member, 'read') });
     expect(res.status).toBe(200);
     const { content: stream, result } = member.decryptItemStream(res.body!, { itemId: plan.idBytes });
     const out = await readAll(stream);
@@ -278,15 +295,15 @@ suite('端到端(真实服务端)', () => {
     await send(owner, plan, 'owner');
 
     const url = api(`/channels/${owner.id}/items/${plan.itemId}/frames`);
-    const first = await fetch(url, { headers: owner.authHeaders('owner') });
+    const first = await fetch(url, { headers: headersFor(owner, 'owner') });
     const decoded = owner.decryptItemStream(first.body!);
     expect(Buffer.compare(await readAll(decoded.content), content)).toBe(0);
 
-    const second = await fetch(url, { headers: owner.authHeaders('owner') });
+    const second = await fetch(url, { headers: headersFor(owner, 'owner') });
     expect(second.status).toBe(410);
     expect(((await second.json()) as { error: string }).error).toBe('gone');
 
-    const resumed = await fetch(`${url}?from=1`, { headers: owner.authHeaders('owner') });
+    const resumed = await fetch(`${url}?from=1`, { headers: headersFor(owner, 'owner') });
     expect(resumed.status).toBe(200);
     await resumed.arrayBuffer();
   }, 60_000);
@@ -308,7 +325,7 @@ suite('端到端(真实服务端)', () => {
       if (sent === 2) break;
       const res = await fetch(api(`/channels/${owner.id}/frames`), {
         method: 'POST',
-        headers: { ...owner.authHeaders('owner'), 'Content-Type': 'application/octet-stream', ...(isFirst ? first.frame0Headers : {}) },
+        headers: { ...headersFor(owner, 'owner'), 'Content-Type': 'application/octet-stream', ...(isFirst ? first.frame0Headers : {}) },
         body: f.bytes,
       });
       expect(res.status).toBe(201);
@@ -322,14 +339,14 @@ suite('端到端(真实服务端)', () => {
     for await (const f of rest.frames) {
       const res = await fetch(api(`/channels/${owner.id}/frames`), {
         method: 'POST',
-        headers: { ...owner.authHeaders('owner'), 'Content-Type': 'application/octet-stream' },
+        headers: { ...headersFor(owner, 'owner'), 'Content-Type': 'application/octet-stream' },
         body: f.bytes,
       });
       statuses.push(res.status);
     }
     expect(statuses).toEqual([200, 201, 201]); // 第 1 帧已存在(幂等),第 2、3 帧是新的
 
-    const res = await fetch(api(`/channels/${owner.id}/items/${toBase64Url(itemId)}/frames`), { headers: owner.authHeaders('owner') });
+    const res = await fetch(api(`/channels/${owner.id}/items/${toBase64Url(itemId)}/frames`), { headers: headersFor(owner, 'owner') });
     const { content: stream, result } = owner.decryptItemStream(res.body!);
     expect(Buffer.compare(await readAll(stream), content)).toBe(0);
     expect((await result).complete).toBe(true);
@@ -343,7 +360,7 @@ suite('端到端(真实服务端)', () => {
     const url = api(`/channels/${owner.id}/items/${plan.itemId}/frames`);
 
     // 第一次:只读前约 1.5 帧就断开
-    const first = await fetch(url, { headers: owner.authHeaders('owner') });
+    const first = await fetch(url, { headers: headersFor(owner, 'owner') });
     const reader = first.body!.getReader();
     const chunks: Uint8Array[] = [];
     let got = 0;
@@ -361,7 +378,7 @@ suite('端到端(真实服务端)', () => {
     })();
     expect(part1.result.complete).toBe(false);
 
-    const second = await fetch(`${url}?from=${part1.result.nextIndex}`, { headers: owner.authHeaders('owner') });
+    const second = await fetch(`${url}?from=${part1.result.nextIndex}`, { headers: headersFor(owner, 'owner') });
     expect(second.status).toBe(200);
     const dec2 = owner.decryptItemStream(second.body!, { fromIndex: part1.result.nextIndex });
     const part2 = await readAll(dec2.content);
@@ -378,12 +395,12 @@ suite('端到端(真实服务端)', () => {
     const blob = await member.sealLabel('我的 iPhone');
     const put = await fetch(api(`/channels/${owner.id}/seats/me`), {
       method: 'PUT',
-      headers: { ...member.authHeaders('read'), 'Content-Type': 'application/octet-stream' },
+      headers: { ...headersFor(member, 'read'), 'Content-Type': 'application/octet-stream' },
       body: blob,
     });
     expect(put.status).toBe(204);
 
-    const res = await fetch(api(`/channels/${owner.id}/seats`), { headers: owner.authHeaders('owner') });
+    const res = await fetch(api(`/channels/${owner.id}/seats`), { headers: headersFor(owner, 'owner') });
     const seats = (await res.json()) as Array<{ endpoint_hash: string; label?: string }>;
     const mine = seats.find((s) => s.endpoint_hash === toBase64Url(member.endpointHash))!;
     expect(await owner.openLabel(mine.label!, mine.endpoint_hash)).toBe('我的 iPhone');
@@ -396,7 +413,7 @@ suite('端到端(真实服务端)', () => {
     const blob = await owner.sealLabel('x'.repeat(228));
     const put = await fetch(api(`/channels/${owner.id}/seats/me`), {
       method: 'PUT',
-      headers: { ...owner.authHeaders('owner'), 'Content-Type': 'application/octet-stream' },
+      headers: { ...headersFor(owner, 'owner'), 'Content-Type': 'application/octet-stream' },
       body: blob,
     });
     expect(put.status).toBe(204);
@@ -415,11 +432,11 @@ suite('端到端(真实服务端)', () => {
       for (const r of records) out.push(...(await reader.push(r)));
       return out;
     })());
-    expect(item!.kind).toBe('raw');
+    expect(item!.kind).toBe('text');
     expect(itemText(item!)).toBe('raw 明文 visible');
 
     // 对比 enc:raw 的明文确实出现在服务端返回的字节里
-    const res = await fetch(api(`/channels/${owner.id}/log`), { headers: member.authHeaders('read') });
+    const res = await fetch(api(`/channels/${owner.id}/log`), { headers: headersFor(member, 'read') });
     expect(new TextDecoder().decode(await res.arrayBuffer())).toContain('raw 明文 visible');
   });
 
@@ -428,8 +445,8 @@ suite('端到端(真实服务端)', () => {
     const member = await ChannelSession.open(owner.link(ORIGIN));
     await joinChannel(member, 'read');
 
-    const res = await fetch(api(`/channels/${owner.id}/seats`), { headers: { ...member.authHeaders('read') } });
+    const res = await fetch(api(`/channels/${owner.id}/seats`), { headers: { ...headersFor(member, 'read') } });
     expect(res.status).toBe(403);
-    expect(() => member.authHeaders('owner')).toThrow();
+    expect(() => headersFor(member, 'owner')).toThrow();
   });
 });

packages/core/test/session.test.ts

@@ -315,29 +315,30 @@ describe('设备名', () => {
 });
 
 describe('raw 模式往返', () => {
-  it('单帧:负载就是内容,没有加密标志', async () => {
+  it('单帧:保留统一元数据,没有加密标志', async () => {
     const { session: owner } = await ChannelSession.create({ mode: 'raw' });
     const member = await ChannelSession.open(owner.link(ORIGIN));
 
     const [frame] = await collectFrames(owner.encryptText('明文内容'));
     expect(frame!.bytes[1]! & 8).toBe(0); // 没有 ENC 标志
-    expect(new TextDecoder().decode(frame!.bytes.slice(26))).toBe('明文内容');
+    expect(new TextDecoder().decode(frame!.bytes.slice(26))).toContain('明文内容');
 
     const item = itemOf(await member.createItemReader().pushFrame(frame!.bytes));
-    expect(item.kind).toBe('raw');
-    expect(item.meta).toBeUndefined();
+    expect(item.kind).toBe('text');
+    expect(item.meta?.kind).toBe('text');
     expect(itemText(item)).toBe('明文内容');
   });
 
   it('大内容拆成 GATED 多帧', async () => {
     const { session } = await ChannelSession.create({ mode: 'raw' });
     const content = pseudoRandom(100, 5);
-    const plan = session.encryptBytes(content, {}, { maxFrameData: 40 });
+    const plan = session.encryptBytes(content, {}, { maxFrameData: 80 });
     const frames = await collectFrames(plan);
 
     expect(plan.gated).toBe(true);
-    expect(frames.map((f) => f.bytes.length - 26)).toEqual([40, 40, 20]);
-    expect(frames.map((f) => f.final)).toEqual([false, false, true]);
+    expect(frames.length).toBeGreaterThan(1);
+    expect(frames.every((f) => f.bytes.length - 26 <= 80)).toBe(true);
+    expect(frames.at(-1)?.final).toBe(true);
 
     const reader = session.createItemReader();
     let last: ReceivedItem | undefined;
@@ -346,10 +347,11 @@ describe('raw 模式往返', () => {
     expect(toHex(last!.content)).toBe(toHex(content));
   });
 
-  it('label 放进第 0 帧的附加请求头', async () => {
+  it('名称使用与加密条目一致的元数据', async () => {
     const { session } = await ChannelSession.create({ mode: 'raw' });
-    const plan = session.encryptBytes(new Uint8Array(3), {}, { label: 'note.txt' });
-    expect(plan.frame0Headers['X-WD-Label']).toBe('note.txt');
+    const plan = session.encryptBytes(new Uint8Array(3), { name: 'note.txt' });
+    const [frame] = await collectFrames(plan);
+    expect(itemOf(await session.createItemReader().pushFrame(frame!.bytes)).meta?.name).toBe('note.txt');
   });
 });
 

packages/core/test/vectors.test.ts

@@ -149,7 +149,10 @@ describe('条目分帧', () => {
           itemId: h(item.item_id),
           ts: m.ts,
           ...(m.dev !== undefined && { dev: m.dev }),
+          ...(m.thread_id !== undefined && { threadId: m.thread_id }),
+          ...(m.folder_id !== undefined && { folderId: m.folder_id }),
           snapshot: item.snapshot,
+          control: item.control,
           gated: item.force_gated ? true : 'auto',
           maxFrameData: item.max_frame_data,
         },