@tangle-network/hub-sdk 0.3.0 → 0.5.1

package/dist/index.js

@@ -49,7 +49,7 @@ function isHubErrorEnvelope(value) {
 function isHubSuccessEnvelope(value) {
 	return typeof value === "object" && value !== null && value.success === true;
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
 function optString(value) {
@@ -83,7 +83,7 @@ function isRunDoneStatus(value) {
 */
 function toRunStreamEvent(eventType, data) {
 	if (eventType === "ping") return { type: "ping" };
-	if (!isRecord(data)) return null;
+	if (!isRecord$1(data)) return null;
 	switch (eventType) {
 		case "snapshot": return typeof data.id === "string" && typeof data.workflowId === "string" && typeof data.status === "string" && Array.isArray(data.actionResults) ? {
 			type: "snapshot",
@@ -226,6 +226,8 @@ var HubClient = class HubClient {
 	apiKey;
 	authHeaders;
 	connections;
+	channels;
+	eventSubscriptions;
 	permissions;
 	tokens;
 	tools;
@@ -239,13 +241,15 @@ var HubClient = class HubClient {
 		this.authHeaders = options.authHeaders;
 		this.fetch = options.fetch ?? fetch.bind(globalThis);
 		this.connections = new HubConnectionsClient((path, init) => this.request(path, init));
+		this.channels = new HubChannelsClient((path, init) => this.request(path, init));
+		this.eventSubscriptions = new HubEventSubscriptionsClient((path, init) => this.request(path, init));
 		this.permissions = new HubPermissionsClient((path, init) => this.request(path, init));
 		this.tokens = new HubTokensClient((path, init) => this.request(path, init));
 		this.tools = new HubToolsClient((path, init) => this.request(path, init));
 		this.approvals = new HubApprovalsClient((path, init) => this.request(path, init));
 		this.audit = new HubAuditClient((path, init) => this.request(path, init));
 		this.githubApp = new HubGithubAppClient((path, init) => this.request(path, init));
-		this.workflows = new HubWorkflowsClient((path, init) => this.request(path, init), (path, init) => this.stream(path, init));
+		this.workflows = new HubWorkflowsClient((path, init) => this.request(path, init), (path, init) => this.stream(path, init), (path, init) => this.requestBytes(path, init));
 	}
 	static fromEnv(options = {}) {
 		const env = options.env ?? readProcessEnv();
@@ -312,6 +316,38 @@ var HubClient = class HubClient {
 		if (!response.body) throw httpError(path, status, response.statusText, "event-stream response had no body", contentType);
 		return response.body;
 	}
+	/**
+	* Fetch raw (non-envelope) bytes — the artifact download route, whose 200 is
+	* the artifact's own content type, not JSON. Error responses on such routes
+	* are still the standard envelope, so a failure surfaces exactly like
+	* {@link request}: a typed `HubSdkError` from a `{success:false}` body,
+	* otherwise an `HUB_HTTP_<status>` transport error.
+	*/
+	async requestBytes(path, init) {
+		const response = await this.fetch(`${this.baseUrl}${path}`, {
+			...init,
+			headers: await this.buildHeaders(init.headers)
+		});
+		const status = response.status;
+		const contentType = response.headers.get("content-type") ?? "";
+		if (!response.ok) {
+			const bodyText = await response.text().catch(() => "");
+			if (contentType.includes("application/json")) {
+				let parsed;
+				try {
+					parsed = JSON.parse(bodyText);
+				} catch {
+					parsed = void 0;
+				}
+				if (isHubErrorEnvelope(parsed)) throw new HubSdkError(parsed.error, { status });
+			}
+			throw httpError(path, status, response.statusText, bodyText, contentType);
+		}
+		return {
+			bytes: new Uint8Array(await response.arrayBuffer()),
+			contentType
+		};
+	}
 	async buildHeaders(headers) {
 		const mergedHeaders = new Headers(headers);
 		if (!mergedHeaders.has("Accept")) mergedHeaders.set("Accept", "application/json");
@@ -504,6 +540,42 @@ function validateApprovedExecution(approved, path, connectionId) {
 		}
 	});
 }
+var HubChannelsClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	async list() {
+		return this.request("/v1/hub/channels", { method: "GET" });
+	}
+	async createEmail(input = {}) {
+		return this.request("/v1/hub/channels/email", {
+			method: "POST",
+			body: JSON.stringify(input),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	async delete(channelId) {
+		return this.request(`/v1/hub/channels/${encodeURIComponent(channelId)}`, { method: "DELETE" });
+	}
+};
+var HubEventSubscriptionsClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	async list() {
+		return this.request("/v1/hub/event-subscriptions", { method: "GET" });
+	}
+	async create(input) {
+		return this.request("/v1/hub/event-subscriptions", {
+			method: "POST",
+			body: JSON.stringify(input),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	async delete(subscriptionId) {
+		return this.request(`/v1/hub/event-subscriptions/${encodeURIComponent(subscriptionId)}`, { method: "DELETE" });
+	}
+};
 var HubConnectionsClient = class {
 	constructor(request) {
 		this.request = request;
@@ -616,13 +688,24 @@ var HubAuditClient = class {
 	}
 };
 var HubWorkflowsClient = class {
-	constructor(request, stream) {
+	constructor(request, stream, download) {
 		this.request = request;
 		this.stream = stream;
+		this.download = download;
 	}
 	async list() {
 		return this.request("/v1/workflows", { method: "GET" });
 	}
+	/**
+	* Owner-wide fleet overview: one row per workflow with its run tallies over
+	* a trailing window (default 7d), sorted failing-first. Answers "how are ALL
+	* my workflows doing" in one call — the per-workflow insights endpoint is
+	* the drill-down, not a way to build this row set client-side.
+	*/
+	async fleetInsights(opts = {}) {
+		const query = opts.window ? `?window=${encodeURIComponent(opts.window)}` : "";
+		return this.request(`/v1/workflows/insights/fleet${query}`, { method: "GET" });
+	}
 	async get(id) {
 		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, { method: "GET" });
 	}
@@ -633,10 +716,21 @@ var HubWorkflowsClient = class {
 			headers: { "Content-Type": "application/json" }
 		});
 	}
-	async update(id, yaml) {
+	/**
+	* Replace the workflow's definition from YAML (recompiled server-side,
+	* triggers reconciled). Every landed update appends a revision;
+	* `opts.note` rides onto that revision row (e.g. "why this change"), visible
+	* in {@link listRevisions}. Throws `HubSdkError`: `WORKFLOW_INVALID` when the
+	* YAML doesn't compile or its connections aren't met, `CONFLICT` on a
+	* concurrent modification, `NOT_FOUND` for an unknown/foreign id.
+	*/
+	async update(id, yaml, opts = {}) {
 		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, {
 			method: "PUT",
-			body: JSON.stringify({ yaml }),
+			body: JSON.stringify({
+				yaml,
+				...opts.note !== void 0 ? { note: opts.note } : {}
+			}),
 			headers: { "Content-Type": "application/json" }
 		});
 	}
@@ -715,6 +809,24 @@ var HubWorkflowsClient = class {
 		});
 	}
 	/**
+	* Re-run a terminal failed/cancelled run: enqueues a FRESH run of the same
+	* workflow with the SAME trigger context the original ran against, linked
+	* back to it via `retriedFromRunId`. The original row is never mutated —
+	* execution is at-most-once, so a retry is always a new run, never a
+	* requeue. The response carries the NEW run id (and the run it retried);
+	* follow it with {@link getRun}/{@link watchRun}/{@link waitForRun} like any
+	* other run. Throws `HubSdkError`: `RUN_NOT_RETRYABLE` when the run is not
+	* terminal-failed/cancelled (queued/running/waiting, or succeeded),
+	* `WORKFLOW_DISABLED` when the workflow has since been disabled, `NOT_FOUND`
+	* for an unknown/foreign run id. Pass `opts.signal` to abort a slow request.
+	*/
+	async retryRun(id, runId, opts = {}) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/retry`, {
+			method: "POST",
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+	}
+	/**
 	* Stream a run's live progress as an async iterable of typed events. The
 	* first event is always a `snapshot` of the current persisted state; then
 	* `action.*` / `iteration.*` / `token` ticks arrive as the run executes;
@@ -820,10 +932,262 @@ var HubWorkflowsClient = class {
 			await delay(delayRemainingMs !== null ? Math.min(pollIntervalMs, delayRemainingMs) : pollIntervalMs, opts.signal);
 		}
 	}
-	async validate(yaml) {
+	/**
+	* The workflow's definition history, newest rev first — metadata only (rev,
+	* attribution, note); fetch the YAML per-rev with {@link getRevision}. Empty
+	* for a pre-versioning workflow until its next update.
+	*/
+	async listRevisions(id) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/revisions`, { method: "GET" });
+	}
+	/**
+	* One revision WITH its YAML (and the actions compiled alongside it), for
+	* diff/inspect views. Throws `HubSdkError(REVISION_NOT_FOUND)` for an
+	* unknown rev, `NOT_FOUND` for an unknown/foreign workflow.
+	*/
+	async getRevision(id, rev) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/revisions/${encodeURIComponent(String(rev))}`, { method: "GET" });
+	}
+	/**
+	* Restore a prior rev's YAML as a NEW head revision (history is append-only)
+	* through the same compile path as {@link update}, so the restored definition
+	* is re-validated against today's connections/models. Throws `HubSdkError`:
+	* `REVISION_NOT_FOUND` for an unknown rev, `WORKFLOW_INVALID` when the old
+	* YAML no longer compiles, `CONFLICT` on a concurrent modification.
+	*/
+	async rollback(id, rev) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/rollback`, {
+			method: "POST",
+			body: JSON.stringify({ rev }),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Deterministic health stats over the workflow's last N terminal runs
+	* (default 20, max 100): per-node visits/failures/cost/duration, failure
+	* clusters by normalized error signature, and distillation CANDIDATES
+	* (agent.run nodes with near-static outputs — labeled with their
+	* measurements, never as verdicts). No model in this path.
+	*/
+	async health(id, opts = {}) {
+		const query = opts.runs !== void 0 ? `?runs=${opts.runs}` : "";
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/health${query}`, { method: "GET" });
+	}
+	/**
+	* Propose a definition change — the intelligence path. SERVICE-TOKEN
+	* callers only (user principals get `HubSdkError(SERVICE_TOKEN_REQUIRED)`,
+	* 403). The YAML is compile-validated server-side (`WORKFLOW_INVALID` on
+	* failure) and appended as a `proposed` revision; the head NEVER advances
+	* until an owner approves.
+	*/
+	async propose(id, input) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals`, {
+			method: "POST",
+			body: JSON.stringify(input),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Pending (proposed) and declined (rejected) revisions, newest first, with
+	* their evidence — the approval surface's input.
+	*/
+	async listProposals(id) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals`, { method: "GET" });
+	}
+	/**
+	* Accept a proposal: its YAML lands as a NEW applied head revision through
+	* the same compile + advance path as {@link rollback} (re-validated against
+	* today's connections/models), and the proposal settles to `applied`.
+	* Throws `HubSdkError`: `PROPOSAL_NOT_PENDING` (409) when the rev is not a
+	* pending proposal, `WORKFLOW_INVALID` when it no longer compiles,
+	* `CONFLICT` on a concurrent modification.
+	*/
+	async approveProposal(id, rev) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals/${encodeURIComponent(String(rev))}/approve`, { method: "POST" });
+	}
+	/**
+	* Decline a proposal: the revision settles to `rejected` (head untouched);
+	* an optional reason is merged into its evidence as `rejectionReason`.
+	* Throws `HubSdkError(PROPOSAL_NOT_PENDING)` (409) when the rev is not a
+	* pending proposal.
+	*/
+	async rejectProposal(id, rev, opts = {}) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals/${encodeURIComponent(String(rev))}/reject`, {
+			method: "POST",
+			body: JSON.stringify(opts.reason !== void 0 ? { reason: opts.reason } : {}),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Mint a fresh webhook hook token, retiring the current one immediately.
+	* The plaintext token is returned exactly once (only the hash is stored).
+	* Requires an active webhook trigger — otherwise `HubSdkError` with
+	* `NO_WEBHOOK_TRIGGER` (409).
+	*/
+	async rotateHookToken(id) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/hook-token/rotate`, { method: "POST" });
+	}
+	/**
+	* One agent round's execution timeline, paged. `action` is the action's
+	* `${steps[N]}` position and `iteration` the round's position in that
+	* action's `iterations` — both exactly as the run detail serializes them.
+	* Pass the previous page's `nextCursor` as `after` for the next page; a null
+	* `nextCursor` means the round is fully read.
+	*/
+	async listRunSteps(id, runId, input) {
+		const params = new URLSearchParams({
+			action: String(input.action),
+			iteration: String(input.iteration)
+		});
+		if (input.after !== void 0) params.set("after", String(input.after));
+		if (input.limit !== void 0) params.set("limit", String(input.limit));
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/steps?${params.toString()}`, { method: "GET" });
+	}
+	/**
+	* Store one artifact for a run (raw bytes) and return the opaque ref — the
+	* value a script.run node returns as its step output. `contentType` defaults
+	* to `application/octet-stream`; `nodeId` attributes the write to a graph
+	* node (owner credential only — a run-scoped token binds its own node).
+	* Throws `HubSdkError(ARTIFACT_TOO_LARGE)` past the server cap.
+	*/
+	async uploadArtifact(id, runId, input) {
+		const headers = {
+			"Content-Type": input.contentType ?? "application/octet-stream",
+			"x-wf-artifact-name": input.name
+		};
+		if (input.nodeId !== void 0) headers["x-wf-artifact-node"] = input.nodeId;
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/artifacts`, {
+			method: "POST",
+			body: input.bytes,
+			headers
+		});
+	}
+	/** Metadata for every artifact of the run (never the bytes), oldest first. */
+	async listArtifacts(id, runId) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/artifacts`, { method: "GET" });
+	}
+	/**
+	* The artifact's raw bytes with their stored content type — the route every
+	* `downloadUrl` attached to an `$artifact` ref in a run detail points at.
+	*/
+	async downloadArtifact(id, runId, artifactId) {
+		const downloadBytes = this.download;
+		if (!downloadBytes) throw new HubSdkError({
+			code: "HUB_CONFIG_INVALID",
+			message: "downloadArtifact needs a byte transport; use HubClient (which wires it up) rather than constructing HubWorkflowsClient directly"
+		});
+		return downloadBytes(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`, { method: "GET" });
+	}
+	/**
+	* The workflow's whole keyspace as metadata (key, version, updatedAt — never
+	* values), key-ordered. Bounded by the server's per-workflow key cap.
+	*/
+	async listKv(id) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv`, { method: "GET" });
+	}
+	/** One KV entry (value + version); `HubSdkError(NOT_FOUND)` when absent. */
+	async getKv(id, key) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}`, { method: "GET" });
+	}
+	/**
+	* Upsert a key; returns the entry with its NEW version (increments on every
+	* write). Throws `HubSdkError(KV_VALUE_TOO_LARGE)` past the 64KiB value cap
+	* or `KV_KEY_LIMIT` past the per-workflow key cap.
+	*/
+	async putKv(id, key, value) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}`, {
+			method: "PUT",
+			body: JSON.stringify({ value }),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Compare-and-swap: the write lands only when the stored version still
+	* equals `expectedVersion`; otherwise `HubSdkError(KV_VERSION_CONFLICT)`
+	* (409) — re-read and retry. Creation is {@link putKv}'s job.
+	*/
+	async casKv(id, key, expectedVersion, value) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}/cas`, {
+			method: "POST",
+			body: JSON.stringify({
+				expectedVersion,
+				value
+			}),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/** Delete a key; idempotent — `deleted` reports whether a row was removed. */
+	async deleteKv(id, key) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}`, { method: "DELETE" });
+	}
+	/** The curated starter gallery runnable on THIS deployment: metadata,
+	*  parameters, referenced providers, and a concrete `previewYaml` per card. */
+	async listTemplates() {
+		return this.request("/v1/workflows/templates", { method: "GET" });
+	}
+	/**
+	* One-click create from a gallery template: substitutes `parameters` into
+	* the template server-side, then runs the SAME create path as
+	* {@link create}. A `{ created: false }` result is NOT an error — an
+	* actionable continuation listing the connections to satisfy before
+	* retrying. Invalid parameters or a compile failure throw `HubSdkError`
+	* (400); an unknown template id throws `NOT_FOUND`.
+	*/
+	async instantiateTemplate(templateId, parameters) {
+		return this.request(`/v1/workflows/templates/${encodeURIComponent(templateId)}/instantiate`, {
+			method: "POST",
+			body: JSON.stringify(parameters ? { parameters } : {}),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* The caller's open decisions across all workflows — the always-available
+	* "pending approvals" surface. Each entry carries its workflow's name (null
+	* when the workflow was deleted while the run was parked).
+	*/
+	async listPendingDecisions() {
+		return this.request("/v1/workflows/decisions/pending", { method: "GET" });
+	}
+	/**
+	* The pending decision a run is parked on. Throws `HubSdkError(NOT_FOUND)`
+	* when the run is unknown/foreign or holds no pending decision.
+	*/
+	async getRunDecision(id, runId) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/decision`, { method: "GET" });
+	}
+	/**
+	* Answer the decision a run is parked on and resume it from the next action.
+	* `decisionId` is REQUIRED: a run can resolve one decision and re-park on the
+	* next, so an answer addressed only by run could silently land on a question
+	* the caller never saw — a mismatch throws `HubSdkError(DECISION_SUPERSEDED)`.
+	* Other typed failures: `INVALID_CHOICE` (400), `DECISION_ALREADY_RESOLVED` /
+	* `DECISION_EXPIRED` (409), `DECISION_NOT_FOUND` (404), `RUN_NOT_WAITING`
+	* (409 — answered, timed out, or cancelled first).
+	*/
+	async resolveRunDecision(id, runId, input) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/decision/resolve`, {
+			method: "POST",
+			body: JSON.stringify(input),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Dry-run a YAML definition against the platform compiler without saving it.
+	*
+	* `opts.structural` selects the CI mode: the platform skips its owner-scoped
+	* connection/skill/profile resolution, so the verdict depends only on the
+	* definition and the deployment's capabilities — identical no matter which
+	* providers the calling account has connected. Use it in pipelines that
+	* assert "this YAML is well-formed"; leave it off in an editor, where naming
+	* the unconnected providers is the point.
+	*/
+	async validate(yaml, opts = {}) {
 		return this.request("/v1/workflows/validate", {
 			method: "POST",
-			body: JSON.stringify({ yaml }),
+			body: JSON.stringify({
+				yaml,
+				...opts.structural ? { structural: true } : {}
+			}),
 			headers: { "Content-Type": "application/json" }
 		});
 	}
@@ -832,6 +1196,263 @@ var HubWorkflowsClient = class {
 	}
 };
 //#endregion
-export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, HubApprovalsClient, HubAuditClient, HubClient, HubConnectionsClient, HubGithubAppClient, HubPermissionsClient, HubSdkError, HubTokensClient, HubToolsClient, HubWorkflowsClient, redactHubValue, resolveHubAuth, resolveHubBaseUrl };
+//#region src/event-delivery.ts
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const MAX_TOLERANCE_SECONDS = 3600;
+const MAX_SIGNATURE_HEADER_LENGTH = 1024;
+const MAX_SIGNATURES = 5;
+const SHA256_HEX_LENGTH = 64;
+const MIN_CALLBACK_SECRET_BYTES = 32;
+const MAX_SECRET_SCOPE_COMPONENT_BYTES = 512;
+const DEFAULT_MAX_CALLBACK_BODY_BYTES = 5308416;
+const MAX_CALLBACK_BODY_BYTES = 10 * 1024 * 1024;
+var HubEventDeliveryError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "HubEventDeliveryError";
+		this.code = code;
+	}
+};
+/**
+* Derive one callback secret per product binding from a single server-held root
+* secret. Products persist only the binding id; the derived secret can be
+* reproduced for callback authentication without another secret table.
+*/
+async function deriveHubEventCallbackSecret(input) {
+	const encoder = new TextEncoder();
+	if (encoder.encode(input.rootSecret).byteLength < MIN_CALLBACK_SECRET_BYTES) throw new HubEventDeliveryError("INVALID_CALLBACK_SECRET", `Hub event root secret must contain at least ${MIN_CALLBACK_SECRET_BYTES} UTF-8 bytes`);
+	for (const [name, value] of [
+		["productId", input.productId],
+		["ownerId", input.ownerId],
+		["bindingId", input.bindingId]
+	]) {
+		const bytes = encoder.encode(value).byteLength;
+		if (bytes === 0 || bytes > MAX_SECRET_SCOPE_COMPONENT_BYTES) throw new HubEventDeliveryError("INVALID_SECRET_SCOPE", `${name} must contain 1-${MAX_SECRET_SCOPE_COMPONENT_BYTES} UTF-8 bytes`);
+	}
+	const subtle = requireSubtleCrypto();
+	const key = await subtle.importKey("raw", encoder.encode(input.rootSecret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const scope = JSON.stringify([
+		"tangle-hub-event-callback",
+		1,
+		input.productId,
+		input.ownerId,
+		input.bindingId
+	]);
+	return bytesToBase64Url(new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(scope))));
+}
+/**
+* Authenticate and parse the platform's callback as one operation. The exact
+* raw body is read once with a size limit before its signature is checked.
+*
+* A successful callback can be retried. Use `delivery.runId` as the durable
+* idempotency key before starting product work.
+*/
+async function authenticateHubEventRequest(input) {
+	if (input.request.method !== "POST") return requestFailure("METHOD_NOT_ALLOWED", 405, "method_not_allowed", { Allow: "POST" });
+	if (input.request.headers.get("x-tangle-event") !== "hub.event") return requestFailure("UNEXPECTED_EVENT", 400, "invalid_hub_event");
+	const contentType = input.request.headers.get("content-type") ?? "";
+	if (!/^application\/json(?:\s*;|$)/i.test(contentType)) return requestFailure("UNSUPPORTED_MEDIA_TYPE", 415, "unsupported_media_type");
+	const maxBodyBytes = input.maxBodyBytes ?? DEFAULT_MAX_CALLBACK_BODY_BYTES;
+	if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || maxBodyBytes > MAX_CALLBACK_BODY_BYTES) throw new HubEventDeliveryError("INVALID_BODY_LIMIT", `Hub event body limit must be an integer from 1 to ${MAX_CALLBACK_BODY_BYTES} bytes`);
+	if (new TextEncoder().encode(input.secret).byteLength < MIN_CALLBACK_SECRET_BYTES) throw new HubEventDeliveryError("INVALID_CALLBACK_SECRET", `Hub event callback secret must contain at least ${MIN_CALLBACK_SECRET_BYTES} UTF-8 bytes`);
+	const declaredLength = input.request.headers.get("content-length");
+	if (declaredLength !== null && /^\d+$/.test(declaredLength) && Number(declaredLength) > maxBodyBytes) return requestFailure("PAYLOAD_TOO_LARGE", 413, "payload_too_large");
+	const body = await readRequestBody(input.request, maxBodyBytes);
+	if (body === null) return requestFailure("PAYLOAD_TOO_LARGE", 413, "payload_too_large");
+	if (!(await verifyHubEventSignature({
+		body,
+		signature: input.request.headers.get("x-tangle-signature"),
+		secret: input.secret,
+		...input.toleranceSeconds !== void 0 ? { toleranceSeconds: input.toleranceSeconds } : {},
+		...input.now !== void 0 ? { now: input.now } : {}
+	})).valid) return requestFailure("INVALID_SIGNATURE", 401, "invalid_signature");
+	let delivery;
+	try {
+		delivery = parseHubEventDelivery(body);
+	} catch (error) {
+		if (error instanceof HubEventDeliveryError) return requestFailure("INVALID_DELIVERY", 400, "invalid_delivery");
+		throw error;
+	}
+	if (input.request.headers.get("x-tangle-delivery-id") !== delivery.runId) return requestFailure("DELIVERY_ID_MISMATCH", 400, "invalid_delivery");
+	return {
+		ok: true,
+		delivery
+	};
+}
+/**
+* Authenticate a Hub event callback against its exact raw request body.
+* The timestamp window rejects captured-request replay, and byte-wise
+* comparison avoids secret-dependent string comparison behavior.
+*/
+async function verifyHubEventSignature(input) {
+	if (!input.signature) return {
+		valid: false,
+		reason: "missing"
+	};
+	if (input.signature.length > MAX_SIGNATURE_HEADER_LENGTH) return {
+		valid: false,
+		reason: "malformed"
+	};
+	const parsed = parseSignatureHeader(input.signature);
+	if (!parsed) return {
+		valid: false,
+		reason: "malformed"
+	};
+	const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+	if (!Number.isFinite(tolerance) || !Number.isInteger(tolerance) || tolerance < 0 || tolerance > MAX_TOLERANCE_SECONDS) throw new HubEventDeliveryError("INVALID_TOLERANCE", `Signature tolerance must be an integer from 0 to ${MAX_TOLERANCE_SECONDS} seconds`);
+	const nowMs = input.now instanceof Date ? input.now.getTime() : typeof input.now === "number" ? input.now : Date.now();
+	if (!Number.isFinite(nowMs) || Math.abs(Math.floor(nowMs / 1e3) - parsed.timestamp) > tolerance) return {
+		valid: false,
+		reason: "stale"
+	};
+	const subtle = requireSubtleCrypto();
+	const encoder = new TextEncoder();
+	const key = await subtle.importKey("raw", encoder.encode(input.secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const expected = new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(`${parsed.timestamp}.${input.body}`)));
+	let matched = 0;
+	for (const signature of parsed.signatures) matched |= constantTimeEqual(expected, signature);
+	return matched === 1 ? {
+		valid: true,
+		timestamp: parsed.timestamp
+	} : {
+		valid: false,
+		reason: "mismatch"
+	};
+}
+function parseHubEventDelivery(input) {
+	let value = input;
+	if (typeof input === "string") try {
+		value = JSON.parse(input);
+	} catch {
+		throw new HubEventDeliveryError("INVALID_JSON", "Hub event callback body is not valid JSON");
+	}
+	if (!isRecord(value)) return invalidDelivery();
+	const source = value.source;
+	const providerEvent = value.providerEvent;
+	if (!nonEmptyString(value.subscriptionId) || !nonEmptyString(value.workflowId) || !nonEmptyString(value.runId) || !isRecord(source) || source.kind !== "channel" && source.kind !== "connection" || !nonEmptyString(source.id) || !nonEmptyString(source.provider) || !nonEmptyString(source.event) || !isRecord(providerEvent) || !nonEmptyString(providerEvent.provider) || !nonEmptyString(providerEvent.connectionId) || !nonEmptyString(providerEvent.type) || providerEvent.provider !== source.provider || providerEvent.type !== source.event || !Object.hasOwn(providerEvent, "payload") || !optionalString(providerEvent.action) || !optionalString(providerEvent.repo) || !optionalString(providerEvent.deliveryId) || !nonEmptyString(value.firedAt) || !Number.isFinite(Date.parse(value.firedAt))) return invalidDelivery();
+	return {
+		subscriptionId: value.subscriptionId,
+		workflowId: value.workflowId,
+		runId: value.runId,
+		source: {
+			kind: source.kind,
+			id: source.id,
+			provider: source.provider,
+			event: source.event
+		},
+		providerEvent: {
+			provider: providerEvent.provider,
+			connectionId: providerEvent.connectionId,
+			type: providerEvent.type,
+			...typeof providerEvent.action === "string" ? { action: providerEvent.action } : {},
+			...typeof providerEvent.repo === "string" ? { repo: providerEvent.repo } : {},
+			...typeof providerEvent.deliveryId === "string" ? { deliveryId: providerEvent.deliveryId } : {},
+			payload: providerEvent.payload
+		},
+		firedAt: value.firedAt
+	};
+}
+function parseSignatureHeader(header) {
+	let timestamp;
+	const signatures = [];
+	for (const segment of header.split(",")) {
+		const separator = segment.indexOf("=");
+		if (separator <= 0) return null;
+		const key = segment.slice(0, separator).trim();
+		const value = segment.slice(separator + 1).trim();
+		if (key === "t") {
+			if (timestamp !== void 0 || !/^\d+$/.test(value)) return null;
+			const candidate = Number(value);
+			if (!Number.isSafeInteger(candidate) || candidate <= 0) return null;
+			timestamp = candidate;
+		} else if (key === "v1") {
+			if (signatures.length >= MAX_SIGNATURES || value.length !== SHA256_HEX_LENGTH || !/^[0-9a-f]+$/i.test(value)) return null;
+			signatures.push(hexToBytes(value));
+		}
+	}
+	return timestamp !== void 0 && signatures.length > 0 ? {
+		timestamp,
+		signatures
+	} : null;
+}
+function hexToBytes(hex) {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+}
+function constantTimeEqual(expected, actual) {
+	let difference = expected.length ^ actual.length;
+	const length = Math.max(expected.length, actual.length);
+	for (let index = 0; index < length; index += 1) difference |= (expected[index % expected.length] ?? 0) ^ (actual[index % actual.length] ?? 0);
+	return difference === 0 ? 1 : 0;
+}
+function nonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function optionalString(value) {
+	return value === void 0 || nonEmptyString(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidDelivery() {
+	throw new HubEventDeliveryError("INVALID_PAYLOAD", "Hub event callback body does not match the delivery contract");
+}
+function requireSubtleCrypto() {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new HubEventDeliveryError("CRYPTO_UNAVAILABLE", "Web Crypto is required for Hub event callback authentication");
+	return subtle;
+}
+function bytesToBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+async function readRequestBody(request, maxBytes) {
+	const reader = request.body?.getReader();
+	if (!reader) return "";
+	const chunks = [];
+	let total = 0;
+	try {
+		while (true) {
+			const next = await reader.read();
+			if (next.done) break;
+			total += next.value.byteLength;
+			if (total > maxBytes) return null;
+			chunks.push(next.value);
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(body);
+}
+function requestFailure(code, status, error, headers) {
+	return {
+		ok: false,
+		code,
+		response: Response.json({ error }, {
+			status,
+			headers: {
+				"cache-control": "no-store",
+				...headers ? Object.fromEntries(new Headers(headers)) : {}
+			}
+		})
+	};
+}
+//#endregion
+export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, HubApprovalsClient, HubAuditClient, HubChannelsClient, HubClient, HubConnectionsClient, HubEventDeliveryError, HubEventSubscriptionsClient, HubGithubAppClient, HubPermissionsClient, HubSdkError, HubTokensClient, HubToolsClient, HubWorkflowsClient, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
 
 //# sourceMappingURL=index.js.map