@protobase/server 0.8.2 → 0.10.0

package/dist/webhooks/subscription.d.ts

@@ -0,0 +1,92 @@
+import { Row, TenantValue } from "../types.js";
+import { EventActor, EventOperation } from "@protobase/schema";
+import { Db } from "@protobase/query";
+//#region src/webhooks/subscription.d.ts
+/** What happened, as a receiver gets it in the `data` of an event. Records use field names, as the API shows them. */
+export type EventData = {
+  resource: string;
+  operation: EventOperation;
+  /** The record's key as its URL has it. */
+  key: string;
+  /** Grows with every change of a record, so a receiver can drop an event older than one it has. */
+  sequence: string;
+  after?: Row;
+  before?: Row;
+  changed: string[];
+  tenant?: TenantValue;
+  actor: EventActor | null;
+  source: 'api' | 'database';
+  transaction: string;
+};
+/** One event as it is delivered: the body of a URL or function target, and what a `run` handler gets. */
+export type SubscriptionEvent = {
+  /** The same on every retry and resend: the receiver's idempotency key (`webhook-id`). */
+  id: string;
+  type: string;
+  /** When the change's transaction started, ISO 8601. */
+  timestamp: string;
+  data: EventData;
+  /** Sent by Send test event: made up from a current record, not raised by a change. */
+  test?: true;
+};
+/** What a `run` handler gets beside the event. */
+export type RunContext = {
+  db: Db;
+  /** 1 for the first try. */
+  attempt: number;
+  signal: AbortSignal;
+};
+/** What every subscription may set beside its target. */
+export type SubscriptionCommon = {
+  /** Event names, such as `orders.created`, `orders.*` for every event of a resource, or `*` for all of them. */
+  events: string[];
+  /** A filter on the record, after the change or before a delete, in the language of access rules. */
+  when?: string;
+  /**
+   * Who the subscription delivers as: it gets only the records and fields these roles may read. Without it, every record
+   * and every field but the sensitive ones.
+   */
+  as?: {
+    roles: string[];
+  };
+  /** Only events of records of this tenant (organization). */
+  tenant?: TenantValue;
+  /** `thin` leaves the records out: a receiver reads them through the API. Default `full`. */
+  payload?: 'full' | 'thin';
+  /** One delivery at a time per record, in order; a failing one holds back the record's next. Default false. */
+  ordered?: boolean;
+  /** Default true. */
+  enabled?: boolean;
+};
+/** How a URL or function target is called: a POST of the event as JSON, signed with Standard Webhooks headers. */
+export type SentOptions = {
+  /** Signs the requests (`whsec_` and base64, as `verifyStandardWebhook` takes it); unsigned without one. Several sign during a rotation. */
+  secret?: string | string[];
+  headers?: Record<string, string>;
+  /** The body sent instead of the event, such as Slack's `{ text }`. */
+  body?: (event: SubscriptionEvent) => unknown;
+};
+export type UrlTarget = {
+  url: string | undefined;
+} & SentOptions;
+/** An API function of the app, `/api/functions/<name>`, called in this process. */
+export type FunctionTarget = {
+  function: string;
+} & SentOptions;
+/** Code run for each event; it throws to have the event retried. Config only. */
+export type RunTarget = {
+  run: (event: SubscriptionEvent, context: RunContext) => Promise<void> | void;
+};
+export type SubscriptionOptions = SubscriptionCommon & (UrlTarget | FunctionTarget | RunTarget);
+export type SubscriptionDefinition = {
+  readonly kind: 'subscription';
+  readonly name: string;
+  readonly options: SubscriptionOptions;
+};
+/**
+ * Delivers the events it names, as they happen: export it from the config module like a resource. The URL usually
+ * comes from the environment (`url: process.env.SLACK_WEBHOOK`); the server refuses to start while an enabled one is
+ * empty.
+ */
+export declare const subscription: (name: string, options: SubscriptionOptions) => SubscriptionDefinition;
+//#endregion

package/dist/webhooks/subscription.js

