Close the _attachment@1 hash-oracle with an optional atomic-upload adapter capability (#106)

[cuibonobo]

Summary

Implements #106, superseding #122. The security fix is the same as #122's: putAttachment() becomes the only non-owner path to an _attachment@1 record, closing the guessed-fileId confirmation oracle. What changed is the adapter-level design that carries it — the combined bytes+record upload is now an optional capability on the composed StackAdapter type, following the repo's existing optional-capability idiom, instead of a required tryPutAttachmentWithMetadata() on StackBlobAdapter that three of four implementations could only stub.

The security fix (unchanged from #122)

• Non-owner _attachment@1 refusal: ScopedStack.create() refuses _attachment@1 (matched by baseId) for any non-owner requester, so a bare create grant can no longer turn a guessed SHA-256 into read access via canAccessFile()'s uploader clause. One carve-out (Close the _attachment@1 hash-oracle: make putAttachment the only non-owner path to a metadata record #106 residual decision 1): a non-owner who can already read a record referencing the fileId may add another metadata record (e.g. their own filename) without re-uploading — satisfied only by a readable referencing record, never by the requester's own prior _attachment@1 record, to prevent one successful guess bootstrapping unlimited further ones.
• Wire change: POST /attachments carries Content-Type/Content-Disposition and creates the _attachment@1 record in the same request, returning the record. The fileId is established from bytes the server received in this request — possession proven by construction, with no seam for a caller-supplied string.
• Anti-oracle cleanup: the mimeType-conflict message no longer names the established mimeType, so a guessed fileId can't leak existence or metadata through the error.
• E1 fix: ScopedStack.putAttachment() normalizes owner uploads to no entityId, matching create()'s normalization (Polish batch: owner entityId stamping, unused timezone, lenient date validation, silent null content filter #69).

The design change (vs. #122)

StackBlobAdapter stays bytes-only, exactly as its contract states. The atomic upload is declared on the composed type:

type StackAdapter = StackRecordAdapter &
  StackBlobAdapter & {
    putAttachmentWithMetadata?(data, mimeType, filename?): Promise<StackRecord>;
  };

• "Bytes + record in one operation" is a property only a whole adapter can have — neither half can ever offer it, so a blob adapter can't even declare it. This deletes all the local-adapter stubs, the try prefix, and the { fileId, record? } optional-record result from Implement atomic attachment upload with metadata (#106) #122.
• It follows the established deleteUnreferencedAttachmentRecords() / listFiles() idiom (which Close the _attachment@1 hash-oracle: make putAttachment the only non-owner path to a metadata record #106 itself pointed to): optional method, truthiness-checked at the call site, described fallback. The spec paragraph explaining why the method deviated from that pattern is replaced by a third example of it.
• combineAdapters() never synthesizes it from parts — a record backend glued to a blob backend has no shared transaction to honor the atomicity promise with.
• Stack.putAttachment() delegates when the capability is present (trusting the returned record as server-authoritative; client-side validation and the mimeType-conflict check are documented as deliberately skipped — the server runs both, and a client-side conflict check against remote state would be racy and itself a mini-oracle), and otherwise falls back to its pre-existing bytes-then-create() sequence. APIAdapter is the one implementation, as a single POST /attachments.

Bytes-only upload is no longer public API

Since POST /attachments always creates a record, there is no bytes-only upload anywhere on the wire — and that emptied putAttachmentBytes()'s constituency entirely: its only wire consumer was the old bytes-only endpoint, non-owner bytes-only upload was already a documented dead end, and owner bytes-only upload just manufactures the bare-bytes orphans the GC sweep exists to clean up. So this PR removes Stack.putAttachmentBytes(), ScopedStack.putAttachmentBytes(), and the StackClient entry. The upload story is now one sentence: putAttachment(data, mimeType, filename?) is the upload operation, everywhere, for everyone.

At the adapter layer, StackBlobAdapter.putAttachment() stays required — it's the storage primitive Stack.putAttachment()'s fallback writes bytes through, and within blob storage every implementation can store bytes. On APIAdapter it throws APIAdapterError before issuing any request (there is no wire mode to map it to; approximating one would mint a default application/octet-stream record as a side effect, #122's behavior). Since Stack.putAttachment() always takes the atomic path on that adapter, the throw is unreachable from Stack's public surface and guards direct adapter-level callers only.

Note — deliberate deviation from #106 residual decision 2, which said to keep putAttachmentBytes for owner/server-internal use with no behavior change. That resolution predates the realization that the wire would lose bytes-only upload entirely, which is what left the method without a legitimate public consumer. Server-internal composition still works: ScopedStack receives the adapter from Stack.asEntity() and composes bytes + its own entityId-stamped create() directly. SDK-surface change only — no wire contract, fixtures, or stored data are affected (#57).

Tests

All #122 coverage is retained (non-owner refusal scenarios, carve-out behavior, exploit regression, anti-oracle message, E1, conformance fixtures for the wire contract), plus:

• Stack.putAttachment() delegates to putAttachmentWithMetadata() when present — arguments forwarded, no separate create() call — and falls back when absent
• combineAdapters() never synthesizes putAttachmentWithMetadata from parts
• APIAdapter.putAttachment() rejects with APIAdapterError and never touches the network
• The GC bare-bytes-orphan tests write through the adapter directly (no Stack method produces bare bytes on purpose anymore); the bytes-only gating tests are dropped as exact duplicates of the putAttachment() suite's coverage

Full suite green across all packages (855 tests), plus typecheck, lint, and format checks.

Closes #106.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QQBTuf3CnEwdvH76nvazJF