@every-app/sdk 0.2.0 → 0.3.0-rc.10

package/dist/internal/events.d.ts

@@ -0,0 +1,193 @@
+/**
+ * The event bus's shared contract (docs/design/2026-10-events-out.md): the
+ * catalogue of types the gateway emits, the pattern a subscription matches
+ * them by, the shape and size an app's own event may have, the headers a
+ * delivery carries, and every limit, in one place the gateway, the CLI
+ * (`everyapp events`), the SDK (`emit`) and the docs drift test read.
+ *
+ * The gateway builds each type's `data` and summary in
+ * apps/every-app-gateway/src/server/events/catalogue.ts; this module knows
+ * the names, versions and one-line descriptions only.
+ */
+export type EventGroup = "member" | "organization" | "app" | "cap" | "group" | "tool" | "connection" | "token" | "access" | "signin_provider" | "mcp_app" | "provider" | "subscription" | "ai" | "ping";
+export interface EventTypeInfo {
+    /** `member.joined`, `cap.reached`, … */
+    readonly type: string;
+    /** Bumped when the type's `data` changes shape; the old one stays documented. */
+    readonly version: number;
+    /** One line, for `everyapp events types`, the Add dialog and the docs. */
+    readonly description: string;
+    readonly group: EventGroup;
+}
+/**
+ * Every type the gateway itself emits, in the order the docs list them.
+ * An app's own events (`app.<id>.<name>`, {@link appEventType}) are a
+ * pattern, not entries here. Reserved entries are emitted by sibling
+ * features (remote MCP apps, the provider registry) through the same bus.
+ */
+export declare const EVENT_TYPES: readonly EventTypeInfo[];
+/** The catalogue entry for a type, or undefined for an app's own event. */
+export declare function eventTypeInfo(type: string): EventTypeInfo | undefined;
+/** The prefix every app's own event carries: `app.<app id>.<name>`. */
+export declare const APP_EVENT_PREFIX = "app.";
+/** An app's event name: `invoice.paid`, `todo_completed`; lowercase, dotted. */
+export declare const APP_EVENT_NAME_PATTERN: RegExp;
+export declare const APP_EVENT_NAME_MAX = 64;
+/** The type an app's event is delivered as. */
+export declare function appEventType(appId: string, name: string): string;
+/**
+ * Whether `type` is an app's own event (`app.<id>.<name>`) rather than one
+ * of the gateway's `app.*` entries, which have exactly one segment after
+ * the prefix.
+ */
+export declare function isAppOwnEventType(type: string): boolean;
+/** What is wrong with an app event's name, or null. */
+export declare function appEventNameProblem(name: unknown): string | null;
+/** Bytes of `data` an app's event may carry, serialized. */
+export declare const APP_EVENT_DATA_MAX_BYTES: number;
+/** Bytes of `data` any event row may carry (the gateway's own included). */
+export declare const EVENT_DATA_MAX_BYTES: number;
+/** How deep `data` may nest. */
+export declare const EVENT_DATA_MAX_DEPTH = 8;
+/** Emits per app per hour (`rate_limit_counters`). */
+export declare const APP_EVENT_RATE_PER_HOUR = 600;
+/** Subscriptions per organization. */
+export declare const EVENT_SUBSCRIPTIONS_MAX = 25;
+/** A webhook signing secret's length. */
+export declare const EVENT_SECRET_MIN_LENGTH = 16;
+export declare const EVENT_SECRET_MAX_LENGTH = 128;
+/**
+ * Deliveries (the queue and its log) are kept this long. Events themselves
+ * are the audit log and live longer ({@link AUDIT_RETENTION_DAYS}).
+ */
+export declare const EVENT_RETENTION_DAYS = 30;
+/**
+ * Events are kept this long: Admin → Activity → Audit, `everyapp workspace
+ * audit` and `everyapp_workspace_audit` read them back. A constant, not a
+ * setting.
+ */
+export declare const AUDIT_RETENTION_DAYS = 90;
+/** The most audit rows one page carries, on every surface. */
+export declare const AUDIT_PAGE_MAX = 200;
+/** A subscription's URL. */
+export declare const EVENT_URL_MAX_LENGTH = 2048;
+/** A subscription's name. */
+export declare const EVENT_SUBSCRIPTION_NAME_MAX = 100;
+/**
+ * The wait after attempt n fails (n from 1): the first attempt is right
+ * after the event; the seventh failure is dead (about 35 hours in all).
+ */
+export declare const EVENT_RETRY_DELAYS_MS: readonly number[];
+export declare const EVENT_DELIVERY_MAX_ATTEMPTS: number;
+/** A webhook's answer is awaited this long. */
+export declare const EVENT_DELIVERY_TIMEOUT_MS = 10000;
+/** How much of a failed answer's body is read, and how much is kept. */
+export declare const EVENT_RESPONSE_READ_MAX_BYTES = 1024;
+export declare const EVENT_RESPONSE_KEEP_CHARS = 200;
+/** The age of a signature's timestamp a receiver should accept. */
+export declare const EVENT_SIGNATURE_TOLERANCE_SECONDS = 300;
+/** The app-to-gateway route an app emits on (over the EVERY_APP_GATEWAY binding). */
+export declare const EVENTS_EMIT_PATH = "/api/events/emit";
+/** The headers every webhook delivery carries. */
+export declare const EVENT_HEADERS: {
+    readonly event: "x-everyapp-event";
+    readonly eventId: "x-everyapp-event-id";
+    readonly delivery: "x-everyapp-delivery";
+    readonly attempt: "x-everyapp-attempt";
+    readonly signature: "x-everyapp-signature";
+};
+/** The Gateway setting that lets http: and private hosts be targets. */
+export declare const EVENTS_ALLOW_PRIVATE_TARGETS_SETTING = "EVENTS_ALLOW_PRIVATE_TARGETS";
+/**
+ * Name suffixes (and exact names) that mean a local or private machine: a
+ * webhook target under one is refused unless EVENTS_ALLOW_PRIVATE_TARGETS
+ * is "true". One list for the gateway (which checks a URL before every
+ * attempt) and the CLI (which checks it when `everyapp events add` writes
+ * the subscription), so the two never drift.
+ */
+export declare const EVENT_PRIVATE_NAME_SUFFIXES: readonly string[];
+/**
+ * Whether a normalized hostname (lowercase, no trailing dot) is a local or
+ * private name: one of {@link EVENT_PRIVATE_NAME_SUFFIXES}, a name under
+ * one (`n8n.lan`, `hooks.acme.corp`), or a bare label (`n8n`), which only
+ * a private resolver answers.
+ */
+export declare function isPrivateEventTargetName(host: string): boolean;
+/** The sinks a subscription delivers to. */
+export declare const EVENT_SINKS: readonly ["webhook", "email"];
+export type EventSink = (typeof EVENT_SINKS)[number];
+/** Whom the email sink mails: the organization's owners, or owners and admins. */
+export declare const EVENT_EMAIL_RECIPIENTS: readonly ["owners", "admins"];
+export type EventEmailRecipients = (typeof EVENT_EMAIL_RECIPIENTS)[number];
+/**
+ * A subscription pattern: `*` (everything but ping), an exact type, or a
+ * prefix with `.*` (`member.*`, `app.*`, `app.crm.*`). `app.*` matches the
+ * gateway's app events and every app's own.
+ */
+export declare function eventPatternMatches(pattern: string, type: string): boolean;
+/** Whether any of a subscription's patterns matches the type. */
+export declare function eventSubscribed(patterns: readonly string[], type: string): boolean;
+/**
+ * What is wrong with a pattern someone typed, or null: a known type, a
+ * prefix of known types (`member.*`), an app's own events (`app.crm.*`,
+ * `app.crm.invoice.paid`), or `*`.
+ */
+export declare function eventPatternProblem(pattern: string): string | null;
+/**
+ * A key that reads like a credential. An event's `data` is refused when any
+ * key, at any depth, matches: a payload can't carry a secret by accident,
+ * whether an app's own or the gateway's (the catalogue's builders are
+ * checked by the same rule).
+ */
+export declare const CREDENTIAL_KEY_PATTERN: RegExp;
+export type EventDataProblem = {
+    code: "event_data_invalid";
+    message: string;
+} | {
+    code: "event_data_too_large";
+    message: string;
+    bytes: number;
+} | {
+    code: "event_data_refused";
+    message: string;
+    key: string;
+};
+export type EventDataCheck = {
+    ok: true;
+    bytes: number;
+} | ({
+    ok: false;
+} & EventDataProblem);
+/**
+ * Check an event's `data`: a JSON object (not an array, not a scalar), at
+ * most `maxBytes` serialized, nested at most {@link EVENT_DATA_MAX_DEPTH}
+ * deep, with no key named like a credential. Functions, bigints, dates and
+ * the like must already be plain JSON: the caller serializes what it got.
+ */
+export declare function checkEventData(data: unknown, maxBytes?: number): EventDataCheck;
+/** What `POST /api/events/emit` takes from an app. */
+export interface EmitEventRequest {
+    /** The app's own name for the event (`invoice.paid`). */
+    event: string;
+    data: Record<string, unknown>;
+}
+/** What it answers. */
+export interface EmitEventResult {
+    /** The event's id (`evt_…`), or `dev-…` under `everyapp dev`. */
+    id: string;
+    /** The delivered type: `app.<app id>.<event>`. */
+    type: string;
+}
+/**
+ * The string a webhook delivery is signed over: the timestamp (seconds
+ * since the epoch), a dot, the exact body.
+ */
+export declare function eventSigningInput(timestamp: number, body: string): string;
+/** `t=<seconds>,v1=<hex>`, as the signature header carries it. */
+export declare function formatEventSignature(timestamp: number, hexDigest: string): string;
+/** The parts of a signature header, or null when it isn't one. */
+export declare function parseEventSignature(header: string | null | undefined): {
+    timestamp: number;
+    v1: string[];
+} | null;
+//# sourceMappingURL=events.d.ts.map

