Skip to content

feat(uploads): bind presigned PUT URLs to the file's SHA-256 checksum - #1981

Merged
pyramation merged 1 commit into
mainfrom
feat/checksum-bound-presigned-put
Nov 10, 2026
Merged

pyramation merged 1 commit into
mainfrom
feat/checksum-bound-presigned-put

Conversation

@pyramation

Copy link
Copy Markdown
Contributor

Summary

A presigned PUT URL was signed over content-length;host only, so any body of the declared size could be written behind a content-addressed key — including a second PUT through the same URL after the first one was confirmed. The URL is now signed over the file's SHA-256 as well, so the object store itself refuses bytes that don't hash to the contentHash the upload was requested with.

graphile-presigned-url-plugin (s3-signer.ts):

generatePresignedPutUrl(s3Config, key, contentType, contentLength, expiresIn, contentHash?)
  // PutObjectCommand({ ..., ChecksumSHA256: checksumSha256Base64(contentHash) })
  // getSignedUrl(..., { unhoistableHeaders: new Set(['x-amz-checksum-sha256']) })
headObject(...) // HeadObjectCommand({ ..., ChecksumMode: 'ENABLED' }) → { ..., checksumSha256? }
  • checksumSha256Base64 is base64 of the raw digest (Buffer.from(hex, 'hex')), the S3 checksum encoding — not base64 of the hex string.
  • unhoistableHeaders matters: the presigner otherwise moves the checksum into the query string, where the store ignores it. As a signed header a wrong body gets 400 BadDigest and a PUT without the header gets 403 SignatureDoesNotMatch (verified against RustFS in s3-signer.integration.test.ts).
  • requestUploadUrl passes the already-validated contentHash; custom-key replace/versioning paths are unchanged (no conditional write — the key can still be replaced, only by bytes that hash to the new request's contentHash).

Clients:

  • @constructive-io/upload-client: putToPresignedUrl(url, body, contentType, signalOrOptions?) takes { signal?, contentHash? } (an AbortSignal still works). When no contentHash is given and the body is in memory (string / ArrayBuffer / typed array / Blob) it hashes it itself (sha256HexOfBody), so existing callers keep working. uploadFile, the XHR progress path and storageTransport.putObject pass the hash they already compute; presignedPutHeaders / sha256HexToBase64 are exported for raw-fetch callers.
  • @constructive-io/graphql-query StorageTransport.putObject(..., signal?, contentHash?); @constructive-io/site-deploy PutObject gets the same trailing contentHash and the default put passes file.hash.
  • @constructive-io/bucket-provisioner: CORS allows x-amz-checksum-sha256.

Rollout: a store that receives the header on a URL that wasn't signed over it still accepts the PUT, so clients can send it before the server signs it; once a server signs it, clients that don't send it get 403, so update raw-fetch clients first.

Link to Devin session: https://app.devin.ai/sessions/136c0078e2fa4f39a88a32ffd4480ed8
Open in Devin Desktop: https://app.devin.ai/desktop/session/136c0078e2fa4f39a88a32ffd4480ed8?variant=devin
Requested by: @pyramation

generatePresignedPutUrl signs x-amz-checksum-sha256 (base64 of the raw
digest of the client's contentHash) into the URL as a header, so the object
store rejects a body that does not hash to it and a PUT that omits it.
headObject asks for ChecksumMode ENABLED and returns checksumSha256.

Clients send the header: putToPresignedUrl accepts { signal, contentHash }
(and hashes an in-memory body itself when no hash is given), uploadFile,
the storage transport and site-deploy pass the hash they already compute,
and bucket CORS allows x-amz-checksum-sha256.
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@luxor-code-review

luxor-code-review Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Review complete. 🟡 1 medium

💬 Inline comments (1)

  • 🟡 Optional contentHash lets custom transports break uploads — transport.ts:31
🧹 Nitpicks (1) — 🟢 1 low
  • 🟢 Test fake drops contentHash — forwarding is untested (storage.node.test.ts:115) — The fake StorageTransport in graphql/query/tests/storage.node.test.ts:119 still has the old 4-argument signature and PutCall records only url/contentType/size, so nothing asserts that uploadToSurface forwards the hash.

The change makes upload integrity checksum-bound end to end: the upload client computes the SHA-256 of the body and sends it as a signed header, the GraphQL upload surface requires and forwards the hash, and the presigned-URL plugin signs it into the PUT so tampered payloads fail signature validation. Bucket CORS rules now allow the checksum header, and site-deploy CAS uploads pass the hash through the retry wrapper. Tests cover the new signer, checksum helpers, and integration flows.

Files Change
graphile/graphile-presigned-url-plugin/src/s3-signer.ts, plugin.ts, index.ts Accept contentHash, validate hex format, and sign it as an unhoistable x-amz-checksum-sha256 header on presigned PUTs; require the hash as a GraphQLNonNull upload input
packages/upload-client/src/checksum.ts, put.ts, upload.ts, storage-transport.ts, index.ts Add sha256HexOfBody/base64 helpers, auto-hash bodies before PUT, lower-case hex, and forward contentHash through fetch and XHR transports
graphql/query/src/storage/transport.ts, upload.ts Extend StorageTransport.putObject with an optional contentHash argument and forward the GraphQL-supplied hash to the transport
packages/bucket-provisioner/src/cors.ts Add x-amz-checksum-sha256 to allowed and exposed CORS headers for upload and private bucket rules
packages/site-deploy/src/cas-upload.ts, types.ts Pass the file hash through the upload retry path and update the PutObject type signature
test files across the four packages New integration/unit tests for the signer, checksum helpers, and checksum-bound upload flows

No critical or high-severity issues were found; the main medium-severity concern is that putObject's contentHash parameter is optional, so out-of-tree transport implementations that ignore it will fail at S3 signature time rather than compile time.

Reviewed commit: 8df8ea6

@luxor-code-review luxor-code-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR binds every presigned S3 PUT to a client-supplied SHA-256 checksum via an unhoistable x-amz-checksum-sha256 header, threading the hash from the upload client through GraphQL to the signer and updating CORS, CAS upload, and tests accordingly.

Key findings

  • 🟡 Optional contentHash lets custom transports break uploads — transport.ts:31

Comment on lines 31 to 37
putObject(
url: string,
body: ArrayBuffer,
contentType: string,
signal?: AbortSignal,
contentHash?: string,
): Promise<void>;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 bug · medium

Optional contentHash lets custom transports break uploads

StorageTransport.putObject accepts contentHash as an optional trailing parameter (graphql/query/src/storage/transport.ts:31), but the server now makes contentHash a required upload input and signs x-amz-checksum-sha256 into every presigned PUT as an unhoistable header (graphile/graphile-presigned-url-plugin/src/s3-signer.ts:71). A pre-existing custom transport that ignores the fifth argument still type-checks but silently sends no header, so its PUTs fail S3 signature validation with an opaque 403. The same optional signature appears in packages/site-deploy/src/types.ts at line 102.

📋 Prompt for AI Agents

In graphql/query/src/storage/transport.ts lines 31-37, change putObject's trailing contentHash?: string to a required contentHash: string, and update the call site in graphql/query/src/storage/upload.ts:117, the default transport in packages/upload-client/src/storage-transport.ts, the PutObject type in packages/site-deploy/src/types.ts:102, and the test fakes in graphql/query/tests/storage.node.test.ts:119. The server signs x-amz-checksum-sha256 into every presigned PUT URL, so a transport that silently drops the hash produces opaque 403 signature errors; requiring the parameter forces third-party implementations to handle it at compile time.

@pyramation
pyramation merged commit 7ccf4d9 into main Nov 10, 2026
20 checks passed
@pyramation
pyramation deleted the feat/checksum-bound-presigned-put branch November 10, 2026 06:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant