feat: Add sqlpage.hmac() function for secure signatures

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

Author: cursoragent

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG.md
 
+## v0.38.0
+ - Added a new `sqlpage.hmac()` function for cryptographic HMAC (Hash-based Message Authentication Code) operations.
+   - Create and verify secure signatures for webhooks (Shopify, Stripe, GitHub, etc.)
+   - 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
+   - See the [function documentation](https://sql-page.com/functions.sql?function=hmac) for detailed examples
+
 ## v0.37.1
  - fixed decoding of UUID values
  - Fixed handling of NULL values in `sqlpage.link`. They were encoded as the string `'null'` instead of being omitted from the link's parameters.

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

@@ -10,63 +10,96 @@ VALUES (
         'hmac',
         '0.38.0',
         'shield-lock',
-        'Computes the [HMAC](https://en.wikipedia.org/wiki/HMAC) (Hash-based Message Authentication Code) of the input data using a secret key and a cryptographic hash function.
+        'Creates a unique "signature" for your data using a secret key. This signature proves that the data hasn''t been tampered with and comes from someone who knows the secret.
 
-HMAC is used to verify both the data integrity and authenticity of a message. It is commonly used for:
- - Generating secure tokens and signatures
- - API request authentication
- - Webhook signature verification
- - Data integrity validation
+Think of it like a wax seal on a letter - only someone with the right seal (your secret key) can create it, and if someone changes the letter, the seal won''t match anymore.
 
-### Example
+### What is HMAC used for?
 
-#### Generate an HMAC for API authentication
+**HMAC** (Hash-based Message Authentication Code) is commonly used to:
+ - **Verify webhooks**: Check that notifications from services like Shopify, Stripe, or GitHub are genuine
+ - **Secure API requests**: Prove that an API request comes from an authorized source
+ - **Generate secure tokens**: Create temporary access codes for downloads or password resets
+ - **Protect data**: Ensure data hasn''t been modified during transmission
 
-```sql
--- Generate a secure signature for an API request
-SELECT sqlpage.hmac(
-    ''user_id=123&action=update'',
-    ''my-secret-api-key'',
-    ''sha256''
-) as request_signature;
-```
+### How to use it
 
-#### Verify a webhook signature
+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`
+
+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.
+
+### Example 1: Verify Shopify Webhooks
+
+When Shopify sends you a webhook (like when someone places an order), it includes a signature. Here''s how to verify it''s really from Shopify:
 
 ```sql
--- Verify that a webhook request is authentic
+-- 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 
-    CASE 
-        WHEN sqlpage.hmac(sqlpage.request_body(), ''webhook-secret'', ''sha256'') = :signature
-        THEN ''Valid webhook''
-        ELSE ''Invalid signature''
-    END as status;
+  sqlpage.request_body(),
+  datetime(''now'')
+WHERE sqlpage.hmac(
+        sqlpage.request_body(),
+        sqlpage.environment_variable(''SHOPIFY_WEBHOOK_SECRET''),
+        ''sha256''
+      ) = sqlpage.header(''X-Shopify-Hmac-SHA256'');
 ```
 
-#### Create a secure download token
+### Example 2: Create Secure Download Links
+
+Generate a token that expires after 1 hour:
 
 ```sql
--- Generate a time-limited download token
+-- Create a download token
 INSERT INTO download_tokens (file_id, token, expires_at)
 VALUES (
     :file_id,
     sqlpage.hmac(
         :file_id || ''|'' || datetime(''now'', ''+1 hour''),
-        sqlpage.environment_variable(''SECRET_KEY''),
+        sqlpage.environment_variable(''DOWNLOAD_SECRET''),
         ''sha256''
     ),
     datetime(''now'', ''+1 hour'')
 );
 ```
 
-### Notes
+### Example 3: Sign API Requests
+
+Prove your API request is authentic:
+
+```sql
+-- Create a signature for your API call
+SELECT sqlpage.hmac(
+    ''user_id=123&action=update&timestamp='' || strftime(''%s'', ''now''),
+    ''my-secret-api-key'',
+    ''sha256''
+) as api_signature;
+```
+
+### Important Security Tips
 
- - The function returns a hexadecimal string representation of the HMAC.
- - If either `data` or `key` is NULL, the function returns NULL.
- - The `algorithm` parameter is optional and defaults to `sha256` if not specified.
- - Supported algorithms: `sha256`, `sha512`.
- - The key can be of any length. For maximum security, use a key that is at least as long as the hash output (32 bytes for SHA-256, 64 bytes for SHA-512).
- - Keep your secret keys secure and never expose them in client-side code or version control.
+ - **Keep your secret key safe**: Store it in environment variables using `sqlpage.environment_variable()`, never hardcode it in your SQL files
+ - **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
+ - **NULL handling**: If your data or key is NULL, the function returns NULL
 '
     );
 

tests/sql_test_files/it_works_hmac_shopify_webhook.sql

@@ -0,0 +1,14 @@
+-- Test Shopify webhook HMAC validation
+-- Shopify sends webhook body and HMAC signature in X-Shopify-Hmac-SHA256 header
+
+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;