suaveplan/openspec/archive/2026-05-11-drive-plugin-chunks-inline-sig/proposal.md

drive-plugin-chunks-inline-sig

Why

DTP-25 (carved out of drive-template-v1) requires that FileLocation.storageHints entries with kind: 'inline' carry an Ed25519 signature over fileId ‖ bytes. Without the sig, an attacker who can write to drive storage (or who can MITM a peer-to-peer drive hand-off) could replace the inline body of a small file with arbitrary bytes; the read-side has no other mechanism to detect tamper because inline files do not flow through the chunk-by-chunk sign / verify pipeline.

The change ships the surface in @suaveplan/drive-plugin-chunks so the chunks plugin owns both flows for small files (chunked path and inline path). Backward compatibility ships in the same change: legacy inline hints (no sig field) read with a drive:inline:legacy warning and rewrite-with-sig on the next write.

What Changes

• Add INLINE_SIG_INVALID to CHUNKS_CODES in packages/drive/drive-plugin-chunks/src/error-codes.ts.
• Add src/inline/ module: inline-hint.ts + inline-hint.md + index.ts exporting InlineHint, LegacyInlineHint, AnyInlineHint, StorageHint, FileLocation, signInlineHint, verifyInlineHint, isLegacyInlineHint, upgradeLegacyInlineHint, inlineSigningInput, VerifyEd25519Fn.
• Wire the new surface into src/index.ts.
• Add tests/inline-file-sig.test.ts covering the three required spec test names plus tamper, fileId-replay, key-mismatch, signing-input canonicalisation, and the catch-arm-via-injectable- verifier paths.
• Update error-codes.md to mention the twelfth code.
• The verifyInlineHint verifier is injectable (defaults to @noble/curves Ed25519) so the catch arm — wrapping a throwing native verifier — is testable without istanbul ignore annotations.

Impact

• Public API addition — no existing consumers depend on inline-hint surface yet (drive-template / drive consumers will adopt this in a follow-up wiring change once they begin emitting FileLocation).
• Wire format: legacy inline hints ({ kind, bytes }) remain readable and are rewritten with sig on next write, so on-disk drives are forward-compat.
• Error registry grows from eleven to twelve codes.
• 100% coverage gate maintained (74 tests, all passing); docs coverage 17/17.