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

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 });
     },
   });