@ciromaciel/contract 1.0.5 → 1.2.0

package/README.md

@@ -13,7 +13,8 @@ described below.
 bun add @ciromaciel/contract
 ```
 
-`zod` is an **optional** peer, needed only by the `/schemas` entrypoint.
+`zod` is an **optional** peer, needed only by the `/schemas` entrypoint, and
+`jose` only by `/token`.
 
 ## Quick start
 
@@ -92,6 +93,46 @@ 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`.
+
+### `@ciromaciel/contract/token`
+
+```js
+import { createTokenVerifier } from '@ciromaciel/contract/token'
+
+const tokens = createTokenVerifier({ authUrl: 'https://auth.worker.myinfrastructure.click' })
+
+await tokens.verifySession(bearer) // REST routes
+await tokens.verifyAccessToken(bearer, { audience: 'https://hoster.worker.myinfrastructure.click/mcp' }) // MCP server
+```
+
+The Auth signs sessions and OAuth access tokens with the same key and issuer;
+only the claims tell them apart. `verifySession` accepts a person's session and
+refuses an access token (`access_token_not_accepted`): a token consented for one
+resource and one scope must never act as the whole account on a REST route.
+`verifyAccessToken` accepts only an access token whose `aud` is this server
+(`wrong_audience` otherwise, RFC 8707) and returns its `scopes`.
+
+Both return `{ ok: true, subject, email, name, scopes, claims }` or
+`{ ok: false, reason }`, never throw on a bad credential, and accept RS256 with
+the `riligar-auth` issuer only. `jose` (5 or 6) is an **optional** peer, needed
+only by this entrypoint.
+
 ## Links
 
 - [Website](https://ciromaciel.click)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ciromaciel/contract",
-    "version": "1.0.5",
+    "version": "1.2.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,21 +13,28 @@
         ".": "./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",
+        "./token": "./src/token.js"
     },
     "scripts": {
         "test": "bun test tests/"
     },
     "peerDependencies": {
-        "zod": "^4.0.0"
+        "zod": "^4.0.0",
+        "jose": "^5.0.0 || ^6.0.0"
     },
     "peerDependenciesMeta": {
         "zod": {
             "optional": true
+        },
+        "jose": {
+            "optional": true
         }
     },
     "devDependencies": {
-        "zod": "^4.5.4"
+        "zod": "^4.5.4",
+        "jose": "^6.2.10"
     },
     "publishConfig": {
         "access": "public"

package/src/token.js

@@ -0,0 +1,146 @@
+// ============================================================================
+// @ciromaciel/contract/token — one way to read an Infrastructure Auth token
+// ============================================================================
+//
+//     import { createTokenVerifier } from '@ciromaciel/contract/token'
+//
+//     const tokens = createTokenVerifier({ authUrl: 'https://auth.worker.myinfrastructure.click' })
+//
+//     // REST routes: a person's session, and nothing else.
+//     const session = await tokens.verifySession(bearer)
+//
+//     // The MCP server: an OAuth access token issued for THIS resource.
+//     const access = await tokens.verifyAccessToken(bearer, { audience: 'https://hoster.worker.myinfrastructure.click/mcp' })
+//
+// The Auth signs two kinds of token with the same key and the same issuer:
+//
+//   session        `{ sub, email, name, role }`, no `aud`. Held by the person
+//                  (dashboard, CLI login, the e-mailed code flow).
+//   access token   `{ sub, aud, scope, client_id, token_type: 'access_token' }`.
+//                  Held by a third-party OAuth client, limited to one resource
+//                  (`aud`, RFC 8707) and to what the person consented to
+//                  (`scope`).
+//
+// Signature and issuer cannot tell them apart; only the claims can. Each
+// product used to verify tokens with its own copy of this code — twelve
+// copies — and the REST ones checked signature and issuer only. So an access
+// token consented as "read" for one product's MCP server worked as a full
+// session on the REST API of every product. This module is the one place that
+// knows the difference, so it can only be right or wrong once.
+//
+// Results are values, never exceptions: `{ ok: true, ... }` or
+// `{ ok: false, reason }`. A wrong credential is an answer the caller turns
+// into 401 or 403, not a failure. `reason` is for logs and for choosing the
+// status; the text shown to the caller stays generic.
+
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+
+/**
+ * The `iss` the Auth writes into every token. It is a fixed name, not the
+ * Auth URL: passing the URL makes every verification fail.
+ */
+export const AUTH_TOKEN_ISSUER = 'riligar-auth'
+
+/** The only algorithm accepted. HS256 would let anyone holding a shared secret forge tokens. */
+const ALGORITHMS = ['RS256']
+
+/** Why a token was refused. */
+export const TOKEN_REFUSAL = {
+    /** Bad signature, unknown key, expired, wrong issuer or no subject. */
+    INVALID: 'invalid_token',
+    /** An OAuth access token presented where only a session is accepted. */
+    ACCESS_TOKEN_NOT_ACCEPTED: 'access_token_not_accepted',
+    /** An access token issued for another resource. */
+    WRONG_AUDIENCE: 'wrong_audience',
+}
+
+// One remote key set per JWKS URL, for the life of the process (or isolate).
+// `jose` caches the keys and refetches on an unknown `kid`, which is what keeps
+// a key rotation from turning into a wave of 401s.
+const remoteKeySets = new Map()
+
+function remoteKeySet(authUrl) {
+    const url = `${String(authUrl).replace(/\/+$/, '')}/.well-known/jwks.json`
+    if (!remoteKeySets.has(url)) remoteKeySets.set(url, createRemoteJWKSet(new URL(url)))
+    return remoteKeySets.get(url)
+}
+
+const audiencesOf = claims => (Array.isArray(claims.aud) ? claims.aud : [claims.aud]).filter(Boolean)
+
+/**
+ * Is this an OAuth access token?
+ *
+ * Either mark is enough: the Auth writes both, and a token with an audience
+ * was issued for one resource, whatever else it says.
+ */
+export const isAccessToken = claims => audiencesOf(claims).length > 0 || claims.token_type === 'access_token'
+
+const scopesOf = claims =>
+    String(claims.scope ?? '')
+        .split(' ')
+        .filter(Boolean)
+
+function identity(claims) {
+    return { subject: claims.sub, email: claims.email, name: claims.name, scopes: scopesOf(claims), claims }
+}
+
+/**
+ * Builds the verifier for one Auth.
+ *
+ * @param {object} options
+ * @param {string} [options.authUrl] The Auth base URL; its JWKS is fetched from `/.well-known/jwks.json`.
+ * @param {string} [options.issuer] The expected `iss`. Defaults to {@link AUTH_TOKEN_ISSUER}.
+ * @param {Function} [options.keySet] A `jose` key set to use instead of the remote JWKS (tests).
+ */
+export function createTokenVerifier({ authUrl, issuer = AUTH_TOKEN_ISSUER, keySet } = {}) {
+    if (!keySet && !authUrl) throw new Error('createTokenVerifier: authUrl is required')
+
+    async function verified(token) {
+        if (!token || typeof token !== 'string') return null
+        try {
+            const { payload } = await jwtVerify(token, keySet ?? remoteKeySet(authUrl), { algorithms: ALGORITHMS, issuer })
+            return payload.sub ? payload : null
+        } catch {
+            return null
+        }
+    }
+
+    return {
+        /**
+         * A person's session — what REST routes accept.
+         *
+         * An OAuth access token is refused here even though its signature is
+         * valid: it was consented for one resource and one scope, and a REST
+         * route would treat it as the person's whole account.
+         *
+         * @returns {Promise<{ok: true, subject: string, email?: string, name?: string, scopes: string[], claims: object} | {ok: false, reason: string}>}
+         */
+        async verifySession(token) {
+            const claims = await verified(token)
+            if (!claims) return { ok: false, reason: TOKEN_REFUSAL.INVALID }
+            if (isAccessToken(claims)) return { ok: false, reason: TOKEN_REFUSAL.ACCESS_TOKEN_NOT_ACCEPTED }
+            return { ok: true, ...identity(claims) }
+        },
+
+        /**
+         * An OAuth access token issued for `audience` — what an MCP server accepts.
+         *
+         * `audience` is the resource this server answers as (RFC 8707); a list
+         * is accepted when one server answers under more than one identifier.
+         * A session has no audience, so it is refused here as `wrong_audience`.
+         *
+         * @param {string} token
+         * @param {{ audience: string | string[] }} options
+         * @returns {Promise<{ok: true, subject: string, email?: string, name?: string, scopes: string[], claims: object} | {ok: false, reason: string}>}
+         */
+        async verifyAccessToken(token, { audience } = {}) {
+            const expected = (Array.isArray(audience) ? audience : [audience]).filter(Boolean)
+            if (expected.length === 0) throw new Error('verifyAccessToken: audience is required')
+
+            const claims = await verified(token)
+            if (!claims) return { ok: false, reason: TOKEN_REFUSAL.INVALID }
+            if (!audiencesOf(claims).some(aud => expected.includes(aud))) return { ok: false, reason: TOKEN_REFUSAL.WRONG_AUDIENCE }
+            return { ok: true, ...identity(claims) }
+        },
+    }
+}

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' }
+}