feat(seed): add advanced transfer seed UI (generate/preview/manage)

[PIKACHUIM]

---

title: Advanced Transfer Seeds — Implementation PR
categories: [guide, advanced]
top: 22

Advanced Transfer Seeds — Implementation PR

This document is the implementation pull-request description for the Advanced Transfer Seeds feature. It complements the design and compatibility specification in transfer-seeds.md and records what was actually implemented, how it was validated, and what remains out of scope.

1. Summary

Advanced Transfer Seeds add a portable, cross-driver, cross-user metadata system built on three sidecar formats:

• .oss — openlist-sharing-seed v1 JSON. The most complete and lossless envelope; every field is optional except format, version, name, created_at, created_by, piece_size, and files.
• .torrent — standard BitTorrent v1 plus a root-level x-openlist extension and a legacy-compatible x-cas extension. Always carries the SHA-1 piece hashes required by BT; additional MD5/SHA-256 and comments/sources live in the extension.
• .cas — byte-for-byte compatible with the reference OpenList-CAS payload: padded Base64 of JSON containing exactly name, size, md5, sliceMd5, and create_time. No extension keys are added, preserving third-party client compatibility.

Users can generate seeds during upload or from the right-click context menu, preview and consume them, convert between formats, rapid-save into another driver, relay a save through an intermediate driver, and edit/recalculate metadata.

2. What is included

