@plitzi/sdk-server 0.33.1 → 0.34.0

package/dist/modules/actions/transport/webhookHandler.js

@@ -0,0 +1,206 @@
+import { ActionRunError } from "../runtime/errors.js";
+import { findTriggerNode, triggerParams } from "../runtime/triggers.js";
+import { precheckRun } from "../runtime/precheck.js";
+import onAbort from "../../../helpers/onAbort.js";
+import { reportReject } from "../runtime/report.js";
+import { verifySignature } from "./verifySignature.js";
+import { triggerHasStaleVerify, triggerVerify } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/transport/webhookHandler.ts
+var DEFAULT_PER_MINUTE = 60;
+var send = (res, status, payload) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	res.send(JSON.stringify(payload));
+};
+/**
+* The signing secret, from the credential the verification NAMES.
+*
+* Named outright rather than templated. This runs before anything else does — before the body is parsed, before a
+* run exists — so there is no flow scope for a token to resolve against, and one that rendered to nothing would
+* leave the endpoint verifying every request against an empty secret.
+*/
+var resolveSecret = async (verification, spaceId, getCredential) => {
+	const secret = (await getCredential?.(spaceId, verification.credential))?.[verification.secretField ?? "secret"];
+	return typeof secret === "string" ? secret : "";
+};
+/**
+* Handles an inbound webhook.
+*
+* The public face of an action, and the one an attacker can reach without a session — so everything that costs
+* anything happens after the signature is checked, in this order: the action must exist and declare the trigger,
+* the rate limit must allow it, the signature must verify, and only then does a run start.
+*
+* The answer is deliberately thin. A sender needs to know it was accepted; it has no business learning whether an
+* action exists, why a run failed, or what the flow did — and a 404 that distinguishes "no such action" from
+* "wrong signature" is an oracle for both.
+*/
+var handleActionWebhook = async (deps) => {
+	const { req, res, config, module, signal, actionId, callerId, lineage } = deps;
+	const { environment = "main", spaceId, revision = 0 } = req.ctx.spaceDeployment ?? {};
+	if (typeof spaceId !== "number") {
+		send(res, 404, { error: "Not found" });
+		return;
+	}
+	/**
+	* Every way this ends without a run, told to whoever configured the endpoint.
+	*
+	* A rejected webhook is the single most common way an integration is broken, and until this existed it was
+	* indistinguishable from the sender never firing: the reason went to the process log, where the person setting
+	* up the integration cannot see it. The SENDER still learns nothing it should not — that answer is unchanged.
+	*/
+	const reject = (reason, detail) => reportReject(config, {
+		actionId,
+		spaceId,
+		environment,
+		trigger: "webhook",
+		reason,
+		callerId,
+		...detail === void 0 ? {} : { detail }
+	});
+	const entry = await config.action?.lookups?.getAction(spaceId, actionId);
+	const trigger = entry ? findTriggerNode(entry.document.nodes, "webhook") : void 0;
+	if (!entry || !trigger) {
+		await reject("not_found", entry ? "The action declares no webhook trigger" : "No action with this identifier");
+		send(res, 404, { error: "Not found" });
+		return;
+	}
+	const stepParams = triggerParams(trigger);
+	const verify = triggerVerify(stepParams);
+	/**
+	* A verification nothing reads is not an unsigned webhook — it is a broken one, and it is refused.
+	*
+	* The check used to be a JSON blob and is now fields on the step. A document stored before that carries the
+	* blob and no signing credential, and reading it as "unsigned" would turn a protected endpoint into a public
+	* one without a single line of it changing. Fail closed, and say which document to fix.
+	*/
+	if (triggerHasStaleVerify(stepParams)) {
+		console.error(`[Actions] webhook "${actionId}" in space ${spaceId} carries a signature check in a format nothing reads any more, so it is refused. Name the signing credential on the trigger step.`);
+		await reject("unverifiable", "The signature check is in a format nothing reads any more; name the signing credential on the trigger step");
+		send(res, 503, { error: "Unavailable" });
+		return;
+	}
+	const perMinute = config.action?.rateLimit?.webhookPerMinute ?? DEFAULT_PER_MINUTE;
+	const window = Math.floor(Date.now() / 6e4);
+	try {
+		if (await module.kv(spaceId).increment(`hook:${actionId}:${callerId}:${window}`, 1, 120) > perMinute) {
+			res.setHeader("Retry-After", "60");
+			await reject("rate_limited", `More than ${perMinute} deliveries in one minute from this caller`);
+			send(res, 429, { error: "Too many requests" });
+			return;
+		}
+	} catch {
+		await reject("unverifiable", "The rate-limit store could not answer, so the endpoint failed closed");
+		send(res, 503, { error: "Unavailable" });
+		return;
+	}
+	const rawBody = req.body ?? "";
+	if (verify) {
+		const secret = await resolveSecret(verify, spaceId, config.action?.lookups?.getCredential);
+		const check = verifySignature(verify, secret, req.headers, rawBody);
+		if (!check.ok) {
+			console.warn(`[Actions] webhook "${actionId}" rejected: ${check.reason}`);
+			await reject("invalid_signature", check.reason);
+			send(res, 401, { error: "Invalid signature" });
+			return;
+		}
+	}
+	let payload = {};
+	try {
+		const parsed = rawBody ? JSON.parse(rawBody) : {};
+		payload = parsed !== null && typeof parsed === "object" ? parsed : {};
+	} catch {
+		await reject("malformed_body", "The body is not JSON");
+		send(res, 400, { error: "Body is not JSON" });
+		return;
+	}
+	const input = {
+		...payload,
+		payload
+	};
+	const limits = module.limitsFor(entry.document);
+	const begin = {
+		spaceId,
+		actionId: entry.id,
+		callerId,
+		input,
+		idempotencyKey: deliveryId(req),
+		sharedKey: true,
+		ttlMs: limits.timeoutMs
+	};
+	const replayed = await module.guards.replay(begin);
+	if (replayed) {
+		send(res, 202, {
+			accepted: true,
+			runId: replayed.runId,
+			status: replayed.status,
+			replayed: true
+		});
+		return;
+	}
+	let run;
+	try {
+		precheckRun(entry, {
+			trigger: "webhook",
+			input,
+			lineage
+		});
+		run = await module.guards.begin(begin);
+	} catch (error) {
+		const reason = error instanceof ActionRunError ? error.reason : "failed";
+		await reject(reason, error instanceof Error ? error.message : void 0);
+		send(res, reason === "duplicate" ? 202 : 400, { accepted: reason === "duplicate" });
+		return;
+	}
+	await config.adapters.meter?.({
+		kind: "server_action",
+		cached: false,
+		req,
+		spaceId,
+		environment,
+		revision
+	});
+	const abortRun = () => run.controller.abort();
+	const releaseAbort = onAbort(signal, abortRun);
+	let outcome;
+	try {
+		const result = await module.runAction({
+			entry,
+			input,
+			spaceId,
+			environment,
+			trigger: "webhook",
+			callerId,
+			runId: run.runId,
+			lineage,
+			signal: run.controller.signal
+		});
+		outcome = result;
+		send(res, 200, {
+			accepted: true,
+			runId: result.runId,
+			status: result.status
+		});
+	} catch (error) {
+		console.error("[Actions] webhook run failed:", error);
+		send(res, 500, { accepted: false });
+	} finally {
+		releaseAbort();
+		await module.guards.end(run, outcome);
+	}
+};
+/** The delivery id a provider sends, under the header names the common ones use. */
+var deliveryId = (req) => {
+	for (const name of [
+		"x-plitzi-delivery",
+		"x-github-delivery",
+		"x-request-id",
+		"idempotency-key"
+	]) {
+		const value = req.headers[name];
+		const single = Array.isArray(value) ? value[0] : value;
+		if (single) return single;
+	}
+};
+//#endregion
+export { handleActionWebhook };

