qubesync 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First version: webhooks only.
+
+- `verify(rawBody, header, { secrets, tolerance = 300, now })` checks the `X-QUBE-Signature`
+  header (HMAC-SHA256 of `"<t>." + raw body`, constant-time compare, one or more secrets while
+  one rotates) and returns a typed event, or throws `SignatureError` with `reason` `missing`,
+  `malformed`, `stale` or `mismatch`.
+- `parse(rawBody)` builds the typed event without verifying.
+- Events: `RequestEvent`, `WorkflowRunEvent`, `NotificationEvent`, `ConnectionEvent`,
+  `NameIndexEvent` and `UnknownEvent`, each with `type`, `event`, `timestamp`, `appId`,
+  `sandbox`, `body`, `revision`, `reference` and `dedupeKey`; `newerThan(storedRevision)` on
+  workflow runs and connections.
+- CommonJS and ESM entry points, TypeScript declarations, zero dependencies, Node 16.17 and later.
+- Tested against the server's own test vectors (`test/fixtures/test_vectors.json`), and CI checks
+  that copy against https://qubesync.com/webhooks/test_vectors.json.
+- A `v*` tag publishes to npm (`release.yml`, with the `NPM_TOKEN` secret).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuBe Sync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# qubesync (Node)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Verify and parse [QuBe Sync](https://qubesync.com) webhooks: QuickBooks Desktop through
+qubesync.com. Plain JavaScript, zero dependencies, Node 16.17 and later, CommonJS and ESM,
+TypeScript declarations included.
+
+```bash
+npm install qubesync
+```
+
+## Webhooks
+
+Every delivery carries an `X-QUBE-Signature` header: `t=<unix seconds>,v1=<hex>[,v1=<hex>...]`,
+one `v1` per active secret while you rotate. `verify` checks it against the **raw** body, then
+parses the body into a typed event:
+
+```js
+const { verify, SignatureError } = require("qubesync"); // or: import { verify, SignatureError } from "qubesync";
+
+const SECRETS = [process.env.QUBE_WEBHOOK_SECRET]; // add the new secret here while you rotate
+
+function handleDelivery(rawBody, signatureHeader) {
+  let event;
+  try {
+    event = verify(rawBody, signatureHeader, { secrets: SECRETS });
+  } catch (error) {
+    if (error instanceof SignatureError) return 401; // error.reason: missing | malformed | stale | mismatch
+    throw error;
+  }
+
+  switch (event.type) {
+    case "request":
+      // A queued request's answer. Dedupe on (page_request_id, state): event.dedupeKey.
+      // A paginated query is done when you hold pages 1..N for the page_request_id.
+      if (alreadyProcessed(event.dedupeKey)) return 200;
+      saveAnswer(event.pageRequestId, event.page, event.state, event.responseJson, event.error);
+      break;
+
+    case "workflow_run":
+      // awaiting_input, completed, failed or cancelled. Deliveries can arrive out of order:
+      // apply one only when it's newer than the revision you stored for the run.
+      if (!event.newerThan(storedRunRevision(event.runId))) return 200;
+      saveRun(event.runId, event.reference, event.revision, event.runState, event.output, event.prompt);
+      break;
+
+    case "notification":
+      // Data a run sends along the way. Dedupe on event.dedupeKey (the delivery id);
+      // never skip one by revision.
+      if (alreadyProcessed(event.dedupeKey)) return 200;
+      saveNotification(event.runId, event.name, event.seq, event.data);
+      break;
+
+    case "connection":
+      // connected, setup_cancelled, stalled, resumed. Dedupe on the delivery id and apply
+      // only when newer than the connection's stored revision.
+      if (alreadyProcessed(event.dedupeKey) || !event.newerThan(storedConnectionRevision(event.connectionId))) return 200;
+      saveConnection(event.connectionId, event.event, event.revision, event.stallReason);
+      break;
+
+    case "name_index":
+      saveNameIndex(event.connectionId, event.nameIndex);
+      break;
+
+    default:
+      // "unknown": an event newer than this library. Accept it; event.body has everything.
+      break;
+  }
+  return 200;
+}
+```
+
+`verify(rawBody, header, { secrets, tolerance = 300, now })`:
+
+- `rawBody` is the body exactly as received, as a `Buffer` or string (a string is signed as its
+  UTF-8 bytes). A parsed object throws a `TypeError`: re-serialized JSON never matches.
+- `header` is the `X-QUBE-Signature` value. Node lowercases header names, so read
+  `req.headers["x-qube-signature"]`.
+- `secrets` is one secret or an array of them. An empty or missing list throws a `TypeError`. The
+  library never reads the environment.
+- `tolerance` is how many seconds the timestamp may be off either way. `now` is unix seconds or a
+  `Date` and defaults to the current time.
+- On failure it throws `SignatureError`, whose `reason` is `missing`, `malformed`, `stale` or
+  `mismatch`, checked in that order. Its message is safe to log: it never holds the secret, the
+  signatures or the body.
+
+`parse(rawBody)` builds the same typed event without verifying, for tests and for code that
+verified elsewhere.
+
+### Events
+
+Every event has `type`, `event` (or `null` for a request's answer), `timestamp`, `appId`,
+`sandbox`, `revision`, `reference`, `dedupeKey` and `body` (the whole parsed body). Missing keys
+read as `null`; nothing throws.
+
+| `type` | when | also |
+| --- | --- | --- |
+| `request` | no `event`, has `page_request_id` | `id`, `pageRequestId`, `state`, `page`, `iterationState`, `responseJson`, `error`; `dedupeKey` is `"<page_request_id>:<state>"` |
+| `workflow_run` | `workflow_run.awaiting_input`, `.completed`, `.failed`, `.cancelled` | `runId`, `reference`, `revision`, `runState`, `workflow`, `connectionId`, `prompt`, `outcome`, `output`, `error`, `summary`, `cancelReason`, `links`, `newerThan(stored)` |
+| `notification` | `workflow_run.notification` | `runId`, `reference`, `revision`, `deliveryId`, `seq`, `name`, `state`, `from`, `data`; `dedupeKey` is the delivery id; no `newerThan` |
+| `connection` | `connection.*` | `deliveryId`, `revision`, `connection`, `connectionId`, `stallReason`, `newerThan(stored)`; `dedupeKey` is the delivery id |
+| `name_index` | `name_index.*` | `connectionId`, `nameIndex` |
+| `unknown` | anything else | the common fields only |
+
+`newerThan(stored)` is `true` when `stored` is `null` or `undefined`, else `revision > stored`.
+
+### Express
+
+Verify before any JSON body parser touches the request: mount `express.raw` on the webhook route
+so `req.body` is the raw `Buffer`.
+
+```js
+const express = require("express");
+const { verify, SignatureError } = require("qubesync");
+
+const app = express();
+
+app.post("/webhooks/qube", express.raw({ type: "application/json" }), (req, res) => {
+  let event;
+  try {
+    event = verify(req.body, req.get("X-QUBE-Signature"), { secrets: [process.env.QUBE_WEBHOOK_SECRET] });
+  } catch (error) {
+    if (error instanceof SignatureError) return res.sendStatus(401);
+    throw error;
+  }
+  // Route by event.type as above, then answer quickly.
+  res.sendStatus(200);
+});
+```
+
+## Development
+
+```sh
+npm test            # node:test, no dependencies
+npm run test:types  # tsc --strict against test/types.ts (fetches TypeScript with npx)
+```
+
+`test/fixtures/test_vectors.json` comes from the QuBe Sync server (`mix webhook_vectors.gen`).
+Copy a new version in; don't edit it.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,157 @@
+// Type definitions for qubesync (QuBe Sync webhooks).
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+export declare const VERSION: string;
+/** The header QuBe Sync signs deliveries in. Node lowercases it: `req.headers["x-qube-signature"]`. */
+export declare const SIGNATURE_HEADER: "X-QUBE-Signature";
+export declare const DEFAULT_TOLERANCE: 300;
+
+export type SignatureErrorReason = "missing" | "malformed" | "stale" | "mismatch";
+export declare const REASONS: readonly SignatureErrorReason[];
+
+/** Thrown by `verify` when a delivery can't be trusted. Answer 401. The message is safe to log. */
+export declare class SignatureError extends Error {
+  constructor(reason: SignatureErrorReason, message: string);
+  readonly name: "SignatureError";
+  readonly reason: SignatureErrorReason;
+}
+
+/** The raw request body exactly as received. A `Buffer` is a `Uint8Array`. */
+export type RawBody = string | Uint8Array;
+
+export interface VerifyOptions {
+  /** One secret, or several while one rotates. Required and non-empty. */
+  secrets: string | readonly string[];
+  /** Seconds the timestamp may be off either way. Default 300. */
+  tolerance?: number;
+  /** Unix seconds or a Date. Default: the current time. */
+  now?: number | Date;
+}
+
+export type EventType = "request" | "workflow_run" | "notification" | "connection" | "name_index" | "unknown";
+
+export declare abstract class Event {
+  /** The whole parsed body. */
+  readonly body: JsonObject;
+  readonly type: EventType;
+  readonly event: string | null;
+  readonly timestamp: number | null;
+  readonly appId: string | null;
+  readonly sandbox: boolean | null;
+  readonly revision: number | null;
+  readonly reference: string | null;
+  readonly dedupeKey: string | null;
+}
+
+/** A queued request's answer: no `event` key, has `page_request_id`. */
+export declare class RequestEvent extends Event {
+  readonly type: "request";
+  readonly revision: null;
+  readonly reference: null;
+  readonly id: string | null;
+  readonly pageRequestId: string | null;
+  readonly state: string | null;
+  readonly page: number | null;
+  readonly iterationState: string | null;
+  readonly responseJson: JsonValue;
+  readonly error: JsonValue;
+  /** `"<page_request_id>:<state>"`. */
+  readonly dedupeKey: string | null;
+}
+
+/** `workflow_run.awaiting_input`, `.completed`, `.failed` or `.cancelled`. */
+export declare class WorkflowRunEvent extends Event {
+  readonly type: "workflow_run";
+  readonly event: string;
+  readonly runId: string | null;
+  readonly runState: string | null;
+  readonly workflow: string | null;
+  readonly connectionId: string | null;
+  readonly prompt: JsonObject | null;
+  readonly outcome: string | null;
+  readonly output: JsonValue;
+  readonly error: JsonValue;
+  readonly summary: JsonObject | null;
+  readonly cancelReason: string | null;
+  readonly links: JsonObject | null;
+  /** Always null: apply a run's webhook when `newerThan(storedRevision)`. */
+  readonly dedupeKey: null;
+  /** True when `storedRevision` is null/undefined, else `revision > storedRevision`. */
+  newerThan(storedRevision: number | null | undefined): boolean;
+}
+
+/** `workflow_run.notification`: data a run sends along the way. Never skipped by revision. */
+export declare class NotificationEvent extends Event {
+  readonly type: "notification";
+  readonly event: "workflow_run.notification";
+  readonly runId: string | null;
+  readonly deliveryId: string | null;
+  readonly seq: number | null;
+  readonly name: string | null;
+  readonly state: string | null;
+  readonly from: JsonObject | null;
+  readonly data: JsonValue;
+  /** The `delivery_id`. */
+  readonly dedupeKey: string | null;
+}
+
+/** `connection.*`. */
+export declare class ConnectionEvent extends Event {
+  readonly type: "connection";
+  readonly event: string;
+  readonly reference: null;
+  readonly deliveryId: string | null;
+  readonly connection: JsonObject | null;
+  /** `connection.id`. */
+  readonly connectionId: string | null;
+  readonly stallReason: string | null;
+  /** The `delivery_id`. */
+  readonly dedupeKey: string | null;
+  /** True when `storedRevision` is null/undefined, else `revision > storedRevision`. */
+  newerThan(storedRevision: number | null | undefined): boolean;
+}
+
+/** `name_index.*`. */
+export declare class NameIndexEvent extends Event {
+  readonly type: "name_index";
+  readonly event: string;
+  readonly revision: null;
+  readonly reference: null;
+  readonly connectionId: string | null;
+  readonly nameIndex: JsonObject | null;
+  readonly dedupeKey: null;
+}
+
+/** Anything else, including events newer than this library. Never refused. */
+export declare class UnknownEvent extends Event {
+  readonly type: "unknown";
+  readonly revision: null;
+  readonly reference: null;
+  readonly dedupeKey: null;
+}
+
+export type WebhookEvent =
+  | RequestEvent
+  | WorkflowRunEvent
+  | NotificationEvent
+  | ConnectionEvent
+  | NameIndexEvent
+  | UnknownEvent;
+
+/**
+ * Verifies the X-QUBE-Signature header over the raw body, then parses it.
+ * Throws `SignatureError` (reason `missing`, `malformed`, `stale` or `mismatch`),
+ * or `TypeError` for a programming mistake (no secrets, a parsed body).
+ */
+export declare function verify(
+  rawBody: RawBody,
+  header: string | readonly string[] | null | undefined,
+  options: VerifyOptions
+): WebhookEvent;
+
+/** Parses a body into a typed event without verifying it. */
+export declare function parse(rawBody: RawBody): WebhookEvent;

package/index.js

@@ -0,0 +1,405 @@
+"use strict";
+
+// QuBe Sync webhooks: verify a delivery's X-QUBE-Signature header, then parse
+// the body into a typed event. Framework-free, zero dependencies.
+
+const crypto = require("crypto");
+
+const VERSION = "0.1.0";
+const SIGNATURE_HEADER = "X-QUBE-Signature";
+const DEFAULT_TOLERANCE = 300;
+const REASONS = Object.freeze(["missing", "malformed", "stale", "mismatch"]);
+
+const WORKFLOW_RUN_EVENTS = Object.freeze([
+  "workflow_run.awaiting_input",
+  "workflow_run.completed",
+  "workflow_run.failed",
+  "workflow_run.cancelled",
+]);
+const NOTIFICATION_EVENT = "workflow_run.notification";
+
+class SignatureError extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.name = "SignatureError";
+    this.reason = reason;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Events
+
+function own(object, key) {
+  if (object === null || typeof object !== "object" || Array.isArray(object)) return null;
+  if (!Object.prototype.hasOwnProperty.call(object, key)) return null;
+  const value = object[key];
+  return value === undefined ? null : value;
+}
+
+class Event {
+  constructor(body) {
+    Object.defineProperty(this, "body", { value: body, enumerable: true });
+  }
+
+  get type() {
+    return "unknown";
+  }
+  get event() {
+    const event = own(this.body, "event");
+    return typeof event === "string" ? event : null;
+  }
+  get timestamp() {
+    return own(this.body, "timestamp");
+  }
+  get appId() {
+    return own(this.body, "app_id");
+  }
+  get sandbox() {
+    return own(this.body, "sandbox");
+  }
+  get revision() {
+    return null;
+  }
+  get reference() {
+    return null;
+  }
+  get dedupeKey() {
+    return null;
+  }
+}
+
+class UnknownEvent extends Event {}
+
+class RequestEvent extends Event {
+  get type() {
+    return "request";
+  }
+  get id() {
+    return own(this.body, "id");
+  }
+  get pageRequestId() {
+    return own(this.body, "page_request_id");
+  }
+  get state() {
+    return own(this.body, "state");
+  }
+  get page() {
+    return own(this.body, "page");
+  }
+  get iterationState() {
+    return own(this.body, "iteration_state");
+  }
+  get responseJson() {
+    return own(this.body, "response_json");
+  }
+  get error() {
+    return own(this.body, "error");
+  }
+  get dedupeKey() {
+    const pageRequestId = this.pageRequestId;
+    const state = this.state;
+    if (pageRequestId === null || state === null) return null;
+    return `${pageRequestId}:${state}`;
+  }
+}
+
+function newerThan(revision, stored) {
+  if (stored === null || stored === undefined) return true;
+  return revision !== null && revision > stored;
+}
+
+class WorkflowRunEvent extends Event {
+  get type() {
+    return "workflow_run";
+  }
+  get runId() {
+    return own(this.body, "run_id");
+  }
+  get reference() {
+    return own(this.body, "reference");
+  }
+  get revision() {
+    return own(this.body, "revision");
+  }
+  get runState() {
+    return own(this.body, "run_state");
+  }
+  get workflow() {
+    return own(this.body, "workflow");
+  }
+  get connectionId() {
+    return own(this.body, "connection_id");
+  }
+  get prompt() {
+    return own(this.body, "prompt");
+  }
+  get outcome() {
+    return own(this.body, "outcome");
+  }
+  get output() {
+    return own(this.body, "output");
+  }
+  get error() {
+    return own(this.body, "error");
+  }
+  get summary() {
+    return own(this.body, "summary");
+  }
+  get cancelReason() {
+    return own(this.body, "cancel_reason");
+  }
+  get links() {
+    return own(this.body, "links");
+  }
+  newerThan(storedRevision) {
+    return newerThan(this.revision, storedRevision);
+  }
+}
+
+// A notification is data a run sends along the way: it carries a revision but
+// is never skipped by it, so it has no newerThan. Dedupe on deliveryId.
+class NotificationEvent extends Event {
+  get type() {
+    return "notification";
+  }
+  get runId() {
+    return own(this.body, "run_id");
+  }
+  get reference() {
+    return own(this.body, "reference");
+  }
+  get revision() {
+    return own(this.body, "revision");
+  }
+  get deliveryId() {
+    return own(this.body, "delivery_id");
+  }
+  get seq() {
+    return own(this.body, "seq");
+  }
+  get name() {
+    return own(this.body, "name");
+  }
+  get state() {
+    return own(this.body, "state");
+  }
+  get from() {
+    return own(this.body, "from");
+  }
+  get data() {
+    return own(this.body, "data");
+  }
+  get dedupeKey() {
+    return this.deliveryId;
+  }
+}
+
+class ConnectionEvent extends Event {
+  get type() {
+    return "connection";
+  }
+  get deliveryId() {
+    return own(this.body, "delivery_id");
+  }
+  get revision() {
+    return own(this.body, "revision");
+  }
+  get connection() {
+    return own(this.body, "connection");
+  }
+  get connectionId() {
+    return own(this.connection, "id");
+  }
+  get stallReason() {
+    const fromConnection = own(this.connection, "stall_reason");
+    return fromConnection !== null ? fromConnection : own(this.body, "stall_reason");
+  }
+  get dedupeKey() {
+    return this.deliveryId;
+  }
+  newerThan(storedRevision) {
+    return newerThan(this.revision, storedRevision);
+  }
+}
+
+class NameIndexEvent extends Event {
+  get type() {
+    return "name_index";
+  }
+  get connectionId() {
+    return own(this.body, "connection_id");
+  }
+  get nameIndex() {
+    return own(this.body, "name_index");
+  }
+}
+
+function eventClassFor(body) {
+  const event = own(body, "event");
+  if (event === null) {
+    return own(body, "page_request_id") !== null ? RequestEvent : UnknownEvent;
+  }
+  if (typeof event !== "string") return UnknownEvent;
+  if (WORKFLOW_RUN_EVENTS.includes(event)) return WorkflowRunEvent;
+  if (event === NOTIFICATION_EVENT) return NotificationEvent;
+  if (event.startsWith("connection.")) return ConnectionEvent;
+  if (event.startsWith("name_index.")) return NameIndexEvent;
+  return UnknownEvent;
+}
+
+// ---------------------------------------------------------------------------
+// Arguments
+
+function bodyBytes(rawBody) {
+  if (Buffer.isBuffer(rawBody)) return rawBody;
+  if (typeof rawBody === "string") return Buffer.from(rawBody, "utf8");
+  if (rawBody instanceof Uint8Array) {
+    return Buffer.from(rawBody.buffer, rawBody.byteOffset, rawBody.byteLength);
+  }
+  if (rawBody !== null && typeof rawBody === "object") {
+    throw new TypeError(
+      "rawBody is a parsed object: pass the raw request body (a Buffer or string, exactly as received), " +
+        'for example from express.raw({ type: "application/json" })'
+    );
+  }
+  throw new TypeError(
+    `rawBody must be the raw request body as a Buffer or string, got ${rawBody === null ? "null" : typeof rawBody}`
+  );
+}
+
+function secretList(secrets) {
+  const list = typeof secrets === "string" || Buffer.isBuffer(secrets) ? [secrets] : secrets;
+  if (!Array.isArray(list)) {
+    throw new TypeError("secrets must be a webhook secret string or an array of them");
+  }
+  if (list.length === 0) {
+    throw new TypeError("secrets is empty: pass at least one webhook secret");
+  }
+  list.forEach((secret, index) => {
+    const ok = (typeof secret === "string" || Buffer.isBuffer(secret)) && secret.length > 0;
+    if (!ok) throw new TypeError(`secrets[${index}] must be a non-empty string`);
+  });
+  return list;
+}
+
+function nowSeconds(now) {
+  if (now === undefined || now === null) return Math.floor(Date.now() / 1000);
+  if (now instanceof Date) {
+    const ms = now.getTime();
+    if (Number.isNaN(ms)) throw new TypeError("now is an invalid Date");
+    return Math.floor(ms / 1000);
+  }
+  if (typeof now === "number" && Number.isFinite(now)) return Math.floor(now);
+  throw new TypeError("now must be unix seconds (a number) or a Date");
+}
+
+function toleranceSeconds(tolerance) {
+  if (tolerance === undefined || tolerance === null) return DEFAULT_TOLERANCE;
+  if (typeof tolerance === "number" && Number.isFinite(tolerance) && tolerance >= 0) return tolerance;
+  throw new TypeError("tolerance must be a non-negative number of seconds");
+}
+
+function headerString(header) {
+  if (Array.isArray(header)) return header.join(",");
+  if (header === undefined || header === null || typeof header === "string") return header;
+  throw new TypeError("header must be the X-QUBE-Signature header value (a string)");
+}
+
+// Splits "t=...,v1=...,v1=..." into the first t and every non-empty v1.
+function parseHeader(header) {
+  let t = null;
+  const signatures = [];
+  for (const rawPart of header.split(",")) {
+    const part = rawPart.trim();
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const key = part.slice(0, eq);
+    const value = part.slice(eq + 1);
+    if (key === "t" && t === null) t = value;
+    else if (key === "v1" && value !== "") signatures.push(value);
+  }
+  return { t, signatures };
+}
+
+function constantTimeEqual(expected, candidate) {
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(candidate, "utf8");
+  if (a.length !== b.length) return false;
+  return crypto.timingSafeEqual(a, b);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+
+function parse(rawBody) {
+  const text = bodyBytes(rawBody).toString("utf8");
+  const body = JSON.parse(text);
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    throw new TypeError("webhook body is not a JSON object");
+  }
+  const EventClass = eventClassFor(body);
+  return new EventClass(body);
+}
+
+function verify(rawBody, header, options) {
+  const opts = options === undefined || options === null ? {} : options;
+  if (typeof opts !== "object") {
+    throw new TypeError("verify(rawBody, header, { secrets, tolerance, now }): options must be an object");
+  }
+  const bytes = bodyBytes(rawBody);
+  const secrets = secretList(opts.secrets);
+  const tolerance = toleranceSeconds(opts.tolerance);
+  const now = nowSeconds(opts.now);
+  const value = headerString(header);
+
+  if (value === undefined || value === null || value.trim() === "") {
+    throw new SignatureError("missing", `webhook signature missing: no ${SIGNATURE_HEADER} header`);
+  }
+
+  const { t, signatures } = parseHeader(value);
+  if (t === null || !/^[0-9]+$/.test(t) || signatures.length === 0) {
+    throw new SignatureError(
+      "malformed",
+      `webhook signature malformed: ${SIGNATURE_HEADER} needs t=<unix seconds> and at least one v1=<hex>`
+    );
+  }
+
+  const age = now - Number(t);
+  if (Math.abs(age) > tolerance) {
+    const when = age > 0 ? `${age} seconds old` : `${-age} seconds in the future`;
+    throw new SignatureError(
+      "stale",
+      `webhook signature stale: its timestamp is ${when} (tolerance ${tolerance} seconds)`
+    );
+  }
+
+  let matched = false;
+  for (const secret of secrets) {
+    const expected = crypto.createHmac("sha256", secret).update(`${t}.`, "utf8").update(bytes).digest("hex");
+    for (const candidate of signatures) {
+      if (constantTimeEqual(expected, candidate)) matched = true;
+    }
+  }
+  if (!matched) {
+    throw new SignatureError("mismatch", "webhook signature mismatch: no v1 matches any of the secrets");
+  }
+
+  return parse(bytes);
+}
+
+module.exports = {
+  VERSION,
+  SIGNATURE_HEADER,
+  DEFAULT_TOLERANCE,
+  REASONS,
+  SignatureError,
+  verify,
+  parse,
+  Event,
+  RequestEvent,
+  WorkflowRunEvent,
+  NotificationEvent,
+  ConnectionEvent,
+  NameIndexEvent,
+  UnknownEvent,
+};

package/index.mjs

@@ -0,0 +1,20 @@
+import qubesync from "./index.js";
+
+export const {
+  VERSION,
+  SIGNATURE_HEADER,
+  DEFAULT_TOLERANCE,
+  REASONS,
+  SignatureError,
+  verify,
+  parse,
+  Event,
+  RequestEvent,
+  WorkflowRunEvent,
+  NotificationEvent,
+  ConnectionEvent,
+  NameIndexEvent,
+  UnknownEvent,
+} = qubesync;
+
+export default qubesync;

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "qubesync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Verify and parse QuBe Sync webhooks (QuickBooks Desktop through qubesync.com).",
+  "license": "MIT",
+  "author": "QuBe Sync",
+  "homepage": "https://docs.qubesync.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qubeintegrations/qube_sync_node.git"
+  },
+  "bugs": "https://github.com/qubeintegrations/qube_sync_node/issues",
+  "keywords": [
+    "qubesync",
+    "quickbooks",
+    "webhooks",
+    "hmac"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.17"
+  },
+  "scripts": {
+    "test": "node --test test/webhooks.test.js test/esm.test.mjs",
+    "test:types": "npx -y -p typescript@5.6.3 tsc --noEmit --strict --module node16 --moduleResolution node16 --target es2020 test/types.ts"
+  }
+}