Initial Commit

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

@@ -0,0 +1,50 @@
+# 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.