hooklatch 0.0.0-stage → 1.0.0

package/dist/cjs/providers/workos.cjs

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workosDescriptor = void 0;
+const bytes_js_1 = require("../internal/bytes.cjs");
+const shared_js_1 = require("./shared.cjs");
+const SIGNATURE_HEADER = 'workos-signature';
+const TIMESTAMP_KEY = 't';
+const SIGNATURE_KEY = 'v1';
+/**
+ * Opaque nonempty printable ASCII unknown-field value: no whitespace, commas,
+ * or additional equals signs. This is a bounded Hooklatch grammar, not a
+ * promise to support an unspecified future signature version.
+ */
+const OPAQUE_VALUE = /^[\x21-\x2b\x2d-\x3c\x3e-\x7e]+$/;
+/**
+ * WorkOS: `WorkOS-Signature: t=<unix milliseconds>, v1=<64 hex>`.
+ *
+ * The comma-separated field list is validated as a whole before required-field
+ * checks. Segments are trimmed only at their outer edges, so whitespace around
+ * `=` is rejected; field names are case-sensitive. `t` must appear exactly once
+ * and be a canonical nonnegative safe decimal integer in milliseconds (zero is
+ * allowed, leading zeros are not). Every `v1` must be a 32-byte hex digest in
+ * either case; repeated `v1` values form a Hooklatch rotation accept-set, but a
+ * malformed `v1` poisons the header. Unknown field names are validated as
+ * opaque values and then ignored.
+ *
+ * The HMAC-SHA256 covers UTF8(original `t` text + ".") concatenated with the
+ * exact raw body. The secret is the literal, untrimmed UTF-8 text; it is never
+ * Base64-decoded. Invalid-UTF-8 body handling is a Hooklatch byte-preservation
+ * policy, not claimed parity with SDKs that decode the body to a string.
+ * Identity is `timestamp = Number(t) / 1000`; freshness is enforced by core and
+ * is never evaluated here.
+ *
+ * This strict grammar, repeated-v1 accept-set, and millisecond identity are
+ * documented receiver policies, not claims of exact WorkOS SDK parity. No
+ * WorkOS-published signature vector is claimed; tests use synthetic anchors.
+ * Sources:
+ * - https://workos.com/docs/events/data-syncing/webhooks
+ * - https://raw.githubusercontent.com/workos/workos-node/ad8bff226e9b37435f0c62390318d4819f76b3d1/src/common/crypto/signature-provider.ts
+ */
+exports.workosDescriptor = {
+    provider: 'workos',
+    decodeSecret(secret) {
+        return (0, shared_js_1.decodeLiteralSecret)(secret, 'WorkOS');
+    },
+    parse(headers, rawBody) {
+        const raw = headers.get(SIGNATURE_HEADER);
+        if (raw === undefined || raw.trim() === '') {
+            return (0, shared_js_1.failure)('missing-signature', 'No WorkOS signature header was provided.');
+        }
+        const signatures = [];
+        let timestampText;
+        let timestampCount = 0;
+        let unknownFields = 0;
+        // Validate the complete structure before any required-field decision.
+        for (const rawSegment of raw.split(',')) {
+            const segment = rawSegment.trim();
+            if (segment === '') {
+                return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+            }
+            // Reject missing keys, empty values, and extra equals signs.
+            const separator = segment.indexOf('=');
+            if (separator <= 0 || separator === segment.length - 1 || segment.indexOf('=', separator + 1) !== -1) {
+                return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+            }
+            const key = segment.slice(0, separator);
+            const value = segment.slice(separator + 1);
+            if (!(0, shared_js_1.isSchemeToken)(key)) {
+                return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+            }
+            if (key === TIMESTAMP_KEY) {
+                timestampCount += 1;
+                // Duplicate timestamps fail even when the values agree.
+                if (timestampCount > 1) {
+                    return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+                }
+                if (!(0, shared_js_1.isCanonicalTimestamp)(value)) {
+                    return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+                }
+                timestampText = value;
+                continue;
+            }
+            if (key === SIGNATURE_KEY) {
+                const decoded = (0, shared_js_1.decodeHexSignature)(value);
+                // One malformed v1 poisons the whole header, even beside a valid v1.
+                if (decoded === null) {
+                    return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+                }
+                signatures.push(decoded);
+                continue;
+            }
+            // Unknown fields are structurally validated, then ignored.
+            if (!OPAQUE_VALUE.test(value)) {
+                return (0, shared_js_1.failure)('malformed-signature', 'The WorkOS signature header is malformed.');
+            }
+            unknownFields += 1;
+        }
+        // Required-field checks run only after the whole structure validated.
+        if (signatures.length === 0) {
+            return unknownFields > 0
+                ? (0, shared_js_1.failure)('unsupported-scheme', 'No supported WorkOS signature scheme was provided.')
+                : (0, shared_js_1.failure)('missing-signature', 'No WorkOS signature value was provided.');
+        }
+        if (timestampText === undefined) {
+            return (0, shared_js_1.failure)('missing-timestamp', 'No WorkOS timestamp was provided.');
+        }
+        const identity = {
+            deliveryId: null,
+            eventId: null,
+            timestamp: Number(timestampText) / 1000,
+            authenticatedFields: ['timestamp'],
+        };
+        return {
+            ok: true,
+            signatures,
+            signedContent: (0, bytes_js_1.concatBytes)((0, bytes_js_1.utf8)(`${timestampText}.`), rawBody),
+            identity,
+        };
+    },
+};