@@ -0,0 +1,28 @@
+//#region src/webhooks/subscription.ts
+const namePattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const targets = [
+	"url",
+	"function",
+	"run"
+];
+/**
+* Delivers the events it names, as they happen: export it from the config module like a resource. The URL usually
+* comes from the environment (`url: process.env.SLACK_WEBHOOK`); the server refuses to start while an enabled one is
+* empty.
+*/
+const subscription = (name, options) => {
+	if (!namePattern.test(name)) throw new Error(`Subscription name "${name}" must start with a letter and hold only letters, digits, "_" and "-"`);
+	const named = targets.filter((target) => target in options);
+	if (named.length !== 1) throw new Error(`Subscription "${name}" needs one target: url, function or run${named.length > 1 ? `, not ${named.join(" and ")}` : ""}`);
+	if (options.events.length === 0) throw new Error(`Subscription "${name}" names no events`);
+	return {
+		kind: "subscription",
+		name,
+		options
+	};
+};
+const isSubscription = (value) => typeof value === "object" && value !== null && value.kind === "subscription" && typeof value.name === "string";
+/** Whether an event name matches a subscription's pattern: the name, `<resource>.*` or `*`. */
+const eventPatternMatches = (pattern, event) => pattern === "*" || pattern === event || pattern.endsWith(".*") && event.startsWith(pattern.slice(0, -1));
+//#endregion
+export { eventPatternMatches, isSubscription, subscription };

package/dist/webhooks/table/address-check.js

@@ -0,0 +1,28 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+//#region src/webhooks/table/address-check.ts
+const v4 = (address) => address.split(".").map(Number);
+const privateV4 = (address) => {
+	const [a, b] = v4(address);
+	return a === 0 || a === 10 || a === 127 || a >= 224 || a === 100 && b >= 64 && b < 128 || a === 169 && b === 254 || a === 172 && b >= 16 && b < 32 || a === 192 && b === 168;
+};
+const privateV6 = (address) => {
+	const lower = address.toLowerCase();
+	const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+	if (mapped) return privateV4(mapped[1]);
+	return lower === "::" || lower === "::1" || /^f[cd]/.test(lower) || /^fe[89ab]/.test(lower) || /^ff/.test(lower);
+};
+/** Whether an IP address is one a webhook must not reach: the server's own host or network. */
+const isPrivateAddress = (address) => isIP(address) === 4 ? privateV4(address) : privateV6(address);
+/**
+* What is wrong with a URL whose host is, or resolves to, a private, loopback or link-local address, so a subscription someone
+* makes in the admin app cannot reach the server's own network. The address is resolved again when the request is
+* sent, so a host that answers differently the second time still gets through: a firewall rule is the stronger guard.
+*/
+const checkWebhookUrl = async (url) => {
+	const host = new URL(url).hostname.replace(/^\[|\]$/g, "");
+	const blocked = (isIP(host) ? [host] : (await lookup(host, { all: true })).map((entry) => entry.address)).find(isPrivateAddress);
+	return blocked ? `${host} is a private address (${blocked}); webhooks reach public addresses only` : void 0;
+};
+//#endregion
+export { checkWebhookUrl, isPrivateAddress };

package/dist/webhooks/table/options.d.ts

@@ -0,0 +1,23 @@
+import { TenantValue } from "../../types.js";
+//#region src/webhooks/table/options.d.ts
+/** Webhook subscriptions made in the admin app (`extends: [webhooks()]`), kept in a table of the app's database. */
+export type WebhooksOptions = {
+  /** The schema of the subscriptions table and the deliveries view; default `webhooks`. */
+  schema?: string;
+  /** Also keep every try, successes too, for 30 days, listed as Webhook delivery log. Default false. */
+  deliveryLog?: boolean;
+  /**
+   * The roles a subscription's owner holds now in its tenant, which it delivers as. Default: read from the project's
+   * Better Auth (`auth`); a project that signs people in otherwise passes its own.
+   */
+  ownerRoles?: (owner: {
+    id: string;
+    tenant?: TenantValue;
+  }) => Promise<string[]>;
+  /**
+   * Lets subscriptions send to private, loopback and link-local addresses, for development and tests. Default false:
+   * a URL whose host resolves to one is refused, so a subscription cannot reach the app's own network.
+   */
+  allowPrivateAddresses?: boolean;
+};
+//#endregion