Repository	Branch	Scope
OpenList-Backends	feat/advanced-transfer-seeds	Go format library, /fs/seed/* API, upload sidecars, file-op sidecars, settings
OpenList-Frontend	feat/advanced-transfer-seeds	HopeUI generation wizard, seed preview, upload/file-op sidecar toggles, settings
OpenList-TSWorker	feat/advanced-transfer-seeds	TS codec and /fs/seed/* routes, streaming hashing, settings
OpenList-Docs	docs/advanced-transfer-seeds	Design spec, compatibility reference, and this PR document

Implemented capabilities:

1. Generate — single or multiple files, three formats at once (oss, torrent, cas), a content hash matrix (md5/sha1/sha256 × whole/pieces), per-file and overall comments, trackers, channels, piece size, and optional share/direct-source embedding.
2. Preflight — driver-provided hashes are reported so the UI can show whether files must be fetched before generation, and the estimated traffic.
3. Preview/parse — unified parsing of .oss, .torrent, and .cas with files, hashes, comments, timestamps, trackers, channels, sources, conversion feasibility, and operation capabilities.
4. Convert — between all three formats with explicit missing-information diagnostics; semantic projection is used instead of incorrect strict-subset claims.
5. Rapid upload — native driver reuse (189pc CAS) when hashes are available; otherwise an explicit unavailable reason (never a silent generic upload).
6. Offline download — authorized source URL into the destination driver via PutURL, an offline-download tool, or a server-side streamed transfer.
7. Relayed transfer — options.mode: "transfer" with transit_path materializes synchronously into an intermediate storage (native rapid upload or PutURL), then copies server-side to the final destination. Asynchronous offline downloads are rejected for relay.
8. Edit — update the overall comment, trackers, channels, per-file comments, and per-file share/direct sources; sources are validated against the configured site URL.
9. Recalculate — re-read server-side files (bounded to 1 GiB) and recompute whole and piece hashes using a supplied matrix; the piece size is validated and written back to the seed.
10. Sidecar lifecycle — upload, copy, move, rename, and delete can optionally manage .oss/.torrent/.cas sidecars alongside the source file.

3. Format specification

.oss (openlist-sharing-seed v1)

{
  "format": "openlist-sharing-seed",
  "version": 1,
  "name": "example",
  "comment": "",
  "created_at": "2026-09-08T00:00:00Z",
  "created_by": "OpenList",
  "piece_size": 10485760,
  "trackers": [],
  "channels": [{"driver": "189pc", "mount_path": "/189pc"}],
  "files": [
    {
      "path": "a.txt",
      "size": 12,
      "modified": "2026-09-08T00:00:00Z",
      "comment": "",
      "hashes": {
        "md5": "...",
        "sha1": "...",
        "sha256": "...",
        "pieces": {"md5": ["..."], "sha1": ["..."], "sha256": ["..."]}
      },
      "sources": [{"type": "openlist-direct", "url": "https://site/d/path"}]
    }
  ]
}

• channels contain only public driver and optional mount_path; credentials are never serialized.
• sources are public direct (/d/) or share (/sd/) URLs validated against the configured site URL.

.torrent

Standard BT v1 info/pieces plus a root x-openlist dictionary holding the same optional metadata and a root x-cas dictionary for 189pc rapid-upload info. x-openlist is cross-validated against info (name, piece length, file list, and SHA-1 pieces) before use.

.cas

Strict reference payload. No extension keys. Large files require either a preserved legacy aggregate sliceMd5 or complete 10 MiB MD5 pieces so conversion is lossless.

4. API reference

All endpoints are under POST /api/fs/seed/* (mounted as /fs/seed/*), with legacy /fs/torrent/* routes retained.

Endpoint	Purpose
/capabilities	Source preflight and destination import planning
/generate	Generate one or more seed artifacts
/parse	Parse and preview a seed document
/convert	Convert between formats with diagnostics
/rapid_upload	Native driver reuse only
/offline_download	Source → destination transfer (including relayed transfer)
/update	Edit metadata and/or recalculate hashes

Common operation envelope: { "seed_data": "<base64>", "file_name": "...", "path": "...", "selected_files": [0], "options": {...} }.

parse returns capabilities: rapid_upload, offline_download, transfer, convert, edit, and recalculate, so the UI only enables actions the backend actually supports.

5. Settings

• seed_site_url — public site URL used to build share/direct sources (required before embedding sources).
• seed_default_matrix — default right-click hash matrix.
• seed_format_policies — global per-format auto-generation switches (all default off).
• seed_auto_generate_policy — global off/on automatic sidecar policy.
• seed_single_direct_preview — open single-file seeds directly in preview (default off).
• Per-storage seed_policy — inherit/on/off override that resolves against the global default.

6. Acceptance criteria

1. Generating a seed for N files reads each file once and computes whole and piece MD5/SHA-1/SHA-256 without loading a whole file into memory.
2. Selecting torrent forces SHA-1 whole + pieces; selecting cas forces MD5 whole + pieces and a fixed 10 MiB slice size.
3. .cas output is byte-identical to the reference five-field payload and round-trips without extra keys.
4. A seed with only MD5 cannot be converted to torrent (missing SHA-1 pieces) and reports that reason.
5. rapid_upload never silently falls back to a generic upload; it reports unavailable.
6. A relayed transfer refuses asynchronous offline downloads and requires a synchronous intermediate save.
7. update validates source URLs against the configured site and rejects cross-host URLs.
8. recalculate writes the effective piece size back to the seed so piece hashes and piece_size stay consistent.
9. File operations with follow_seed only touch sidecars of real files, not directories.
10. All seed parsing enforces byte, file-count, depth, and path-traversal limits.

7. Validation

• Go: go build ./... passes; go test ./pkg/torrent/... ./server/handles/... ./internal/op/... passes (format compatibility, path safety, parse limits).
• TypeScript: tsc --noEmit reports zero errors in internal/seed and server/seed.
• HopeUI: pnpm lint reports zero errors in the seed preview, types, and API files; production build transforms 1209 modules successfully.

8. Security, stability, performance, compliance

• Security: path-traversal checks, content-write and copy/offline-download permission bits, source URLs restricted to the configured site, SSRF-safe fetch with redirect re-validation, and parse resource limits.
• Stability: streaming single-pass hashing, bounded memory, synchronous-vs-async relay separation, and rollback of created shares on generation failure.
• Performance: single-pass multi-hash computation, driver-capability preflight to avoid unnecessary fetches, and 1 GiB synchronous hashing bound.
• Compliance: no credentials or usernames are serialized into shareable seeds; channels carry only public discovery metadata.

9. Risks and limitations

• .cas intentionally preserves only the five reference fields; it is lossy by design and cannot carry comments, channels, trackers, or sources.
• Relayed transfer requires an intermediate storage with synchronous native reuse or PutURL; a fully asynchronous cross-driver relay is out of scope.
• Recalculate requires the source file to already exist on the server; it does not download from an external source.
• BT distribution produces a valid .torrent but does not make OpenList a BitTorrent peer; tracker/webseed availability depends on deployment.