@ironfang/render 2.0.0 → 3.0.1

package/README.md

@@ -7,6 +7,17 @@ URL or from HTML you send. Zero dependencies; Node 20 and later.
 Formerly `@ironfang/renderwolf`; 2.0.0 removed the old `Renderwolf` and
 `RenderwolfError` exports. Webhooks are signed with the `Ironfang-*` headers.
 
+3.0.0 follows Ironfang's move from credits to metered usage on one billing
+account: a render reports `meter` and `quantity` instead of `credits`, a job
+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.
+
 ```sh
 npm install @ironfang/render
 ```
@@ -18,12 +29,12 @@ const rw = new IronfangRender({ apiKey: process.env.IRONFANG_API_KEY! });
 
 const shot = await rw.screenshot({ url: 'https://example.com', full_page: true });
 await shot.saveTo('page.png');
-console.log(shot.credits, shot.renderMs, shot.requestId);
+console.log(shot.meter, shot.quantity, shot.renderMs, shot.requestId);
 ```
 
 Every render returns the bytes plus what the API reports about them: content
-type, credits charged (zero on a cache hit), render time and the request id
-to quote to support.
+type, the billing meter it counted against and the quantity it counted there
+(zero on a cache hit), render time and the request id to quote to support.
 
 ## Change the page before capture
 
@@ -68,9 +79,32 @@ if (done.status === 'succeeded') {
 }
 ```
 
