@plitzi/sdk-server 0.33.1 → 0.34.0

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

@@ -0,0 +1,233 @@
+import { ActionRunError } from "../runtime/errors.js";
+import { triggerParams } from "../runtime/triggers.js";
+import { precheckRun } from "../runtime/precheck.js";
+import onAbort from "../../../helpers/onAbort.js";
+import { openStream, wantsStream } from "./stream.js";
+import { reportReject } from "../runtime/report.js";
+import { triggerAccess } from "@plitzi/sdk-shared/actions";
+//#region src/modules/actions/transport/callHandler.ts
+/**
+* How a refusal reaches the caller.
+*
+* Every reason maps to a status the client can act on without parsing prose — a 409 means "your other run is still
+* going", a 429 means "come back", a 508 means "you built a loop". `recursion` is the one worth the unusual code:
+* 508 Loop Detected says exactly what happened, and anything else would read as a server fault.
+*/
+var STATUS_BY_REASON = {
+	not_found: 404,
+	disabled: 409,
+	unauthenticated: 401,
+	forbidden: 403,
+	invalid_input: 422,
+	duplicate: 409,
+	over_capacity: 429,
+	recursion: 508,
+	timeout: 504,
+	aborted: 499,
+	failed: 500
+};
+var parseBody = (body) => {
+	if (!body) return;
+	try {
+		const parsed = JSON.parse(body);
+		return parsed !== null && typeof parsed === "object" ? parsed : void 0;
+	} catch {
+		return;
+	}
+};
+var send = (res, status, payload, runId) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	if (runId) res.setHeader("X-Plitzi-Run-Id", runId);
+	res.send(JSON.stringify(payload));
+};
+var fail = (res, reason, error, runId) => send(res, STATUS_BY_REASON[reason], {
+	error,
+	reason
+}, runId);
+/**
+* Whether the caller may be told what the flow DID, as opposed to what it answered.
+*
+* The dev-tools Actions tab reads the trace, so this is the rule that decides what it can show — and it is the
+* action's own access rule, not the server's mode. An action open to everybody has already decided that starting
+* it is anybody's business, so its steps are too; one that asks for a session owes its steps to a session and to
+* nobody else. `devMode` on its own is not an answer to that question: it says this deployment is being built,
+* not that whoever just posted to the endpoint is the person building it.
+*
+* It is deliberately a second lock on a door `precheckRun` already shut — an anonymous call to a `session` action
+* never becomes a run. That is the point: the trace is the one part of the answer that carries the author's own
+* data, and the day a deployment mounts a trigger of its own is the day it stops being covered by the first lock.
+*/
+var mayReadTrace = (trigger, user) => triggerAccess(triggerParams(trigger))?.mode === "public" || user !== void 0;
+/**
+* Handles an action-addressed call.
+*
+* The browser names an action and hands it inputs. Everything that decides whether the run may happen — the
+* document, the access rule, the input contract, the lineage — is the runner's, so a deployment mounting its own
+* trigger cannot end up with a weaker set of checks than this endpoint applies.
+*/
+var handleActionCall = async (deps) => {
+	const { req, res, raw, config, module, signal, callerId, lineage } = deps;
+	const { environment = "main", spaceId, revision = 0, authoring } = req.ctx.spaceDeployment ?? {};
+	if (typeof spaceId !== "number") {
+		fail(res, "not_found", "Invalid space deployment");
+		return;
+	}
+	const body = parseBody(req.body);
+	if (!body?.actionId) {
+		fail(res, "invalid_input", "Expected { actionId, input }");
+		return;
+	}
+	/**
+	* A call that never became a run, told to whoever keeps the deployment's records.
+	*
+	* The caller already learns the reason from the status and the payload — that is what makes a refusal
+	* actionable for them. This is the other half: an author watching their own space see that calls are arriving
+	* and being turned away, which is otherwise a thing only the browser's network tab knows.
+	*/
+	const reject = (reason, detail) => reportReject(config, {
+		actionId: body.actionId,
+		spaceId,
+		environment,
+		trigger: "call",
+		reason,
+		callerId,
+		...detail === void 0 ? {} : { detail }
+	});
+	const entry = await config.action?.lookups?.getAction(spaceId, body.actionId, {
+		environment,
+		revision
+	});
+	if (!entry) {
+		await reject("not_found", "No action with this identifier at the revision being served");
+		fail(res, "not_found", "Unknown action");
+		return;
+	}
+	const limits = module.limitsFor(entry.document);
+	const input = body.input ?? {};
+	const begin = {
+		spaceId,
+		actionId: entry.id,
+		callerId,
+		input,
+		...body.idempotencyKey ? { idempotencyKey: body.idempotencyKey } : {},
+		ttlMs: limits.timeoutMs
+	};
+	/**
+	* The answer this key already produced, for a caller repeating itself after the first run finished.
+	*
+	* Only ever a key the caller NAMED: they told us which request this is, so answering the retry with what it
+	* answered the first time is what they asked for. Not metered and not counted — nothing ran.
+	*/
+	const replayed = await module.guards.replay(begin);
+	if (replayed) {
+		res.setHeader("X-Plitzi-Replayed", "true");
+		send(res, 200, {
+			...replayed,
+			replayed: true
+		}, replayed.runId);
+		return;
+	}
+	let run;
+	let entryPoint;
+	try {
+		entryPoint = precheckRun(entry, {
+			trigger: "call",
+			input,
+			user: req.ctx.user,
+			lineage
+		}).trigger;
+		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);
+		fail(res, reason, error instanceof Error ? error.message : "Action refused");
+		return;
+	}
+	await config.adapters.meter?.({
+		kind: "server_action",
+		cached: false,
+		req,
+		spaceId,
+		environment,
+		revision
+	});
+	const abortRun = () => run.controller.abort();
+	const releaseAbort = onAbort(signal, abortRun);
+	const stream = wantsStream(req.headers.accept) ? openStream(raw, abortRun, run.runId) : void 0;
+	let outcome;
+	try {
+		const result = await module.runAction({
+			entry,
+			input,
+			spaceId,
+			environment,
+			trigger: "call",
+			user: req.ctx.user,
+			callerId,
+			runId: run.runId,
+			lineage,
+			at: {
+				environment,
+				revision
+			},
+			signal: run.controller.signal,
+			...stream ? {
+				emit: (chunk) => stream.send({
+					event: "data",
+					data: { chunk }
+				}),
+				onNode: (id, status) => stream.send({
+					event: "node",
+					data: {
+						id,
+						status
+					}
+				})
+			} : {}
+		});
+		outcome = result;
+		if (stream) {
+			stream.send({
+				event: "done",
+				data: {
+					runId: result.runId,
+					status: result.status,
+					output: result.output
+				}
+			});
+			stream.close();
+			return;
+		}
+		const payload = {
+			runId: result.runId,
+			status: result.status,
+			output: result.output
+		};
+		if ((authoring === true || config.devMode === true) && mayReadTrace(entryPoint, req.ctx.user)) payload.trace = result.trace;
+		send(res, 200, payload, result.runId);
+	} catch (error) {
+		const reason = error instanceof ActionRunError ? error.reason : "failed";
+		const message = error instanceof ActionRunError ? error.message : "Action failed";
+		if (!(error instanceof ActionRunError)) console.error("[Actions] run failed:", error);
+		if (stream) {
+			stream.send({
+				event: "error",
+				data: {
+					runId: run.runId,
+					error: message,
+					reason
+				}
+			});
+			stream.close();
+			return;
+		}
+		fail(res, reason, message, run.runId);
+	} finally {
+		releaseAbort();
+		await module.guards.end(run, outcome);
+	}
+};
+//#endregion
+export { handleActionCall };

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

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