package/dist/webhooks/table/options.js

@@ -0,0 +1,14 @@
+//#region src/webhooks/table/options.ts
+const schemaPattern = /^[a-z_][a-z0-9_]*$/;
+/** The schema of the options, checked. */
+const webhooksSchema = (options = {}) => {
+	const schema = options.schema ?? "webhooks";
+	if (!schemaPattern.test(schema)) throw new Error(`Invalid webhooks schema "${schema}": use lowercase letters, digits and "_"`);
+	return schema;
+};
+/** A table subscription's name among all subscriptions: config ones cannot start with `ui:`. */
+const tableSubscriptionName = (id) => `ui:${id}`;
+/** The event names and patterns of a subscription row: separated by spaces or commas. */
+const parseEvents = (text) => text.split(/[\s,]+/).filter((part) => part !== "");
+//#endregion
+export { parseEvents, tableSubscriptionName, webhooksSchema };

package/dist/webhooks/table/owner-roles.js

@@ -0,0 +1,29 @@
+import { parseRoles } from "../../better-auth/parse-roles.js";
+import { effectiveRoles, globalRoles } from "../../better-auth/organizations/app-roles.js";
+import { findMember } from "../../better-auth/organizations/store.js";
+import { resolveActiveRole } from "../../better-auth/roles/active-role.js";
+//#region src/webhooks/table/owner-roles.ts
+const heldIn = async (auth, user, tenant) => {
+	if (!auth.organizations) return parseRoles(user.role);
+	const global = globalRoles(user.role);
+	if (tenant === void 0) return global;
+	const { adapter } = await auth.$context;
+	const member = await findMember(adapter, {
+		organizationId: String(tenant),
+		userId: user.id
+	});
+	return member ? effectiveRoles(global, member.appRoles) : global;
+};
+/**
+* The role someone acts with now, as their next session's token would carry it: the one they last chose while they
+* hold it, else their first (see `resolveActiveRole`). None for a user who is banned or gone, or holds no role.
+*/
+const betterAuthOwnerRoles = (auth) => async ({ id, tenant }) => {
+	const { internalAdapter } = await auth.$context;
+	const user = await internalAdapter.findUserById(id);
+	if (!user || user.banned) return [];
+	const active = resolveActiveRole(await heldIn(auth, user, tenant), [user.lastRole]);
+	return active === void 0 ? [] : [active];
+};
+//#endregion
+export { betterAuthOwnerRoles };

package/dist/webhooks/table/plugin.d.ts

@@ -0,0 +1,10 @@
+import { WebhooksOptions } from "./options.js";
+import { ProjectConfig } from "../../project-config.js";
+//#region src/webhooks/table/plugin.d.ts
+/**
+ * Webhook subscriptions made in the admin app: `extends: [webhooks()]` in `protobase.config.ts`. It adds the Webhook
+ * subscriptions and Webhook deliveries pages, over a `webhooks` schema that `protobase migration` writes. Who may
+ * create subscriptions is the resources' access (`webhook_subscriptions.create`, ...); each delivers as its owner.
+ */
+export declare const webhooks: (options?: WebhooksOptions) => ProjectConfig;
+//#endregion

package/dist/webhooks/table/plugin.js

@@ -0,0 +1,18 @@
+import { webhooksSchema } from "./options.js";
+import { webhookResources } from "@protobase/schema";
+//#region src/webhooks/table/plugin.ts
+/**
+* Webhook subscriptions made in the admin app: `extends: [webhooks()]` in `protobase.config.ts`. It adds the Webhook
+* subscriptions and Webhook deliveries pages, over a `webhooks` schema that `protobase migration` writes. Who may
+* create subscriptions is the resources' access (`webhook_subscriptions.create`, ...); each delivers as its owner.
+*/
+const webhooks = (options = {}) => {
+	const schema = webhooksSchema(options);
+	return {
+		name: "protobase-webhooks",
+		config: webhookResources(schema, { deliveryLog: Boolean(options.deliveryLog) }),
+		webhooks: options
+	};
+};
+//#endregion
+export { webhooks };