package/dist/modules/actions/transport/webhookHandler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/actions/types.d.ts

@@ -0,0 +1,234 @@
+import { ActionEntry, ActionLimits, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTriggerType, ConnectorManifest, Environment, InteractionCallbackParam, InteractionNode, InteractionNodeStatus, SpaceRevision, SSRUser } from '@plitzi/sdk-shared';
+/** Resolved secret material, as the connector engine already models it. */
+export type ActionCredential = Record<string, string>;
+/**
+ * A connector with its secret already resolved.
+ *
+ * Handed over as one thing because the engine needs both, and a task holding only the manifest would have to go
+ * looking for the credential itself — which is exactly the lookup that must not be open to a task. Authorizing
+ * the connector authorizes the credential it names: that is what the `/_action` write endpoint has always done.
+ */
+export type ResolvedConnector = {
+    manifest: ConnectorManifest;
+    credential?: ActionCredential;
+};
+/**
+ * A connection to a database that is NOT this deployment's.
+ *
+ * Registered by the deployment, one per engine it supports, and reached only through a credential the space
+ * declared — which is the whole security position of `db.query`: a flow queries a database its owner configured,
+ * never the one holding other tenants' spaces.
+ *
+ * `params` are BOUND, never interpolated. The task refuses a statement containing a template for exactly that
+ * reason, and a driver that pastes them into the SQL itself would undo the rule from the other end.
+ */
+export type ActionDbDriver = {
+    /** Engine name a credential names, e.g. `mysql`, `postgres`. */
+    engine: string;
+    query: (dsn: string, sql: string, params: unknown[], signal: AbortSignal) => Promise<unknown[]>;
+};
+/**
+ * Where a deployment keeps the `kv` tasks' data — Redis, Memcached, a table, whatever it already runs.
+ *
+ * Deliberately the DUMBEST possible surface: five operations over strings, with no rule to obey. Everything that
+ * decides how a counter behaves — the key prefixing, the JSON round trip, and the one rule a rate limit lives or
+ * dies by — is `createKvStore`'s, above this. An adapter that had to remember "extend the TTL only when the
+ * counter did not exist" would be an adapter each deployment gets to write that rule wrongly in.
+ *
+ * Making it a seam at all is what keeps rate limiting and idempotency across replicas a deployment's decision
+ * rather than a silent no-op: the in-process default counts only its own replica, and honestly says so.
+ */
+export type ActionKvAdapter = {
+    /** The stored string, or undefined when the key is absent OR has expired. */
+    get: (key: string) => Promise<string | undefined>;
+    set: (key: string, value: string, ttlSeconds?: number) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    /** Adds to a counter and answers the NEW total. Must be atomic — this is what get-then-set cannot be. */
+    increment: (key: string, amount: number) => Promise<number>;
+    /** Sets a lifetime on a key that already exists. When to call it is decided above, never here. */
+    expire: (key: string, ttlSeconds: number) => Promise<void>;
+};
+/**
+ * The `kv` tasks' own view: values rather than strings, and a TTL that means what a caller expects.
+ *
+ * Built by `createKvStore` over an {@link ActionKvAdapter}, and then narrowed to one space by `namespaceKv`. A
+ * task never sees an adapter.
+ */
+export type ActionKvStore = {
+    get: (key: string) => Promise<unknown>;
+    set: (key: string, value: unknown, ttlSeconds?: number) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    increment: (key: string, amount: number, ttlSeconds?: number) => Promise<number>;
+};
+/** Re-exported so the module's files import one place. One type for actions and connectors: it is one concept. */
+export type { SpaceRevision } from '@plitzi/sdk-shared';
+/**
+ * How the server reaches a space's actions. Structurally identical in spirit to `ConnectorLookups`: the module
+ * never learns where a deployment stores anything.
+ */
+export type ActionLookups = {
+    getAction: (spaceId: number, actionId: string, at?: SpaceRevision) => Promise<ActionEntry | undefined>;
+    /** Only the builder's catalog, the MCP and the scheduler need the list; a page call never asks for it. */
+    listActions?: (spaceId: number, at?: SpaceRevision) => Promise<ActionEntry[]>;
+    getCredential?: (spaceId: number, identifier: string) => Promise<ActionCredential | undefined>;
+    getConnector?: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<ConnectorManifest | undefined>;
+};
+/**
+ * The only door a task has to the outside world.
+ *
+ * `credential` and `connector` answer solely for identifiers the running document declared, so a task cannot reach
+ * a secret the action did not ask for — the check lives here rather than in each task, where it would be optional.
+ * `fetch` is the run's own: abort-wired and counted against the request budget.
+ */
+export type ActionTaskContext = {
+    runId: string;
+    spaceId: number;
+    environment: Environment;
+    trigger: ActionTriggerType;
+    user?: SSRUser;
+    /**
+     * Who is asking, as the transport identified them: `user:<id>` for a session, `ip:<address>` for everyone else,
+     * and `render` or `schedule` for the runs no visitor started.
+     *
+     * A task that must happen once per PERSON has nothing else to key on — a `public` action has no session, and an
+     * identifier the caller sent is not an identity. Coarse by construction, since a shared address is one caller,
+     * and personal data when it is one: a task that stores it is storing that.
+     */
+    callerId: string;
+    signal: AbortSignal;
+    /**
+     * The flow scope as the current node sees it: `input`, every previous node's result by id, `user`, and the
+     * credentials the document declared. Read-only, and present because a `rawParams` task has to render templates
+     * against something.
+     */
+    scope: Readonly<Record<string, unknown>>;
+    credential: (identifier: string) => Promise<ActionCredential | undefined>;
+    connector: (connectorId: string) => Promise<ResolvedConnector | undefined>;
+    fetch: typeof fetch;
+    /** Key/value storage, namespaced to this space by the runner — a key one space writes is a key only it reads. */
+    kv: ActionKvStore;
+    /** The database engines this deployment registered, for the `db.query` task. */
+    dbDrivers: ActionDbDriver[];
+    /** Pushes a `data` frame to a streaming caller. A no-op when nobody negotiated a stream. */
+    emit: (chunk: unknown) => void;
+};
+/**
+ * One step a server action can take.
+ *
+ * `params` is the same `InteractionCallbackParam` map the builder's WorkflowNode already renders, which is what
+ * lets a deployment's own task appear in its editor without a single change there.
+ */
+export type ActionTask<T extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Addressed in a node as `<namespace>.<action>`. */
+    namespace: string;
+    action: string;
+    title: string;
+    description?: string;
+    params: Record<keyof T, InteractionCallbackParam<T>>;
+    /**
+     * Receive params BEFORE twig resolution. Only for a task whose whole job is to render a template — resolving
+     * first would consume the very tokens it exists to interpret. The client engine special-cases `twigTemplate` by
+     * name for this; a flag is the same rule without the name check.
+     */
+    rawParams?: boolean;
+    run: (params: T, ctx: ActionTaskContext) => unknown;
+};
+/** A task with its addressable name resolved, as the registry stores and lists it. */
+export type RegisteredTask = ActionTask<Record<string, unknown>> & {
+    name: string;
+};
+export type ActionTaskRegistry = {
+    get: (name: string) => RegisteredTask | undefined;
+    list: () => RegisteredTask[];
+};
+/** What a deployment hands to `createServer` under `actions`. Absent → the module is never constructed. */
+export type ActionsConfig = {
+    lookups: ActionLookups;
+    /** Deployment-owned tasks, validated at boot against the built-ins. */
+    tasks?: ActionTask<never>[];
+    /** Ceilings a per-action document may tighten but never exceed. */
+    limits?: ActionLimits;
+    /** How many runs may be in flight at once. Counted per space and for the process as a whole. */
+    concurrency?: {
+        perSpace?: number;
+        perProcess?: number;
+        renderPerProcess?: number;
+    };
+    /** Where the `kv` tasks keep things. Omitted → an in-process Map, which is per-replica by definition. */
+    kv?: ActionKvAdapter;
+    /** Inbound webhooks are public, so they are counted per caller per minute. Default 60. */
+    rateLimit?: {
+        webhookPerMinute?: number;
+    };
+    /** Database engines this deployment lets a flow reach. Empty → the `db.query` task is not offered at all. */
+    dbDrivers?: ActionDbDriver[];
+    /**
+     * Called once per run that started, for a deployment that keeps a record.
+     *
+     * Best-effort by contract: it is awaited but never allowed to fail a run — a logging outage must not take an
+     * action down, which is the same rule metering follows.
+     */
+    onRun?: (record: ActionRunRecord) => void | Promise<void>;
+    /**
+     * Called once per request that was REFUSED before it became a run.
+     *
+     * Its own hook rather than a status on `onRun`, because the two answer different questions and a deployment
+     * wants them in different places: runs are history, refusals are a fault report. Without it a webhook rejected
+     * for a bad signature is invisible to everyone but whoever reads the process log — which is nobody, on the
+     * afternoon the integration is being set up.
+     *
+     * Everything is reported, including the refusals that are somebody else retrying politely. Which of them are
+     * worth keeping is a policy the deployment owns; the mechanism does not decide it by staying quiet.
+     */
+    onReject?: (record: ActionRejectRecord) => void | Promise<void>;
+    /**
+     * How long a COMPLETED run's answer may be replayed to a caller that asks for it again by the same key.
+     *
+     * Off by default, and it only ever applies to an explicit key — an `idempotencyKey` on the call, or the
+     * delivery id a webhook sender stamps. A derived key is a hash of the input, and two identical calls a minute
+     * apart are usually two things somebody wants to happen twice.
+     *
+     * Needs a shared {@link ActionKvAdapter} to mean anything across replicas, exactly as single-flight does.
+     */
+    idempotency?: {
+        replayTtlMs?: number;
+    };
+    fetchImpl?: typeof fetch;
+};
+/** Re-exported so the module's own files import one place, and a deployment writing an `onRun` or an `onReject`
+ *  sees the same shapes the module emits. */
+export type { ActionRejectRecord, ActionRunRecord } from '@plitzi/sdk-shared';
+export type ResolvedActionLimits = Required<ActionLimits>;
+export type ActionRunRequest = {
+    entry: ActionEntry;
+    input: Record<string, unknown>;
+    spaceId: number;
+    environment: Environment;
+    trigger: ActionTriggerType;
+    user?: SSRUser;
+    /** Who is asking. Stated by whatever started the run — see {@link ActionTaskContext.callerId}. */
+    callerId: string;
+    runId: string;
+    /** Chain of run ids that caused this one; a run naming its own action is refused before its first node. */
+    lineage?: string[];
+    /**
+     * The published version this run belongs to, when a page started it.
+     *
+     * The action was read as of this revision, so the connectors it calls are read as of it too — a flow and the
+     * manifests it goes through are one published thing, and mixing versions inside one run is the discrepancy in
+     * miniature.
+     */
+    at?: SpaceRevision;
+    emit?: (chunk: unknown) => void;
+    /** Reports each step as it settles, for a caller watching the run happen. Absent for a plain request/response. */
+    onNode?: (id: string, status: InteractionNodeStatus) => void;
+    signal?: AbortSignal;
+};
+export type ActionRunResult = {
+    runId: string;
+    status: ActionRunStatus;
+    /** Projected down to the document's declared `output`. Never the raw flow scope. */
+    output: Record<string, unknown>;
+    /** The same shape the dev-tools Interactions panel renders. Redacted before it leaves the process. */
+    trace: InteractionNode[];
+};

