@obelism/content 0.5.0 → 0.7.0

package/dist/standardWebhooks-ew5mhpac.mjs

@@ -0,0 +1,41 @@
+// Standard Webhooks (https://www.standardwebhooks.com/), the scheme the CMS
+// signs both webhooks and prompt requests with: HMAC-SHA256 over
+// `{id}.{timestamp}.{body}`, keyed with the base64 part of the `whsec_…`
+// secret, in `webhook-signature` as `v1,<base64>` (several, space-separated,
+// while a secret is rotated).
+const SECRET_PREFIX = 'whsec_';
+// Seconds a request's timestamp may be off, against replays.
+const DEFAULT_TOLERANCE = 5 * 60;
+const base64ToBytes = (value)=>Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
+// Checks a message's signature and timestamp; calls `fail` (which throws the
+// caller's own error) when it isn't from the CMS.
+const verifySignature = async ({ body, id, timestamp, signatures }, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now(), fail })=>{
+    if (!id || !timestamp || !signatures) fail('Missing signature headers');
+    const seconds = Number(timestamp);
+    if (!Number.isFinite(seconds) || Math.abs(now / 1000 - seconds) > tolerance) {
+        fail('Timestamp outside the tolerance');
+    }
+    const key = await crypto.subtle.importKey('raw', base64ToBytes(secret.slice(SECRET_PREFIX.length)), {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'verify'
+    ]);
+    const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+    let valid = false;
+    for (const signature of signatures.split(' ')){
+        const [version, value] = signature.split(',');
+        if (version !== 'v1' || !value) continue;
+        let bytes;
+        try {
+            bytes = base64ToBytes(value);
+        } catch  {
+            continue;
+        }
+        // crypto.subtle.verify compares in constant time.
+        if (await crypto.subtle.verify('HMAC', key, bytes, signed)) valid = true;
+    }
+    if (!valid) fail('Invalid signature');
+};
+
+export { DEFAULT_TOLERANCE as D, SECRET_PREFIX as S, verifySignature as v };

package/dist/standardWebhooks-kh5dc0ff.js

@@ -0,0 +1,43 @@
+// Standard Webhooks (https://www.standardwebhooks.com/), the scheme the CMS
+// signs both webhooks and prompt requests with: HMAC-SHA256 over
+// `{id}.{timestamp}.{body}`, keyed with the base64 part of the `whsec_…`
+// secret, in `webhook-signature` as `v1,<base64>` (several, space-separated,
+// while a secret is rotated).
+const SECRET_PREFIX = 'whsec_';
+// Seconds a request's timestamp may be off, against replays.
+const DEFAULT_TOLERANCE = 5 * 60;
+const base64ToBytes = (value)=>Uint8Array.from(atob(value), (char)=>char.charCodeAt(0));
+// Checks a message's signature and timestamp; calls `fail` (which throws the
+// caller's own error) when it isn't from the CMS.
+const verifySignature = async ({ body, id, timestamp, signatures }, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now(), fail })=>{
+    if (!id || !timestamp || !signatures) fail('Missing signature headers');
+    const seconds = Number(timestamp);
+    if (!Number.isFinite(seconds) || Math.abs(now / 1000 - seconds) > tolerance) {
+        fail('Timestamp outside the tolerance');
+    }
+    const key = await crypto.subtle.importKey('raw', base64ToBytes(secret.slice(SECRET_PREFIX.length)), {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'verify'
+    ]);
+    const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
+    let valid = false;
+    for (const signature of signatures.split(' ')){
+        const [version, value] = signature.split(',');
+        if (version !== 'v1' || !value) continue;
+        let bytes;
+        try {
+            bytes = base64ToBytes(value);
+        } catch  {
+            continue;
+        }
+        // crypto.subtle.verify compares in constant time.
+        if (await crypto.subtle.verify('HMAC', key, bytes, signed)) valid = true;
+    }
+    if (!valid) fail('Invalid signature');
+};
+
+exports.DEFAULT_TOLERANCE = DEFAULT_TOLERANCE;
+exports.SECRET_PREFIX = SECRET_PREFIX;
+exports.verifySignature = verifySignature;

package/dist/webhooks.d.mts

