@ironfang/render 3.0.0 → 3.0.2

package/README.md

@@ -13,6 +13,16 @@ reports `usage` instead of `credits`, `usage()` returns the month per meter,
 request history records `meter` and `quantity`, and billing refusals throw
 `IronfangBillingError`. Renders accept `idempotencyKey`.
 
+3.0.1 fixes `verifyWebhook` for Render: it used the text of the signing secret as
+the HMAC key, while a Render secret is the hex of the 32-byte key deliveries
+are signed with, so it rejected every genuine delivery. Upgrade if you
+verify Render webhooks with it.
+
+3.0.2 types a template's `vars` as `Record<string, string>` in `image()` and
+`sign()`, as the API has always required: a number, boolean or object passed
+the type check and then came back as a 400. Code that passed one no longer
+compiles; pass it as text (`String(n)`).
+
 ```sh
 npm install @ironfang/render
 ```
@@ -96,7 +106,10 @@ if (!('unmetered' in usage)) {
 
 ## Verifying a webhook
 
-Run the check over the raw request body, before parsing it.
+Run the check over the raw request body, before parsing it. Pass the signing
+secret exactly as it was shown when the destination was created: a Render (or
+Finance) secret is 64 hex characters, and the check decodes it to the 32-byte
+key; an Ironfang Audit secret (`awsec_...`) is used as it is.
 
 ```ts
 import { verifyWebhook } from '@ironfang/render';

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { ClipRequest, Destination, DestinationDraft, ImageRequest, Job, JobSubmission, PdfRequest, QrRequest, RequestFilter, RequestRecord, ScreenshotRequest, SignRequest, SignedUrl, SitePreviewRequest, UnmeteredUsage, Usage } from './types.js';
-export declare const VERSION = "3.0.0";
+export declare const VERSION = "3.0.1";
 export interface ClientOptions {
     /** Your `rw_live_...` key. Never ship this to a browser. */
     apiKey: string;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { BILLING_CODES, IronfangBillingError, IronfangRenderError } from './errors.js';
-export const VERSION = '3.0.0';
+export const VERSION = '3.0.1';
 export class IronfangRender {
     apiKey;
     baseUrl;

package/dist/types.d.ts

@@ -85,7 +85,9 @@ export interface QrRequest {
     logo_pad?: boolean;
 }
 export interface ImageRequest {
-    vars?: Record<string, unknown>;
+    /** The template's placeholder values. Text only: the API refuses a number,
+     * boolean or object with 400, so pass `String(n)` for a number. */
+    vars?: Record<string, string>;
     format?: 'png' | 'jpeg' | 'webp';
 }
 export interface ClipRequest {
@@ -168,7 +170,8 @@ export interface SignRequest {
     kind: 'screenshot' | 'image';
     url?: string;
     template?: string;
-    vars?: Record<string, unknown>;
+    /** Placeholder values for an `image` URL: text only, as for `image()`. */
+    vars?: Record<string, string>;
     width?: number;
     height?: number;
     full_page?: boolean;

package/dist/webhook.d.ts

@@ -6,9 +6,15 @@
  * result as `Ironfang-Signature: v1=<hex>` with `Ironfang-Timestamp` beside
  * it. The check must run over the raw bytes as received: re-serialising parsed
  * JSON changes them and the signature will not match.
+ *
+ * Pass the signing secret exactly as Ironfang returned it. A Render or
+ * Finance secret is 64 hex characters, the hex form of a 32-byte key, and the
+ * key is those 32 bytes; an Audit secret (`awsec_...`) is used as it is. This
+ * module decodes accordingly, so the same call verifies a delivery from any of
+ * the three.
  */
 export interface WebhookInput {
-    /** The endpoint's signing secret, shown once when the destination was created. */
+    /** The endpoint's signing secret, exactly as it was shown once when the destination was created. */
     secret: string;
     /** The `Ironfang-Timestamp` header. */
     timestamp: string;

package/dist/webhook.js

@@ -13,7 +13,7 @@ export async function verifyWebhook(input) {
 }
 /** Compute the signature Ironfang Render would send. Exposed for tests and for tooling that replays deliveries. */
 export async function signWebhook(secret, timestamp, payload) {
-    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const key = await crypto.subtle.importKey('raw', signingKey(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
     const body = typeof payload === 'string' ? encoder.encode(payload) : payload;
     const signed = new Uint8Array(encoder.encode(timestamp + '.').length + body.length);
     signed.set(encoder.encode(timestamp + '.'), 0);
@@ -21,6 +21,24 @@ export async function signWebhook(secret, timestamp, payload) {
     const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, signed));
     return 'v1=' + Array.from(mac, (b) => b.toString(16).padStart(2, '0')).join('');
 }
+const HEX_SECRET = /^[0-9a-f]{64}$/i;
+/**
+ * The HMAC key a secret stands for. Render and Finance mint 32 random bytes
+ * and show them as 64 hex characters, and sign with the bytes; Audit shows an
+ * `awsec_` string and signs with that string. Until 3.0.1 this used the text
+ * of every secret, so no Render delivery verified.
+ */
+function signingKey(secret) {
+    const trimmed = secret.trim();
+    if (!HEX_SECRET.test(trimmed)) {
+        return encoder.encode(secret);
+    }
+    const key = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        key[i] = parseInt(trimmed.slice(2 * i, 2 * i + 2), 16);
+    }
+    return key;
+}
 function constantTimeEqual(a, b) {
     const x = encoder.encode(a);
     const y = encoder.encode(b);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ironfang/render",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Ironfang Render API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML.",
   "license": "MIT",
   "type": "module",