package/dist/cjs/providers/workos.d.cts

@@ -0,0 +1,32 @@
+import type { NormalizedHeaders, ParseResult } from '../internal/provider.cjs';
+/**
+ * WorkOS: `WorkOS-Signature: t=<unix milliseconds>, v1=<64 hex>`.
+ *
+ * The comma-separated field list is validated as a whole before required-field
+ * checks. Segments are trimmed only at their outer edges, so whitespace around
+ * `=` is rejected; field names are case-sensitive. `t` must appear exactly once
+ * and be a canonical nonnegative safe decimal integer in milliseconds (zero is
+ * allowed, leading zeros are not). Every `v1` must be a 32-byte hex digest in
+ * either case; repeated `v1` values form a Hooklatch rotation accept-set, but a
+ * malformed `v1` poisons the header. Unknown field names are validated as
+ * opaque values and then ignored.
+ *
+ * The HMAC-SHA256 covers UTF8(original `t` text + ".") concatenated with the
+ * exact raw body. The secret is the literal, untrimmed UTF-8 text; it is never
+ * Base64-decoded. Invalid-UTF-8 body handling is a Hooklatch byte-preservation
+ * policy, not claimed parity with SDKs that decode the body to a string.
+ * Identity is `timestamp = Number(t) / 1000`; freshness is enforced by core and
+ * is never evaluated here.
+ *
+ * This strict grammar, repeated-v1 accept-set, and millisecond identity are
+ * documented receiver policies, not claims of exact WorkOS SDK parity. No
+ * WorkOS-published signature vector is claimed; tests use synthetic anchors.
+ * Sources:
+ * - https://workos.com/docs/events/data-syncing/webhooks
+ * - https://raw.githubusercontent.com/workos/workos-node/ad8bff226e9b37435f0c62390318d4819f76b3d1/src/common/crypto/signature-provider.ts
+ */
+export declare const workosDescriptor: {
+    provider: "workos";
+    decodeSecret(secret: string): Uint8Array;
+    parse(headers: NormalizedHeaders, rawBody: Uint8Array): ParseResult;
+};

package/dist/cjs/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/types.d.cts