package/dist/webhooks/table/schema-sql.js

@@ -0,0 +1,116 @@
+import { jobsSchema } from "../../jobs/schema.js";
+import { quoteIdent } from "../../changes/capture-sql.js";
+/** The comment the schema's functions carry, which the startup check reads. */
+const webhooksComment = `Protobase webhooks 1`;
+/** The delivery jobs, whose waiting and failed ones the deliveries view lists. */
+const deliveryJobs = ["webhooks.deliver", "webhooks.deliver-ordered"];
+/** The job that sends a subscription a test event. */
+const sendTestJob = "webhooks.send-test";
+const randomSecret = `'whsec_' || encode(decode(replace(gen_random_uuid()::text || gen_random_uuid()::text, '-', ''), 'hex'), 'base64')`;
+/**
+* The subscriptions table. The owner is the API's caller, from the change capture's `actor` setting; the tenant is set by
+* the API like any tenant column. `rotate_secret`, `send_test` and `resend_failed` are commands: an update that sets one
+* runs it and stores false.
+*/
+const subscriptionsSql = (schema, changesSchema) => `create table if not exists ${quoteIdent(schema)}."subscriptions" (
+  "id" uuid primary key default gen_random_uuid(),
+  "name" text not null,
+  "events" text not null,
+  "url" text not null,
+  "filter" text,
+  "headers" jsonb,
+  "payload" text not null default 'full' check ("payload" in ('full', 'thin')),
+  "enabled" boolean not null default true,
+  "secret" text not null default (${randomSecret}),
+  "previous_secret" text,
+  "previous_secret_until" timestamptz,
+  "tenant_id" text,
+  "owner_id" text default (nullif(current_setting('${changesSchema}.actor', true), '')::jsonb ->> 'id'),
+  "disabled_reason" text,
+  "last_success_at" timestamptz,
+  "failing_since" timestamptz,
+  "created_at" timestamptz not null default now(),
+  "updated_at" timestamptz not null default now(),
+  "rotate_secret" boolean not null default false,
+  "send_test" boolean not null default false,
+  "resend_failed" boolean not null default false
+);
+create index if not exists "subscriptions_tenant" on ${quoteIdent(schema)}."subscriptions" ("tenant_id")`;
+const retryJobs = (where) => `update ${jobsSchema}.job
+    set state = 'retry', retry_limit = retry_limit + 1, completed_on = null,
+      start_after = greatest(start_after, ${jobsSchema}.job_now()), keep_until = greatest(keep_until, ${jobsSchema}.job_now() + interval '14 days')
+    where name = any(array['${deliveryJobs.join("', '")}']) and state = 'failed' and ${where}`;
+/** The commands of the subscriptions table, and a re-enabled subscription starting afresh. */
+const commandsSql = (schema) => `create or replace function ${quoteIdent(schema)}."subscription_commands"() returns trigger
+language plpgsql as $$
+begin
+  if new.rotate_secret then
+    new.previous_secret := old.secret;
+    new.previous_secret_until := now() + interval '24 hours';
+    new.secret := ${randomSecret};
+    new.rotate_secret := false;
+  end if;
+  if new.send_test then
+    perform ${jobsSchema}.enqueue('${sendTestJob}', jsonb_build_object('subscription', new.id));
+    new.send_test := false;
+  end if;
+  if new.resend_failed then
+    ${retryJobs(`data ->> 'subscription' = 'ui:' || new.id::text`)};
+    new.resend_failed := false;
+  end if;
+  if new.enabled and not old.enabled then
+    new.disabled_reason := null;
+    new.failing_since := null;
+  end if;
+  new.updated_at := now();
+  return new;
+end
+$$;
+comment on function ${quoteIdent(schema)}."subscription_commands"() is '${webhooksComment}';
+drop trigger if exists "subscription_commands" on ${quoteIdent(schema)}."subscriptions";
+create trigger "subscription_commands" before update on ${quoteIdent(schema)}."subscriptions" for each row execute function ${quoteIdent(schema)}."subscription_commands"()`;
+/**
+* The deliveries of table subscriptions that wait for a retry or failed for good: the delivery jobs, with their
+* subscription's tenant. Updating `resend` to true runs a failed one once more.
+*/
+const deliveriesSql = (schema) => `drop view if exists ${quoteIdent(schema)}."deliveries";
+create view ${quoteIdent(schema)}."deliveries" as
+select j.id, s.id as subscription_id, s.tenant_id,
+  coalesce(j.data -> 'event' ->> 'type', j.data -> 'events' -> 0 ->> 'type') as event_type,
+  coalesce(j.data -> 'event' ->> 'id', j.data -> 'events' -> 0 ->> 'id') as event_id,
+  case when j.state = 'failed' then 'failed' else 'waiting' end as status,
+  coalesce((j.data ->> 'attempt')::integer, j.retry_count + 1) as attempt,
+  case when j.state = 'failed' then null else j.start_after end as next_attempt,
+  coalesce(j.output ->> 'message', j.data ->> 'lastError') as last_error,
+  j.created_on as created_at,
+  false as resend
+from ${jobsSchema}.job j join ${quoteIdent(schema)}."subscriptions" s on j.data ->> 'subscription' = 'ui:' || s.id::text
+where j.name = any(array['${deliveryJobs.join("', '")}']) and j.state in ('created', 'retry', 'failed');
+create or replace function ${quoteIdent(schema)}."deliveries_resend"() returns trigger
+language plpgsql as $$
+begin
+  if new.resend then
+    ${retryJobs("id = old.id")};
+  end if;
+  return new;
+end
+$$;
+comment on function ${quoteIdent(schema)}."deliveries_resend"() is '${webhooksComment}';
+create trigger "deliveries_resend" instead of update on ${quoteIdent(schema)}."deliveries" for each row execute function ${quoteIdent(schema)}."deliveries_resend"()`;
+/** Every try of a table subscription's deliveries, kept 30 days, with `deliveryLog`. */
+const deliveryLogSql = (schema) => `create table if not exists ${quoteIdent(schema)}."delivery_log" (
+  "id" bigint generated always as identity primary key,
+  "subscription_id" uuid not null references ${quoteIdent(schema)}."subscriptions" ("id") on delete cascade,
+  "tenant_id" text,
+  "event_id" text not null,
+  "event_type" text not null,
+  "status" text not null check ("status" in ('delivered', 'failed')),
+  "attempt" integer not null,
+  "status_code" integer,
+  "response" text,
+  "duration_ms" integer not null,
+  "at" timestamptz not null default now()
+);
+create index if not exists "delivery_log_subscription" on ${quoteIdent(schema)}."delivery_log" ("subscription_id", "at")`;
+//#endregion
+export { commandsSql, deliveriesSql, deliveryJobs, deliveryLogSql, sendTestJob, subscriptionsSql, webhooksComment };