package/dist/modules/connectors/engine.js

@@ -1,6 +1,7 @@
 import { getByPath } from "./getByPath.js";
-import { BODYLESS_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS } from "@plitzi/sdk-shared/connectors";
+import { assertOutboundAllowed } from "../../helpers/outboundGuard.js";
 import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
+import { BODYLESS_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS } from "@plitzi/sdk-shared/connectors";
 //#region src/modules/connectors/engine.ts
 var DEFAULT_LIMIT = 10;
 /** Only scalars can become a URL fragment, a header or a record key. Anything else is treated as absent. */
@@ -149,6 +150,7 @@ var fetchConnectorRecords = async ({ manifest, endpoint = DEFAULT_READ_ENDPOINT,
 		...renderEntries(read.query ?? {}, variables),
 		...renderFilters(resolved, connection.operators, variables)
 	}).forEach(([key, value]) => url.searchParams.set(key, value));
+	await assertOutboundAllowed(url);
 	const method = read.method ?? "GET";
 	const headers = {
 		...applyAuth(connection, variables, url),
@@ -200,6 +202,7 @@ var writeConnectorRecord = async ({ manifest, credential = {}, action, resource,
 	};
 	const url = new URL(render(operation.path, variables), connection.baseUrl);
 	Object.entries(renderEntries(operation.query ?? {}, variables)).forEach(([key, value]) => url.searchParams.set(key, value));
+	await assertOutboundAllowed(url);
 	const headers = {
 		...applyAuth(connection, variables, url),
 		...renderEntries(operation.headers ?? {}, variables)

package/dist/modules/connectors/resolver.d.ts

@@ -1,8 +1,16 @@
 import { ConnectorCredential, ConnectorManifest } from './types';
 import { RscElementResolver } from '../rsc/resolveRscData';
+import { SpaceRevision } from '@plitzi/sdk-shared';
 export type ConnectorLookups = {
-    /** Reads a manifest by id. Server-side state: manifests name endpoints and must never reach the browser. */
-    getConnector: (spaceId: number, connectorId: string) => Promise<ConnectorManifest | undefined>;
+    /**
+     * Reads a manifest by id, as of a published revision. Server-side state: manifests name endpoints and must never
+     * reach the browser.
+     *
+     * `at` absent means the live document, the one the builder edits. A page passes the revision it was published
+     * at, so it reads through the manifest it shipped with rather than whatever it says after somebody points that
+     * connector at a different API.
+     */
+    getConnector: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<ConnectorManifest | undefined>;
     /** Resolves the secret referenced by `manifest.credential`. */
     getCredential?: (spaceId: number, identifier: string) => Promise<ConnectorCredential | undefined>;
     fetchImpl?: typeof fetch;

package/dist/modules/connectors/resolver.js

@@ -28,11 +28,16 @@ var toPage = (queryParams, attributes) => {
 * An element without a connector resolves to nothing rather than failing — an unconfigured provider on a page is a
 * draft, not an error.
 */
-var createConnectorResolver = ({ getConnector, getCredential, fetchImpl }) => async ({ element, flat, routeParams, queryParams, spaceId }) => {
+var createConnectorResolver = ({ getConnector, getCredential, fetchImpl }) => async ({ element, flat, routeParams, queryParams, spaceId, environment, req }) => {
+	const deployment = req.ctx.spaceDeployment;
+	const at = {
+		environment: deployment?.environment ?? environment,
+		revision: deployment?.revision ?? 0
+	};
 	const attributes = element.attributes;
 	const { connector: connectorId, endpoint, resource, limit, singleRecord = false, filters } = attributes;
 	if (!connectorId) return;
-	const manifest = await getConnector(spaceId, connectorId);
+	const manifest = await getConnector(spaceId, connectorId, at);
 	if (!manifest) throw new Error(`Connector "${connectorId}" is not configured for space ${spaceId}`);
 	const credential = manifest.credential && getCredential ? await getCredential(spaceId, manifest.credential) : void 0;
 	const pageSize = toLimit(limit, singleRecord);
@@ -62,7 +67,7 @@ var createConnectorResolver = ({ getConnector, getCredential, fetchImpl }) => as
 		errorMessage: ""
 	};
 	if (manifest.projection === "full") return slice;
-	return projectSlice(slice, collectBoundPaths(flat, element.id, getSourceName(element.definition.type, element)));
+	return projectSlice(slice, collectBoundPaths(flat, element.id, getSourceName(element.definition.type, element.id)));
 };
 //#endregion
 export { createConnectorResolver };

package/dist/modules/mysql/accounts.d.ts

@@ -0,0 +1,5 @@
+import { Tables } from './config';
+import { Queryable } from './query';
+import { AccountAdapters } from '../../core/auth/api';
+import { IdentityAdapters } from '../../core/auth/identity';
+export declare const createAccountStore: (db: Queryable, t: Tables) => IdentityAdapters & AccountAdapters;