@@ -0,0 +1,68 @@
+/** Contract version 1. Verification never parses or validates payload schemas. */
+export type Provider = 'stripe' | 'github' | 'shopify' | 'standard-webhooks' | 'clerk' | 'svix' | 'razorpay' | 'paddle' | 'lemon-squeezy' | 'dodo-payments' | 'gitlab' | 'replicate' | 'workos' | 'sentry' | 'doppler' | 'sanity' | 'grafana' | 'polar' | 'linear' | 'vercel' | 'fal';
+export type HeaderInput = Headers | Readonly<Record<string, string | readonly string[] | undefined>> | readonly (readonly [string, string])[];
+export interface WebhookRequest {
+    readonly rawBody: Uint8Array;
+    readonly headers: HeaderInput;
+}
+export type GrafanaOptions = {
+    readonly mode: 'body';
+    readonly signatureHeader?: string;
+    readonly timestampHeader?: never;
+} | {
+    readonly mode: 'timestamped';
+    readonly signatureHeader?: string;
+    readonly timestampHeader: string;
+};
+export interface PolarOptions {
+    readonly secretMode?: 'current' | 'legacy';
+}
+interface CommonVerifyOptions {
+    readonly toleranceSeconds?: number;
+    readonly now?: () => number;
+    readonly maxBodyBytes?: number;
+}
+export type FalVerifyOptions = CommonVerifyOptions & {
+    readonly provider: 'fal';
+    readonly publicKeys: readonly Uint8Array[];
+    readonly expectedUserId: string;
+    readonly secrets?: never;
+    readonly providerOptions?: never;
+};
+export type VerifyOptions = FalVerifyOptions | (CommonVerifyOptions & {
+    readonly secrets: readonly string[];
+} & ({
+    readonly provider: Exclude<Provider, 'grafana' | 'polar' | 'fal'>;
+    readonly providerOptions?: never;
+} | {
+    readonly provider: 'grafana';
+    readonly providerOptions: GrafanaOptions;
+} | {
+    readonly provider: 'polar';
+    readonly providerOptions?: PolarOptions;
+}));
+export type IdentityField = 'deliveryId' | 'eventId' | 'timestamp';
+export interface EventIdentity {
+    readonly deliveryId: string | null;
+    readonly eventId: string | null;
+    readonly timestamp: number | null;
+    readonly authenticatedFields: readonly IdentityField[];
+}
+export type VerificationFailureReason = 'missing-signature' | 'malformed-signature' | 'unsupported-scheme' | 'invalid-signature' | 'missing-identity' | 'missing-timestamp' | 'timestamp-expired' | 'timestamp-future' | 'body-too-large';
+export interface FailureDetails {
+    readonly ok: false;
+    readonly reason: VerificationFailureReason;
+    readonly message: string;
+}
+export interface VerificationSuccess {
+    readonly ok: true;
+    readonly provider: Provider;
+    readonly rawBody: Uint8Array;
+    readonly identity: EventIdentity;
+}
+export interface VerificationFailure extends FailureDetails {
+    readonly provider: Provider;
+}
+export type VerificationResult = VerificationSuccess | VerificationFailure;
+export type HooklatchErrorCode = 'unknown-provider' | 'missing-secrets' | 'invalid-secret' | 'invalid-options' | 'invalid-input' | 'body-consumed' | 'body-read-failed' | 'crypto-unavailable' | 'internal';
+export {};

package/dist/cli/args.d.ts

