@ciromaciel/contract 1.0.4 → 1.1.0

package/README.md

@@ -92,6 +92,23 @@ the prefix, the slugs and the wording of the notice; the cache, the fail-open,
 the product-prefix check and the choice between `PLAN_LIMIT` and
 `SUBSCRIPTION_REQUIRED` are the same reasoning everywhere.
 
+### `@ciromaciel/contract/webhooks`
+
+```js
+import { webhookHeaders, verifyWebhook, generateSigningSecret } from '@ciromaciel/contract/webhooks'
+
+const headers = await webhookHeaders(secret, { id: event.id, body }) // x-ccm-id, x-ccm-timestamp, x-ccm-signature
+const result = await verifyWebhook([secret, previousSecret], { id, timestamp, signature, body })
+```
+
+One protocol for every webhook of the stack: Standard Webhooks with the `x-ccm`
+prefix. The signature is `v1,<base64 HMAC-SHA256 of "id.timestamp.body">`, the
+key is the base64 after `whsec_`, and a timestamp more than five minutes off is
+refused. `verifyWebhook` takes several secrets so a rotation has a grace period,
+and answers with a reason (`stale_timestamp`, `bad_signature`, …) instead of a
+bare boolean. Also exports `signWebhook`, `secretPrefixOf` and
+`SIGNATURE_TOLERANCE_SECONDS`.
+
 ## Links
 
 - [Website](https://ciromaciel.click)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ciromaciel/contract",
-    "version": "1.0.4",
+    "version": "1.1.0",
     "license": "MIT",
     "type": "module",
     "description": "A single response envelope, a closed catalogue of error codes, and helpers that make answering outside it impossible.",
@@ -13,7 +13,8 @@
         ".": "./src/index.js",
         "./codes": "./src/codes.js",
         "./schemas": "./src/schemas.js",
-        "./plan": "./src/plan/index.js"
+        "./plan": "./src/plan/index.js",
+        "./webhooks": "./src/webhooks.js"
     },
     "scripts": {
         "test": "bun test tests/"

package/src/plan/notice.js

@@ -38,11 +38,13 @@ export async function getPlanNotice(gate, cfg, ownerId, copy = {}, current = nul
      * NO PLAN IS NOT A PROBLEM TO REPORT. Since the free floor became one
      * resource (2026-09-17), an owner with no plan is simply on the free tier,
      * and telling them "your subscription is not active" reads as a billing
-     * failure they never had. The notice speaks only when the free tier is
-     * actually full — and it can only know that from `current`, so without it
-     * there is no notice: the refusal on creation already says what to do.
+     * failure they never had. Using what the free tier gives — even all of it —
+     * is not a problem either: the refusal on the next creation already offers
+     * the upgrade at the right moment. The notice speaks only when the owner has
+     * MORE than the free tier covers (a lapsed plan left resources behind), and
+     * it can only know that from `current` — without it there is no notice.
      */
-    if (typeof current !== 'number' || limit === null || current < limit) {
+    if (typeof current !== 'number' || limit === null || current <= limit) {
         return { state: 'free', plan: ent.plan, limit, message: null }
     }
     const product = copy.product || 'este produto'
@@ -52,7 +54,7 @@ export async function getPlanNotice(gate, cfg, ownerId, copy = {}, current = nul
         state: 'none',
         plan: ent.plan,
         limit,
-        message: `O plano gratuito do ${product} chegou ao limite. ${keeps} — ${frozen}. Assine para criar mais.`,
+        message: `O plano gratuito do ${product} inclui ${limit} e você tem ${current}. ${keeps} — ${frozen}. Assine para voltar a criar.`,
     }
 }
 

package/src/webhooks.js

@@ -0,0 +1,119 @@
+// ============================================================================
+// @ciromaciel/contract/webhooks — one protocol for every webhook of the stack
+// ============================================================================
+//
+//     import { webhookHeaders, verifyWebhook } from '@ciromaciel/contract/webhooks'
+//
+// Standard Webhooks (the scheme OpenAI and Anthropic use) with our `x-ccm`
+// prefix. Three headers travel with the body:
+//
+//     x-ccm-id:        the event's own id (resending it is a no-op)
+//     x-ccm-timestamp: unix seconds; more than 5 minutes off is refused
+//     x-ccm-signature: `v1,<base64 HMAC-SHA256 of "id.timestamp.body">`,
+//                      several separated by spaces while a secret rotates
+//
+// The HMAC key is the secret after `whsec_`, base64-decoded, exactly as the
+// Standard Webhooks libraries do, so any of them signs for us once the header
+// names are ours. The id and the timestamp are inside the signed string: a
+// captured request cannot be replayed with a fresh timestamp or passed off as
+// another event.
+//
+// WHY IT LIVES HERE. People wrote it first, to VERIFY what its sources send.
+// Videos is the first product that EMITS in this protocol, twice (to People
+// and to a customer's own endpoint), and Auth, Hoster and Payments will emit
+// when they gain webhooks. One file, or four copies that drift — the plan gate
+// already paid for that lesson.
+//
+// IT RUNS ON BOTH RUNTIMES: only Web Crypto, TextEncoder and btoa/atob.
+
+/** How far a signature's timestamp may drift from now, in seconds. */
+export const SIGNATURE_TOLERANCE_SECONDS = 300
+
+const encoder = new TextEncoder()
+const toBase64 = bytes => btoa(String.fromCharCode(...new Uint8Array(bytes)))
+const fromBase64 = value => Uint8Array.from(atob(value), c => c.charCodeAt(0))
+
+/**
+ * A new signing secret: `whsec_` and 32 random bytes in base64, the Standard
+ * Webhooks shape. Whoever finds it in a config knows at a glance what it is.
+ */
+export function generateSigningSecret() {
+    return `whsec_${toBase64(crypto.getRandomValues(new Uint8Array(32)))}`
+}
+
+/** The part of a secret that may be shown again: enough to recognise it. */
+export const secretPrefixOf = secret => String(secret).slice(0, 12)
+
+/**
+ * The HMAC key of a secret: the base64 after `whsec_`. A secret that is not
+ * base64 (hex from before the switch is valid base64 too) falls back to its
+ * raw bytes, so both sides still derive the same key.
+ */
+function keyBytes(secret) {
+    try {
+        return fromBase64(String(secret).replace(/^whsec_/, ''))
+    } catch {
+        return encoder.encode(String(secret))
+    }
+}
+
+async function hmacBase64(secret, payload) {
+    const key = await crypto.subtle.importKey('raw', keyBytes(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+    return toBase64(await crypto.subtle.sign('HMAC', key, encoder.encode(payload)))
+}
+
+/** The `x-ccm-signature` value for one delivery. */
+export async function signWebhook(secret, { id, timestamp, body }) {
+    return `v1,${await hmacBase64(secret, `${id}.${timestamp}.${body}`)}`
+}
+
+/**
+ * The three headers of one delivery, ready to send.
+ *
+ * @param {string} secret `whsec_…`
+ * @param {{id: string, body: string, timestamp?: number}} delivery
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function webhookHeaders(secret, { id, body, timestamp = Math.floor(Date.now() / 1000) }) {
+    return { 'x-ccm-id': String(id), 'x-ccm-timestamp': String(timestamp), 'x-ccm-signature': await signWebhook(secret, { id, timestamp, body }) }
+}
+
+/** Compares without leaking, through timing, how many leading characters matched. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length) return false
+    let diff = 0
+    for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+    return diff === 0
+}
+
+/**
+ * Is this body really from a holder of one of `secrets`? More than one while a
+ * rotation's grace lasts: the new secret and the one it replaced.
+ *
+ * Returns a reason instead of a boolean so the refusal can say what to fix;
+ * the reasons never echo the expected signature.
+ *
+ * @param {string[]} secrets
+ * @param {{id: string|null, timestamp: string|null, signature: string|null, body: string}} delivery
+ * @param {number} [now] unix seconds
+ * @returns {Promise<{ok: true} | {ok: false, reason: 'missing_headers'|'malformed_timestamp'|'stale_timestamp'|'malformed_signature'|'bad_signature'}>}
+ */
+export async function verifyWebhook(secrets, { id, timestamp, signature, body }, now = Math.floor(Date.now() / 1000)) {
+    if (!id || !timestamp || !signature) return { ok: false, reason: 'missing_headers' }
+    const seconds = Number(timestamp)
+    if (!/^\d+$/.test(String(timestamp)) || !Number.isFinite(seconds)) return { ok: false, reason: 'malformed_timestamp' }
+    if (Math.abs(now - seconds) > SIGNATURE_TOLERANCE_SECONDS) return { ok: false, reason: 'stale_timestamp' }
+
+    const offered = String(signature)
+        .split(' ')
+        .map(part => part.trim())
+        .filter(part => part.startsWith('v1,'))
+        .map(part => part.slice(3))
+    if (!offered.length) return { ok: false, reason: 'malformed_signature' }
+
+    for (const secret of secrets) {
+        const expected = await hmacBase64(secret, `${id}.${seconds}.${body}`)
+        if (offered.some(value => timingSafeEqual(expected, value))) return { ok: true }
+    }
+    return { ok: false, reason: 'bad_signature' }
+}