@kindgi/crypto 0.1.6 → 0.1.7-rc.0

package/dist/inbound-signature.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Verifying a request a webhook trigger receives, in the scheme its sender
+ * signs with (`WebhookSignatureScheme`, `@kindgi/types`):
+ *
+ * - `hmac-sha256`: HMAC-SHA256 of the raw body under the secret's UTF-8
+ *   bytes, read from one header (`hex` or `base64`, after an optional
+ *   prefix). WooCommerce, Shopify, GitHub and Drupal's Webhooks module sign
+ *   this way.
+ * - `standard-webhooks`: {@link verifyWebhook}.
+ *
+ * The comparison is constant-time. A missing header, a malformed one and a
+ * wrong signature are told apart only in the result's `reason`, for the
+ * receiver's own record: a receiver answers all of them the same way.
+ */
+import { type KeyObject } from 'node:crypto';
+import type { WebhookSignatureScheme } from '@kindgi/types';
+import { type WebhookRequestHeaders } from './webhook.js';
+export interface VerifyInboundSignatureInput {
+    readonly scheme: WebhookSignatureScheme;
+    /**
+     * The shared secret (its UTF-8 bytes for `hmac-sha256`; `whsec_…` for
+     * `standard-webhooks`), or the key {@link inboundSigningKey} derived
+     * from it for the same scheme.
+     */
+    readonly secret: string | KeyObject;
+    readonly headers: WebhookRequestHeaders;
+    /** The raw request body, exactly as received — never a re-serialized JSON value. */
+    readonly body: string | Uint8Array;
+    /** Clock in milliseconds, for a scheme with a timestamp; default `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Why a request isn't verified:
+ * - `signature-missing`: the scheme's header (or headers) isn't there;
+ * - `signature-invalid`: present, but malformed or not matching;
+ * - `stale`: the signed timestamp is outside the tolerance;
+ * - `secret-invalid`: the secret can't be used with the scheme (empty, or
+ *   not a `whsec_` key for `standard-webhooks`).
+ */
+export type VerifyInboundSignatureFailure = 'signature-missing' | 'signature-invalid' | 'stale' | 'secret-invalid';
+export type VerifyInboundSignatureResult = {
+    readonly kind: 'ok';
+    /** The id the scheme itself signs (`webhook-id`), when it signs one. */
+    readonly signedId?: string;
+} | {
+    readonly kind: 'err';
+    readonly reason: VerifyInboundSignatureFailure;
+};
+/**
+ * A trigger's signing key, derived from its secret for its scheme: the
+ * secret's UTF-8 bytes for `hmac-sha256`, the key a `whsec_…` secret
+ * encodes for `standard-webhooks`. A `KeyObject`, so a receiver that keeps
+ * it for a while holds no string of the secret, and nothing logs or
+ * serializes it by accident (`JSON.stringify` gives `{}`).
+ */
+export declare function inboundSigningKey(scheme: WebhookSignatureScheme, secret: string): {
+    readonly kind: 'ok';
+    readonly key: KeyObject;
+} | {
+    readonly kind: 'err';
+    readonly reason: 'secret-invalid';
+};
+/** Verify a received request against its trigger's signature scheme. */
+export declare function verifyInboundSignature(input: VerifyInboundSignatureInput): VerifyInboundSignatureResult;
+//# sourceMappingURL=inbound-signature.d.ts.map

package/dist/inbound-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-signature.d.ts","sourceRoot":"","sources":["../src/inbound-signature.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAgD,MAAM,aAAa,CAAC;AAE3F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE5D,OAAO,EACL,KAAK,qBAAqB,EAI3B,MAAM,cAAc,CAAC;AAItB,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,6BAA6B,GACrC,mBAAmB,GACnB,mBAAmB,GACnB,OAAO,GACP,gBAAgB,CAAC;AAErB,MAAM,MAAM,4BAA4B,GACpC;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAA;CAAE,CAAC;AAE7E;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,sBAAsB,EAC9B,MAAM,EAAE,MAAM,GAEZ;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAY9D;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CA8C9B"}

package/dist/inbound-signature.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Verifying a request a webhook trigger receives, in the scheme its sender
+ * signs with (`WebhookSignatureScheme`, `@kindgi/types`):
+ *
+ * - `hmac-sha256`: HMAC-SHA256 of the raw body under the secret's UTF-8
+ *   bytes, read from one header (`hex` or `base64`, after an optional
+ *   prefix). WooCommerce, Shopify, GitHub and Drupal's Webhooks module sign
+ *   this way.
+ * - `standard-webhooks`: {@link verifyWebhook}.
+ *
+ * The comparison is constant-time. A missing header, a malformed one and a
+ * wrong signature are told apart only in the result's `reason`, for the
+ * receiver's own record: a receiver answers all of them the same way.
+ */
+import { createHmac, createSecretKey, timingSafeEqual } from 'node:crypto';
+import { parseWebhookSecret, readHeader, verifyWebhookWith, } from './webhook.js';
+const SHA256_BYTES = 32;
+/**
+ * A trigger's signing key, derived from its secret for its scheme: the
+ * secret's UTF-8 bytes for `hmac-sha256`, the key a `whsec_…` secret
+ * encodes for `standard-webhooks`. A `KeyObject`, so a receiver that keeps
+ * it for a while holds no string of the secret, and nothing logs or
+ * serializes it by accident (`JSON.stringify` gives `{}`).
+ */
+export function inboundSigningKey(scheme, secret) {
+    const bytes = scheme.kind === 'standard-webhooks'
+        ? parseWebhookSecret(secret)
+        : secret.length === 0
+            ? null
+            : Buffer.from(secret, 'utf-8');
+    if (bytes === null)
+        return { kind: 'err', reason: 'secret-invalid' };
+    const key = createSecretKey(bytes);
+    // The key keeps its own copy.
+    bytes.fill(0);
+    return { kind: 'ok', key };
+}
+/** Verify a received request against its trigger's signature scheme. */
+export function verifyInboundSignature(input) {
+    const { scheme } = input;
+    if (scheme.kind === 'standard-webhooks') {
+        const verified = verifyWebhookWith({
+            headers: input.headers,
+            body: input.body,
+            ...(scheme.toleranceSeconds !== undefined && {
+                toleranceSeconds: scheme.toleranceSeconds,
+            }),
+            ...(input.now !== undefined && { now: input.now }),
+        }, input.secret);
+        if (verified.kind === 'ok')
+            return { kind: 'ok', signedId: verified.id };
+        switch (verified.reason) {
+            case 'missing-headers':
+                return { kind: 'err', reason: 'signature-missing' };
+            case 'timestamp-out-of-tolerance':
+                return { kind: 'err', reason: 'stale' };
+            case 'invalid-secret':
+                return { kind: 'err', reason: 'secret-invalid' };
+            default:
+                return { kind: 'err', reason: 'signature-invalid' };
+        }
+    }
+    const { secret } = input;
+    if (typeof secret === 'string' && secret.length === 0) {
+        return { kind: 'err', reason: 'secret-invalid' };
+    }
+    const raw = readHeader(input.headers, scheme.header.toLowerCase());
+    if (raw === undefined)
+        return { kind: 'err', reason: 'signature-missing' };
+    const prefix = scheme.prefix ?? '';
+    if (!raw.startsWith(prefix))
+        return { kind: 'err', reason: 'signature-invalid' };
+    const provided = decodeDigest(raw.slice(prefix.length).trim(), scheme.encoding);
+    if (provided === undefined)
+        return { kind: 'err', reason: 'signature-invalid' };
+    const expected = createHmac('sha256', typeof secret === 'string' ? Buffer.from(secret, 'utf-8') : secret)
+        .update(typeof input.body === 'string' ? Buffer.from(input.body, 'utf-8') : input.body)
+        .digest();
+    return timingSafeEqual(provided, expected)
+        ? { kind: 'ok' }
+        : { kind: 'err', reason: 'signature-invalid' };
+}
+/** A 32-byte digest from its `hex` or `base64` form; `undefined` when it isn't one. */
+function decodeDigest(text, encoding) {
+    if (encoding === 'hex') {
+        return /^[0-9a-fA-F]{64}$/.test(text) ? Buffer.from(text, 'hex') : undefined;
+    }
+    // Base64 of 32 bytes is 44 characters with one `=` of padding.
+    if (!/^[A-Za-z0-9+/]{43}=$/.test(text))
+        return undefined;
+    const bytes = Buffer.from(text, 'base64');
+    return bytes.length === SHA256_BYTES ? bytes : undefined;
+}
+//# sourceMappingURL=inbound-signature.js.map

package/dist/inbound-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-signature.js","sourceRoot":"","sources":["../src/inbound-signature.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export type { Ed25519KeyPair } from './ed25519.js';
 export { hmacSha256Sign, hmacSha256Verify } from './hmac.js';
 export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, generateWebhookSecret, isStrongWebhookSecret, signWebhook, verifyWebhook, WEBHOOK_HEADERS, WEBHOOK_SECRET_MIN_BYTES, WEBHOOK_SECRET_PREFIX, webhookHeaders, } from './webhook.js';
 export type { SignWebhookInput, VerifyWebhookFailure, VerifyWebhookInput, VerifyWebhookResult, WebhookRequestHeaders, } from './webhook.js';