package/dist/modules/actions/transport/cancelHandler.d.ts

@@ -0,0 +1,23 @@
+import { ActionsModule } from '../index';
+import { SSRResponseHelpers } from '@plitzi/sdk-shared';
+export type ActionCancelDeps = {
+    res: SSRResponseHelpers;
+    module: ActionsModule;
+    runId: string;
+    callerId: string;
+};
+/**
+ * Stops a run in flight.
+ *
+ * The socket closing already aborts a run, so this exists for the cases it cannot cover: a mobile client whose
+ * peer is gone without the server seeing it for minutes, and a run started in one tab that the visitor wants to
+ * stop from another. Ownership is checked in the guards — a run id travels to the browser, and holding one must
+ * not let anybody stop somebody else's run.
+ *
+ * A run that is not there, or is not the caller's, answers 404 either way: distinguishing them would turn this
+ * into an oracle for which run ids are live.
+ *
+ * Awaited because the run is usually somewhere else: behind a load balancer the tab asking to stop a checkout
+ * almost never reaches the replica running it, so the cancel is left in the shared store for the one that is.
+ */
+export declare const handleActionCancel: ({ res, module, runId, callerId }: ActionCancelDeps) => Promise<void>;

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

@@ -0,0 +1,23 @@
+//#region src/modules/actions/transport/cancelHandler.ts
+/**
+* Stops a run in flight.
+*
+* The socket closing already aborts a run, so this exists for the cases it cannot cover: a mobile client whose
+* peer is gone without the server seeing it for minutes, and a run started in one tab that the visitor wants to
+* stop from another. Ownership is checked in the guards — a run id travels to the browser, and holding one must
+* not let anybody stop somebody else's run.
+*
+* A run that is not there, or is not the caller's, answers 404 either way: distinguishing them would turn this
+* into an oracle for which run ids are live.
+*
+* Awaited because the run is usually somewhere else: behind a load balancer the tab asking to stop a checkout
+* almost never reaches the replica running it, so the cancel is left in the shared store for the one that is.
+*/
+var handleActionCancel = async ({ res, module, runId, callerId }) => {
+	const cancelled = await module.guards.cancel(runId, callerId);
+	res.setStatus(cancelled ? 204 : 404);
+	res.setHeader("Cache-Control", "no-store");
+	res.send("");
+};
+//#endregion
+export { handleActionCancel };

