@cuvo-health-us/api 0.1.0-next.0 → 0.1.0-next.1

package/README.md

@@ -212,6 +212,20 @@ During the 24 hour grace after a secret rotation a delivery carries two signatur
 `verifySignature` accepts a match against either, so you can move to the new secret whenever you
 like inside the window.
 
+Testing that handler needs a signature of your own, and so does `cuvo webhooks listen`, which
+mirrors the event stream to a local URL and re-signs what it forwards. `signWebhook` is that half:
+
+```ts
+import { signWebhook } from "@cuvo-health-us/api";
+
+const rawBody = JSON.stringify(event);
+const signatureHeader = signWebhook({ rawBody, secret: process.env.CUVO_WEBHOOK_SECRET! });
+```
+
+Sign the exact string you send, never the object, because the digest covers the bytes. Cuvo's own
+deliveries are signed by the platform, so a header this produces proves only that whoever made it
+held the secret.
+
 `parseEvent` returns the event keyed by its `type`, so the branch above knows `event.data` is a
 `Case` and `expandEvent` answers with one. An event read from `GET /v1/events` arrives as the
 contract's single `Event` shape instead, because that is what one schema for the whole catalog
@@ -257,8 +271,10 @@ The package publishes from `dist`, under the `next` tag, at the prerelease versi
 
 ```sh
 pnpm pack                 # inspect the tarball first
-npm publish --tag next    # requires an npm login with access to the @cuvo scope
+npm publish --tag next    # needs an npm login in the cuvo-health-us organization
 ```
 
-Nothing goes out under `latest` until the contract is stable and the founder says so: a stable tag
-is what a partner's `pnpm add @cuvo-health-us/api` resolves to by default.
+`next` is the tag every prerelease goes out under. The registry also pointed `latest` at the
+first publish, because npm sets `latest` when a package has no tags at all, so `pnpm add
+@cuvo-health-us/api` without a tag resolves to the prerelease today. `latest` moves to the first
+stable release when the contract is stable and the founder says so.

package/dist/index.d.ts

@@ -9,4 +9,4 @@ export { CuvoApiError, type Problem, type ProblemIssue, unwrap } from "./errors.
 export { type CuvoEvent, type CuvoEventOf, type CuvoEventResourceOf, type CuvoEventResourceType, type CuvoEventResourceTypeOf, type CuvoEventType, type CuvoTypedEvent, type ExpandedResource, expandEvent, typedEvent, } from "./events.js";
 export type { components, operations, paths } from "./generated/v1.js";
 export { type ListPage, paginate } from "./pagination.js";
-export { DEFAULT_TOLERANCE_SECONDS, parseEvent, type VerifySignatureOptions, verifySignature, } from "./webhooks.js";
+export { DEFAULT_TOLERANCE_SECONDS, parseEvent, type SignWebhookOptions, signWebhook, type VerifySignatureOptions, verifySignature, } from "./webhooks.js";

package/dist/index.js

@@ -8,4 +8,4 @@ export { createCuvoClient, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, } from "./clie
 export { CuvoApiError, unwrap } from "./errors.js";
 export { expandEvent, typedEvent, } from "./events.js";
 export { paginate } from "./pagination.js";
-export { DEFAULT_TOLERANCE_SECONDS, parseEvent, verifySignature, } from "./webhooks.js";
+export { DEFAULT_TOLERANCE_SECONDS, parseEvent, signWebhook, verifySignature, } from "./webhooks.js";

package/dist/webhooks.d.ts

@@ -1,6 +1,7 @@
 import { type CuvoTypedEvent } from "./events.js";
 /**
- * Webhook verification, the receiving half of the recipe in api/lib/webhooks/sign.ts:
+ * Webhook signatures: the receiving half of the recipe in api/lib/webhooks/sign.ts, plus a
+ * signer for the code that stands in for the sender.
  *
  *   Cuvo-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, `${t}.${rawBody}`)>
  *
@@ -32,6 +33,26 @@ export interface VerifySignatureOptions {
  * when it is false, and never act on an unverified body.
  */
 export declare function verifySignature(options: VerifySignatureOptions): boolean;
+/** What `signWebhook` needs to produce a `Cuvo-Signature` header. */
+export interface SignWebhookOptions {
+    /** The bytes that will be sent, exactly as they will be sent. */
+    rawBody: string;
+    /** The signing secret, `whsec_…`. */
+    secret: string;
+    /** Unix SECONDS. Defaults to now; pass it to make a test deterministic. */
+    timestamp?: number;
+}
+/**
+ * The sending half, for the code that stands in for Cuvo.
+ *
+ * Two callers, neither of them a delivery: a test that exercises its own handler against a body
+ * it made up, and `cuvo webhooks listen`, which re-signs the events it mirrors to a local handler
+ * with a session secret of its own. Cuvo's own deliveries are signed by the platform, never by
+ * this package, and a signature this makes is only ever as trustworthy as the secret behind it.
+ *
+ * One `v1=` value, because only a rotation puts two on the wire and nothing here rotates.
+ */
+export declare function signWebhook(options: SignWebhookOptions): string;
 /**
  * Parse a verified delivery body into an event keyed by its `type`, so a handler branching on
  * `event.type` gets the resource that type carries without a cast.

package/dist/webhooks.js

@@ -1,7 +1,8 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { typedEvent } from "./events.js";
 /**
- * Webhook verification, the receiving half of the recipe in api/lib/webhooks/sign.ts:
+ * Webhook signatures: the receiving half of the recipe in api/lib/webhooks/sign.ts, plus a
+ * signer for the code that stands in for the sender.
  *
  *   Cuvo-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, `${t}.${rawBody}`)>
  *
@@ -58,6 +59,22 @@ export function verifySignature(options) {
     // nothing to leak by the number of comparisons, only by their duration.
     return candidates.some((candidate) => matches(candidate, expected));
 }
+/**
+ * The sending half, for the code that stands in for Cuvo.
+ *
+ * Two callers, neither of them a delivery: a test that exercises its own handler against a body
+ * it made up, and `cuvo webhooks listen`, which re-signs the events it mirrors to a local handler
+ * with a session secret of its own. Cuvo's own deliveries are signed by the platform, never by
+ * this package, and a signature this makes is only ever as trustworthy as the secret behind it.
+ *
+ * One `v1=` value, because only a rotation puts two on the wire and nothing here rotates.
+ */
+export function signWebhook(options) {
+    const { rawBody, secret, timestamp = Math.floor(Date.now() / 1000) } = options;
+    const seconds = Math.floor(timestamp);
+    const signature = createHmac("sha256", secret).update(`${seconds}.${rawBody}`).digest("hex");
+    return `t=${seconds},v1=${signature}`;
+}
 /**
  * Parse a verified delivery body into an event keyed by its `type`, so a handler branching on
  * `event.type` gets the resource that type carries without a cast.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuvo-health-us/api",
-  "version": "0.1.0-next.0",
+  "version": "0.1.0-next.1",
   "type": "module",
   "description": "TypeScript client for the Cuvo Integrations API, generated from the v1 contract.",
   "types": "./dist/index.d.ts",