+export { inboundSigningKey, verifyInboundSignature } from './inbound-signature.js';
+export type { VerifyInboundSignatureFailure, VerifyInboundSignatureInput, VerifyInboundSignatureResult, } from './inbound-signature.js';
 export { createInMemorySigningKeyBinding } from './binding.js';
 export { EXPORT_SIGNING_ALGORITHMS, createEcdsaP256ExportSigner, createEd25519ExportSigner, createExportSignerFromPem, ecdsaDerToP1363, exportSigningKey, } from './export-signing.js';
 export { parseRetiredExportKeys, withRetiredExportKeys } from './retired-export-keys.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACzF,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE9F,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACnF,YAAY,EACV,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACzF,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAE9F,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@
 export { ED25519_SIGNATURE_BYTES, generateEd25519KeyPair, parsePrivateKeyBase64, parsePrivateKeyPem, parsePublicKeyBase64, parsePublicKeyPem, serializePrivateKeyBase64, serializePrivateKeyPem, serializePublicKeyBase64, serializePublicKeyPem, signEd25519, verifyEd25519, } from './ed25519.js';
 export { hmacSha256Sign, hmacSha256Verify } from './hmac.js';
 export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, generateWebhookSecret, isStrongWebhookSecret, signWebhook, verifyWebhook, WEBHOOK_HEADERS, WEBHOOK_SECRET_MIN_BYTES, WEBHOOK_SECRET_PREFIX, webhookHeaders, } from './webhook.js';