package/dist/webhooks/table/schema.d.ts

@@ -0,0 +1,13 @@
+import { EventsOptions } from "../../changes/events-options.js";
+import { WebhooksOptions } from "./options.js";
+import { Db } from "@protobase/query";
+//#region src/webhooks/table/schema.d.ts
+/**
+ * The SQL that brings the `webhooks` schema to what `webhooks()` needs: the subscriptions table, its commands, the
+ * deliveries view and, with `deliveryLog`, the log table. `undefined` when current. Needs the jobs schema, which the
+ * deliveries view reads. Tables are never dropped.
+ */
+export declare const webhooksMigration: (db: Db, options?: WebhooksOptions, events?: EventsOptions) => Promise<string | undefined>;
+/** Refuses to go on while the `webhooks` schema lacks what `webhooks()` needs; the project's migrations add it. */
+export declare const checkWebhooksSchema: (db: Db, options?: WebhooksOptions) => Promise<void>;
+//#endregion

package/dist/webhooks/table/schema.js

@@ -0,0 +1,44 @@
+import { quoteIdent } from "../../changes/capture-sql.js";
+import { changesSchema } from "../../changes/events-options.js";
+import { webhooksSchema } from "./options.js";
+import { commandsSql, deliveriesSql, deliveryLogSql, subscriptionsSql, webhooksComment } from "./schema-sql.js";
+import { migrationCommand } from "../../changes/capture-schema.js";
+import { sql } from "kysely";
+//#region src/webhooks/table/schema.ts
+const functionNames = ["subscription_commands", "deliveries_resend"];
+const readWebhooksSchema = async (db, schema) => {
+	const exists = async (table) => (await sql`select to_regclass(${`${quoteIdent(schema)}.${quoteIdent(table)}`}) is not null as found`.execute(db)).rows[0].found;
+	const { rows } = await sql`select p.proname as name, obj_description(p.oid, 'pg_proc') as comment
+    from pg_proc p join pg_namespace n on n.oid = p.pronamespace where n.nspname = ${schema} and p.proname = any(${functionNames}::text[])`.execute(db);
+	return {
+		subscriptions: await exists("subscriptions"),
+		current: functionNames.every((name) => rows.some((row) => row.name === name && row.comment === webhooksComment)) && await exists("deliveries"),
+		deliveryLog: await exists("delivery_log")
+	};
+};
+/**
+* The SQL that brings the `webhooks` schema to what `webhooks()` needs: the subscriptions table, its commands, the
+* deliveries view and, with `deliveryLog`, the log table. `undefined` when current. Needs the jobs schema, which the
+* deliveries view reads. Tables are never dropped.
+*/
+const webhooksMigration = async (db, options = {}, events) => {
+	const schema = webhooksSchema(options);
+	const found = await readWebhooksSchema(db, schema);
+	const needsLog = Boolean(options.deliveryLog) && !found.deliveryLog;
+	if (found.subscriptions && found.current && !needsLog) return void 0;
+	return `${[
+		`create schema if not exists ${quoteIdent(schema)}`,
+		...found.subscriptions ? [] : [subscriptionsSql(schema, changesSchema(events))],
+		...found.current && found.subscriptions ? [] : [commandsSql(schema), deliveriesSql(schema)],
+		...needsLog ? [deliveryLogSql(schema)] : []
+	].join(";\n\n")};`;
+};
+/** Refuses to go on while the `webhooks` schema lacks what `webhooks()` needs; the project's migrations add it. */
+const checkWebhooksSchema = async (db, options = {}) => {
+	const schema = webhooksSchema(options);
+	const found = await readWebhooksSchema(db, schema);
+	if (found.subscriptions && found.current && (!options.deliveryLog || found.deliveryLog)) return;
+	throw new Error(`The ${schema} schema is missing or behind this version of Protobase. Write it as a migration with \`${migrationCommand}\`, apply it with the project's migrations, then start again.`);
+};
+//#endregion
+export { checkWebhooksSchema, webhooksMigration };

