Switch to request-time HTTP message signing

Author: timkelty

README.md

@@ -53,6 +53,113 @@ composer update "craftcms/cms:^5" "craftcms/flysystem:^2.0" --with-all-dependenc
 
 ## Developer Features
 
+### Signed HTTP Requests
+
+Use the module’s request signer to sign a PSR-7 request with Cloud’s signing key before sending it to any destination that can verify HTTP message signatures.
+
+```php
+use craft\cloud\Module;
+use GuzzleHttp\Psr7\Request;
+
+$signer = Module::getInstance()->getRequestSigner();
+
+$signedRequest = $signer->sign(new Request('POST', 'https://example.test/webhook'));
+```
+
+For Guzzle clients, use the signer’s handler stack helper so each request is signed when it is sent.
+
+```php
+use Craft;
+use craft\cloud\Module;
+use GuzzleHttp\RequestOptions;
+
+$signer = Module::getInstance()->getRequestSigner();
+
+$client = Craft::createGuzzleClient([
+    'handler' => $signer->createHandlerStack(),
+]);
+
+$client->post('https://example.test/webhook', [
+    RequestOptions::JSON => [
+        'event' => 'asset.saved',
+    ],
+]);
+```
+
+External systems can create compatible signatures without this PHP package. For example, install
+[`http-message-signatures`](https://www.npmjs.com/package/http-message-signatures) in a Node-based build environment:
+
+```bash
+npm install http-message-signatures
+```
+
+Then a Vercel build script can sign a Craft GraphQL request:
+
+```js
+import httpMessageSignatures from 'http-message-signatures';
+
+const {
+    createSigner,
+    httpbis: { signMessage },
+} = httpMessageSignatures;
+
+const method = 'POST';
+const url = process.env.CRAFT_GRAPHQL_URL;
+const signingKey = process.env.CRAFT_CLOUD_SIGNING_KEY;
+
+if (!url || !signingKey) {
+    throw new Error('CRAFT_GRAPHQL_URL and CRAFT_CLOUD_SIGNING_KEY are required.');
+}
+
+const unsignedRequest = {
+    method,
+    headers: {
+        'Content-Type': 'application/json',
+        ...(process.env.CRAFT_GRAPHQL_TOKEN
+            ? { Authorization: `Bearer ${process.env.CRAFT_GRAPHQL_TOKEN}` }
+            : {}),
+    },
+    body: JSON.stringify({
+        query: `
+            query BuildData {
+                entries(section: "news") {
+                    title
+                    url
+                }
+            }
+        `,
+    }),
+    url,
+};
+
+const signedRequest = await signMessage(
+    {
+        key: createSigner(signingKey, 'hmac-sha256', 'hmac'),
+        fields: ['@method', '@target-uri'],
+        params: ['created', 'expires', 'alg', 'keyid'],
+    },
+    unsignedRequest,
+);
+
+const response = await fetch(url, {
+    method: signedRequest.method,
+    headers: signedRequest.headers,
+    body: signedRequest.body,
+});
+
+if (!response.ok) {
+    throw new Error(`Craft GraphQL request failed: ${response.status}`);
+}
+
+const responseBody = await response.json();
+
+if (responseBody.errors) {
+    throw new Error(`Craft GraphQL returned errors: ${JSON.stringify(responseBody.errors)}`);
+}
+```
+
+The `@target-uri` value must be the exact URL being requested, including any query string.
+
 ### Template Helpers
 
 #### `cloud.artifactUrl()`
@@ -109,7 +216,7 @@ Most configuration (to Craft and the extension itself) is handled directly by Cl
 | `accessSecret`        | `string`       | AWS access secret, used in conjunction with the `accessKey`.                                                                    |
 | `accessToken`         | `string`       | AWS access token.                                                                                                               |
 | `redisUrl`            | `string`       | Connection string for the environment’s Redis instance.                                                                         |
-| `signingKey`          | `string`       | A secret value used to protect transform URLs against abuse.                                                                    |
+| `signingKey`          | `string`       | A secret value used to protect transform URLs and sign HTTP requests. |
 | `useAssetBundleCdn`   | `boolean`      | Whether or not to enable the CDN for asset bundles.                                                                             |
 | `previewDomain`       | `string\|null` | Set when accessing an environment from its [preview domain](https://craftcms.com/knowledge-base/cloud-domains#preview-domains). |
 | `useQueue`            | `boolean`      | Whether or not to use Cloud’s SQS-backed queue driver.                                                                          |

composer.json

@@ -8,14 +8,14 @@
     "bref/extra-php-extensions": "^3",
     "craftcms/cms": "^4.6 || ^5",
     "craftcms/flysystem": "^1.0.0 || ^2.0.0",
+    "craftcms/http-message-signatures": "^0.1",
     "guzzlehttp/guzzle": "^7.4.5",
     "league/flysystem-aws-s3-v3": "^3.15",
     "league/uri": "^7.6",
     "league/uri-components": "^7.6",
     "yiisoft/yii2-redis": "^2.0",
     "yiisoft/yii2-queue": "^2.3.7",
     "phlak/semver": "^4.1",
-    "99designs/http-signatures": "^4.0",
     "symfony/process": "^6",
     "aws/aws-sdk-php": "^3.342.6",
     "craftcms/yii2-cache-cascade": "^1.2.1"