+export { inboundSigningKey, verifyInboundSignature } from './inbound-signature.js';
 export { createInMemorySigningKeyBinding } from './binding.js';
 export { EXPORT_SIGNING_ALGORITHMS, createEcdsaP256ExportSigner, createEd25519ExportSigner, createExportSignerFromPem, ecdsaDerToP1363, exportSigningKey, } from './export-signing.js';
 export { parseRetiredExportKeys, withRetiredExportKeys } from './retired-export-keys.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAiBzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,iCAAiC,EACjC,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAOnF,OAAO,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAiBzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}

package/dist/webhook.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Webhook signatures in the Standard Webhooks format
+ * (https://www.standardwebhooks.com), symmetric variant `v1`:
+ *
+ *   webhook-id:        the message id (the same on every retry)
+ *   webhook-timestamp: Unix seconds when the message was signed
+ *   webhook-signature: `v1,<base64 HMAC-SHA256>`, space-separated when
+ *                      several secrets sign (secret rotation)
+ *
+ * The signed content is `${id}.${timestamp}.${body}`, with `body` the raw
+ * request body exactly as sent. Secrets are `whsec_` + base64 of the key
+ * bytes. A receiver can verify with this module or with any Standard
+ * Webhooks library.
+ */
+import { type KeyObject } from 'node:crypto';
 import type { Result } from '@kindgi/types';
 import type { MalformedKeyError } from './errors.js';
 /** Prefix of a webhook signing secret. */
@@ -71,4 +86,14 @@ export type VerifyWebhookResult = {
  * constant-time. On `ok`, deduplicate on `id` — delivery is at least once.
  */
 export declare function verifyWebhook(input: VerifyWebhookInput): VerifyWebhookResult;
+/**
+ * {@link verifyWebhook} with the secret as given, or as the key already
+ * decoded from it (a `KeyObject`, which a receiver can keep without holding
+ * the secret as a string). Within the package.
+ */
+export declare function verifyWebhookWith(input: Omit<VerifyWebhookInput, 'secret'>, secret: string | KeyObject): VerifyWebhookResult;
+/** Key bytes of a `whsec_…` (or bare base64) secret; `null` when malformed. Within the package. */
+export declare function parseWebhookSecret(secret: string): Buffer | null;
+/** A header's first value (`name` in lower case, matched case-insensitively); `undefined` when absent or empty. */
+export declare function readHeader(headers: WebhookRequestHeaders, name: string): string | undefined;
 //# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAE9C,0DAA0D;AAC1D,eAAO,MAAM,eAAe;;;;CAIlB,CAAC;AAEX,gFAAgF;AAChF,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAKrD,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,yEAAyE;AACzE,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAG7D;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CActF;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,GACtB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAW7D;AAED,4EAA4E;AAC5E,MAAM,MAAM,qBAAqB,GAC7B;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,GACpC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;AAErE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACnC,yDAAyD;IACzD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,mBAAmB,GACnB,4BAA4B,GAC5B,gBAAgB,GAChB,uBAAuB,CAAC;AAE5B,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEpE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CA2B5E"}
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"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"}

package/dist/webhook.js

@@ -39,7 +39,7 @@ export function generateWebhookSecret() {
  * base64) of at least {@link WEBHOOK_SECRET_MIN_BYTES} bytes.
  */
 export function isStrongWebhookSecret(secret) {
-    const key = parseSecret(secret);
+    const key = parseWebhookSecret(secret);
     return key !== null && key.length >= WEBHOOK_SECRET_MIN_BYTES;
 }
 /**
@@ -58,7 +58,7 @@ export function signWebhook(input) {
     const content = signedContent(input.id, String(input.timestamp), input.body);
     const signatures = [];
     for (const secret of secrets) {
-        const key = parseSecret(secret);
+        const key = parseWebhookSecret(secret);
         if (key === null)
             return malformedKey('webhook secret must be `whsec_` + base64 key bytes');
         signatures.push(`${SIGNATURE_VERSION},${hmac(key, content).toString('base64')}`);
@@ -85,6 +85,14 @@ export function webhookHeaders(input) {
  * constant-time. On `ok`, deduplicate on `id` — delivery is at least once.
  */
 export function verifyWebhook(input) {
+    return verifyWebhookWith(input, input.secret);
+}
+/**
+ * {@link verifyWebhook} with the secret as given, or as the key already
+ * decoded from it (a `KeyObject`, which a receiver can keep without holding
+ * the secret as a string). Within the package.
+ */
+export function verifyWebhookWith(input, secret) {
     const id = readHeader(input.headers, WEBHOOK_HEADERS.id);
     const timestampRaw = readHeader(input.headers, WEBHOOK_HEADERS.timestamp);
     const signatureHeader = readHeader(input.headers, WEBHOOK_HEADERS.signature);
@@ -99,7 +107,7 @@ export function verifyWebhook(input) {
     if (Math.abs(nowSeconds - timestamp) > tolerance) {
         return { kind: 'err', reason: 'timestamp-out-of-tolerance' };
     }
-    const key = parseSecret(input.secret);
+    const key = typeof secret === 'string' ? parseWebhookSecret(secret) : secret;
     if (key === null)
         return { kind: 'err', reason: 'invalid-secret' };
     const expected = hmac(key, signedContent(id, timestampRaw, input.body));
@@ -122,8 +130,8 @@ function signedContent(id, timestamp, body) {
 function hmac(key, content) {
     return createHmac('sha256', key).update(content).digest();
 }
-/** Key bytes of a `whsec_…` (or bare base64) secret; `null` when malformed. */
-function parseSecret(secret) {
+/** Key bytes of a `whsec_…` (or bare base64) secret; `null` when malformed. Within the package. */
+export function parseWebhookSecret(secret) {
     const encoded = secret.startsWith(WEBHOOK_SECRET_PREFIX)
         ? secret.slice(WEBHOOK_SECRET_PREFIX.length)
         : secret;
@@ -132,7 +140,8 @@ function parseSecret(secret) {
     const key = Buffer.from(encoded, 'base64');
     return key.length === 0 ? null : key;
 }
-function readHeader(headers, name) {
+/** A header's first value (`name` in lower case, matched case-insensitively); `undefined` when absent or empty. */
+export function readHeader(headers, name) {
     if (typeof headers.get === 'function') {
         const value = headers.get(name);
         return value === null || value.length === 0 ? undefined : value;

package/dist/webhook.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/crypto",
-  "version": "0.1.6",
+  "version": "0.1.7-rc.0",
   "description": "Kindgi™ cryptographic primitives. Ed25519 signatures for asymmetric use (signed audit bundles, provenance exports, deployment attestations) and HMAC-SHA256 for symmetric use (webhook payloads). Includes SigningKeyBinding interface + in-memory reference impl, PEM/base64 key format converters, and typed error interfaces. Pure Node built-ins, zero runtime deps. Deployments plug their own key store (KMS, Vault, env-var) via SigningKeyBinding.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/types": "0.1.6"
+    "@kindgi/types": "0.1.7-rc.0"
   },
   "engines": {
     "node": ">=22.12.0"

package/src/inbound-signature.ts

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Verifying a request a webhook trigger receives, in the scheme its sender
+ * signs with (`WebhookSignatureScheme`, `@kindgi/types`):
+ *
+ * - `hmac-sha256`: HMAC-SHA256 of the raw body under the secret's UTF-8
+ *   bytes, read from one header (`hex` or `base64`, after an optional
+ *   prefix). WooCommerce, Shopify, GitHub and Drupal's Webhooks module sign
+ *   this way.
+ * - `standard-webhooks`: {@link verifyWebhook}.
+ *
+ * The comparison is constant-time. A missing header, a malformed one and a
+ * wrong signature are told apart only in the result's `reason`, for the
+ * receiver's own record: a receiver answers all of them the same way.
+ */
+
+import { type KeyObject, createHmac, createSecretKey, timingSafeEqual } from 'node:crypto';
+
+import type { WebhookSignatureScheme } from '@kindgi/types';
+
+import {
+  type WebhookRequestHeaders,
+  parseWebhookSecret,
+  readHeader,
+  verifyWebhookWith,
+} from './webhook.js';
+
+const SHA256_BYTES = 32;
+
+export interface VerifyInboundSignatureInput {
+  readonly scheme: WebhookSignatureScheme;
+  /**
+   * The shared secret (its UTF-8 bytes for `hmac-sha256`; `whsec_…` for
+   * `standard-webhooks`), or the key {@link inboundSigningKey} derived
+   * from it for the same scheme.
+   */
+  readonly secret: string | KeyObject;
+  readonly headers: WebhookRequestHeaders;
+  /** The raw request body, exactly as received — never a re-serialized JSON value. */
+  readonly body: string | Uint8Array;
+  /** Clock in milliseconds, for a scheme with a timestamp; default `Date.now`. */
+  readonly now?: () => number;
+}
+
+/**
+ * Why a request isn't verified:
+ * - `signature-missing`: the scheme's header (or headers) isn't there;
+ * - `signature-invalid`: present, but malformed or not matching;
+ * - `stale`: the signed timestamp is outside the tolerance;
+ * - `secret-invalid`: the secret can't be used with the scheme (empty, or
+ *   not a `whsec_` key for `standard-webhooks`).
+ */
+export type VerifyInboundSignatureFailure =
+  | 'signature-missing'
+  | 'signature-invalid'
+  | 'stale'
+  | 'secret-invalid';
+
+export type VerifyInboundSignatureResult =
+  | {
+      readonly kind: 'ok';
+      /** The id the scheme itself signs (`webhook-id`), when it signs one. */
+      readonly signedId?: string;
+    }
+  | { readonly kind: 'err'; readonly reason: VerifyInboundSignatureFailure };
+
+/**
+ * A trigger's signing key, derived from its secret for its scheme: the
+ * secret's UTF-8 bytes for `hmac-sha256`, the key a `whsec_…` secret
+ * encodes for `standard-webhooks`. A `KeyObject`, so a receiver that keeps
+ * it for a while holds no string of the secret, and nothing logs or
+ * serializes it by accident (`JSON.stringify` gives `{}`).
+ */
+export function inboundSigningKey(
+  scheme: WebhookSignatureScheme,
+  secret: string,
+):
+  | { readonly kind: 'ok'; readonly key: KeyObject }
+  | { readonly kind: 'err'; readonly reason: 'secret-invalid' } {
+  const bytes =
+    scheme.kind === 'standard-webhooks'
+      ? parseWebhookSecret(secret)
+      : secret.length === 0
+        ? null
+        : Buffer.from(secret, 'utf-8');
+  if (bytes === null) return { kind: 'err', reason: 'secret-invalid' };
+  const key = createSecretKey(bytes);
+  // The key keeps its own copy.
+  bytes.fill(0);
+  return { kind: 'ok', key };
+}
+
+/** Verify a received request against its trigger's signature scheme. */
+export function verifyInboundSignature(
+  input: VerifyInboundSignatureInput,
+): VerifyInboundSignatureResult {
+  const { scheme } = input;
+  if (scheme.kind === 'standard-webhooks') {
+    const verified = verifyWebhookWith(
+      {
+        headers: input.headers,
+        body: input.body,
+        ...(scheme.toleranceSeconds !== undefined && {
+          toleranceSeconds: scheme.toleranceSeconds,
+        }),
+        ...(input.now !== undefined && { now: input.now }),
+      },
+      input.secret,
+    );
+    if (verified.kind === 'ok') return { kind: 'ok', signedId: verified.id };
+    switch (verified.reason) {
+      case 'missing-headers':
+        return { kind: 'err', reason: 'signature-missing' };
+      case 'timestamp-out-of-tolerance':
+        return { kind: 'err', reason: 'stale' };
+      case 'invalid-secret':
+        return { kind: 'err', reason: 'secret-invalid' };
+      default:
+        return { kind: 'err', reason: 'signature-invalid' };
+    }
+  }
+
+  const { secret } = input;
+  if (typeof secret === 'string' && secret.length === 0) {
+    return { kind: 'err', reason: 'secret-invalid' };
+  }
+  const raw = readHeader(input.headers, scheme.header.toLowerCase());
+  if (raw === undefined) return { kind: 'err', reason: 'signature-missing' };
+  const prefix = scheme.prefix ?? '';
+  if (!raw.startsWith(prefix)) return { kind: 'err', reason: 'signature-invalid' };
+  const provided = decodeDigest(raw.slice(prefix.length).trim(), scheme.encoding);
+  if (provided === undefined) return { kind: 'err', reason: 'signature-invalid' };
+  const expected = createHmac(
+    'sha256',
+    typeof secret === 'string' ? Buffer.from(secret, 'utf-8') : secret,
+  )
+    .update(typeof input.body === 'string' ? Buffer.from(input.body, 'utf-8') : input.body)
+    .digest();
+  return timingSafeEqual(provided, expected)
+    ? { kind: 'ok' }
+    : { kind: 'err', reason: 'signature-invalid' };
+}
+
+/** A 32-byte digest from its `hex` or `base64` form; `undefined` when it isn't one. */
+function decodeDigest(text: string, encoding: 'hex' | 'base64'): Buffer | undefined {
+  if (encoding === 'hex') {
+    return /^[0-9a-fA-F]{64}$/.test(text) ? Buffer.from(text, 'hex') : undefined;
+  }
+  // Base64 of 32 bytes is 44 characters with one `=` of padding.
+  if (!/^[A-Za-z0-9+/]{43}=$/.test(text)) return undefined;
+  const bytes = Buffer.from(text, 'base64');
+  return bytes.length === SHA256_BYTES ? bytes : undefined;
+}

package/src/index.ts

@@ -38,6 +38,13 @@ export type {
   WebhookRequestHeaders,
 } from './webhook.js';
 
+export { inboundSigningKey, verifyInboundSignature } from './inbound-signature.js';
+export type {
+  VerifyInboundSignatureFailure,
+  VerifyInboundSignatureInput,
+  VerifyInboundSignatureResult,
+} from './inbound-signature.js';
+
 export { createInMemorySigningKeyBinding } from './binding.js';
 
 export {

package/src/webhook.ts

@@ -16,7 +16,7 @@
  * Webhooks library.
  */
 
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { type KeyObject, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 
 import type { Result } from '@kindgi/types';
 
@@ -52,7 +52,7 @@ export function generateWebhookSecret(): string {
  * base64) of at least {@link WEBHOOK_SECRET_MIN_BYTES} bytes.
  */
 export function isStrongWebhookSecret(secret: string): boolean {
-  const key = parseSecret(secret);
+  const key = parseWebhookSecret(secret);
   return key !== null && key.length >= WEBHOOK_SECRET_MIN_BYTES;
 }
 
@@ -86,7 +86,7 @@ export function signWebhook(input: SignWebhookInput): Result<string, MalformedKe
   const content = signedContent(input.id, String(input.timestamp), input.body);
   const signatures: string[] = [];
   for (const secret of secrets) {
-    const key = parseSecret(secret);
+    const key = parseWebhookSecret(secret);
     if (key === null) return malformedKey('webhook secret must be `whsec_` + base64 key bytes');
     signatures.push(`${SIGNATURE_VERSION},${hmac(key, content).toString('base64')}`);
   }
@@ -142,6 +142,18 @@ export type VerifyWebhookResult =
  * constant-time. On `ok`, deduplicate on `id` — delivery is at least once.
  */
 export function verifyWebhook(input: VerifyWebhookInput): VerifyWebhookResult {
+  return verifyWebhookWith(input, input.secret);
+}
+
+/**
+ * {@link verifyWebhook} with the secret as given, or as the key already
+ * decoded from it (a `KeyObject`, which a receiver can keep without holding
+ * the secret as a string). Within the package.
+ */
+export function verifyWebhookWith(
+  input: Omit<VerifyWebhookInput, 'secret'>,
+  secret: string | KeyObject,
+): VerifyWebhookResult {
   const id = readHeader(input.headers, WEBHOOK_HEADERS.id);
   const timestampRaw = readHeader(input.headers, WEBHOOK_HEADERS.timestamp);
   const signatureHeader = readHeader(input.headers, WEBHOOK_HEADERS.signature);
@@ -155,7 +167,7 @@ export function verifyWebhook(input: VerifyWebhookInput): VerifyWebhookResult {
   if (Math.abs(nowSeconds - timestamp) > tolerance) {
     return { kind: 'err', reason: 'timestamp-out-of-tolerance' };
   }
-  const key = parseSecret(input.secret);
+  const key = typeof secret === 'string' ? parseWebhookSecret(secret) : secret;
   if (key === null) return { kind: 'err', reason: 'invalid-secret' };
 
   const expected = hmac(key, signedContent(id, timestampRaw, input.body));
@@ -176,12 +188,12 @@ function signedContent(id: string, timestamp: string, body: string | Uint8Array)
   return Buffer.concat([prefix, bodyBytes]);
 }
 
-function hmac(key: Buffer, content: Buffer): Buffer {
+function hmac(key: Buffer | KeyObject, content: Buffer): Buffer {
   return createHmac('sha256', key).update(content).digest();
 }
 
-/** Key bytes of a `whsec_…` (or bare base64) secret; `null` when malformed. */
-function parseSecret(secret: string): Buffer | null {
+/** Key bytes of a `whsec_…` (or bare base64) secret; `null` when malformed. Within the package. */
+export function parseWebhookSecret(secret: string): Buffer | null {
   const encoded = secret.startsWith(WEBHOOK_SECRET_PREFIX)
     ? secret.slice(WEBHOOK_SECRET_PREFIX.length)
     : secret;
@@ -190,7 +202,8 @@ function parseSecret(secret: string): Buffer | null {
   return key.length === 0 ? null : key;
 }
 
-function readHeader(headers: WebhookRequestHeaders, name: string): string | undefined {
+/** A header's first value (`name` in lower case, matched case-insensitively); `undefined` when absent or empty. */
+export function readHeader(headers: WebhookRequestHeaders, name: string): string | undefined {
   if (typeof (headers as { get?: unknown }).get === 'function') {
     const value = (headers as { get(name: string): string | null }).get(name);
     return value === null || value.length === 0 ? undefined : value;