@@ -0,0 +1,86 @@
+import type { Provider } from '../types.js';
+export type Framework = 'express' | 'nextjs' | 'hono' | 'cloudflare';
+export declare const FRAMEWORKS: readonly ["express", "nextjs", "hono", "cloudflare"];
+export type GrafanaMode = 'body' | 'timestamped';
+export type PolarSecretMode = 'current' | 'legacy';
+export interface GrafanaCliOptions {
+    readonly mode: GrafanaMode;
+    readonly signatureHeader?: string;
+    readonly timestampHeader?: string;
+}
+export interface PolarCliOptions {
+    readonly secretMode: PolarSecretMode;
+}
+export interface FalCliOptions {
+    readonly publicKeyEnv: string;
+    readonly expectedUserEnv: string;
+}
+export type ProviderCliOptions = {
+    readonly provider: 'grafana';
+    readonly options: GrafanaCliOptions;
+} | {
+    readonly provider: 'polar';
+    readonly options: PolarCliOptions;
+} | {
+    readonly provider: 'fal';
+    readonly options: FalCliOptions;
+};
+/** Raw flag values collected by the argument scanner, before provider rules. */
+export interface RawProviderFlags {
+    readonly grafanaMode: string | undefined;
+    readonly signatureHeader: string | undefined;
+    readonly timestampHeader: string | undefined;
+    readonly polarSecretMode: string | undefined;
+    readonly publicKeyEnv?: string | undefined;
+    readonly expectedUserEnv?: string | undefined;
+}
+export type ProviderCliOptionsResult = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'options';
+    readonly options: ProviderCliOptions;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+interface CommandFields {
+    readonly framework: Framework;
+    readonly out: string;
+    readonly bodyLimit: number;
+    readonly dryRun: boolean;
+}
+export type WebhookCommand = CommandFields & ({
+    readonly provider: 'fal';
+    readonly publicKeyEnv: string;
+    readonly expectedUserEnv: string;
+    readonly secretEnv?: never;
+    readonly providerOptions?: never;
+} | {
+    readonly provider: Exclude<Provider, 'fal'>;
+    readonly secretEnv: string;
+    readonly publicKeyEnv?: never;
+    readonly expectedUserEnv?: never;
+    readonly providerOptions?: Exclude<ProviderCliOptions, {
+        readonly provider: 'fal';
+    }>;
+});
+export type ParseResult = {
+    readonly kind: 'help';
+} | {
+    readonly kind: 'command';
+    readonly command: WebhookCommand;
+} | {
+    readonly kind: 'error';
+    readonly exitCode: 2;
+    readonly message: string;
+};
+export declare const HELP_TEXT = "Usage: hooklatch init webhook --provider <id> --framework <id> [options]\n\nGenerate one TypeScript webhook endpoint file from an existing Hooklatch adapter.\n\nRequired:\n  --provider <id>       Implemented provider id.\n  --framework <id>      One of: express, nextjs, hono, cloudflare.\n\nOptions:\n  --out <dir>           Output directory (default: hooklatch).\n  --secret-env <NAME>   Environment variable holding the secret (default by provider).\n  --body-limit <bytes>  Positive safe integer body limit (default: 1048576).\n  --grafana-mode <mode> Grafana only: body or timestamped (required for grafana).\n  --signature-header <NAME>\n                        Grafana only: RFC 9110 header token (default x-grafana-alerting-signature).\n  --timestamp-header <NAME>\n                        Grafana only: required with timestamped; forbidden with body.\n  --polar-secret-mode <mode>\n                        Polar only: current (default) or legacy.\n  --public-key-env <NAME>\n                        Fal only: env var holding comma-separated Base64url public keys (default FAL_WEBHOOK_PUBLIC_KEYS).\n  --expected-user-env <NAME>\n                        Fal only: env var holding the expected user id (default FAL_WEBHOOK_USER_ID).\n  --dry-run             Print the target path and contents without writing.\n  -h, --help            Show this help.\n\nExit codes:\n  0  Success, dry run, or help.\n  1  Unexpected generation or I/O error.\n  2  Invalid arguments or unsafe path.\n  3  Target file already exists.\n";
+/**
+ * Apply provider-specific flag rules. Registration stays coordinator-owned:
+ * a provider that is not yet in the public registry is rejected by
+ * `parseArgs` before this function runs.
+ */
+export declare function buildProviderCliOptions(provider: string, flags: RawProviderFlags): ProviderCliOptionsResult;
+export declare function parseArgs(argv: readonly string[]): ParseResult;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

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