Add HMAC-SHA256 signed URL support for time-limited PDF access

[Copilot]

Storage needs to serve PDFs via signed URLs with expiration validation, no user authentication required. Backend generates signatures, storage validates and enforces access control.

Implementation

URL Signing (pkg/urlsigner)

• HMAC-SHA256 signature generation: path:timestamp → base64-encoded signature
• Validation with constant-time comparison (timing attack prevention)
• Query parameter format: ?expires={unix_ts}&signature={hmac}

Server Validation (internal/api/http/middleware/signature.go)

• Intercepts GET requests to /buckets/{bucket}/{object}
• Validates signature + expiration on PDF files only (backward compatible)
• Returns 403 for expired/invalid/missing signatures
• Bypasses validation for ?metadataOnly=true requests

Client API (pkg/filestorage)

// Generate signed URL valid for 1 hour
signedURL, err := storage.GetSignedFileURL(
    "bucket", "file.pdf", 
    1*time.Hour, 
    signingSecret,
)

Configuration

• SIGNING_SECRET env var (logs ERROR if unset)
• Shared secret between backend and storage

Behavior

Scenario	Response
Valid signature, not expired	200 + file content
Expired signature	403 Forbidden
Invalid/tampered signature	403 Forbidden
Missing signature (PDF)	403 Forbidden
Missing signature (non-PDF)	200 + file content
Metadata request	200 + metadata JSON

Testing

• 27 tests covering signing, validation, integration
• End-to-end validation with test server

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• go.googlesource.com
  • Triggering command: /update-job-proxy /update-job-proxy /home/REDACTED/work/_temp/runtime-logs/mkcert/rootCA.pem --updater-env NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/dbot-ca.crt 8426�� g_.a -I ache/go/1.24.12/168.63.129.16 --gdwarf-5 ge/internal/api/rev-parse -o ache/go/1.24.12/53 (dns block)
  • Triggering command: /update-job-proxy /update-job-proxy -o br-0a67a4931c29 -j DROP igiCert_High_Assurance_EV_Root_CA.pem /opt/hostedtoolc-e /bin/test (dns block)
• go.uber.org
  • Triggering command: /update-job-proxy /update-job-proxy /home/REDACTED/work/_temp/runtime-logs/mkcert/rootCA.pem --updater-env NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/dbot-ca.crt 8426�� g_.a -I ache/go/1.24.12/168.63.129.16 --gdwarf-5 ge/internal/api/rev-parse -o ache/go/1.24.12/53 (dns block)
  • Triggering command: /update-job-proxy /update-job-proxy -o br-0a67a4931c29 -j DROP igiCert_High_Assurance_EV_Root_CA.pem /opt/hostedtoolc-e /bin/test (dns block)
• gopkg.in
  • Triggering command: /update-job-proxy /update-job-proxy /home/REDACTED/work/_temp/runtime-logs/mkcert/rootCA.pem --updater-env NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/dbot-ca.crt 8426�� g_.a -I ache/go/1.24.12/168.63.129.16 --gdwarf-5 ge/internal/api/rev-parse -o ache/go/1.24.12/53 (dns block)
  • Triggering command: /update-job-proxy /update-job-proxy -o br-0a67a4931c29 -j DROP igiCert_High_Assurance_EV_Root_CA.pem /opt/hostedtoolc-e /bin/test (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>File Storage — Support signed, time-limited access to task PDFs</issue_title>
<issue_description>Title
File Storage: Enable signed, time-limited access for task description PDFs

Description
File storage must support signed URLs that allow temporary, unauthenticated access to individual PDF files.
Storage itself should not perform user authentication — only signature and expiration validation.

Context / Motivation

• PDFs are accessed by clients via URLs generated by the backend

• Storage must be able to validate:

  • Signature authenticity
  • Expiration timestamp
  • HTTP method (GET only)

• This allows scalable, secure file delivery without backend involvement

Requirements

• Storage must:

  • Validate cryptographic signatures generated by backend
  • Enforce expiration timestamps
  • Reject expired or tampered URLs with 403
  • Serve files only over HTTPS

• Signed URLs must:

  • Be scoped to a specific object path
  • Not allow listing, overwrite, or deletion

• Support CDN caching if applicable (signature in query params)

Non-Requirements

• No user/session authentication at storage level
• No cookies or custom auth headers
• No long-lived or public URLs

Security Considerations

• Use HMAC or provider-native signing mechanism
• Signing keys must be securely stored and rotated
• Storage access logs should include signature validation failures

Acceptance Criteria

• Valid signed URL → PDF is returned
• Expired or modified URL → 403 Forbidden
• URL without signature → 403 Forbidden
• Only GET requests are allowed

Notes

• Prefer built-in mechanisms (e.g. S3 pre-signed URLs, GCS signed URLs, Azure SAS)
• TTL should align with backend configuration</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes File Storage — Support signed, time-limited access to task PDFs #13

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

Adds signed, time-limited URL support to enable unauthenticated (but authorized via HMAC) PDF downloads, enforced at the storage service layer via HTTP middleware.

Changes:

• Introduce pkg/urlsigner for HMAC-SHA256 signing/validation (expires + signature query params).
• Enforce signed URL validation for GET requests to object endpoints, requiring signatures for PDF downloads (with a metadataOnly=true bypass).
• Expose signed URL generation from the Go client (pkg/filestorage) and document the feature.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
pkg/urlsigner/urlsigner.go	Implements HMAC signing and signature/expiry validation.
pkg/urlsigner/urlsigner_test.go	Unit tests for signing/validation behavior.
internal/api/http/middleware/signature.go	Adds request-time validation/enforcement middleware for signed URLs.
internal/api/http/middleware/signature_test.go	Middleware unit tests for valid/invalid/expired/missing signature scenarios.
internal/api/http/server/router.go	Wires the signature middleware into the server and updates NewServer signature.
internal/config/config.go	Adds SIGNING_SECRET config loading into app configuration.
cmd/app/main.go	Instantiates URLSigner and passes it into the HTTP server.
cmd/app/integration_test.go	End-to-end-ish test verifying middleware enforcement through the server handler.
pkg/filestorage/file_storage.go	Adds GetSignedFileURL to generate signed URLs from the client library.
pkg/filestorage/file_storage_test.go	Adds tests for GetSignedFileURL behavior.
SIGNED_URLS.md	New documentation for signed URL format, usage, and behavior.
Readme.md	Mentions signed URL support and links to detailed docs.
.env.dist	Adds SIGNING_SECRET to the example environment file.
.gitignore	Ignores the built file-storage binary.
go.mod	Promotes lumberjack.v2 to a direct dependency (used by logger).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.