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"