@@ -0,0 +1,72 @@
+import { Environment } from './index.mjs';
+
+type WebhookEntry = {
+    id: string;
+    contentType: string;
+    name: string;
+    path: string | null;
+};
+type WebhookEventOf<TType extends string, TData> = {
+    type: TType;
+    timestamp: string;
+    space: string;
+    environment: Environment;
+    data: TData;
+};
+type EntryPublishedEvent = WebhookEventOf<'entry.published', {
+    entry: WebhookEntry;
+}>;
+type EntryUnpublishedEvent = WebhookEventOf<'entry.unpublished', {
+    entry: WebhookEntry;
+}>;
+type EntryDeletedEvent = WebhookEventOf<'entry.deleted', {
+    entry: WebhookEntry;
+}>;
+type EntryMovedEvent = WebhookEventOf<'entry.moved', {
+    entry: WebhookEntry;
+    previousPath: string | null;
+}>;
+type AssetUpdatedEvent = WebhookEventOf<'asset.updated', {
+    asset: {
+        id: string;
+        filename: string;
+    };
+    entries: WebhookEntry[];
+}>;
+type ModelChangedEvent = WebhookEventOf<'model.changed', {
+    contentTypes: {
+        apiId: string;
+        action: 'create' | 'update' | 'delete';
+    }[];
+}>;
+type LocalesChangedEvent = WebhookEventOf<'locales.changed', {
+    defaultLocale: string;
+    locales: string[];
+}>;
+type WebhookTestEvent = WebhookEventOf<'webhook.test', Record<string, never>>;
+type WebhookEvent = EntryPublishedEvent | EntryUnpublishedEvent | EntryDeletedEvent | EntryMovedEvent | AssetUpdatedEvent | ModelChangedEvent | LocalesChangedEvent | WebhookTestEvent;
+type WebhookEventType = WebhookEvent['type'];
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type WebhookMessage = {
+    body: string;
+    headers: Headers | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+};
+type VerifyWebhookOptions = {
+    tolerance?: number | undefined;
+    now?: number;
+};
+declare const verifyWebhook: (request: Request | WebhookMessage, secret: string, { tolerance, now, }?: VerifyWebhookOptions) => Promise<WebhookEvent>;
+type WebhookHandlerOptions = {
+    secret: string;
+    onEvent: (event: WebhookEvent, meta: {
+        id: string;
+    }) => unknown;
+    tolerance?: number | undefined;
+};
+declare const createWebhookHandler: ({ secret, onEvent, tolerance }: WebhookHandlerOptions) => (request: Request) => Promise<Response>;
+
+export { WebhookVerificationError, createWebhookHandler, verifyWebhook };
+export type { AssetUpdatedEvent, EntryDeletedEvent, EntryMovedEvent, EntryPublishedEvent, EntryUnpublishedEvent, LocalesChangedEvent, ModelChangedEvent, VerifyWebhookOptions, WebhookEntry, WebhookEvent, WebhookEventType, WebhookHandlerOptions, WebhookMessage, WebhookTestEvent };
+//# sourceMappingURL=webhooks.d.mts.map

package/dist/webhooks.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.mts","sources":["../src/webhooks.ts"],"mappings":";;AACA,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB;AACA;AACA;AACA,iBAAiB,WAAW;AAC5B;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC,WAAW,YAAY;AACvB;AACA,KAAK,qBAAqB,GAAG,cAAc;AAC3C,WAAW,YAAY;AACvB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC,WAAW,YAAY;AACvB;AACA,KAAK,eAAe,GAAG,cAAc;AACrC,WAAW,YAAY;AACvB;AACA;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA,aAAa,YAAY;AACzB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC;AACA;AACA;AACA,KAAK,gBAAgB,GAAG,cAAc,iBAAiB,MAAM;AAC7D,KAAK,YAAY,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB;AACtL,KAAK,gBAAgB,GAAG,YAAY;AACpC,cAAc,wBAAwB,SAAS,KAAK;AACpD;AACA;AACA,KAAK,cAAc;AACnB;AACA,aAAa,OAAO,GAAG,MAAM,0CAA0C,QAAQ;AAC/E;AACA,KAAK,oBAAoB;AACzB;AACA;AACA;AACA,cAAc,aAAa,YAAY,OAAO,GAAG,cAAc,wCAAwC,oBAAoB,KAAK,OAAO,CAAC,YAAY;AACpJ,KAAK,qBAAqB;AAC1B;AACA,qBAAqB,YAAY;AACjC;AACA;AACA;AACA;AACA,cAAc,oBAAoB,mCAAmC,qBAAqB,eAAe,OAAO,KAAK,OAAO,CAAC,QAAQ","names":[]}

package/dist/webhooks.d.ts