+The job's `usage` says what it holds: `{ meter, reserved, committed }`. The
+most the job can count is reserved when it is accepted, and what it produced
+is committed when it succeeds. A job that fails or is cancelled while queued
+counts nothing.
+
+## Usage and billing
+
+Ironfang Render has no plans or credits. Usage is billed to your
+organisation's Ironfang billing account, shared by every Ironfang product and
+managed in Billing in the [Ironfang portal](https://portal.ironfang.com). Each
+kind of render counts against a meter, and each meter has a monthly free
+allowance; beyond it, usage is pay-as-you-go once paid usage is enabled.
+
+```ts
+const usage = await rw.usage();
+if (!('unmetered' in usage)) {
+  for (const m of usage.meters) console.log(m.id, m.used, m.remaining_free);
+}
+```
+
 ## 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';
@@ -86,9 +120,35 @@ const ok = await verifyWebhook({
 ## Errors
 
 Failures throw `IronfangRenderError` with `status`, the API's `code`
-(`quota_exhausted`, `render_failed`, ...) and `requestId`. Synchronous renders
-are never retried by the client: a render that timed out may already have
-been charged, and retrying it blind doubles the bill.
+(`render_failed`, `rate_limited`, ...), `requestId` and, when the API sent
+one, `retryAfter` in seconds. Branch on `code` rather than the status: rate
+limits and billing refusals can share a 429.
+
+When the billing account refuses a render, nothing is rendered or counted and
+the error is an `IronfangBillingError` (a subclass) with `product`, and
+`meter` and `resetAt` when the API states them. The codes are
+`free_allowance_exhausted`, `account_budget_exhausted`,
+`product_budget_exhausted`, `exemption_limit_reached`, `paid_usage_paused`,
+`payment_required`, `payment_action_required`, `account_restricted`,
+`product_not_eligible`, `account_closed`, `operation_too_large` and
+`billing_temporarily_unavailable`. Only the last clears by itself, after
+`retryAfter`; the rest are resolved in Billing or when the month rolls over.
+
+```ts
+import { IronfangBillingError } from '@ironfang/render';
+
+try {
+  await rw.screenshot({ url: 'https://example.com' });
+} catch (err) {
+  if (err instanceof IronfangBillingError) console.error(err.code, err.resetAt);
+  else throw err;
+}
+```
+
+Synchronous renders are never retried by the client: a render that timed out
+may already have counted, and retrying it blind counts it twice. Pass
+`idempotencyKey` to make a render count at most once; the same key again is
+refused with `idempotency_key_used`, since a synchronous result is not kept.
 
 ## Keys
 

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, Usage } from './types.js';
-export declare const VERSION = "2.0.0";
+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.1";
 export interface ClientOptions {
     /** Your `rw_live_...` key. Never ship this to a browser. */
     apiKey: string;
@@ -11,18 +11,27 @@ export interface ClientOptions {
     fetch?: typeof fetch;
 }
 export interface RequestOptions {
-    /** Cancel the request. A synchronous render that has started may still be charged. */
+    /** Cancel the request. A synchronous render that has started may still count. */
     signal?: AbortSignal;
     /** Your own correlation id, echoed as X-Request-ID and kept in request history. */
     requestId?: string;
     timeoutMs?: number;
+    /**
+     * Sent as Idempotency-Key, up to 255 characters. On a render it makes the
+     * render happen, and count, at most once: the same key again is refused
+     * with `idempotency_key_used`, because a synchronous result is not kept.
+     * On a job submission the same key returns the existing job.
+     */
+    idempotencyKey?: string;
 }
 /** A finished synchronous render with the facts the API reports about it. */
 export interface RenderResult {
     bytes: Uint8Array;
     contentType: string;
-    /** Credits this render cost. Zero when served from cache. */
-    credits: number;
+    /** The billing meter the render counted against, e.g. `render.screenshot`. */
+    meter: string | undefined;
+    /** What it counted there: 1 for a unit render, output seconds for video, 0 from cache. */
+    quantity: number;
     renderMs: number;
     cached: boolean;
     /** The id to quote to support. */
@@ -36,7 +45,10 @@ export interface RenderResult {
 export interface SitePreviewResult {
     poster: Uint8Array;
     video: Uint8Array;
-    credits: number;
+    /** `render.site_preview_second`. */
+    meter: string | undefined;
+    /** Output seconds counted, rounded up; 0 from cache. */
+    quantity: number;
     renderMs: number;
     outputSeconds: number;
     cached: boolean;
@@ -66,11 +78,11 @@ export declare class IronfangRender {
     readonly jobs: {
         /**
          * Submit a durable job. Pass `idempotencyKey` to make a retry of the same
-         * submission return the same job instead of a second one.
+         * submission return the same job instead of a second one. The most the
+         * job can count is reserved when it is accepted; its `usage` says what it
+         * holds and, once it succeeds, what it committed.
          */
-        submit: (sub: JobSubmission, opts?: RequestOptions & {
-            idempotencyKey?: string;
-        }) => Promise<Job>;
+        submit: (sub: JobSubmission, opts?: RequestOptions) => Promise<Job>;
         get: (id: string, opts?: RequestOptions) => Promise<Job>;
         list: (params?: {
             status?: string;
@@ -104,7 +116,13 @@ export declare class IronfangRender {
     };
     /** Mint a signed render URL that an <img> or an email can fetch directly. */
     sign(req: SignRequest, opts?: RequestOptions): Promise<SignedUrl>;
-    usage(opts?: RequestOptions): Promise<Usage>;
+    /**
+     * This month's Ironfang Render usage from your organisation's billing
+     * account: per meter, what was used, how much the free allowance covered
+     * and what is held by work in flight. A deployment with billing off, or an
+     * unmetered key, answers `{ unmetered: true }`.
+     */
+    usage(opts?: RequestOptions): Promise<Usage | UnmeteredUsage>;
     /** Request history for the last seven days. */
     requests(filter?: RequestFilter, opts?: RequestOptions): Promise<{
         requests: RequestRecord[];

package/dist/client.js

@@ -1,5 +1,5 @@
-import { IronfangRenderError } from './errors.js';
-export const VERSION = '2.0.0';
+import { BILLING_CODES, IronfangBillingError, IronfangRenderError } from './errors.js';
+export const VERSION = '3.0.1';
 export class IronfangRender {
     apiKey;
     baseUrl;
@@ -32,7 +32,7 @@ export class IronfangRender {
         return this.render('/v1/video', req, opts);
     }
     async sitePreview(req, opts = {}) {
-        const resp = await this.send('POST', '/v1/site-preview', req, opts);
+        const resp = await this.send('POST', '/v1/site-preview', req, opts, idempotency(opts));
         const form = await resp.formData();
         const poster = form.get('poster');
         const video = form.get('video');
@@ -44,7 +44,7 @@ export class IronfangRender {
         return {
             poster: new Uint8Array(await poster.arrayBuffer()),
             video: new Uint8Array(await video.arrayBuffer()),
-            credits: num(resp.headers.get('X-Ironfang-Credits')),
+            ...usageOf(resp),
             renderMs: num(resp.headers.get('X-Ironfang-Render-Ms')),
             outputSeconds: num(resp.headers.get('X-Ironfang-Output-Seconds')),
             cached: resp.headers.get('X-Ironfang-Cache') === 'hit',
@@ -53,12 +53,12 @@ export class IronfangRender {
         };
     }
     async render(path, body, opts) {
-        const resp = await this.send('POST', path, body, opts);
+        const resp = await this.send('POST', path, body, opts, idempotency(opts));
         const bytes = new Uint8Array(await resp.arrayBuffer());
         return {
             bytes,
             contentType: (resp.headers.get('Content-Type') ?? 'application/octet-stream').split(';')[0].trim(),
-            credits: num(resp.headers.get('X-Ironfang-Credits')),
+            ...usageOf(resp),
             renderMs: num(resp.headers.get('X-Ironfang-Render-Ms')),
             cached: resp.headers.get('X-Ironfang-Cache') === 'hit',
             requestId: requestIdOf(resp),
@@ -70,13 +70,12 @@ export class IronfangRender {
     jobs = {
         /**
          * Submit a durable job. Pass `idempotencyKey` to make a retry of the same
-         * submission return the same job instead of a second one.
+         * submission return the same job instead of a second one. The most the
+         * job can count is reserved when it is accepted; its `usage` says what it
+         * holds and, once it succeeds, what it committed.
          */
         submit: async (sub, opts = {}) => {
-            const headers = {};
-            if (opts.idempotencyKey)
-                headers['Idempotency-Key'] = opts.idempotencyKey;
-            const resp = await this.send('POST', '/v1/jobs', sub, opts, headers);
+            const resp = await this.send('POST', '/v1/jobs', sub, opts, idempotency(opts));
             return (await resp.json());
         },
         get: async (id, opts = {}) => {
@@ -98,7 +97,9 @@ export class IronfangRender {
             return {
                 bytes,
                 contentType: (resp.headers.get('Content-Type') ?? 'application/octet-stream').split(';')[0].trim(),
-                credits: 0,
+                // Collecting a result counts nothing; the job's `usage` says what it did.
+                meter: undefined,
+                quantity: 0,
                 renderMs: 0,
                 cached: false,
                 requestId: requestIdOf(resp),
@@ -151,6 +152,12 @@ export class IronfangRender {
         const resp = await this.send('POST', '/v1/sign', req, opts);
         return (await resp.json());
     }
+    /**
+     * This month's Ironfang Render usage from your organisation's billing
+     * account: per meter, what was used, how much the free allowance covered
+     * and what is held by work in flight. A deployment with billing off, or an
+     * unmetered key, answers `{ unmetered: true }`.
+     */
     async usage(opts = {}) {
         const resp = await this.send('GET', '/v1/usage', undefined, opts);
         return (await resp.json());
@@ -187,7 +194,7 @@ export class IronfangRender {
         }
         catch (err) {
             // No retry here on purpose: a synchronous render that timed out may
-            // have been charged, and retrying it blind doubles the bill.
+            // already have counted, and retrying it blind counts it twice.
             if (controller.signal.aborted) {
                 const reason = controller.signal.reason;
                 const timedOut = reason instanceof DOMException && reason.name === 'TimeoutError';
@@ -208,17 +215,43 @@ export class IronfangRender {
 async function errorFrom(resp) {
     let code = `http_${resp.status}`;
     let message = `request failed with HTTP ${resp.status}`;
+    let detail = {};
     try {
         const body = (await resp.json());
         if (body?.error?.code)
             code = body.error.code;
         if (body?.error?.message)
             message = body.error.message;
+        if (body?.error)
+            detail = body.error;
     }
     catch {
         // Not JSON; the status is all there is.
     }
-    return new IronfangRenderError(message, { status: resp.status, code, requestId: requestIdOf(resp) });
+    const opts = { status: resp.status, code, requestId: requestIdOf(resp), retryAfter: retryAfterOf(resp) };
+    if (BILLING_CODES.includes(code)) {
+        return new IronfangBillingError(message, {
+            ...opts, product: text(detail.product), meter: text(detail.meter), resetAt: text(detail.reset_at),
+        });
+    }
+    return new IronfangRenderError(message, opts);
+}
+/** The meter and quantity a render response reports. */
+function usageOf(resp) {
+    return { meter: resp.headers.get('X-Ironfang-Meter') ?? undefined, quantity: num(resp.headers.get('X-Ironfang-Quantity')) };
+}
+function idempotency(opts) {
+    return opts.idempotencyKey ? { 'Idempotency-Key': opts.idempotencyKey } : {};
+}
+/** Retry-After in seconds; the API sends whole seconds. */
+function retryAfterOf(resp) {
+    const v = resp.headers.get('Retry-After');
+    if (v === null || !/^\d+$/.test(v.trim()))
+        return undefined;
+    return Number(v.trim());
+}
+function text(v) {
+    return typeof v === 'string' && v !== '' ? v : undefined;
 }
 function requestIdOf(resp) {
     return resp.headers.get('X-Ironfang-Request-ID') ?? '';

package/dist/errors.d.ts

@@ -1,20 +1,54 @@
 /**
  * An error the API returned, or a failure to reach it.
  *
- * `code` is the API's stable error code (`bad_request`, `quota_exhausted`,
- * `render_failed`, ...) or a client-side one (`network_error`, `timeout`,
- * `aborted`). `requestId` is the id to quote to support; it is on every
- * response the server produced, including errors.
+ * `code` is the API's stable error code (`bad_request`, `render_failed`,
+ * `free_allowance_exhausted`, ...) or a client-side one (`network_error`,
+ * `timeout`, `aborted`). `requestId` is the id to quote to support; it is on
+ * every response the server produced, including errors. `retryAfter` is the
+ * API's `Retry-After` in seconds, when it sent one.
  */
 export declare class IronfangRenderError extends Error {
     readonly status: number;
     readonly code: string;
     readonly requestId: string | undefined;
+    readonly retryAfter: number | undefined;
     constructor(message: string, opts: {
         status: number;
         code: string;
         requestId?: string | undefined;
+        retryAfter?: number | undefined;
     });
     /** The request was refused before any work was done. */
     get isClientError(): boolean;
 }
+/**
+ * The codes a billing refusal carries. They are the same in every Ironfang
+ * product, because every product admits work through the one billing account.
+ */
+export declare const BILLING_CODES: readonly string[];
+/**
+ * The organisation's billing account refused the request before any work
+ * started: nothing was rendered and nothing counted. Most refusals are
+ * resolved in Billing in the Ironfang portal (enable paid usage, raise a
+ * limit, update the payment method) or by the month rolling over; only
+ * `billing_temporarily_unavailable` clears on its own, after `retryAfter`
+ * seconds.
+ *
+ * `product` is the product whose usage was refused (always `render` here).
+ * `meter` and `resetAt` (when the free allowance renews, RFC 3339) are set
+ * when the API states them.
+ */
+export declare class IronfangBillingError extends IronfangRenderError {
+    readonly product: string;
+    readonly meter: string | undefined;
+    readonly resetAt: string | undefined;
+    constructor(message: string, opts: {
+        status: number;
+        code: string;
+        requestId?: string | undefined;
+        retryAfter?: number | undefined;
+        product?: string | undefined;
+        meter?: string | undefined;
+        resetAt?: string | undefined;
+    });
+}

package/dist/errors.js

@@ -1,24 +1,69 @@
 /**
  * An error the API returned, or a failure to reach it.
  *
- * `code` is the API's stable error code (`bad_request`, `quota_exhausted`,
- * `render_failed`, ...) or a client-side one (`network_error`, `timeout`,
- * `aborted`). `requestId` is the id to quote to support; it is on every
- * response the server produced, including errors.
+ * `code` is the API's stable error code (`bad_request`, `render_failed`,
+ * `free_allowance_exhausted`, ...) or a client-side one (`network_error`,
+ * `timeout`, `aborted`). `requestId` is the id to quote to support; it is on
+ * every response the server produced, including errors. `retryAfter` is the
+ * API's `Retry-After` in seconds, when it sent one.
  */
 export class IronfangRenderError extends Error {
     status;
     code;
     requestId;
+    retryAfter;
     constructor(message, opts) {
         super(message);
         this.name = 'IronfangRenderError';
         this.status = opts.status;
         this.code = opts.code;
         this.requestId = opts.requestId;
+        this.retryAfter = opts.retryAfter;
     }
     /** The request was refused before any work was done. */
     get isClientError() {
         return this.status >= 400 && this.status < 500;
     }
 }
+/**
+ * The codes a billing refusal carries. They are the same in every Ironfang
+ * product, because every product admits work through the one billing account.
+ */
+export const BILLING_CODES = [
+    'free_allowance_exhausted',
+    'account_budget_exhausted',
+    'product_budget_exhausted',
+    'exemption_limit_reached',
+    'paid_usage_paused',
+    'payment_required',
+    'payment_action_required',
+    'account_restricted',
+    'product_not_eligible',
+    'account_closed',
+    'operation_too_large',
+    'billing_temporarily_unavailable',
+];
+/**
+ * The organisation's billing account refused the request before any work
+ * started: nothing was rendered and nothing counted. Most refusals are
+ * resolved in Billing in the Ironfang portal (enable paid usage, raise a
+ * limit, update the payment method) or by the month rolling over; only
+ * `billing_temporarily_unavailable` clears on its own, after `retryAfter`
+ * seconds.
+ *
+ * `product` is the product whose usage was refused (always `render` here).
+ * `meter` and `resetAt` (when the free allowance renews, RFC 3339) are set
+ * when the API states them.
+ */
+export class IronfangBillingError extends IronfangRenderError {
+    product;
+    meter;
+    resetAt;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = 'IronfangBillingError';
+        this.product = opts.product ?? 'render';
+        this.meter = opts.meter;
+        this.resetAt = opts.resetAt;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { IronfangRender, VERSION } from './client.js';
 export type { ClientOptions, RequestOptions, RenderResult, SitePreviewResult, WaitOptions } from './client.js';
-export { IronfangRenderError } from './errors.js';
+export { IronfangBillingError, IronfangRenderError } from './errors.js';
 export { verifyWebhook, signWebhook } from './webhook.js';
 export type { WebhookInput } from './webhook.js';
 export type * from './types.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { IronfangRender, VERSION } from './client.js';
-export { IronfangRenderError } from './errors.js';
+export { IronfangBillingError, IronfangRenderError } from './errors.js';
 export { verifyWebhook, signWebhook } from './webhook.js';

package/dist/types.d.ts

@@ -118,6 +118,17 @@ export interface JobDelivery {
     storage_destination?: string;
     storage_key?: string;
 }
+/**
+ * What a job counts against the billing account: its meter, the quantity
+ * reserved when it was accepted (0 when unmetered) and the quantity its
+ * success committed, never more than was reserved. A job that fails or is
+ * cancelled commits nothing.
+ */
+export interface JobUsage {
+    meter: string;
+    reserved: number;
+    committed: number;
+}
 export interface JobSubmission {
     kind: JobKind;
     request: Record<string, unknown>;
@@ -136,11 +147,7 @@ export interface Job {
     queued_at: string;
     started_at?: string | null;
     completed_at?: string | null;
-    credits: {
-        reserved: number;
-        charged: number;
-        refunded: number;
-    };
+    usage: JobUsage;
     request_summary?: Record<string, unknown>;
     delivery?: JobDelivery;
     error?: {
@@ -171,23 +178,55 @@ export interface SignedUrl {
     url: string;
     path: string;
 }
+/** One Ironfang Render meter's position in the month. */
+export interface MeterUsage {
+    /** The meter, e.g. `render.screenshot` or `render.video_second_hd`. */
+    id: string;
+    unit: string;
+    unit_plural: string;
+    /** This month's free quantity. */
+    free_allowance: number;
+    /** Quantity committed this month. */
+    used: number;
+    /** How much of `used` the free allowance covered. */
+    free_used: number;
+    /** `used` beyond the free allowance. */
+    billable: number;
+    /** Quantity held by work in flight. */
+    reserved: number;
+    /** Free allowance left once work in flight is counted. */
+    remaining_free: number;
+    /** What `billable` costs before tax, as an exact decimal string. */
+    charge: string;
+    /** A meter that is never charged (QR codes). */
+    free_utility?: boolean;
+    /** The account is exempt from settling this product. */
+    exempt?: boolean;
+}
+/**
+ * This UTC calendar month's Ironfang Render usage from the organisation's
+ * billing account. Amounts are exact decimal strings in `currency`, before
+ * tax. The whole account, every product included, is managed in Billing in
+ * the Ironfang portal.
+ */
 export interface Usage {
-    period: string;
-    credits: number;
-    renders: number;
-    limit: number;
+    product: 'render';
+    /** The period as [period_start, period_end) in UTC dates. */
     period_start: string;
     period_end: string;
-    by_kind?: Record<string, {
-        credits: number;
-        count: number;
-    }>;
-    unattributed?: number;
-    daily?: {
-        day: string;
-        credits: number;
-        by_kind?: Record<string, number>;
-    }[];
+    catalogue_version: string;
+    /** `enabled` means paid usage beyond the free allowances is on. */
+    mode: 'free' | 'setup_pending' | 'enabled' | 'paused' | 'closed';
+    currency: string;
+    /** What Ironfang Render's settled usage costs this period. */
+    settled: string;
+    /** The most work in flight could add if it all succeeds; not charged on top of `settled`. */
+    reserved: string;
+    meters: MeterUsage[];
+}
+/** The usage answer for an unmetered key, or a deployment with billing off. */
+export interface UnmeteredUsage {
+    unmetered: true;
 }
 /** One row of request history: what was asked for and what happened, never the values. */
 export interface RequestRecord {
@@ -202,8 +241,10 @@ export interface RequestRecord {
     outcome: 'ok' | 'error' | 'cancelled';
     error_code?: string;
     cache_hit: boolean;
-    credits_charged: number;
-    credits_refunded: number;
+    /** The billing meter the request counted against. */
+    meter?: string;
+    /** What it committed there: 0 for a cache hit, a failure or an unmetered key. */
+    quantity: number;
     response_bytes: number;
     content_type?: string;
     duration_ms: number;

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": "2.0.0",
+  "version": "3.0.1",
   "description": "Ironfang Render API client: screenshots, PDFs, QR codes, template images, clips and site previews from a URL or HTML.",
   "license": "MIT",
   "type": "module",