package/dist/webhooks/table/table-subscriptions.js

@@ -0,0 +1,77 @@
+import { quoteIdent } from "../../changes/capture-sql.js";
+import { parseEvents, tableSubscriptionName } from "./options.js";
+import { sql } from "kysely";
+//#region src/webhooks/table/table-subscriptions.ts
+/** A UI subscription is disabled after this long without a success. */
+const failingFor = "3 days";
+/**
+* The subscriptions people made in the admin app, as the dispatcher and the delivery jobs use them: named `ui:<id>`,
+* delivering as their owner with the roles they hold now, signed with their secret and, for 24 hours after a rotation,
+* the previous one too. What happens to their deliveries is kept on their row.
+*/
+const tableSubscriptions = ({ schema, ownerRoles, deliveryLog }) => {
+	const table = sql.raw(`${quoteIdent(schema)}."subscriptions"`);
+	const definition = async (row) => {
+		const tenant = row.tenant_id ?? void 0;
+		const roles = row.owner_id ? await ownerRoles({
+			id: row.owner_id,
+			...tenant !== void 0 && { tenant }
+		}) : [];
+		return {
+			kind: "subscription",
+			name: tableSubscriptionName(row.id),
+			options: {
+				events: parseEvents(row.events),
+				url: row.url,
+				...row.filter && { when: row.filter },
+				...row.headers && { headers: row.headers },
+				payload: row.payload,
+				enabled: row.enabled,
+				secret: row.overlapping && row.previous_secret ? [row.secret, row.previous_secret] : row.secret,
+				...tenant !== void 0 && { tenant },
+				as: { roles }
+			}
+		};
+	};
+	const select = sql`select "id"::text as id, "events", "url", "filter", "headers", "payload", "enabled", "secret", "previous_secret",
+    coalesce("previous_secret_until" > now(), false) as overlapping, "tenant_id", "owner_id" from ${table}`;
+	/** Every enabled one. */
+	const load = async (db) => Promise.all((await sql`${select} where "enabled"`.execute(db)).rows.map(definition));
+	/** One by id, enabled or not; `undefined` once it is deleted. */
+	const find = async (db, id) => {
+		const [row] = (await sql`${select} where "id"::text = ${id}`.execute(db)).rows;
+		return row && definition(row);
+	};
+	/** The row's record of a try: its last success, how long it has been failing, and disabling it when it should stop. */
+	const record = async (db, id, event, tried, result, durationMs) => {
+		if (result.ok) await sql`update ${table} set "last_success_at" = now(), "failing_since" = null where "id"::text = ${id}`.execute(db);
+		else {
+			const gone = result.status === 410;
+			await sql`update ${table} set "failing_since" = coalesce("failing_since", now()),
+          "enabled" = "enabled" and not (${gone} or coalesce("failing_since", now()) < now() - ${failingFor}::interval),
+          "disabled_reason" = case
+            when ${gone} then 'The receiver answered 410 Gone'
+            when coalesce("failing_since", now()) < now() - ${failingFor}::interval then 'No delivery succeeded for ${sql.raw(failingFor)}'
+            else "disabled_reason" end
+        where "id"::text = ${id}`.execute(db);
+		}
+		if (!deliveryLog) return;
+		const status = result.ok ? "delivered" : "failed";
+		const response = result.ok ? null : result.error.slice(0, 2048);
+		await sql`insert into ${sql.raw(`${quoteIdent(schema)}."delivery_log"`)} ("subscription_id", "tenant_id", "event_id", "event_type", "status", "attempt", "status_code", "response", "duration_ms")
+      select "id", "tenant_id", ${event.id}, ${event.type}, ${status}, ${tried}, ${result.status ?? null}, ${response}, ${Math.round(durationMs)} from ${table} where "id"::text = ${id}`.execute(db);
+	};
+	/** Deletes the log's tries older than 30 days. */
+	const prune = async (db) => {
+		await sql`delete from ${sql.raw(`${quoteIdent(schema)}."delivery_log"`)} where "at" < now() - interval '30 days'`.execute(db);
+	};
+	return {
+		load,
+		find,
+		record,
+		prune,
+		deliveryLog
+	};
+};
+//#endregion
+export { tableSubscriptions };