@@ -0,0 +1,72 @@
+import { Environment } from './index.js';
+
+type WebhookEntry = {
+    id: string;
+    contentType: string;
+    name: string;
+    path: string | null;
+};
+type WebhookEventOf<TType extends string, TData> = {
+    type: TType;
+    timestamp: string;
+    space: string;
+    environment: Environment;
+    data: TData;
+};
+type EntryPublishedEvent = WebhookEventOf<'entry.published', {
+    entry: WebhookEntry;
+}>;
+type EntryUnpublishedEvent = WebhookEventOf<'entry.unpublished', {
+    entry: WebhookEntry;
+}>;
+type EntryDeletedEvent = WebhookEventOf<'entry.deleted', {
+    entry: WebhookEntry;
+}>;
+type EntryMovedEvent = WebhookEventOf<'entry.moved', {
+    entry: WebhookEntry;
+    previousPath: string | null;
+}>;
+type AssetUpdatedEvent = WebhookEventOf<'asset.updated', {
+    asset: {
+        id: string;
+        filename: string;
+    };
+    entries: WebhookEntry[];
+}>;
+type ModelChangedEvent = WebhookEventOf<'model.changed', {
+    contentTypes: {
+        apiId: string;
+        action: 'create' | 'update' | 'delete';
+    }[];
+}>;
+type LocalesChangedEvent = WebhookEventOf<'locales.changed', {
+    defaultLocale: string;
+    locales: string[];
+}>;
+type WebhookTestEvent = WebhookEventOf<'webhook.test', Record<string, never>>;
+type WebhookEvent = EntryPublishedEvent | EntryUnpublishedEvent | EntryDeletedEvent | EntryMovedEvent | AssetUpdatedEvent | ModelChangedEvent | LocalesChangedEvent | WebhookTestEvent;
+type WebhookEventType = WebhookEvent['type'];
+declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+type WebhookMessage = {
+    body: string;
+    headers: Headers | Record<string, string | string[] | undefined> | Iterable<[string, string]>;
+};
+type VerifyWebhookOptions = {
+    tolerance?: number | undefined;
+    now?: number;
+};
+declare const verifyWebhook: (request: Request | WebhookMessage, secret: string, { tolerance, now, }?: VerifyWebhookOptions) => Promise<WebhookEvent>;
+type WebhookHandlerOptions = {
+    secret: string;
+    onEvent: (event: WebhookEvent, meta: {
+        id: string;
+    }) => unknown;
+    tolerance?: number | undefined;
+};
+declare const createWebhookHandler: ({ secret, onEvent, tolerance }: WebhookHandlerOptions) => (request: Request) => Promise<Response>;
+
+export { WebhookVerificationError, createWebhookHandler, verifyWebhook };
+export type { AssetUpdatedEvent, EntryDeletedEvent, EntryMovedEvent, EntryPublishedEvent, EntryUnpublishedEvent, LocalesChangedEvent, ModelChangedEvent, VerifyWebhookOptions, WebhookEntry, WebhookEvent, WebhookEventType, WebhookHandlerOptions, WebhookMessage, WebhookTestEvent };
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sources":["../src/webhooks.ts"],"mappings":";;AACA,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB;AACA;AACA;AACA,iBAAiB,WAAW;AAC5B;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC,WAAW,YAAY;AACvB;AACA,KAAK,qBAAqB,GAAG,cAAc;AAC3C,WAAW,YAAY;AACvB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC,WAAW,YAAY;AACvB;AACA,KAAK,eAAe,GAAG,cAAc;AACrC,WAAW,YAAY;AACvB;AACA;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA,aAAa,YAAY;AACzB;AACA,KAAK,iBAAiB,GAAG,cAAc;AACvC;AACA;AACA;AACA;AACA;AACA,KAAK,mBAAmB,GAAG,cAAc;AACzC;AACA;AACA;AACA,KAAK,gBAAgB,GAAG,cAAc,iBAAiB,MAAM;AAC7D,KAAK,YAAY,GAAG,mBAAmB,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,eAAe,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB;AACtL,KAAK,gBAAgB,GAAG,YAAY;AACpC,cAAc,wBAAwB,SAAS,KAAK;AACpD;AACA;AACA,KAAK,cAAc;AACnB;AACA,aAAa,OAAO,GAAG,MAAM,0CAA0C,QAAQ;AAC/E;AACA,KAAK,oBAAoB;AACzB;AACA;AACA;AACA,cAAc,aAAa,YAAY,OAAO,GAAG,cAAc,wCAAwC,oBAAoB,KAAK,OAAO,CAAC,YAAY;AACpJ,KAAK,qBAAqB;AAC1B;AACA,qBAAqB,YAAY;AACjC;AACA;AACA;AACA;AACA,cAAc,oBAAoB,mCAAmC,qBAAqB,eAAe,OAAO,KAAK,OAAO,CAAC,QAAQ","names":[]}