package/dist/modules/actions/transport/catalogHandler.d.ts

@@ -0,0 +1,18 @@
+import { ActionsModule } from '../index';
+import { SSRResponseHelpers } from '@plitzi/sdk-shared';
+export type ActionCatalogDeps = {
+    res: SSRResponseHelpers;
+    module: ActionsModule;
+};
+/**
+ * Serves the tasks this server can run.
+ *
+ * The editor asks the SERVER what steps exist instead of holding a hardcoded list, and that is the whole reason a
+ * self-hoster's own task appears in their builder with no fork: registering it is publishing it. It also means a
+ * deployment with no mail transport never offers `email.send` — the catalog is what that deployment actually has,
+ * not what the SDK could imagine.
+ *
+ * Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something
+ * to hand an anonymous visitor.
+ */
+export declare const handleActionCatalog: ({ res, module }: ActionCatalogDeps) => void;

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

@@ -0,0 +1,21 @@
+import { describeCatalog } from "../taskCatalog.js";
+//#region src/modules/actions/transport/catalogHandler.ts
+/**
+* Serves the tasks this server can run.
+*
+* The editor asks the SERVER what steps exist instead of holding a hardcoded list, and that is the whole reason a
+* self-hoster's own task appears in their builder with no fork: registering it is publishing it. It also means a
+* deployment with no mail transport never offers `email.send` — the catalog is what that deployment actually has,
+* not what the SDK could imagine.
+*
+* Session-gated by the pipeline: the catalog names a deployment's server-side capabilities, which is not something
+* to hand an anonymous visitor.
+*/
+var handleActionCatalog = ({ res, module }) => {
+	res.setStatus(200);
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.setHeader("Cache-Control", "no-store");
+	res.send(JSON.stringify({ tasks: describeCatalog(module.registry) }));
+};
+//#endregion
+export { handleActionCatalog };

package/dist/modules/actions/transport/stream.d.ts

@@ -0,0 +1,23 @@
+import { RawResponse } from '../../../helpers/buildResponseHelpers';
+import { ActionStreamFrame } from '@plitzi/sdk-shared';
+export type ActionStream = {
+    /** Sends one frame. Silently drops once the socket is gone — a stream writing into a closed peer is not an error
+     *  worth failing a run over. */
+    send: (frame: ActionStreamFrame) => void;
+    /** Ends the stream and stops the heartbeat. */
+    close: () => void;
+    /** Whether the peer is still there. */
+    isOpen: () => boolean;
+};
+/**
+ * Opens a Server-Sent Events response.
+ *
+ * Written straight to the RAW response, never through the response helpers: those compress the body, set a
+ * Content-Length and end it in one go, which is precisely what a stream cannot do. `no-transform` says the same
+ * thing to every proxy in between, and `X-Accel-Buffering: no` says it to nginx, which otherwise holds frames
+ * until its buffer fills and turns a live stream into one late burst.
+ */
+export declare const openStream: (raw: RawResponse, onAbort: () => void, runId: string) => ActionStream;
+/** Whether this caller asked for a stream. The negotiation is the client's, so a page that cannot read one never
+ *  gets one by accident. */
+export declare const wantsStream: (accept: string | string[] | undefined) => boolean;

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

