Initial Commit

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

@@ -0,0 +1,57 @@
+# drive-plugin-chunks spec delta — DTP-25 (inline-sig)
+
+## ADDED Requirements
+
+### Requirement: Inline hint signed over fileId ‖ bytes
+
+`FileLocation.storageHints` entries with `kind: 'inline'` SHALL be
+`{ kind: 'inline'; bytes: Uint8Array; sig: Uint8Array }` where
+`sig = Ed25519-sign(driveSecretKey, fileId ‖ bytes)`. The drive
+SHALL verify the signature before returning `bytes`; failure SHALL
+throw `CHUNKS.INLINE_SIG_INVALID`.
+
+The verifier SHALL be Ed25519 over the canonical concatenation
+exposed by `inlineSigningInput(fileId, bytes)`. A tampered signature,
+tampered bytes, replay onto a different `fileId`, or signature
+produced under a different key SHALL all reject with
+`CHUNKS.INLINE_SIG_INVALID`.
+
+The `verifyInlineHint` function SHALL accept an optional
+`VerifyEd25519Fn` parameter so engine-substitution scenarios where a
+native verifier throws (rather than returning false) compose cleanly.
+When the injected verifier throws, the implementation SHALL wrap the
+exception as `CHUNKS.INLINE_SIG_INVALID` with the original error
+attached as `cause`.
+
+**Verified by:** `tests/inline-file-sig.test.ts`::"inline file with
+valid sig reads successfully" AND "inline file with bad sig throws
+INLINE_SIG_INVALID" AND "sig bound to fileId — replay onto a
+different fileId rejects" AND "byte tamper rejects with
+INLINE_SIG_INVALID" AND "rejects under a different public key" AND
+"verify catch arm wraps a throwing verifier".
+
+### Requirement: Legacy inline hints accepted with rewrite-on-write
+
+Drives reading old-format inline entries (no `sig` field) SHALL
+accept them via the `LegacyInlineHint` shape and SHALL emit a
+`drive:inline:legacy` warning event. `isLegacyInlineHint(hint)` SHALL
+discriminate the two wire shapes (legacy vs signed). On the next
+write that touches such a hint, `upgradeLegacyInlineHint(legacy,
+fileId, driveSecretKey)` SHALL produce a signed `InlineHint` so the
+upgrade lands at-rest and subsequent reads no longer trigger the
+legacy warning.
+
+**Verified by:** `tests/inline-file-sig.test.ts`::"old-format inline
+reads with warning AND rewrites with sig on next write" AND
+"isLegacyInlineHint distinguishes signed from legacy hints".
+
+### Requirement: Canonical signing input exposed
+
+`inlineSigningInput(fileId: Uint8Array, bytes: Uint8Array)` SHALL
+return `concat(fileId, bytes)` as a freshly-allocated `Uint8Array`.
+Any consumer that wants to re-derive the bytes that are signed (for
+auditing, alternate-keypath signing, or cross-checking against a
+hardware signer) SHALL use this function.
+
+**Verified by:** `tests/inline-file-sig.test.ts`::"inlineSigningInput
+is the canonical fileId ‖ bytes concatenation".