feat: Add base64 output option to hmac function

Co-authored-by: contact <[email protected]>

Author: cursoragent

CHANGELOG.md

@@ -6,7 +6,7 @@
    - Generate tamper-proof tokens for API authentication
    - Secure download links and temporary access codes
    - Supports SHA-256 (default) and SHA-512 algorithms
-   - Returns hexadecimal string representation of HMAC
+   - Output formats: hexadecimal (default) or base64 (e.g., `sha256-base64`)
    - See the [function documentation](https://sql-page.com/functions.sql?function=hmac) for detailed examples
 
 ## v0.37.1

examples/official-site/sqlpage/migrations/67_hmac_function.sql

@@ -27,9 +27,13 @@ Think of it like a wax seal on a letter - only someone with the right seal (your
 The `sqlpage.hmac` function takes three inputs:
 1. **Your data** - The text you want to sign (like a message or request body)
 2. **Your secret key** - A password only you know (keep this safe!)
-3. **Algorithm** (optional) - Either `sha256` (default) or `sha512`
+3. **Algorithm** (optional) - The hash algorithm and output format:
+   - `sha256` (default) - SHA-256 with hexadecimal output
+   - `sha256-base64` - SHA-256 with base64 output
+   - `sha512` - SHA-512 with hexadecimal output
+   - `sha512-base64` - SHA-512 with base64 output
 
-It returns a long string of letters and numbers (the signature). If someone changes even one letter in your data, the signature will be completely different.
+It returns a signature string. If someone changes even one letter in your data, the signature will be completely different.
 
 ### Example 1: Verify Shopify Webhooks
 
@@ -39,27 +43,21 @@ When Shopify sends you a webhook (like when someone places an order), it include
 -- Shopify includes the signature in the X-Shopify-Hmac-SHA256 header
 -- and sends the webhook data in the request body
 
-SELECT ''text'' as component,
-  CASE 
-    WHEN sqlpage.hmac(
-           sqlpage.request_body(),
-           sqlpage.environment_variable(''SHOPIFY_WEBHOOK_SECRET''),
-           ''sha256''
-         ) = sqlpage.header(''X-Shopify-Hmac-SHA256'')
-    THEN ''✅ Webhook verified! This is really from Shopify.''
-    ELSE ''❌ Invalid signature - this might be fake!''
-  END as contents;
-
--- If verified, process the order:
-INSERT INTO orders (order_data, received_at)
-SELECT 
-  sqlpage.request_body(),
-  datetime(''now'')
+-- First, verify the signature - redirect to error page if invalid
+SELECT ''redirect'' as component,
+  ''/error.sql?message='' || sqlpage.url_encode(''Invalid webhook signature'') as link
 WHERE sqlpage.hmac(
         sqlpage.request_body(),
         sqlpage.environment_variable(''SHOPIFY_WEBHOOK_SECRET''),
-        ''sha256''
-      ) = sqlpage.header(''X-Shopify-Hmac-SHA256'');
+        ''sha256-base64''
+      ) != sqlpage.header(''X-Shopify-Hmac-SHA256'');
+
+-- If we reach here, the signature is valid - process the order:
+INSERT INTO orders (order_data, received_at)
+VALUES (sqlpage.request_body(), datetime(''now''));
+
+SELECT ''text'' as component,
+  ''✅ Webhook verified and processed successfully!'' as contents;
 ```
 
 ### Example 2: Create Secure Download Links
@@ -99,6 +97,7 @@ SELECT sqlpage.hmac(
  - **Use strong keys**: Your secret should be long and random (at least 32 characters)
  - **The signature is case-sensitive**: Even one wrong letter means the signature won''t match
  - **Algorithms**: Use `sha256` for most cases (it''s the default), or `sha512` for extra security
+ - **Output formats**: Use `hex` (default) for most cases, or `base64` when the service expects base64 (like Shopify)
  - **NULL handling**: If your data or key is NULL, the function returns NULL
 '
     );
@@ -128,6 +127,6 @@ VALUES (
         'hmac',
         3,
         'algorithm',
-        'The hash algorithm to use. Optional, defaults to `sha256`. Supported values: `sha256`, `sha512`.',
+        'The hash algorithm and output format. Optional, defaults to `sha256` (hex output). Supported values: `sha256`, `sha256-base64`, `sha512`, `sha512-base64`.',
         'TEXT'
     );

src/webserver/database/sqlpage_functions/functions.rs

@@ -757,7 +757,15 @@ async fn hmac<'a>(
     };
 
     let algorithm = algorithm.as_deref().unwrap_or("sha256");
-    let result = match algorithm.to_lowercase().as_str() {
+    
+    // Parse algorithm and output format (e.g., "sha256" or "sha256-base64")
+    let (hash_algo, output_format) = if let Some((algo, format)) = algorithm.split_once('-') {
+        (algo, format)
+    } else {
+        (algorithm, "hex")
+    };
+    
+    let result = match hash_algo.to_lowercase().as_str() {
         "sha256" => {
             let mut mac = Hmac::<Sha256>::new_from_slice(key.as_bytes())
                 .map_err(|e| anyhow!("Invalid HMAC key: {e}"))?;
@@ -772,18 +780,30 @@ async fn hmac<'a>(
         }
         _ => {
             anyhow::bail!(
-                "Unsupported HMAC algorithm: {algorithm}. Supported algorithms: sha256, sha512"
+                "Unsupported HMAC algorithm: {hash_algo}. Supported algorithms: sha256, sha512"
             )
         }
     };
 
-    // Convert to hexadecimal string
-    let hex_result = result.into_iter().fold(String::new(), |mut acc, byte| {
-        write!(&mut acc, "{byte:02x}").unwrap();
-        acc
-    });
+    // Convert to requested output format
+    let output = match output_format.to_lowercase().as_str() {
+        "hex" => {
+            result.into_iter().fold(String::new(), |mut acc, byte| {
+                write!(&mut acc, "{byte:02x}").unwrap();
+                acc
+            })
+        }
+        "base64" => {
+            base64::Engine::encode(&base64::engine::general_purpose::STANDARD, result)
+        }
+        _ => {
+            anyhow::bail!(
+                "Unsupported output format: {output_format}. Supported formats: hex, base64"
+            )
+        }
+    };
 
-    Ok(Some(hex_result))
+    Ok(Some(output))
 }
 
 async fn client_ip(request: &RequestInfo) -> Option<String> {

tests/sql_test_files/it_works_hmac_base64.sql

@@ -0,0 +1,6 @@
+-- Test HMAC with base64 output format
+-- Redirect if hash doesn't match expected value
+SELECT 'redirect' as component, '/error.sql' as link
+WHERE sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha256-base64') != '97yD9DBThCSxMpjmqm+xQ+9NWaFJRhdZl0edvC0aPNg=';
+
+SELECT 'text' as component, 'It works ! HMAC SHA-256 base64 output is correct' as contents;

tests/sql_test_files/it_works_hmac_default.sql

@@ -1,6 +1,5 @@
-SELECT 'text' as component,
-    CASE 
-        WHEN sqlpage.hmac('test data', 'test key') = sqlpage.hmac('test data', 'test key', 'sha256')
-        THEN 'It works ! HMAC default algorithm is SHA-256'
-        ELSE 'Default algorithm mismatch'
-    END as contents;
+-- Redirect if default algorithm doesn't match sha256
+SELECT 'redirect' as component, '/error.sql' as link
+WHERE sqlpage.hmac('test data', 'test key') != sqlpage.hmac('test data', 'test key', 'sha256');
+
+SELECT 'text' as component, 'It works ! HMAC default algorithm is SHA-256' as contents;

tests/sql_test_files/it_works_hmac_sha256.sql

@@ -1,6 +1,5 @@
-SELECT 'text' as component,
-    CASE 
-        WHEN sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha256') = 'f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8'
-        THEN 'It works ! HMAC SHA-256 hash is correct'
-        ELSE 'Hash mismatch: ' || sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha256')
-    END as contents;
+-- Redirect if hash doesn't match expected value
+SELECT 'redirect' as component, '/error.sql' as link
+WHERE sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha256') != 'f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8';
+
+SELECT 'text' as component, 'It works ! HMAC SHA-256 hash is correct' as contents;

tests/sql_test_files/it_works_hmac_sha512.sql

@@ -1,6 +1,5 @@
-SELECT 'text' as component,
-    CASE 
-        WHEN sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha512') = 'b42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3a'
-        THEN 'It works ! HMAC SHA-512 hash is correct'
-        ELSE 'Hash mismatch: ' || sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha512')
-    END as contents;
+-- Redirect if hash doesn't match expected value
+SELECT 'redirect' as component, '/error.sql' as link
+WHERE sqlpage.hmac('The quick brown fox jumps over the lazy dog', 'key', 'sha512') != 'b42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3a';
+
+SELECT 'text' as component, 'It works ! HMAC SHA-512 hash is correct' as contents;

tests/sql_test_files/it_works_hmac_shopify_webhook.sql

@@ -1,14 +1,15 @@
--- Test Shopify webhook HMAC validation
--- Shopify sends webhook body and HMAC signature in X-Shopify-Hmac-SHA256 header
+-- Test Shopify webhook HMAC validation with base64 output
+-- Shopify sends webhook body and HMAC signature in X-Shopify-Hmac-SHA256 header (base64 format)
 
+-- Redirect to error if signature doesn't match (proper pattern)
+SELECT 'redirect' as component,
+    '/error.sql?msg=invalid_signature' as link
+WHERE sqlpage.hmac(
+    '{"id":1234567890,"email":"[email protected]","total_price":"123.45"}',
+    'test-webhook-secret',
+    'sha256-base64'
+) != 'QNyObTlKbMx2qDlPF/ZOZcBqg5OgPg+2oky3zldc0Gw=';
+
+-- If we reach here, signature is valid
 SELECT 'text' as component,
-    CASE 
-        -- Example webhook data and signature (simulating Shopify webhook)
-        WHEN sqlpage.hmac(
-            '{"id":1234567890,"email":"[email protected]","total_price":"123.45"}',
-            'test-webhook-secret',
-            'sha256'
-        ) = '40dc8e6d394a6ccc76a8394f17f64e65c06a8393a03e0fb6a24cb7ce575cd06c'
-        THEN 'It works ! Shopify webhook signature verified'
-        ELSE 'Signature mismatch: ' || sqlpage.hmac('{"id":1234567890,"email":"[email protected]","total_price":"123.45"}', 'test-webhook-secret', 'sha256')
-    END as contents;
+    'It works ! Shopify webhook signature verified (base64 format)' as contents;