feat(objectstore): add Rask.ObjectStore, an S3 and Azure Blob client with no cloud SDK

[pal-tamas]

Item 2 of #642.

Why a client rather than an SDK

The AWS and Azure SDKs are large, reflection-heavy, and not usable from a browser — which rules them out for the place this is most needed: a WASM app talking to a bucket with no backend in between. Signing SigV4 is a few dozen lines of HMAC and an Azure SAS needs no signing at all, so Rask.ObjectStore does both itself and runs unchanged server-side and in the browser.

It is standalone (Microsoft.Extensions.* only, no Rask.Core), so it is also immediately useful outside #642: Rask.SQLite.Snapshots currently has only a DirectorySnapshotStore, and this is what a cloud one would be built on.

IObjectStore

Deliberately the small intersection every store agrees on, covering S3, Cloudflare R2, Google Cloud Storage (via its S3 interop keys), MinIO, Backblaze B2, DigitalOcean Spaces and Azure Blob.

• Ranged reads, streamed writes. Object storage charges per byte moved, so GetRangeAsync asks for a range rather than an object. PutAsync(key, Stream, length) uploads without buffering, keeping object size and memory use unrelated.
• A missing object returns null; a range past the end returns a short read. Kept distinguishable on purpose — anything walking an append-only log must tell "gone" from "nothing new yet", and collapsing them is how a sync client silently concludes its peers vanished.
• TryCreateAsync is mutual exclusion without a lock service — atomic compare-and-create via If-None-Match: *, which S3, Azure Blob and GCS all support. Chosen over an Azure blob lease, which exists on one provider, needs renewal, and strands the resource if the holder disappears.
• Credentials are asked for per request, so an expiring STS session or SAS refreshes without rebuilding the store.

How SigV4 is verified

This is the part worth reviewing. A signature that is wrong by one byte is rejected exactly like no signature, and the service never says which part was wrong — so it is either exactly right or silently useless.

The expected Authorization headers in the tests were produced by a separate implementation of the algorithm written in Python from the AWS specification, not by running this code and recording its output. A golden file captured from the implementation under test would only prove it hasn't changed.

That Python reference self-checks against a published vector before its output is used — and that self-check failed on the first run, which was the point of having it. The cause turned out to be a misremembered constant rather than a wrong algorithm, so I pulled the specification and confirmed the derivation and every encoding rule against it. The remaining tests then assert the rules the spec names individually — %20 rather than +, no double-encoding, slashes preserved in a key name, query parameters sorted after encoding, which headers must be signed — so a shared misreading is caught as well as a coding mistake.

Two judgement calls that differ from a minimal reading of the spec:

• Range and If-None-Match are signed, though only host and x-amz-* are required. They are what say which bytes are being read and whether an existing object may be overwritten; unsigned, anything in the middle could change the meaning of the request. They are safe to sign because this client sets them itself, unlike hop-by-hop headers.
• TryCreateAsync treats 409 as well as 412 as "someone else won", because S3-compatible stores disagree about which they return.

A limitation found by a failing test

I had asserted that x/y/z and x%2Fy%2Fz sign differently. They don't: System.Uri normalises %2F back to a real separator while parsing, so a key whose name contains an encoded slash is indistinguishable from a path separator before any signing code can see it. Such keys are legal in S3 and unreachable through this client.

That is now documented on IObjectStore and pinned by a test, so if the platform ever changes the behaviour it says so rather than a signature quietly starting to differ.

Clock skew

SigV4 rejects any request more than 15 minutes off the service's clock, and device clocks are genuinely wrong often enough to matter — a user a day out would otherwise get a 403 that says nothing about time. The service's own Date is read from the rejected response and subsequent requests sign against corrected time, so a wrong clock costs one round trip. The streaming upload path probes for the offset first, because a forward-only stream cannot be rewound for a retry.

Testing

• 58 unit tests: three cross-implementation SigV4 vectors, the individually-named encoding rules, and behaviour for both stores (URL shape, path vs virtual-host addressing, range arithmetic, 404/416 handling, conditional-create outcomes, list pagination for both S3 continuation tokens and Azure markers, credential resolution and DI precedence).
• Full local unit gate green, dotnet format --verify-no-changes clean, solution builds -warnaserror clean on both net10.0 and net10.0-browser.
• Browser E2E green (GuideCatalog.cs is under samples/).
• PackageDependencyTests green — which is what forced the pack steps in release.yml and nightly.yml and the NUGET.md entry. Without those the package would have been built, tested and documented while existing on no feed.

Docs

New docs/object-storage.md (provider table, credentials, the CORS and clock-skew traps, and the stated limits), its own NUGET.md, a guide-catalog entry, llms.txt, and the CHANGELOG.

Not included

Multipart upload, presigned URL generation, bucket administration and server-side copy. Presigned URLs are worth adding to the snapshot-upload path later — they fit "one method, one key, one expiry" — but they do not fit a sync client minting new keys continuously and needing LIST, which would need a backend to mint them and is the thing #642 exists to avoid.