package/dist/webhooks/table/validate-hook.js

@@ -0,0 +1,32 @@
+import { badRequest } from "../../problem.js";
+import { subscriptionProblems } from "../route-events.js";
+import { parseEvents } from "./options.js";
+//#region src/webhooks/table/validate-hook.ts
+const isHeaders = (value) => value === null || value === void 0 || typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string");
+/**
+* Checks a webhook subscription as it is written: events that are declared, a filter that checks against every resource
+* it covers, headers of text, and a URL at a public address. A refusal is a 400 problem, and the write rolls back.
+*/
+const subscriptionWriteCheck = (models, checkUrl) => async (event) => {
+	if (event.resource.name !== "webhook_subscriptions" || !event.after) return;
+	const { events, url, filter, headers } = event.after;
+	const candidate = {
+		kind: "subscription",
+		name: "it",
+		options: {
+			events: parseEvents(events),
+			url,
+			...filter && { when: filter }
+		}
+	};
+	const problems = [
+		...parseEvents(events).length === 0 ? ["names no events"] : [],
+		...subscriptionProblems([candidate], models, []).map((problem) => problem.replace("Subscription \"it\" ", "")),
+		...isHeaders(headers) ? [] : ["headers must be an object of text values"]
+	];
+	const blocked = problems.length === 0 && checkUrl ? await checkUrl(url) : void 0;
+	const all = [...problems, ...blocked ? [blocked] : []];
+	if (all.length > 0) throw badRequest("invalid-webhook-subscription", `The webhook subscription cannot be saved: ${all.join("; ")}`);
+};
+//#endregion
+export { subscriptionWriteCheck };