@@ -0,0 +1,100 @@
+//#region src/modules/actions/transport/stream.ts
+/** How often a comment frame goes out. Short enough that a dead peer is noticed in seconds, long enough that an
+*  idle stream costs nothing worth counting. */
+var HEARTBEAT_MS = 15e3;
+/**
+* How long a hand-rolled `EventSource` waits before reconnecting, if one ever gets here.
+*
+* A day, deliberately. `EventSource` reconnects whenever a stream ends — INCLUDING on normal completion — so a
+* client using it would start a fresh run every time one finished, forever. Our own client uses `fetch` and a
+* reader for exactly this reason; this value is what stops somebody else's from becoming a loop.
+*/
+var RETRY_MS = 864e5;
+/**
+* How much unread body may pile up before the run is stopped.
+*
+* A `write` that answers `false` has been buffered rather than sent, which is normal for a moment and a leak
+* forever: a peer that stopped reading — a phone that slept, a proxy that wedged — otherwise has the whole run's
+* output accumulated for it in memory. The socket says nothing, so the only signal is this one.
+*/
+var MAX_BUFFERED_BYTES = 1e6;
+var encode = (frame) => `event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`;
+/** What the host has written but not yet handed to the socket. Node's own response reports it; the minimum raw
+*  response this server accepts does not have to, and a host that cannot say simply never trips the cap. */
+var bufferedBytes = (raw) => {
+	const { writableLength } = raw;
+	return typeof writableLength === "number" ? writableLength : 0;
+};
+/**
+* Opens a Server-Sent Events response.
+*
+* Written straight to the RAW response, never through the response helpers: those compress the body, set a
+* Content-Length and end it in one go, which is precisely what a stream cannot do. `no-transform` says the same
+* thing to every proxy in between, and `X-Accel-Buffering: no` says it to nginx, which otherwise holds frames
+* until its buffer fills and turns a live stream into one late burst.
+*/
+var openStream = (raw, onAbort, runId) => {
+	let open = true;
+	raw.writeHead(200, {
+		"Content-Type": "text/event-stream; charset=utf-8",
+		"Cache-Control": "no-cache, no-transform",
+		Connection: "keep-alive",
+		"X-Accel-Buffering": "no",
+		/**
+		* The run's id, on the response head rather than in a frame.
+		*
+		* A streaming step returns as soon as the stream OPENS — that is what makes it a stream — so anything it
+		* learns from a frame arrives after the flow has already carried on. The head is the one place a caller can
+		* read the id in time to cancel the run it just started.
+		*/
+		"X-Plitzi-Run-Id": runId
+	});
+	raw.write(`retry: ${RETRY_MS}\n\n`);
+	const heartbeat = setInterval(() => {
+		if (!open) return;
+		try {
+			raw.write(": ping\n\n");
+		} catch {
+			open = false;
+			clearInterval(heartbeat);
+			onAbort();
+		}
+	}, HEARTBEAT_MS);
+	const close = () => {
+		if (!open) return;
+		open = false;
+		clearInterval(heartbeat);
+		try {
+			raw.end();
+		} catch {}
+	};
+	return {
+		send: (frame) => {
+			if (!open) return;
+			try {
+				raw.write(encode(frame));
+				if (bufferedBytes(raw) > MAX_BUFFERED_BYTES) {
+					open = false;
+					clearInterval(heartbeat);
+					onAbort();
+					try {
+						raw.end();
+					} catch {}
+				}
+			} catch {
+				open = false;
+				clearInterval(heartbeat);
+				onAbort();
+			}
+		},
+		close,
+		isOpen: () => open
+	};
+};
+/** Whether this caller asked for a stream. The negotiation is the client's, so a page that cannot read one never
+*  gets one by accident. */
+var wantsStream = (accept) => {
+	return (Array.isArray(accept) ? accept.join(",") : accept ?? "").includes("text/event-stream");
+};
+//#endregion
+export { openStream, wantsStream };

package/dist/modules/actions/transport/verifySignature.d.ts

