Commit453d09d7Recorded6 Sep 2026Repositorysigil-cloudflare

Prepare R2 client release with readable source and live verification notes

Changed
 AGENTS.md                     |   3 ++-
 README.md                     |   5 +++--
 package.sgl                   |   9 +++++++--
 src/cloudflare/r2.sgl         | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------
 src/cloudflare/r2/signing.sgl | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------------------------------------
 test/test-network.sgl         |  12 ++++++++++--
 test/test-signing.sgl         |   7 ++++++-
 7 files changed, 252 insertions(+), 100 deletions(-)
Diff
AGENTS.mdmodified
@@ -9,4 +9,5 @@ and sigil-crypto. Preserve raw-key UTF-8 signing semantics and test against an
9
independent reference, including maximum key sizes and malformed input.
10
Run `sigil test --sgl --strict` and `node test/http.mjs`; the latter starts an
11
ephemeral loopback fake service. Tests must never use real credentials or R2.
−12
No live-provider verification has been performed. Keep README limits accurate.
+12
Keep README limits and verification evidence accurate. Format Sigil with readable
+13
line breaks and consistent indentation; avoid compressing statements and bindings.
README.mdmodified
@@ -76,8 +76,9 @@ They also check deletion, error status, truncated response rejection and that
76
redirects/retries do not send extra requests. `test-port:` explicitly enables
77
an HTTP endpoint restricted to 127.0.0.1 for fake-service tests; use fake credentials.
78
−79
No live R2 bucket has been tested yet. Cloudflare bucket credentials, the custom
−80
domain and Rezvibe's in-page upload integration remain to be configured.
+79
A separate live-provider verification on 2026-09-06 exercised a 4096-byte
+80
PUT/GET/HEAD/DELETE round trip against R2 and removed the temporary probe object.
+81
This manual check used authorized credentials outside the automated test suite.
82
83
References: [Cloudflare R2 S3 API](https://developers.cloudflare.com/r2/api/s3/api/),
84
[custom domains](https://developers.cloudflare.com/r2/buckets/public-buckets/),
package.sglmodified
@@ -13,5 +13,10 @@
13
dev-dependencies: (list
14
(from-git url: "codeberg:sigil/sigil" package: "sigil-test" version: ">=0.21")
15
(from-git url: "codeberg:sigil/sigil" package: "sigil-test-runner" version: ">=0.21"))
−16
tasks: (list (task name: 'build description: "Compile Cloudflare modules"
−17
steps: (list (compile-sigil-modules sources: "src/**/*.sgl" output-dir: (config-output-subdir "lib"))))))
+16
tasks: (list
+17
(task name: 'build
+18
description: "Compile Cloudflare modules"
+19
steps: (list
+20
(compile-sigil-modules
+21
sources: "src/**/*.sgl"
+22
output-dir: (config-output-subdir "lib"))))))
src/cloudflare/r2.sglmodified
@@ -1,73 +1,142 @@
1
;;; Cloudflare R2's S3 API. All calls are synchronous, buffered and do not retry.
2
(define-library (cloudflare r2)
−3
(import (sigil core) (sigil io) (sigil string) (sigil list) (sigil time)
−4
(sigil http client) (cloudflare r2 signing))
−5
(export r2-client r2-put-object r2-get-object r2-head-object r2-delete-object r2-public-url)
+3
(import (sigil core)
+4
(sigil io)
+5
(sigil string)
+6
(sigil list)
+7
(sigil time)
+8
(sigil http client)
+9
(cloudflare r2 signing))
+10
+11
(export r2-client
+12
r2-put-object
+13
r2-get-object
+14
r2-head-object
+15
r2-delete-object
+16
r2-public-url)
+17
18
(begin
19
;; A closure deliberately keeps credentials out of printed client values.
20
(define (r2-client account-id access-key-id secret-access-key bucket
−9
(keys: (public-base-url #f) (timeout 30) (test-port #f)))
−10
(unless (and (string? account-id) (= (string-length account-id) 32)
−11
(every (lambda (c) (or (and (char<=? #\0 c) (char<=? c #\9)) (and (char<=? #\a c) (char<=? c #\f))))
+21
(keys: (public-base-url #f)
+22
(timeout 30)
+23
(test-port #f)))
+24
(unless (and (string? account-id)
+25
(= (string-length account-id) 32)
+26
(every (lambda (c)
+27
(or (and (char<=? #\0 c) (char<=? c #\9))
+28
(and (char<=? #\a c) (char<=? c #\f))))
29
(string->list account-id)))
30
(error "R2 account ID must be 32 lowercase hex characters"))
−14
(unless (and (string? bucket) (<= 3 (string-length bucket) 63)
−15
(every (lambda (c) (or (and (char<=? #\a c) (char<=? c #\z)) (and (char<=? #\0 c) (char<=? c #\9)) (char=? c #\-))) (string->list bucket))
+31
(unless (and (string? bucket)
+32
(<= 3 (string-length bucket) 63)
+33
(every (lambda (c)
+34
(or (and (char<=? #\a c) (char<=? c #\z))
+35
(and (char<=? #\0 c) (char<=? c #\9))
+36
(char=? c #\-)))
+37
(string->list bucket))
38
(not (char=? (string-ref bucket 0) #\-))
−17
(not (char=? (string-ref bucket (- (string-length bucket) 1)) #\-)))
+39
(not (char=? (string-ref bucket (- (string-length bucket) 1))
+40
#\-)))
41
(error "Invalid R2 bucket name"))
−19
(unless (and (string? access-key-id) (> (string-length access-key-id) 0)
+42
(unless (and (string? access-key-id)
+43
(> (string-length access-key-id) 0)
44
(every char-alphabetic-or-numeric? (string->list access-key-id))
−21
(string? secret-access-key) (> (string-length secret-access-key) 0)
−22
(number? timeout) (> timeout 0))
+45
(string? secret-access-key)
+46
(> (string-length secret-access-key) 0)
+47
(number? timeout)
+48
(> timeout 0))
49
(error "Invalid R2 credentials or timeout"))
50
(when test-port
−25
(unless (and (integer? test-port) (<= 1 test-port 65535)) (error "Invalid R2 loopback test port")))
−26
(when public-base-url (validate-public-origin public-base-url))
−27
(let* ((host (if test-port (string-append "127.0.0.1:" (number->string test-port))
−28
(string-append account-id ".r2.cloudflarestorage.com")))
+51
(unless (and (integer? test-port) (<= 1 test-port 65535))
+52
(error "Invalid R2 loopback test port")))
+53
(when public-base-url
+54
(validate-public-origin public-base-url))
+55
(let* ((host (if test-port
+56
(string-append "127.0.0.1:" (number->string test-port))
+57
(string-append account-id ".r2.cloudflarestorage.com")))
58
(origin (string-append (if test-port "http://" "https://") host)))
59
(lambda (action key body headers)
60
(validate-key key)
61
(if (eq? action 'public-url)
−33
(and public-base-url (string-append public-base-url "/" (r2-uri-encode key preserve-slashes?: #t)))
−34
(let* ((now (current-second))
−35
(stamp (string-append (string-join (string-split (format-date now #t) "-") "") "T"
−36
(string-join (string-split (format-time now #t) ":") "") "Z"))
−37
(signed (r2-sign-request action (string-append "/" bucket "/" key) '()
−38
(cons (cons "host" host) headers) (or body (make-bytevector 0))
−39
access-key-id secret-access-key stamp))
−40
;; The HTTP client supplies Host itself. Sending it twice can
−41
;; invalidate the signature; sign once, send once.
−42
(wire-headers (filter (lambda (h) (not (string=? (car h) "host"))) (dict-ref signed headers:)))
−43
(result (http-fetch-bytes action (string-append origin (dict-ref signed path:))
−44
headers: wire-headers body: body timeout: timeout)))
−45
(when result
−46
(let* ((length-header (assoc "content-length" (dict-ref result headers:)))
−47
(expected (and length-header (string->number (cdr length-header)))))
−48
(when (and (not (eq? action 'HEAD)) expected
−49
(not (= expected (bytevector-length (dict-ref result body:)))))
−50
(set! result #f))))
−51
result)))))
+62
(and public-base-url
+63
(string-append public-base-url "/"
+64
(r2-uri-encode key preserve-slashes?: #t)))
+65
(let* ((now (current-second))
+66
(stamp (string-append
+67
(string-join (string-split (format-date now #t) "-") "")
+68
"T"
+69
(string-join (string-split (format-time now #t) ":") "")
+70
"Z"))
+71
(signed (r2-sign-request
+72
action (string-append "/" bucket "/" key) '()
+73
(cons (cons "host" host) headers)
+74
(or body (make-bytevector 0))
+75
access-key-id secret-access-key stamp))
+76
;; The HTTP client supplies Host itself. Sending it twice can
+77
;; invalidate the signature; sign once, send once.
+78
(wire-headers (filter (lambda (h)
+79
(not (string=? (car h) "host")))
+80
(dict-ref signed headers:)))
+81
(result (http-fetch-bytes
+82
action (string-append origin (dict-ref signed path:))
+83
headers: wire-headers body: body timeout: timeout)))
+84
(when result
+85
(let* ((length-header (assoc "content-length"
+86
(dict-ref result headers:)))
+87
(expected (and length-header
+88
(string->number (cdr length-header)))))
+89
(when (and (not (eq? action 'HEAD))
+90
expected
+91
(not (= expected
+92
(bytevector-length (dict-ref result body:)))))
+93
(set! result #f))))
+94
result)))))
+95
96
(define (char-alphabetic-or-numeric? c)
−53
(or (and (char<=? #\a c) (char<=? c #\z)) (and (char<=? #\A c) (char<=? c #\Z)) (and (char<=? #\0 c) (char<=? c #\9))))
+97
(or (and (char<=? #\a c) (char<=? c #\z))
+98
(and (char<=? #\A c) (char<=? c #\Z))
+99
(and (char<=? #\0 c) (char<=? c #\9))))
+100
101
(define (validate-public-origin origin)
102
;; A public URL is a separate R2 custom-domain origin, never the signed API.
103
(let ((url (and (string? origin) (parse-url origin))))
−57
(unless (and url (string=? (url-scheme url) "https")
−58
(not (url-query url)) (string=? (url-path url) "/")
−59
(not (string-contains? origin "@")) (not (string-contains? origin "#"))
−60
(not (string-contains? origin "\r")) (not (string-contains? origin "\n"))
−61
(not (char=? (string-ref origin (- (string-length origin) 1)) #\/)))
+104
(unless (and url
+105
(string=? (url-scheme url) "https")
+106
(not (url-query url))
+107
(string=? (url-path url) "/")
+108
(not (string-contains? origin "@"))
+109
(not (string-contains? origin "#"))
+110
(not (string-contains? origin "\r"))
+111
(not (string-contains? origin "\n"))
+112
(not (char=? (string-ref origin (- (string-length origin) 1))
+113
#\/)))
114
(error "R2 public base URL must be an HTTPS origin without a trailing slash"))))
+115
116
(define (validate-key key)
−64
(unless (and (string? key) (<= 1 (bytevector-length (string->utf8 key)) 1024))
+117
(unless (and (string? key)
+118
(<= 1 (bytevector-length (string->utf8 key)) 1024))
119
(error "R2 object key must contain 1 to 1024 UTF-8 bytes")))
−66
(define (r2-put-object client key bytes (keys: (content-type "application/octet-stream") (cache-control #f)))
−67
(unless (bytevector? bytes) (error "R2 upload body must be a bytevector"))
−68
(client 'PUT key bytes (append (list (cons "content-type" content-type))
−69
(if cache-control (list (cons "cache-control" cache-control)) '()))))
−70
(define (r2-get-object client key) (client 'GET key #f '()))
−71
(define (r2-head-object client key) (client 'HEAD key #f '()))
−72
(define (r2-delete-object client key) (client 'DELETE key #f '()))
−73
(define (r2-public-url client key) (client 'public-url key #f '()))))
+120
+121
(define (r2-put-object client key bytes
+122
(keys: (content-type "application/octet-stream")
+123
(cache-control #f)))
+124
(unless (bytevector? bytes)
+125
(error "R2 upload body must be a bytevector"))
+126
(client 'PUT key bytes
+127
(append (list (cons "content-type" content-type))
+128
(if cache-control
+129
(list (cons "cache-control" cache-control))
+130
'()))))
+131
+132
(define (r2-get-object client key)
+133
(client 'GET key #f '()))
+134
+135
(define (r2-head-object client key)
+136
(client 'HEAD key #f '()))
+137
+138
(define (r2-delete-object client key)
+139
(client 'DELETE key #f '()))
+140
+141
(define (r2-public-url client key)
+142
(client 'public-url key #f '()))))
src/cloudflare/r2/signing.sglmodified
@@ -1,75 +1,138 @@
1
;;; S3 Signature Version 4. Inputs are raw paths/query strings, never pre-escaped.
2
(define-library (cloudflare r2 signing)
−3
(import (sigil core) (sigil io) (sigil math) (sigil string) (sigil list) (sigil crypto))
−4
(export r2-uri-encode r2-canonical-query r2-sign-request)
+3
(import (sigil core)
+4
(sigil io)
+5
(sigil math)
+6
(sigil string)
+7
(sigil list)
+8
(sigil crypto))
+9
+10
(export r2-uri-encode
+11
r2-canonical-query
+12
r2-sign-request)
+13
14
(begin
15
(define hex "0123456789ABCDEF")
+16
17
(define (r2-uri-encode value (keys: (preserve-slashes? #f)))
18
(let ((bytes (string->utf8 value)))
19
(let loop ((i 0) (out '()))
−10
(if (= i (bytevector-length bytes)) (string-join (reverse out) "")
−11
(let ((b (bytevector-u8-ref bytes i)))
−12
(loop (+ i 1)
−13
(cons (if (or (<= 65 b 90) (<= 97 b 122) (<= 48 b 57)
−14
(member b '(45 46 95 126)) (and preserve-slashes? (= b 47)))
−15
(string (integer->char b))
−16
(string #\% (string-ref hex (quotient b 16)) (string-ref hex (modulo b 16)))) out)))))))
+20
(if (= i (bytevector-length bytes))
+21
(string-join (reverse out) "")
+22
(let ((b (bytevector-u8-ref bytes i)))
+23
(loop (+ i 1)
+24
(cons (if (or (<= 65 b 90)
+25
(<= 97 b 122)
+26
(<= 48 b 57)
+27
(member b '(45 46 95 126))
+28
(and preserve-slashes? (= b 47)))
+29
(string (integer->char b))
+30
(string #\%
+31
(string-ref hex (quotient b 16))
+32
(string-ref hex (modulo b 16))))
+33
out)))))))
+34
35
(define (r2-canonical-query query)
36
(string-join
−19
(map (lambda (p) (string-append (car p) "=" (cdr p)))
−20
(list-sort (lambda (a b) (or (string<? (car a) (car b))
−21
(and (string=? (car a) (car b)) (string<? (cdr a) (cdr b)))))
−22
(map (lambda (p) (cons (r2-uri-encode (car p)) (r2-uri-encode (cdr p)))) query))) "&"))
+37
(map (lambda (p)
+38
(string-append (car p) "=" (cdr p)))
+39
(list-sort
+40
(lambda (a b)
+41
(or (string<? (car a) (car b))
+42
(and (string=? (car a) (car b))
+43
(string<? (cdr a) (cdr b)))))
+44
(map (lambda (p)
+45
(cons (r2-uri-encode (car p))
+46
(r2-uri-encode (cdr p))))
+47
query)))
+48
"&"))
+49
50
(define (header-value value)
51
(unless (and (string? value)
−25
(not (string-contains? value "\r")) (not (string-contains? value "\n")))
+52
(not (string-contains? value "\r"))
+53
(not (string-contains? value "\n")))
54
(error "Invalid signing header value"))
55
(let loop ((chars (string->list value)) (out '()) (space? #f))
−28
(cond ((null? chars) (list->string (reverse out)))
−29
((or (char=? (car chars) #\space) (char=? (car chars) #\tab))
−30
(loop (cdr chars) out (not (null? out))))
−31
(else (loop (cdr chars)
−32
(cons (car chars) (if space? (cons #\space out) out)) #f)))))
+56
(cond
+57
((null? chars)
+58
(list->string (reverse out)))
+59
((or (char=? (car chars) #\space)
+60
(char=? (car chars) #\tab))
+61
(loop (cdr chars) out (not (null? out))))
+62
(else
+63
(loop (cdr chars)
+64
(cons (car chars) (if space? (cons #\space out) out))
+65
#f)))))
+66
67
(define (normalize-headers headers)
68
(let loop ((entries headers) (out '()))
−35
(if (null? entries) (list-sort (lambda (a b) (string<? (car a) (car b))) out)
−36
(let* ((p (car entries)) (name (string-downcase (car p))))
−37
(unless (and (> (string-length name) 0)
−38
(every (lambda (c) (or (and (char<=? #\a c) (char<=? c #\z)) (and (char<=? #\0 c) (char<=? c #\9)) (char=? c #\-))) (string->list name)))
−39
(error "Invalid signing header name"))
−40
(when (assoc name out) (error "Duplicate signing header"))
−41
(loop (cdr entries) (cons (cons name (header-value (cdr p))) out))))))
+69
(if (null? entries)
+70
(list-sort (lambda (a b) (string<? (car a) (car b))) out)
+71
(let* ((p (car entries))
+72
(name (string-downcase (car p))))
+73
(unless (and (> (string-length name) 0)
+74
(every (lambda (c)
+75
(or (and (char<=? #\a c) (char<=? c #\z))
+76
(and (char<=? #\0 c) (char<=? c #\9))
+77
(char=? c #\-)))
+78
(string->list name)))
+79
(error "Invalid signing header name"))
+80
(when (assoc name out)
+81
(error "Duplicate signing header"))
+82
(loop (cdr entries)
+83
(cons (cons name (header-value (cdr p))) out))))))
+84
85
;; Result contains signed headers and canonical details: it is sensitive and
86
;; must never be logged. A region override supports official AWS test vectors.
−44
(define (r2-sign-request method path query headers payload access-key secret-key timestamp
−45
(keys: (region "auto")))
+87
(define (r2-sign-request method path query headers payload
+88
access-key secret-key timestamp
+89
(keys: (region "auto")))
90
(unless (and (= (string-length timestamp) 16)
−47
(char=? (string-ref timestamp 8) #\T) (char=? (string-ref timestamp 15) #\Z)
−48
(every char-numeric? (append (string->list (substring timestamp 0 8))
−49
(string->list (substring timestamp 9 15)))))
+91
(char=? (string-ref timestamp 8) #\T)
+92
(char=? (string-ref timestamp 15) #\Z)
+93
(every char-numeric?
+94
(append (string->list (substring timestamp 0 8))
+95
(string->list (substring timestamp 9 15)))))
96
(error "Invalid signing timestamp"))
97
(let* ((body-hash (sha256 payload))
98
(base (normalize-headers headers)))
−53
(unless (assoc "host" base) (error "Signing requires host header"))
−54
(when (or (assoc "authorization" base) (assoc "x-amz-date" base) (assoc "x-amz-content-sha256" base))
+99
(unless (assoc "host" base)
+100
(error "Signing requires host header"))
+101
(when (or (assoc "authorization" base)
+102
(assoc "x-amz-date" base)
+103
(assoc "x-amz-content-sha256" base))
104
(error "Reserved signing header"))
−56
(let* ((signed (normalize-headers (append base
−57
(list (cons "x-amz-date" timestamp) (cons "x-amz-content-sha256" body-hash)))))
+105
(let* ((signed (normalize-headers
+106
(append base
+107
(list (cons "x-amz-date" timestamp)
+108
(cons "x-amz-content-sha256" body-hash)))))
109
(names (string-join (map car signed) ";"))
110
(uri (r2-uri-encode path preserve-slashes?: #t))
111
(qs (r2-canonical-query query))
−61
(canonical (string-append (symbol->string method) "\n" uri "\n" qs "\n"
−62
(apply string-append (map (lambda (p) (string-append (car p) ":" (cdr p) "\n")) signed))
−63
"\n" names "\n" body-hash))
+112
(canonical (string-append
+113
(symbol->string method) "\n" uri "\n" qs "\n"
+114
(apply string-append
+115
(map (lambda (p)
+116
(string-append (car p) ":" (cdr p) "\n"))
+117
signed))
+118
"\n" names "\n" body-hash))
119
(date (substring timestamp 0 8))
120
(scope (string-append date "/" region "/s3/aws4_request"))
−66
(to-sign (string-append "AWS4-HMAC-SHA256\n" timestamp "\n" scope "\n" (sha256 canonical)))
+121
(to-sign (string-append "AWS4-HMAC-SHA256\n" timestamp "\n"
+122
scope "\n" (sha256 canonical)))
123
(key (hmac-sha256-bytes
124
(hmac-sha256-bytes
125
(hmac-sha256-bytes
−70
(hmac-sha256-bytes (string-append "AWS4" secret-key) date) region) "s3") "aws4_request"))
+126
(hmac-sha256-bytes (string-append "AWS4" secret-key) date)
+127
region)
+128
"s3")
+129
"aws4_request"))
130
(signature (hmac-sha256 key to-sign))
−72
(authorization (string-append "AWS4-HMAC-SHA256 Credential=" access-key "/" scope
+131
(authorization (string-append
+132
"AWS4-HMAC-SHA256 Credential=" access-key "/" scope
133
", SignedHeaders=" names ", Signature=" signature)))
134
#{ headers: (cons (cons "authorization" authorization) signed)
−75
canonical-request: canonical signature: signature path: uri query: qs })))))
+135
canonical-request: canonical
+136
signature: signature
+137
path: uri
+138
query: qs })))))
test/test-network.sglmodified
@@ -1,4 +1,9 @@
−1
(import (sigil core) (sigil test) (sigil process) (sigil crypto) (cloudflare r2))
+1
(import (sigil core)
+2
(sigil test)
+3
(sigil process)
+4
(sigil crypto)
+5
(cloudflare r2))
+6
7
;; test/http.mjs supplies a loopback-only fake service and independently checks
8
;; signatures, raw bodies and methods. No real credentials or Cloudflare calls.
9
(when (getenv "R2_TEST_PORT")
@@ -8,7 +13,10 @@
13
"test-assets" test-port: (string->number (getenv "R2_TEST_PORT")) timeout: 2))
14
(key "logos/é +%雪.png")
15
(bytes (make-bytevector 65536)))
−11
(let loop ((i 0)) (when (< i 65536) (bytevector-u8-set! bytes i (modulo i 256)) (loop (+ i 1))))
+16
(let loop ((i 0))
+17
(when (< i 65536)
+18
(bytevector-u8-set! bytes i (modulo i 256))
+19
(loop (+ i 1))))
20
(assert-equal (dict-ref (r2-put-object client key bytes content-type: "image/png" cache-control: "public, max-age=3600") status:) 200)
21
(let ((got (r2-get-object client key)))
22
(assert-equal (dict-ref got status:) 200)
test/test-signing.sglmodified
@@ -1,4 +1,9 @@
−1
(import (sigil core) (sigil test) (sigil crypto) (cloudflare r2) (cloudflare r2 signing))
+1
(import (sigil core)
+2
(sigil test)
+3
(sigil crypto)
+4
(cloudflare r2)
+5
(cloudflare r2 signing))
+6
7
(define access "AKIAIOSFODNN7EXAMPLE")
8
(define secret "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
9
(test-group "R2 SigV4"