package/dist/internal/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/internal/events.ts"],"names":[],"mappings":"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"}

package/dist/internal/events.js

@@ -0,0 +1,367 @@
+/**
+ * The event bus's shared contract (docs/design/2026-10-events-out.md): the
+ * catalogue of types the gateway emits, the pattern a subscription matches
+ * them by, the shape and size an app's own event may have, the headers a
+ * delivery carries, and every limit, in one place the gateway, the CLI
+ * (`everyapp events`), the SDK (`emit`) and the docs drift test read.
+ *
+ * The gateway builds each type's `data` and summary in
+ * apps/every-app-gateway/src/server/events/catalogue.ts; this module knows
+ * the names, versions and one-line descriptions only.
+ */
+const entry = (group, type, description, version = 1) => ({ type, version, description, group });
+/**
+ * Every type the gateway itself emits, in the order the docs list them.
+ * An app's own events (`app.<id>.<name>`, {@link appEventType}) are a
+ * pattern, not entries here. Reserved entries are emitted by sibling
+ * features (remote MCP apps, the provider registry) through the same bus.
+ */
+export const EVENT_TYPES = [
+    entry("member", "member.invited", "Someone was invited to the workspace"),
+    entry("member", "member.joined", "Someone joined the workspace"),
+    entry("member", "member.role_changed", "A member's role changed"),
+    entry("member", "member.deactivated", "A member was deactivated"),
+    entry("member", "member.reactivated", "A member was reactivated"),
+    entry("member", "member.removed", "A member was removed"),
+    entry("member", "member.password_reset", "A member reset their password"),
+    entry("member", "member.invitation_cancelled", "A pending invitation was cancelled"),
+    entry("organization", "organization.renamed", "The workspace was renamed"),
+    entry("organization", "organization.linked_dev_changed", "Linked dev (everyapp dev against this Gateway) was turned on or off"),
+    entry("app", "app.installed", "An app was installed on the Gateway"),
+    entry("app", "app.updated", "An app was redeployed"),
+    entry("app", "app.live", "An app went live on the Gateway"),
+    entry("app", "app.removed", "An app was removed from the Gateway"),
+    entry("app", "app.needs_setup", "An app needs a setting before it opens"),
+    entry("app", "app.ready", "An app has every setting it needs"),
+    entry("app", "app.paused_cap", "An app is paused: its monthly cap is reached"),
+    entry("app", "app.tools_changed", "An app's AI tools changed"),
+    entry("app", "app.renamed", "An app's name or description changed"),
+    entry("app", "app.settings_changed", "An app's settings were set or unset (names only)"),
+    entry("app", "app.access_changed", "Who can open an app changed"),
+    entry("app", "app.email_changed", "An app's email senders or inbound changed"),
+    entry("cap", "cap.warning", "An app is at 80% of its monthly cap"),
+    entry("cap", "cap.reached", "An app reached its monthly cap"),
+    entry("cap", "cap.raised", "An app's monthly cap, or the workspace default, was raised or removed"),
+    entry("cap", "cap.changed", "An app's monthly cap, or the workspace default, was set or lowered"),
+    entry("group", "group.created", "A group was created"),
+    entry("group", "group.updated", "A group was renamed or described"),
+    entry("group", "group.removed", "A group was removed"),
+    entry("group", "group.members_changed", "A group's members changed"),
+    entry("group", "group.apps_changed", "The apps a group opens changed"),
+    entry("tool", "tool.blocked", "An AI client's tool call was blocked"),
+    entry("tool", "tool.error", "An AI client's tool call failed"),
+    entry("connection", "connection.created", "An AI app was connected"),
+    entry("connection", "connection.revoked", "An AI app connection was revoked"),
+    entry("connection", "connection.used", "Linked dev used the Gateway's services (first call of the day)"),
+    entry("token", "token.created", "A personal access token was created"),
+    entry("token", "token.revoked", "A personal access token was revoked"),
+    entry("access", "access.changed", "Cloudflare Access was turned on or off"),
+    entry("signin_provider", "signin_provider.added", "A sign-in provider (Continue with Google, …) was turned on"),
+    entry("signin_provider", "signin_provider.removed", "A sign-in provider was turned off"),
+    entry("mcp_app", "mcp_app.added", "An MCP app was added"),
+    entry("mcp_app", "mcp_app.removed", "An MCP app was removed"),
+    entry("mcp_app", "mcp_app.enabled", "An MCP app is being served again"),
+    entry("mcp_app", "mcp_app.disabled", "An MCP app stopped being served"),
+    entry("mcp_app", "mcp_app.updated", "An MCP app's risk default, name or description changed"),
+    entry("mcp_app", "mcp_app.tool_changed", "One tool of an MCP app was overridden: its risk, or on/off"),
+    entry("provider", "provider.added", "A provider was registered"),
+    entry("provider", "provider.removed", "A provider was removed"),
+    entry("provider", "provider.updated", "A provider's spec or OAuth client was replaced"),
+    entry("provider", "provider.connected", "Someone connected an account at an OAuth provider"),
+    entry("provider", "provider.disconnected", "An OAuth provider account was disconnected"),
+    entry("provider", "provider.connection_expired", "An OAuth provider refused to refresh a connection; it needs reconnecting"),
+    entry("subscription", "subscription.created", "An event subscription was added"),
+    entry("subscription", "subscription.updated", "An event subscription was changed, paused or resumed"),
+    entry("subscription", "subscription.removed", "An event subscription was removed"),
+    entry("subscription", "subscription.redelivered", "A delivery was queued again by hand"),
+    entry("ai", "ai.default_changed", "The default model provider changed"),
+    entry("ai", "ai.model_changed", "A provider's default model changed"),
+    entry("ping", "ping", "A test event, sent to one subscription on request"),
+];
+const typesByName = new Map(EVENT_TYPES.map((info) => [info.type, info]));
+/** The catalogue entry for a type, or undefined for an app's own event. */
+export function eventTypeInfo(type) {
+    return typesByName.get(type);
+}
+/** The prefix every app's own event carries: `app.<app id>.<name>`. */
+export const APP_EVENT_PREFIX = "app.";
+/** An app's event name: `invoice.paid`, `todo_completed`; lowercase, dotted. */
+export const APP_EVENT_NAME_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+export const APP_EVENT_NAME_MAX = 64;
+/** The type an app's event is delivered as. */
+export function appEventType(appId, name) {
+    return `${APP_EVENT_PREFIX}${appId}.${name}`;
+}
+/**
+ * Whether `type` is an app's own event (`app.<id>.<name>`) rather than one
+ * of the gateway's `app.*` entries, which have exactly one segment after
+ * the prefix.
+ */
+export function isAppOwnEventType(type) {
+    return (type.startsWith(APP_EVENT_PREFIX) &&
+        !typesByName.has(type) &&
+        type.slice(APP_EVENT_PREFIX.length).includes("."));
+}
+/** What is wrong with an app event's name, or null. */
+export function appEventNameProblem(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        return "event is required: a name like invoice.paid";
+    }
+    if (name.length > APP_EVENT_NAME_MAX) {
+        return `event is at most ${APP_EVENT_NAME_MAX} characters`;
+    }
+    if (!APP_EVENT_NAME_PATTERN.test(name)) {
+        return "event is lowercase letters, digits and underscores, in segments joined by dots (invoice.paid)";
+    }
+    return null;
+}
+/** Bytes of `data` an app's event may carry, serialized. */
+export const APP_EVENT_DATA_MAX_BYTES = 8 * 1024;
+/** Bytes of `data` any event row may carry (the gateway's own included). */
+export const EVENT_DATA_MAX_BYTES = 16 * 1024;
+/** How deep `data` may nest. */
+export const EVENT_DATA_MAX_DEPTH = 8;
+/** Emits per app per hour (`rate_limit_counters`). */
+export const APP_EVENT_RATE_PER_HOUR = 600;
+/** Subscriptions per organization. */
+export const EVENT_SUBSCRIPTIONS_MAX = 25;
+/** A webhook signing secret's length. */
+export const EVENT_SECRET_MIN_LENGTH = 16;
+export const EVENT_SECRET_MAX_LENGTH = 128;
+/**
+ * Deliveries (the queue and its log) are kept this long. Events themselves
+ * are the audit log and live longer ({@link AUDIT_RETENTION_DAYS}).
+ */
+export const EVENT_RETENTION_DAYS = 30;
+/**
+ * Events are kept this long: Admin → Activity → Audit, `everyapp workspace
+ * audit` and `everyapp_workspace_audit` read them back. A constant, not a
+ * setting.
+ */
+export const AUDIT_RETENTION_DAYS = 90;
+/** The most audit rows one page carries, on every surface. */
+export const AUDIT_PAGE_MAX = 200;
+/** A subscription's URL. */
+export const EVENT_URL_MAX_LENGTH = 2048;
+/** A subscription's name. */
+export const EVENT_SUBSCRIPTION_NAME_MAX = 100;
+/**
+ * The wait after attempt n fails (n from 1): the first attempt is right
+ * after the event; the seventh failure is dead (about 35 hours in all).
+ */
+export const EVENT_RETRY_DELAYS_MS = [
+    60_000, 300_000, 1_800_000, 7_200_000, 28_800_000, 86_400_000,
+];
+export const EVENT_DELIVERY_MAX_ATTEMPTS = EVENT_RETRY_DELAYS_MS.length + 1;
+/** A webhook's answer is awaited this long. */
+export const EVENT_DELIVERY_TIMEOUT_MS = 10_000;
+/** How much of a failed answer's body is read, and how much is kept. */
+export const EVENT_RESPONSE_READ_MAX_BYTES = 1024;
+export const EVENT_RESPONSE_KEEP_CHARS = 200;
+/** The age of a signature's timestamp a receiver should accept. */
+export const EVENT_SIGNATURE_TOLERANCE_SECONDS = 300;
+/** The app-to-gateway route an app emits on (over the EVERY_APP_GATEWAY binding). */
+export const EVENTS_EMIT_PATH = "/api/events/emit";
+/** The headers every webhook delivery carries. */
+export const EVENT_HEADERS = {
+    event: "x-everyapp-event",
+    eventId: "x-everyapp-event-id",
+    delivery: "x-everyapp-delivery",
+    attempt: "x-everyapp-attempt",
+    signature: "x-everyapp-signature",
+};
+/** The Gateway setting that lets http: and private hosts be targets. */
+export const EVENTS_ALLOW_PRIVATE_TARGETS_SETTING = "EVENTS_ALLOW_PRIVATE_TARGETS";
+/**
+ * Name suffixes (and exact names) that mean a local or private machine: a
+ * webhook target under one is refused unless EVENTS_ALLOW_PRIVATE_TARGETS
+ * is "true". One list for the gateway (which checks a URL before every
+ * attempt) and the CLI (which checks it when `everyapp events add` writes
+ * the subscription), so the two never drift.
+ */
+export const EVENT_PRIVATE_NAME_SUFFIXES = [
+    "localhost",
+    "local",
+    "localdomain",
+    "internal",
+    "intranet",
+    "lan",
+    "corp",
+    "private",
+    "home.arpa",
+    "onion",
+];
+/**
+ * Whether a normalized hostname (lowercase, no trailing dot) is a local or
+ * private name: one of {@link EVENT_PRIVATE_NAME_SUFFIXES}, a name under
+ * one (`n8n.lan`, `hooks.acme.corp`), or a bare label (`n8n`), which only
+ * a private resolver answers.
+ */
+export function isPrivateEventTargetName(host) {
+    if (!host.includes("."))
+        return true;
+    return EVENT_PRIVATE_NAME_SUFFIXES.some((suffix) => host === suffix || host.endsWith(`.${suffix}`));
+}
+/** The sinks a subscription delivers to. */
+export const EVENT_SINKS = ["webhook", "email"];
+/** Whom the email sink mails: the organization's owners, or owners and admins. */
+export const EVENT_EMAIL_RECIPIENTS = ["owners", "admins"];
+/**
+ * A subscription pattern: `*` (everything but ping), an exact type, or a
+ * prefix with `.*` (`member.*`, `app.*`, `app.crm.*`). `app.*` matches the
+ * gateway's app events and every app's own.
+ */
+export function eventPatternMatches(pattern, type) {
+    // Everything but a test ping and the bus's own housekeeping: a webhook
+    // hears about subscriptions only when it names `subscription.*`, so a
+    // catch-all's first delivery is the event it was made for, not itself.
+    if (pattern === "*")
+        return type !== "ping" && !type.startsWith("subscription.");
+    if (pattern.endsWith(".*")) {
+        return type.startsWith(pattern.slice(0, -1));
+    }
+    return pattern === type;
+}
+/** Whether any of a subscription's patterns matches the type. */
+export function eventSubscribed(patterns, type) {
+    return patterns.some((pattern) => eventPatternMatches(pattern, type));
+}
+const PATTERN_SHAPE = /^(\*|[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*(\.\*)?)$/;
+/**
+ * What is wrong with a pattern someone typed, or null: a known type, a
+ * prefix of known types (`member.*`), an app's own events (`app.crm.*`,
+ * `app.crm.invoice.paid`), or `*`.
+ */
+export function eventPatternProblem(pattern) {
+    if (!PATTERN_SHAPE.test(pattern) || pattern.length > APP_EVENT_NAME_MAX + 8) {
+        return `"${pattern}" isn't an event type or pattern (member.joined, member.*, app.crm.*, *)`;
+    }
+    if (pattern === "*" || typesByName.has(pattern))
+        return null;
+    if (pattern.endsWith(".*")) {
+        const prefix = pattern.slice(0, -1);
+        if (EVENT_TYPES.some((info) => info.type.startsWith(prefix)))
+            return null;
+        if (pattern.startsWith(APP_EVENT_PREFIX))
+            return null; // app.<id>.*
+        return `"${pattern}" matches no event type (everyapp events types lists them)`;
+    }
+    if (isAppOwnEventType(pattern))
+        return null;
+    return `"${pattern}" isn't an event type (everyapp events types lists them)`;
+}
+/**
+ * A key that reads like a credential. An event's `data` is refused when any
+ * key, at any depth, matches: a payload can't carry a secret by accident,
+ * whether an app's own or the gateway's (the catalogue's builders are
+ * checked by the same rule).
+ */
+export const CREDENTIAL_KEY_PATTERN = /secret|token|password|passwd|authorization|api[_-]?key|private[_-]?key|credential|cookie|session/i;
+function findCredentialKey(value, depth) {
+    if (depth > EVENT_DATA_MAX_DEPTH)
+        return "\0depth";
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = findCredentialKey(item, depth + 1);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (value && typeof value === "object") {
+        for (const [key, inner] of Object.entries(value)) {
+            if (CREDENTIAL_KEY_PATTERN.test(key))
+                return key;
+            const found = findCredentialKey(inner, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Check an event's `data`: a JSON object (not an array, not a scalar), at
+ * most `maxBytes` serialized, nested at most {@link EVENT_DATA_MAX_DEPTH}
+ * deep, with no key named like a credential. Functions, bigints, dates and
+ * the like must already be plain JSON: the caller serializes what it got.
+ */
+export function checkEventData(data, maxBytes = APP_EVENT_DATA_MAX_BYTES) {
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        return {
+            ok: false,
+            code: "event_data_invalid",
+            message: "data is a JSON object",
+        };
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(data);
+    }
+    catch {
+        return {
+            ok: false,
+            code: "event_data_invalid",
+            message: "data must serialize as JSON",
+        };
+    }
+    if (serialized === undefined) {
+        return {
+            ok: false,
+            code: "event_data_invalid",
+            message: "data is a JSON object",
+        };
+    }
+    const bytes = new TextEncoder().encode(serialized).length;
+    if (bytes > maxBytes) {
+        return {
+            ok: false,
+            code: "event_data_too_large",
+            message: `data is at most ${maxBytes.toLocaleString("en-US")} bytes as JSON (this is ${bytes.toLocaleString("en-US")})`,
+            bytes,
+        };
+    }
+    const key = findCredentialKey(JSON.parse(serialized), 1);
+    if (key === "\0depth") {
+        return {
+            ok: false,
+            code: "event_data_invalid",
+            message: `data nests at most ${EVENT_DATA_MAX_DEPTH} levels deep`,
+        };
+    }
+    if (key) {
+        return {
+            ok: false,
+            code: "event_data_refused",
+            message: `data must not carry a credential: the key "${key}" reads like one (secret, token, password, authorization, api key, private key, credential, cookie, session)`,
+            key,
+        };
+    }
+    return { ok: true, bytes };
+}
+/**
+ * The string a webhook delivery is signed over: the timestamp (seconds
+ * since the epoch), a dot, the exact body.
+ */
+export function eventSigningInput(timestamp, body) {
+    return `${timestamp}.${body}`;
+}
+/** `t=<seconds>,v1=<hex>`, as the signature header carries it. */
+export function formatEventSignature(timestamp, hexDigest) {
+    return `t=${timestamp},v1=${hexDigest}`;
+}
+/** The parts of a signature header, or null when it isn't one. */
+export function parseEventSignature(header) {
+    if (!header)
+        return null;
+    let timestamp = null;
+    const v1 = [];
+    for (const part of header.split(",")) {
+        const [key, value] = part.trim().split("=", 2);
+        if (key === "t" && value && /^\d+$/.test(value))
+            timestamp = Number(value);
+        else if (key === "v1" && value && /^[0-9a-f]{64}$/i.test(value)) {
+            v1.push(value.toLowerCase());
+        }
+    }
+    return timestamp !== null && v1.length > 0 ? { timestamp, v1 } : null;
+}

package/dist/internal/gatewaySettings.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The Gateway's settings and the app's own secrets, by name: the Gateway
+ * settings an operator changes with `everyapp secret set <NAME>` (plain
+ * secrets on the Gateway Worker, read on its next request), the ones the
+ * install writes once, and the names an app's own secret can never take.
+ * What an app's manifest needs of them is appSettings.ts. One registry serves
+ * the CLI (a Gateway name goes to the Gateway, any other to the app in the
+ * current directory), the manifest validator (an app's `secrets` may not
+ * take a Gateway name, since the app reaches those through `providers` and
+ * `capabilities`) and the Gateway's dev config, which a test keeps
+ * declaring every settable one.
+ */
+import { type CapabilitySecret } from "./capabilities.js";
+/**
+ * The Gateway's own settings: the install writes them once (`everyapp
+ * setup`), or an operator by hand (THIRD_PARTY_DEPLOYS), and `everyapp
+ * secret set` never changes them. An app's own Worker may still have a
+ * secret of the same name (OpenSEO's BETTER_AUTH_SECRET): the two never meet.
+ */
+export declare const INSTALL_OWNED_GATEWAY_SETTINGS: readonly ["GATEWAY_URL", "APP_BASE_DOMAIN", "BETTER_AUTH_SECRET", "JWT_PRIVATE_KEY", "JWT_PUBLIC_KEY", "GATEWAY_DEPLOYMENT_MODE", "CLOUDFLARE_ACCOUNT_ID", "THIRD_PARTY_DEPLOYS"];
+export declare function isInstallOwnedGatewaySetting(name: string): boolean;
+/** The Gateway's own optional settings `everyapp secret set` changes: nothing a provider reads. */
+export declare const GATEWAY_OWN_SETTINGS: readonly ["AI_PROXY_EXTRA_ROUTES", "EMAIL_REST_API_TOKEN", "RESEND_API_KEY", "EMAIL_PROVIDER", "EMAIL_FROM", "EMAIL_FROM_NAME", "MCP_OAUTH_ENABLED", "MCP_DCR_ENABLED", "MCP_ALLOWED_ORIGINS", "MCP_AUDIT_RETENTION_DAYS", "CLOUDFLARE_ACCESS_OIDC_ISSUER", "CLOUDFLARE_ACCESS_OIDC_CLIENT_ID", "CLOUDFLARE_ACCESS_OIDC_CLIENT_SECRET", "CLOUDFLARE_ACCESS_OIDC_LABEL", "CLOUDFLARE_ACCESS_TEAM_DOMAIN", "CLOUDFLARE_ACCESS_AUD", "CLOUDFLARE_ACCESS_APPS_AUD", "CLOUDFLARE_ACCESS_AUTO_JOIN_DOMAINS", "CLOUDFLARE_ACCESS_OUTER_RING_AUTO_JOIN", "EMAIL_PASSWORD_SIGN_IN", "HOSTED_OPEN_SIGNUP", "CF_DEPLOY_TOKEN", "BROWSER_APP_INSTALLS", "DISPATCH_NAMESPACE", "THIRD_PARTY_DOMAIN", "EVENTS_ALLOW_PRIVATE_TARGETS"];
+export type SettableGatewaySetting = Exclude<CapabilitySecret, (typeof INSTALL_OWNED_GATEWAY_SETTINGS)[number]> | (typeof GATEWAY_OWN_SETTINGS)[number];
+/**
+ * The Gateway's optional settings `everyapp secret set` changes: every
+ * setting a catalog provider reads, the Gateway's own, then the sign-in
+ * providers' (`<ID>_SIGNIN_<FIELD>`, ./signInProviders.ts).
+ */
+export declare const SETTABLE_GATEWAY_SETTINGS: readonly SettableGatewaySetting[];
+/**
+ * The credential names of remote MCP apps (`everyapp mcp add <url>`,
+ * ./remoteMcp.ts): `<ID>_MCP_TOKEN` by default, any name ending in
+ * `_MCP_TOKEN` by choice. A family rather than a list, so the names a
+ * registry row declares at run time route to the Gateway like the fixed
+ * names (`everyapp secret set` reads no registry to decide), an app's own
+ * secret can never take one (the manifest validator refuses the family),
+ * and a remote server can never be given a fixed provider key.
+ */
+export declare const REMOTE_MCP_SECRET_PATTERN: RegExp;
+/** Whether `name` is a remote MCP app's credential name (`TREG_MCP_TOKEN`). */
+export declare function isRemoteMcpSecretName(name: string): boolean;
+/**
+ * Whether `everyapp secret set <name>` changes the Gateway: one of the
+ * fixed settings, or a remote MCP app's credential name.
+ */
+export declare function isSettableGatewaySetting(name: string): boolean;
+/**
+ * Settable Gateway settings whose value is a plain word, address, list
+ * or switch rather than a credential: a sender, a provider choice, a
+ * URL, an audience, a flag. `everyapp secret set` may show these as they
+ * are typed and check their shape; anything else is a credential and
+ * stays hidden.
+ */
+export declare const PLAIN_GATEWAY_SETTINGS: readonly ["EMAIL_FROM", "EMAIL_FROM_NAME", "EMAIL_PROVIDER", "EMAIL_PASSWORD_SIGN_IN", "AI_PROXY_EXTRA_ROUTES", "MCP_OAUTH_ENABLED", "MCP_DCR_ENABLED", "MCP_ALLOWED_ORIGINS", "MCP_AUDIT_RETENTION_DAYS", "CLOUDFLARE_ACCESS_OIDC_ISSUER", "CLOUDFLARE_ACCESS_OIDC_CLIENT_ID", "CLOUDFLARE_ACCESS_OIDC_LABEL", "CLOUDFLARE_ACCESS_TEAM_DOMAIN", "CLOUDFLARE_ACCESS_AUD", "CLOUDFLARE_ACCESS_APPS_AUD", "CLOUDFLARE_ACCESS_AUTO_JOIN_DOMAINS", "CLOUDFLARE_ACCESS_OUTER_RING_AUTO_JOIN", "HOSTED_OPEN_SIGNUP", "BROWSER_APP_INSTALLS", "DISPATCH_NAMESPACE", "THIRD_PARTY_DOMAIN", "EVENTS_ALLOW_PRIVATE_TARGETS"];
+/** Whether a settable Gateway setting's value is a plain value, not a credential. */
+export declare function isPlainGatewaySetting(name: string): boolean;
+/**
+ * Settable Gateway settings only the hosted gateway reads: a self-hosted
+ * install never needs them, so `secret list` leaves them out there.
+ */
+export declare const HOSTED_ONLY_GATEWAY_SETTINGS: readonly ["HOSTED_OPEN_SIGNUP", "DISPATCH_NAMESPACE", "THIRD_PARTY_DOMAIN"];
+export declare function isHostedOnlyGatewaySetting(name: string): boolean;
+/** Gateway settings for local testing only, set in the gateway's `.dev.vars`, never deployed. */
+export declare const DEV_ONLY_GATEWAY_SETTINGS: readonly ["MCP_ACCESS_TOKEN_TTL", "DATAFORSEO_SANDBOX"];
+export declare function isDevOnlyGatewaySetting(name: string): boolean;
+/** What the reserved names are, for messages. */
+export declare const RESERVED_APP_SECRET_NAMES_TEXT = "GATEWAY_URL, CF_VERSION_METADATA and the EVERYAPP_*, EVERY_APP_* and APP__* names";
+export declare function isReservedAppSecretName(name: string): boolean;
+/** Which AI provider or capability reads a Gateway setting, if any does. */
+export type GatewaySettingOwner = {
+    kind: "provider";
+    id: string;
+} | {
+    kind: "capability";
+    id: string;
+};
+/**
+ * The AI provider or capability a Gateway setting belongs to: what to list
+ * in a manifest instead of holding the key as the app's own.
+ */
+export declare function gatewaySettingOwner(name: string): GatewaySettingOwner | null;
+//# sourceMappingURL=gatewaySettings.d.ts.map

package/dist/internal/gatewaySettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatewaySettings.d.ts","sourceRoot":"","sources":["../../src/internal/gatewaySettings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAM3B;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,mLASjC,CAAC;AAMX,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElE;AAmBD,mGAAmG;AACnG,eAAO,MAAM,oBAAoB,yrBAkCvB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAC9B,OAAO,CAAC,gBAAgB,EAAE,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC,GAC1E,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,sBAAsB,EAItE,CAAC;AAIF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAgC,CAAC;AAEvE,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,olBAuBmB,CAAC;AASvD,qFAAqF;AACrF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,6EAIa,CAAC;AAIvD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,iGAAiG;AACjG,eAAO,MAAM,yBAAyB,yDAI5B,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAmBD,iDAAiD;AACjD,eAAO,MAAM,8BAA8B,sFAC0C,CAAC;AAEtF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAQ5E"}