@@ -0,0 +1,16 @@
+import { ActionWebhookVerification } from '@plitzi/sdk-shared';
+export type SignatureCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Checks an inbound webhook signature against the RAW body.
+ *
+ * Raw, before parsing, because a signature covers bytes: `JSON.parse` then `JSON.stringify` reorders keys and
+ * drops whitespace, and the digest of the result is not the digest the sender computed. That is the single most
+ * common way a webhook verification is written wrong, and it fails closed — which is why it is worth naming here
+ * rather than trusting every caller to remember.
+ */
+export declare const verifySignature: (verification: ActionWebhookVerification, secret: string, headers: Record<string, string | string[] | undefined>, rawBody: string) => SignatureCheck;

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

@@ -0,0 +1,72 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/modules/actions/transport/verifySignature.ts
+/**
+* Digests as senders actually write them.
+*
+* A provider sends the same bytes in one of a few dressings — bare hex, base64, `sha256=<hex>` (GitHub), or a
+* comma-separated list of `k=v` pairs where one value is the signature (Stripe). Accepting all of them is what
+* lets one declarative verification cover real webhooks instead of only the tidy ones.
+*/
+var candidates = (header) => {
+	const parts = [header.trim()];
+	for (const segment of header.split(",")) {
+		const [, value] = segment.split("=", 2);
+		if (value) parts.push(value.trim());
+	}
+	return parts;
+};
+/** Constant time, and only for equal-length values: a length comparison leaks nothing an attacker cannot measure
+*  from the encoding anyway, while `timingSafeEqual` throws outright on a mismatch. */
+var matches = (expected, received) => {
+	const a = Buffer.from(expected);
+	const b = Buffer.from(received);
+	return a.length === b.length && timingSafeEqual(a, b);
+};
+/**
+* Checks an inbound webhook signature against the RAW body.
+*
+* Raw, before parsing, because a signature covers bytes: `JSON.parse` then `JSON.stringify` reorders keys and
+* drops whitespace, and the digest of the result is not the digest the sender computed. That is the single most
+* common way a webhook verification is written wrong, and it fails closed — which is why it is worth naming here
+* rather than trusting every caller to remember.
+*/
+var verifySignature = (verification, secret, headers, rawBody) => {
+	const raw = headers[verification.header.toLowerCase()];
+	const signature = Array.isArray(raw) ? raw[0] : raw;
+	if (!signature) return {
+		ok: false,
+		reason: `Missing "${verification.header}" signature`
+	};
+	if (!secret) return {
+		ok: false,
+		reason: "Signing secret is not available"
+	};
+	let signed = rawBody;
+	if (verification.timestampHeader) {
+		const rawStamp = headers[verification.timestampHeader.toLowerCase()];
+		const stamp = Array.isArray(rawStamp) ? rawStamp[0] : rawStamp;
+		if (!stamp) return {
+			ok: false,
+			reason: `Missing "${verification.timestampHeader}" timestamp`
+		};
+		const sentAt = Number.parseInt(stamp, 10);
+		if (!Number.isFinite(sentAt)) return {
+			ok: false,
+			reason: "Timestamp is not a number"
+		};
+		const tolerance = verification.toleranceSeconds;
+		if (tolerance !== void 0 && Math.abs(Date.now() / 1e3 - sentAt) > tolerance) return {
+			ok: false,
+			reason: "Signature is outside its tolerance window"
+		};
+		signed = `${stamp}.${rawBody}`;
+	}
+	const hex = createHmac(verification.algorithm, secret).update(signed).digest("hex");
+	const base64 = createHmac(verification.algorithm, secret).update(signed).digest("base64");
+	return candidates(signature).some((value) => matches(hex, value) || matches(base64, value)) ? { ok: true } : {
+		ok: false,
+		reason: "Signature does not match"
+	};
+};
+//#endregion
+export { verifySignature };

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

@@ -0,0 +1,25 @@
+import { ActionsModule } from '../index';
+import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+export type ActionWebhookDeps = {
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    config: SSRPageServerConfig;
+    module: ActionsModule;
+    signal: AbortSignal;
+    actionId: string;
+    /** The caller's address: a webhook has no session, so this is all there is to rate limit by. */
+    callerId: string;
+    lineage: string[];
+};
+/**
+ * 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.
+ */
+export declare const handleActionWebhook: (deps: ActionWebhookDeps) => Promise<void>;