package/dist/webhooks/table/webhook-table.js

@@ -0,0 +1,23 @@
+import { webhooksSchema } from "./options.js";
+import { checkWebhookUrl } from "./address-check.js";
+import { betterAuthOwnerRoles } from "./owner-roles.js";
+import { tableSubscriptions } from "./table-subscriptions.js";
+//#region src/webhooks/table/webhook-table.ts
+/**
+* What `createAdmin` needs for the subscriptions of `webhooks()`: the table, the owners' current roles (from Better Auth
+* unless the options say otherwise) and, unless allowed, the check that keeps URLs off private addresses.
+*/
+const webhookTable = (options, auth) => {
+	const ownerRoles = options.ownerRoles ?? (auth && betterAuthOwnerRoles(auth));
+	if (!ownerRoles) throw new Error("webhooks() delivers as each subscription's owner, with their current roles: pass `auth` (Better Auth) or `ownerRoles` to webhooks()");
+	return {
+		subscriptions: tableSubscriptions({
+			schema: webhooksSchema(options),
+			ownerRoles,
+			deliveryLog: Boolean(options.deliveryLog)
+		}),
+		...!options.allowPrivateAddresses && { checkUrl: checkWebhookUrl }
+	};
+};
+//#endregion
+export { webhookTable };

package/dist/webhooks/test-event.js

@@ -0,0 +1,48 @@
+import { HttpProblem } from "../problem.js";
+import { subscriberSession } from "./subscriber-view.js";
+import { eventPatternMatches } from "./subscription.js";
+import { encodeKey } from "@protobase/schema";
+//#region src/webhooks/test-event.ts
+/**
+* What Send test event sends: the first declared event the subscription takes, made up from the newest record of its
+* resource that the subscription may read, or with no record when it may read none. It is marked `test`.
+*/
+const testEvent = async (deps, records, subscription) => {
+	const { options } = subscription;
+	const found = deps.registry.entries.flatMap((entry) => (entry.model.events ?? []).map((event) => ({
+		entry,
+		name: event.name
+	}))).find(({ name }) => options.events.some((pattern) => eventPatternMatches(pattern, name)));
+	if (!found) throw new Error(`The subscription "${subscription.name}" takes no declared event`);
+	const { entry, name } = found;
+	const item = (await records(subscriberSession(subscription) ?? { user: {
+		id: `subscription:${subscription.name}`,
+		roles: []
+	} }).list(entry.name, { page_size: 1 }).catch((error) => {
+		if (error instanceof HttpProblem) return void 0;
+		throw error;
+	}))?.items[0];
+	const record = item && Object.fromEntries(Object.entries(item).filter(([field]) => Object.hasOwn(entry.model.fields, field)));
+	const thin = options.payload === "thin";
+	const tenant = entry.model.tenant && record ? record[entry.model.tenant] : void 0;
+	return {
+		id: `test_${crypto.randomUUID()}`,
+		type: name,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		data: {
+			resource: entry.name,
+			operation: "create",
+			key: record ? encodeKey(entry.model.primaryKey.map((field) => record[field])) : "",
+			sequence: "0",
+			...record && !thin && { after: record },
+			changed: [],
+			...tenant !== void 0 && tenant !== null && { tenant },
+			actor: null,
+			source: "database",
+			transaction: "0"
+		},
+		test: true
+	};
+};
+//#endregion
+export { testEvent };