package/dist/webhooks.js

@@ -0,0 +1,110 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var standardWebhooks = require('./standardWebhooks-kh5dc0ff.js');
+
+// Webhooks from Obelism Content (the CMS's docs/guides/webhooks): one signed
+// POST per event (Standard Webhooks), telling your site what the delivery
+// API answers has changed. Verify it and revalidate:
+//
+//   // app/api/revalidate/route.ts
+//   import { revalidatePath } from 'next/cache'
+//   import { createWebhookHandler } from '@obelism/content/webhooks'
+//
+//   export const POST = createWebhookHandler({
+//     secret: process.env.CONTENT_WEBHOOK_SECRET!,
+//     onEvent: (event) => {
+//       if (event.type === 'entry.published' && event.data.entry.path) {
+//         revalidatePath(`/${event.data.entry.path}`)
+//       }
+//     },
+//   })
+class WebhookVerificationError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'WebhookVerificationError';
+    }
+}
+const headerReader = (headers)=>{
+    if (typeof headers.get === 'function') {
+        return (name)=>headers.get(name);
+    }
+    const lower = new Map();
+    const entries = Symbol.iterator in headers ? headers : Object.entries(headers);
+    for (const [name, value] of entries){
+        if (value === undefined) continue;
+        lower.set(name.toLowerCase(), Array.isArray(value) ? value.join(' ') : String(value));
+    }
+    return (name)=>lower.get(name) ?? null;
+};
+// Checks a webhook's signature and timestamp and returns its event. Throws
+// WebhookVerificationError when it isn't from the CMS, or too old.
+const verifyWebhook = async (request, secret, { tolerance = standardWebhooks.DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
+    if (!secret?.startsWith(standardWebhooks.SECRET_PREFIX)) {
+        throw new Error('The webhook secret must be the whsec_… shown when the webhook was added');
+    }
+    // Not `instanceof Request`: frameworks may bring their own Request class.
+    const body = typeof request.body === 'string' ? request.body : await request.text();
+    const header = headerReader(request.headers);
+    await standardWebhooks.verifySignature({
+        body,
+        id: header('webhook-id'),
+        timestamp: header('webhook-timestamp'),
+        signatures: header('webhook-signature')
+    }, secret, {
+        tolerance,
+        now,
+        fail: (message)=>{
+            throw new WebhookVerificationError(message);
+        }
+    });
+    let event;
+    try {
+        event = JSON.parse(body);
+    } catch  {
+        throw new WebhookVerificationError('The body is not JSON');
+    }
+    if (typeof event?.type !== 'string') {
+        throw new WebhookVerificationError('The body is not a webhook event');
+    }
+    return event;
+};
+// A fetch-style handler (Request → Response) for the webhook's URL: Next.js
+// route handlers, Hono, Workers, Bun, Deno. Answers 401 to anything not
+// signed by the CMS, 204 once `onEvent` is done and 500 when it throws, so
+// the delivery is retried.
+const createWebhookHandler = ({ secret, onEvent, tolerance })=>async (request)=>{
+        let event;
+        try {
+            event = await verifyWebhook(request, secret, {
+                tolerance
+            });
+        } catch (error) {
+            if (error instanceof WebhookVerificationError) {
+                return Response.json({
+                    error: error.message
+                }, {
+                    status: 401
+                });
+            }
+            throw error;
+        }
+        try {
+            await onEvent(event, {
+                id: request.headers.get('webhook-id')
+            });
+        } catch (error) {
+            console.error('[@obelism/content webhooks]', error);
+            return Response.json({
+                error: 'Handling the event failed'
+            }, {
+                status: 500
+            });
+        }
+        return new Response(null, {
+            status: 204
+        });
+    };
+
+exports.WebhookVerificationError = WebhookVerificationError;
+exports.createWebhookHandler = createWebhookHandler;
+exports.verifyWebhook = verifyWebhook;

package/dist/webhooks.mjs

@@ -0,0 +1,106 @@
+import { S as SECRET_PREFIX, v as verifySignature, D as DEFAULT_TOLERANCE } from './standardWebhooks-ew5mhpac.mjs';
+
+// Webhooks from Obelism Content (the CMS's docs/guides/webhooks): one signed
+// POST per event (Standard Webhooks), telling your site what the delivery
+// API answers has changed. Verify it and revalidate:
+//
+//   // app/api/revalidate/route.ts
+//   import { revalidatePath } from 'next/cache'
+//   import { createWebhookHandler } from '@obelism/content/webhooks'
+//
+//   export const POST = createWebhookHandler({
+//     secret: process.env.CONTENT_WEBHOOK_SECRET!,
+//     onEvent: (event) => {
+//       if (event.type === 'entry.published' && event.data.entry.path) {
+//         revalidatePath(`/${event.data.entry.path}`)
+//       }
+//     },
+//   })
+class WebhookVerificationError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'WebhookVerificationError';
+    }
+}
+const headerReader = (headers)=>{
+    if (typeof headers.get === 'function') {
+        return (name)=>headers.get(name);
+    }
+    const lower = new Map();
+    const entries = Symbol.iterator in headers ? headers : Object.entries(headers);
+    for (const [name, value] of entries){
+        if (value === undefined) continue;
+        lower.set(name.toLowerCase(), Array.isArray(value) ? value.join(' ') : String(value));
+    }
+    return (name)=>lower.get(name) ?? null;
+};
+// Checks a webhook's signature and timestamp and returns its event. Throws
+// WebhookVerificationError when it isn't from the CMS, or too old.
+const verifyWebhook = async (request, secret, { tolerance = DEFAULT_TOLERANCE, now = Date.now() } = {})=>{
+    if (!secret?.startsWith(SECRET_PREFIX)) {
+        throw new Error('The webhook secret must be the whsec_… shown when the webhook was added');
+    }
+    // Not `instanceof Request`: frameworks may bring their own Request class.
+    const body = typeof request.body === 'string' ? request.body : await request.text();
+    const header = headerReader(request.headers);
+    await verifySignature({
+        body,
+        id: header('webhook-id'),
+        timestamp: header('webhook-timestamp'),
+        signatures: header('webhook-signature')
+    }, secret, {
+        tolerance,
+        now,
+        fail: (message)=>{
+            throw new WebhookVerificationError(message);
+        }
+    });
+    let event;
+    try {
+        event = JSON.parse(body);
+    } catch  {
+        throw new WebhookVerificationError('The body is not JSON');
+    }
+    if (typeof event?.type !== 'string') {
+        throw new WebhookVerificationError('The body is not a webhook event');
+    }
+    return event;
+};
+// A fetch-style handler (Request → Response) for the webhook's URL: Next.js
+// route handlers, Hono, Workers, Bun, Deno. Answers 401 to anything not
+// signed by the CMS, 204 once `onEvent` is done and 500 when it throws, so
+// the delivery is retried.
+const createWebhookHandler = ({ secret, onEvent, tolerance })=>async (request)=>{
+        let event;
+        try {
+            event = await verifyWebhook(request, secret, {
+                tolerance
+            });
+        } catch (error) {
+            if (error instanceof WebhookVerificationError) {
+                return Response.json({
+                    error: error.message
+                }, {
+                    status: 401
+                });
+            }
+            throw error;
+        }
+        try {
+            await onEvent(event, {
+                id: request.headers.get('webhook-id')
+            });
+        } catch (error) {
+            console.error('[@obelism/content webhooks]', error);
+            return Response.json({
+                error: 'Handling the event failed'
+            }, {
+                status: 500
+            });
+        }
+        return new Response(null, {
+            status: 204
+        });
+    };
+
+export { WebhookVerificationError, createWebhookHandler, verifyWebhook };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@obelism/content",
-	"description": "Obelism Content SDK: the delivery API client, the visual editor bridge with prompt editing, editing on your own site, and the content model CLI",
-	"version": "0.5.0",
+	"description": "Obelism Content SDK: the delivery API client, the visual editor bridge with prompt editing, editing on your own site, webhook verification, and the content model CLI",
+	"version": "0.7.0",
 	"keywords": [
 		"cms",
 		"headless-cms",
@@ -62,6 +62,16 @@
 				"types": "./dist/prompt.d.ts",
 				"default": "./dist/prompt.js"
 			}
+		},
+		"./webhooks": {
+			"import": {
+				"types": "./dist/webhooks.d.mts",
+				"default": "./dist/webhooks.mjs"
+			},
+			"require": {
+				"types": "./dist/webhooks.d.ts",
+				"default": "./dist/webhooks.js"
+			}
 		}
 	},
 	"scripts": {