@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/team-secrets/sign.js

@@ -0,0 +1,71 @@
+/**
+ * Signatures over team-secrets files (§4): Ed25519 over the canonical JSON (keys sorted at every depth, no
+ * whitespace, `undefined` dropped) of the document without its `signature` field. YAML formatting, key
+ * order in the file and line endings therefore never change what was signed.
+ */
+import { sign, verify } from 'node:crypto';
+import { base64url, fromBase64url, signingPrivateKey, signingPublicKey } from './keys.js';
+import { teamSecretsError } from './errors.js';
+/**
+ * Canonical JSON of `value`: object keys sorted at every depth, no whitespace, `undefined` values (object
+ * fields only, never array elements) dropped. Only JSON's own shapes are accepted — `null`, booleans,
+ * strings, finite numbers, arrays, and plain objects (prototype `Object.prototype` or `null`) — so a
+ * `Date`, `Map`, `Set`, class instance, function, symbol, `NaN` or `±Infinity` throws rather than silently
+ * signing something that would not round-trip through YAML the same way twice. `-0` is written as `0`
+ * (`JSON.stringify` already does this, and YAML has no distinct negative zero), which is deliberate, not
+ * an oversight.
+ *
+ * @throws WirebenchError `team-secrets-not-canonical`
+ */
+export function canonicalJson(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'boolean' || typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw teamSecretsError('team-secrets-not-canonical', { reason: 'non-finite number' });
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw teamSecretsError('team-secrets-not-canonical', { reason: 'not a plain object' });
+        }
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+    }
+    // undefined, function, symbol, bigint — none of them are a JSON value.
+    throw teamSecretsError('team-secrets-not-canonical', { reason: `unsupported type ${typeof value}` });
+}
+/** A shallow copy of `doc` without its `signature` field. */
+export function withoutSignature(doc) {
+    const copy = { ...doc };
+    delete copy['signature'];
+    return copy;
+}
+function signedBytes(doc) {
+    return Buffer.from(canonicalJson(withoutSignature(doc)), 'utf8');
+}
+/** `doc` with a fresh `signature` by `keys`; an existing signature is replaced. */
+export function signDocument(doc, keys) {
+    const signature = base64url(sign(null, signedBytes(doc), signingPrivateKey(keys)));
+    return { ...withoutSignature(doc), signature };
+}
+/** Whether `doc.signature` is `signingKey`'s signature over the rest of `doc`. Never throws. */
+export function verifyDocument(doc, signingKey) {
+    try {
+        return verify(null, signedBytes(doc), signingPublicKey(signingKey), fromBase64url(doc.signature));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/team-secrets/vault.d.ts

@@ -0,0 +1,49 @@
+import type { MachineKeys } from './keys.js';
+import type { AccessState, KeyInfo } from './log.js';
+import { type SecretKey, type VaultEntryFile } from './schema.js';
+/** A new value (§3.3): fresh data key, wrapped for `recipients`, signed by `signer`, dated `at`. */
+export declare function buildVaultEntry(input: {
+    readonly secret: SecretKey;
+    readonly label: string;
+    readonly value: string;
+    readonly recipients: readonly KeyInfo[];
+    readonly signer: MachineKeys;
+    readonly at: string;
+}): VaultEntryFile;
+/** The same value under a fresh data key for `recipients` only (§3.6); the value time is kept. */
+export declare function sealVaultEntry(entry: VaultEntryFile, value: string, recipients: readonly KeyInfo[], signer: MachineKeys): VaultEntryFile;
+/** Every approved key the log has a verified request for. */
+export declare function approvedRecipients(state: AccessState): KeyInfo[];
+export type VaultVerdict = 'trusted' | 'wrong-id' | 'not-approved' | 'bad-signature';
+/** §6: trusted only when it sits under its own id and an approved key signed it. */
+export declare function verifyVaultEntry(entry: VaultEntryFile, fileId: string, state: AccessState): VaultVerdict;
+/** The value, when `entry` is wrapped for `me` and opens; `undefined` otherwise. */
+export declare function openVaultEntry(entry: VaultEntryFile, me: MachineKeys): string | undefined;
+/**
+ * §3.4 healing: `entry` with a wrap added for each approved key it lacks, under the same data key, re-signed
+ * by `me`. `undefined` when nothing is missing or `me` cannot open the data key. Never removes a wrap.
+ * Callers heal trusted entries only.
+ */
+export declare function healVaultEntry(entry: VaultEntryFile, state: AccessState, me: MachineKeys): VaultEntryFile | undefined;
+/** Plan decision 6: the entry still carries a wrap for a key the log no longer approves. */
+export declare function wrapsUnapprovedKey(entry: VaultEntryFile, state: AccessState): boolean;
+export interface RotateMark {
+    readonly entryId: string;
+    readonly label: string;
+    readonly secret: SecretKey;
+    /** The names on the removed keys that could read this value. */
+    readonly removedNames: string[];
+}
+/**
+ * §3.6: a value set at or before a removal was readable by the removed key (plan decision 5), so it is marked
+ * until it changes. Pass trusted entries only, keyed by id.
+ */
+export declare function rotateMarks(values: ReadonlyMap<string, VaultEntryFile>, state: AccessState): RotateMark[];
+/**
+ * {@link rotateMarks} for removals given by name and time: a machine that remembers a removal it saw keeps its
+ * marks even after the removed key's request file is gone from the tree.
+ */
+export declare function rotateMarksFor(values: ReadonlyMap<string, VaultEntryFile>, removals: readonly {
+    readonly at: string;
+    readonly name: string;
+}[]): RotateMark[];

package/dist/team-secrets/vault.js

@@ -0,0 +1,148 @@
+/**
+ * Vault entries (§2, §3.3–§3.6): build one for the approved keys, verify it against the replayed log,
+ * open it with this machine's key, seal it again with a fresh data key (removal, late re-encryption), heal
+ * it with wraps for keys approved since, and say which values a removed key could read. Pure.
+ *
+ * Wrapping a data key for a recipient can fail with `team-secrets-bad-key` (a malformed or low-order
+ * key, e.g. from a corrupted key request that still passed schema validation). One bad recipient must
+ * never stop the others: it is skipped, and its absence from `wraps` is the only report a caller needs —
+ * a recipient that was supposed to be able to read the value but has no wrap for it simply cannot.
+ */
+import { decryptValue, encryptValue, newDataKey, unwrapDataKey, wrapDataKey } from './envelope.js';
+import { WirebenchError } from '../errors.js';
+import { vaultEntryId } from './schema.js';
+import { signDocument, verifyDocument, withoutSignature } from './sign.js';
+/** `wrapDataKey(dataKey, recipient.encryptionKey)`, or `undefined` for a recipient whose key is bad. */
+function tryWrap(dataKey, recipient) {
+    try {
+        return wrapDataKey(dataKey, recipient.encryptionKey);
+    }
+    catch (error) {
+        if (error instanceof WirebenchError && error.code === 'team-secrets-bad-key') {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function seal(body, value, recipients, signer) {
+    const dataKey = newDataKey();
+    const wraps = {};
+    for (const recipient of recipients) {
+        const wrap = tryWrap(dataKey, recipient);
+        if (wrap !== undefined) {
+            wraps[recipient.keyId] = wrap;
+        }
+    }
+    return signDocument({
+        version: 1,
+        secret: body.secret,
+        label: body.label,
+        cipher: encryptValue(value, dataKey, vaultEntryId(body.secret)),
+        wraps,
+        updatedAt: body.updatedAt,
+        updatedBy: signer.keyId,
+    }, signer);
+}
+/** A new value (§3.3): fresh data key, wrapped for `recipients`, signed by `signer`, dated `at`. */
+export function buildVaultEntry(input) {
+    return seal({ secret: input.secret, label: input.label, updatedAt: input.at }, input.value, input.recipients, input.signer);
+}
+/** The same value under a fresh data key for `recipients` only (§3.6); the value time is kept. */
+export function sealVaultEntry(entry, value, recipients, signer) {
+    return seal(entry, value, recipients, signer);
+}
+/** Every approved key the log has a verified request for. */
+export function approvedRecipients(state) {
+    return [...state.approved].flatMap((keyId) => {
+        const info = state.keys.get(keyId);
+        return info === undefined ? [] : [info];
+    });
+}
+/** §6: trusted only when it sits under its own id and an approved key signed it. */
+export function verifyVaultEntry(entry, fileId, state) {
+    if (vaultEntryId(entry.secret) !== fileId) {
+        return 'wrong-id';
+    }
+    if (!state.approved.has(entry.updatedBy)) {
+        return 'not-approved';
+    }
+    const signer = state.keys.get(entry.updatedBy);
+    if (signer === undefined) {
+        // Approved, but the log never saw a verified key request for it — there is no signature to check.
+        return 'not-approved';
+    }
+    return verifyDocument(entry, signer.signingKey) ? 'trusted' : 'bad-signature';
+}
+/** The value, when `entry` is wrapped for `me` and opens; `undefined` otherwise. */
+export function openVaultEntry(entry, me) {
+    const wrap = entry.wraps[me.keyId];
+    if (wrap === undefined) {
+        return undefined;
+    }
+    try {
+        return decryptValue(entry.cipher, unwrapDataKey(wrap, me), vaultEntryId(entry.secret));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * §3.4 healing: `entry` with a wrap added for each approved key it lacks, under the same data key, re-signed
+ * by `me`. `undefined` when nothing is missing or `me` cannot open the data key. Never removes a wrap.
+ * Callers heal trusted entries only.
+ */
+export function healVaultEntry(entry, state, me) {
+    const missing = approvedRecipients(state).filter((recipient) => entry.wraps[recipient.keyId] === undefined);
+    const mine = entry.wraps[me.keyId];
+    if (missing.length === 0 || mine === undefined) {
+        return undefined;
+    }
+    let dataKey;
+    try {
+        dataKey = unwrapDataKey(mine, me);
+    }
+    catch {
+        return undefined;
+    }
+    const wraps = { ...entry.wraps };
+    let added = false;
+    for (const recipient of missing) {
+        const wrap = tryWrap(dataKey, recipient);
+        if (wrap !== undefined) {
+            wraps[recipient.keyId] = wrap;
+            added = true;
+        }
+    }
+    if (!added) {
+        // Every missing recipient had a bad key, so healing would produce nothing but a re-signed copy of
+        // the same wraps — machines would re-sign and commit this forever with no progress.
+        return undefined;
+    }
+    return signDocument({ ...withoutSignature(entry), wraps, updatedBy: me.keyId }, me);
+}
+/** Plan decision 6: the entry still carries a wrap for a key the log no longer approves. */
+export function wrapsUnapprovedKey(entry, state) {
+    return Object.keys(entry.wraps).some((keyId) => !state.approved.has(keyId));
+}
+/**
+ * §3.6: a value set at or before a removal was readable by the removed key (plan decision 5), so it is marked
+ * until it changes. Pass trusted entries only, keyed by id.
+ */
+export function rotateMarks(values, state) {
+    return rotateMarksFor(values, state.removed.map((removal) => ({ at: removal.at, name: state.keys.get(removal.keyId)?.name ?? removal.keyId })));
+}
+/**
+ * {@link rotateMarks} for removals given by name and time: a machine that remembers a removal it saw keeps its
+ * marks even after the removed key's request file is gone from the tree.
+ */
+export function rotateMarksFor(values, removals) {
+    const marks = [];
+    for (const [entryId, entry] of values) {
+        const setAt = Date.parse(entry.updatedAt);
+        const names = removals.filter((removal) => setAt <= Date.parse(removal.at)).map((removal) => removal.name);
+        if (names.length > 0) {
+            marks.push({ entryId, label: entry.label, secret: entry.secret, removedNames: [...new Set(names)] });
+        }
+    }
+    return marks;
+}

package/dist/validate/wsi/run-message.d.ts

@@ -5,7 +5,7 @@
  * wire — both halves of it. The report shape is the same {@link WsiReport}, so a single renderer
  * (and a single HTML export) serves both.
  */
-import type { SoapExchange } from '../../types.js';
+import type { SoapExchange } from '../../soap/types.js';
 import type { WsdlDefinition } from '../../wsdl/model.js';
 import type { OperationRef } from '../../soap/request-builder.js';
 import type { WsiMessageBinding, WsiMessageContext, WsiMessageDirection, WsiReport } from './types.js';
@@ -41,7 +41,7 @@ export declare function wsiMessageContext(exchange: SoapExchange, options: RunMe
 export declare function runMessageAssertions(exchange: SoapExchange, options: RunMessageAssertionsOptions): WsiReport;
 /**
  * Derives the {@link WsiMessageBinding} one operation implies, so a caller holding an
- * `ImportResult` does not have to walk the model itself. Returns `undefined` when the binding is
+ * `WsdlImportResult` does not have to walk the model itself. Returns `undefined` when the binding is
  * not a SOAP binding, or has no such operation.
  *
  * @param definition the merged description

package/dist/validate/wsi/run-message.js

@@ -162,7 +162,7 @@ export function runMessageAssertions(exchange, options) {
 }
 /**
  * Derives the {@link WsiMessageBinding} one operation implies, so a caller holding an
- * `ImportResult` does not have to walk the model itself. Returns `undefined` when the binding is
+ * `WsdlImportResult` does not have to walk the model itself. Returns `undefined` when the binding is
  * not a SOAP binding, or has no such operation.
  *
  * @param definition the merged description

package/dist/validate/wsi/run-wsdl.d.ts

@@ -6,7 +6,7 @@ import type { DefinitionBundle } from '../../wsdl/resolver.js';
 import type { SchemaSet } from '../../xsd/schema-set.js';
 import type { ValidationProblem } from '../types.js';
 import type { WsiReport, WsiWsdlContext } from './types.js';
-/** What {@link wsiWsdlContext} needs: exactly the interesting half of an `ImportResult`. */
+/** What {@link wsiWsdlContext} needs: exactly the interesting half of a `WsdlImportResult`. */
 export interface WsiWsdlContextInput {
     readonly definition: WsdlDefinition;
     readonly bundle: DefinitionBundle;
@@ -15,7 +15,7 @@ export interface WsiWsdlContextInput {
 /**
  * Builds the context the assertions run against, indexing the bundle's documents by location.
  *
- * @param input the parsed definition, its bundle and its schema set (an `ImportResult` fits)
+ * @param input the parsed definition, its bundle and its schema set (a `WsdlImportResult` fits)
  */
 export declare function wsiWsdlContext(input: WsiWsdlContextInput): WsiWsdlContext;
 /** Options accepted by {@link runWsdlAssertions}. */

package/dist/validate/wsi/run-wsdl.js

@@ -6,7 +6,7 @@ import { isNotApplicable } from './types.js';
 /**
  * Builds the context the assertions run against, indexing the bundle's documents by location.
  *
- * @param input the parsed definition, its bundle and its schema set (an `ImportResult` fits)
+ * @param input the parsed definition, its bundle and its schema set (a `WsdlImportResult` fits)
  */
 export function wsiWsdlContext(input) {
     const documents = new Map();

package/dist/validate/wsi/types.d.ts

@@ -10,7 +10,7 @@
  * licence); the rest of every assertion's description is a paraphrase.
  */
 import type { Document, Element } from '@xmldom/xmldom';
-import type { SoapExchange } from '../../types.js';
+import type { SoapExchange } from '../../soap/types.js';
 import type { WsdlDefinition } from '../../wsdl/model.js';
 import type { DefinitionBundle } from '../../wsdl/resolver.js';
 import type { SchemaSet } from '../../xsd/schema-set.js';

package/dist/webhooks/model.d.ts

@@ -0,0 +1,138 @@
+/**
+ * A project's webhook collection: outbound requests that play a provider calling the user's own
+ * receiver (spec `2026-09-28-wirebench-openapi-webhooks-import-design.md` §4). Items are ordinary
+ * REST requests; the collection and its folders carry a *target* where an API carries a base URL.
+ */
+import { WirebenchError } from '../errors.js';
+import type { AuthConfig, CreateOptions } from '../project/model.js';
+import type { RestFolder, RestRequestDef } from '../rest/model.js';
+import type { SignatureScheme } from '../http/webhook-signature.js';
+/** The link from an imported item back to the OpenAPI entry it came from. */
+export type HookLink = {
+    readonly kind: 'webhook';
+    readonly name: string;
+} | {
+    readonly kind: 'callback';
+    /** The parent operation's contract key, e.g. `post /subscriptions`. */
+    readonly operation: string;
+    readonly name: string;
+    /** The callback's path-item key, verbatim, e.g. `{$request.body#/callbackUrl}`. */
+    readonly expression: string;
+};
+/**
+ * How the webhook collection, a folder or an item signs what it sends (spec §5.1). Absent means
+ * inherit: the item, then the nearest folder, then the collection; nothing set anywhere is `none`.
+ */
+export type WebhookSigning = {
+    readonly mode: 'none';
+} | {
+    readonly mode: 'sign';
+    readonly scheme: SignatureScheme;
+    /** Opaque reference into the OS-keychain-backed secret store. Never a secret value. */
+    readonly secretRef?: string;
+    /** The name CI supplies this secret under: `WIREBENCH_SECRET_<name>`. Not a secret; committed. */
+    readonly secretEnv?: string;
+};
+/** The signing an item sends with, and where it was set. */
+export interface EffectiveSigning {
+    readonly signing: WebhookSigning;
+    readonly from: 'item' | 'folder' | 'collection' | 'default';
+    /** The item's or the folder's name; absent for the collection and the default. */
+    readonly fromName?: string;
+}
+/** A folder of the webhook collection: a REST folder that may override the target. */
+export interface WebhookFolder extends Omit<RestFolder, 'folders'> {
+    /** Overrides the inherited target for everything inside; the nearest folder that sets one wins. */
+    readonly target?: string;
+    /** Overrides the inherited signing for everything inside. */
+    readonly signing?: WebhookSigning;
+    /** Set on a group imported from an API's definition: that API, so its update can find the group. */
+    readonly source?: {
+        readonly apiId: string;
+    };
+    readonly folders: readonly WebhookFolder[];
+}
+/** One project's webhook collection. */
+export interface WebhookCollection {
+    /** Where items are sent; may contain `${…}` properties. */
+    readonly target: string;
+    /** What items (and folders) whose auth is `inherit` end up using. */
+    readonly auth?: AuthConfig;
+    /** Overrides the inherited signing for everything inside. */
+    readonly signing?: WebhookSigning;
+    readonly folders: readonly WebhookFolder[];
+    readonly requests: readonly RestRequestDef[];
+}
+/** The target a new collection starts with. */
+export declare const DEFAULT_WEBHOOK_TARGET = "${webhookTarget}";
+/** The project property a new collection seeds, empty, when the project has none by that name. */
+export declare const WEBHOOK_TARGET_PROPERTY = "webhookTarget";
+/** Prefix of the id the desktop gives a project's collection on the wire: `webhooks:<projectId>`. */
+export declare const WEBHOOKS_COLLECTION_PREFIX = "webhooks:";
+export interface CreateWebhookCollectionInput {
+    readonly target?: string;
+    readonly auth?: AuthConfig;
+    readonly signing?: WebhookSigning;
+    readonly folders?: readonly WebhookFolder[];
+    readonly requests?: readonly RestRequestDef[];
+}
+/** Creates an empty collection aimed at {@link DEFAULT_WEBHOOK_TARGET}. */
+export declare function createWebhookCollection(input?: CreateWebhookCollectionInput): WebhookCollection;
+export interface CreateWebhookFolderInput extends CreateOptions {
+    readonly slug?: string;
+    readonly description?: string;
+    readonly auth?: AuthConfig;
+    readonly target?: string;
+    readonly signing?: WebhookSigning;
+    readonly source?: {
+        readonly apiId: string;
+    };
+    readonly folders?: readonly WebhookFolder[];
+    readonly requests?: readonly RestRequestDef[];
+}
+/** Creates a webhook folder. */
+export declare function createWebhookFolder(name: string, input?: CreateWebhookFolderInput): WebhookFolder;
+type Tree = Pick<WebhookCollection, 'folders' | 'requests'>;
+/** Every request of the collection, root first, then each folder depth-first. */
+export declare function webhookRequests(tree: Tree): RestRequestDef[];
+/** Every folder of the collection, depth-first. */
+export declare function webhookFolders(tree: Tree): WebhookFolder[];
+/** The request with `id`, and the folders from the root down to it. */
+export declare function webhookPath(tree: Tree, id: string): {
+    readonly request: RestRequestDef;
+    readonly chain: readonly WebhookFolder[];
+} | undefined;
+/** The request with `id`, anywhere in the collection. */
+export declare function findWebhookRequest(tree: Tree, id: string): RestRequestDef | undefined;
+/** The target an item under `chain` (root → leaf folders) is sent to, before property expansion. */
+export declare function effectiveTarget(collection: Pick<WebhookCollection, 'target'>, chain: readonly WebhookFolder[]): string;
+/**
+ * The signing `request`, under `chain` (root → leaf folders), is sent with: its own, else the
+ * nearest folder's, else the collection's, else none. Takes the request itself so a caller holding
+ * an edited copy (the desktop's draft) resolves what will actually be sent.
+ */
+export declare function signingAlong(collection: Pick<WebhookCollection, 'signing'>, chain: readonly WebhookFolder[], request: RestRequestDef): EffectiveSigning;
+/** The signing request `requestId` is sent with (spec §5.1); none for an id the collection lacks. */
+export declare function effectiveSigning(collection: WebhookCollection, requestId: string): EffectiveSigning;
+/** `the item “Paid”`, `the folder “Orders”`, `the Webhooks collection`. */
+export declare function signingSourceLabel(effective: EffectiveSigning): string;
+/**
+ * The ref a run's `GetSecret` is asked for. With only a CI name, a pseudo-ref whose declared name
+ * is that CI name, so `WIREBENCH_SECRET_<secretEnv>` is read first (`envVariablesFor`).
+ */
+export declare function signingSecretRef(signing: Extract<WebhookSigning, {
+    mode: 'sign';
+}>): string | undefined;
+/**
+ * Refuses a webhook item's target that cannot be sent to, once it is expanded: an empty one (unless
+ * the item's own URL is absolute) and one that is not `http(s)`. A target still holding a reference
+ * nothing resolved is left to the unresolved list, which already refuses the send and names it.
+ *
+ * @throws WirebenchError `webhook-target-missing` | `webhook-target-invalid`
+ */
+export declare function assertWebhookTarget(baseUrl: string, url: string, unresolved: boolean): void;
+/** The refusal when signing is set but its secret is not: a send never goes out unsigned (§5.2). */
+export declare function signingSecretMissing(effective: EffectiveSigning, ref?: string): WirebenchError;
+/** The key *Update definition* matches an imported item by: kind, name, method — never the URL. */
+export declare function hookKey(link: HookLink, method: string): string;
+export {};

package/dist/webhooks/model.js

@@ -0,0 +1,150 @@
+/**
+ * A project's webhook collection: outbound requests that play a provider calling the user's own
+ * receiver (spec `2026-09-28-wirebench-openapi-webhooks-import-design.md` §4). Items are ordinary
+ * REST requests; the collection and its folders carry a *target* where an API carries a base URL.
+ */
+import { WirebenchError } from '../errors.js';
+import { generateId } from '../project/model.js';
+import { slugify } from '../project/paths.js';
+import { SIGNING_PSEUDO_REF_PREFIX } from '../secrets/env-names.js';
+/** The target a new collection starts with. */
+export const DEFAULT_WEBHOOK_TARGET = '${webhookTarget}';
+/** The project property a new collection seeds, empty, when the project has none by that name. */
+export const WEBHOOK_TARGET_PROPERTY = 'webhookTarget';
+/** Prefix of the id the desktop gives a project's collection on the wire: `webhooks:<projectId>`. */
+export const WEBHOOKS_COLLECTION_PREFIX = 'webhooks:';
+/** Creates an empty collection aimed at {@link DEFAULT_WEBHOOK_TARGET}. */
+export function createWebhookCollection(input = {}) {
+    return {
+        target: input.target ?? DEFAULT_WEBHOOK_TARGET,
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        ...(input.signing !== undefined ? { signing: input.signing } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates a webhook folder. */
+export function createWebhookFolder(name, input = {}) {
+    return {
+        id: input.id ?? (input.newId ?? generateId)(),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        ...(input.target !== undefined ? { target: input.target } : {}),
+        ...(input.signing !== undefined ? { signing: input.signing } : {}),
+        ...(input.source !== undefined ? { source: { apiId: input.source.apiId } } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Every request of the collection, root first, then each folder depth-first. */
+export function webhookRequests(tree) {
+    return [...tree.requests, ...tree.folders.flatMap((folder) => webhookRequests(folder))];
+}
+/** Every folder of the collection, depth-first. */
+export function webhookFolders(tree) {
+    return tree.folders.flatMap((folder) => [folder, ...webhookFolders(folder)]);
+}
+/** The request with `id`, and the folders from the root down to it. */
+export function webhookPath(tree, id) {
+    const request = tree.requests.find((candidate) => candidate.id === id);
+    if (request !== undefined)
+        return { request, chain: [] };
+    for (const folder of tree.folders) {
+        const found = webhookPath(folder, id);
+        if (found !== undefined)
+            return { request: found.request, chain: [folder, ...found.chain] };
+    }
+    return undefined;
+}
+/** The request with `id`, anywhere in the collection. */
+export function findWebhookRequest(tree, id) {
+    return webhookPath(tree, id)?.request;
+}
+/** The target an item under `chain` (root → leaf folders) is sent to, before property expansion. */
+export function effectiveTarget(collection, chain) {
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const target = chain[index]?.target;
+        if (target !== undefined)
+            return target;
+    }
+    return collection.target;
+}
+const NO_SIGNING = { signing: { mode: 'none' }, from: 'default' };
+/**
+ * The signing `request`, under `chain` (root → leaf folders), is sent with: its own, else the
+ * nearest folder's, else the collection's, else none. Takes the request itself so a caller holding
+ * an edited copy (the desktop's draft) resolves what will actually be sent.
+ */
+export function signingAlong(collection, chain, request) {
+    if (request.signing !== undefined)
+        return { signing: request.signing, from: 'item', fromName: request.name };
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const folder = chain[index];
+        if (folder.signing !== undefined)
+            return { signing: folder.signing, from: 'folder', fromName: folder.name };
+    }
+    return collection.signing !== undefined ? { signing: collection.signing, from: 'collection' } : NO_SIGNING;
+}
+/** The signing request `requestId` is sent with (spec §5.1); none for an id the collection lacks. */
+export function effectiveSigning(collection, requestId) {
+    const path = webhookPath(collection, requestId);
+    return path === undefined ? NO_SIGNING : signingAlong(collection, path.chain, path.request);
+}
+/** `the item “Paid”`, `the folder “Orders”`, `the Webhooks collection`. */
+export function signingSourceLabel(effective) {
+    switch (effective.from) {
+        case 'item':
+            return `the item “${effective.fromName ?? ''}”`;
+        case 'folder':
+            return `the folder “${effective.fromName ?? ''}”`;
+        default:
+            return 'the Webhooks collection';
+    }
+}
+/**
+ * The ref a run's `GetSecret` is asked for. With only a CI name, a pseudo-ref whose declared name
+ * is that CI name, so `WIREBENCH_SECRET_<secretEnv>` is read first (`envVariablesFor`).
+ */
+export function signingSecretRef(signing) {
+    if (signing.secretRef !== undefined && signing.secretRef !== '')
+        return signing.secretRef;
+    return signing.secretEnv !== undefined ? `${SIGNING_PSEUDO_REF_PREFIX}${signing.secretEnv}` : undefined;
+}
+const ABSOLUTE_HTTP = /^https?:\/\//i;
+/**
+ * Refuses a webhook item's target that cannot be sent to, once it is expanded: an empty one (unless
+ * the item's own URL is absolute) and one that is not `http(s)`. A target still holding a reference
+ * nothing resolved is left to the unresolved list, which already refuses the send and names it.
+ *
+ * @throws WirebenchError `webhook-target-missing` | `webhook-target-invalid`
+ */
+export function assertWebhookTarget(baseUrl, url, unresolved) {
+    if (baseUrl.trim() === '') {
+        if (!ABSOLUTE_HTTP.test(url)) {
+            throw new WirebenchError('webhook-target-missing', 'Set the Webhooks target');
+        }
+        return;
+    }
+    if (!ABSOLUTE_HTTP.test(baseUrl) && !(unresolved && baseUrl.includes('${'))) {
+        throw new WirebenchError('webhook-target-invalid', 'The Webhooks target must start with http:// or https://');
+    }
+}
+/** The refusal when signing is set but its secret is not: a send never goes out unsigned (§5.2). */
+export function signingSecretMissing(effective, ref) {
+    return new WirebenchError('webhook-signing-secret', `Signing is set on ${signingSourceLabel(effective)} but its secret is not set`, {
+        details: {
+            from: effective.from,
+            ...(effective.fromName !== undefined ? { fromName: effective.fromName } : {}),
+            // The CLI names the variable to set from this (`explainMissingSecret`).
+            ...(ref !== undefined ? { ref } : {}),
+        },
+    });
+}
+/** The key *Update definition* matches an imported item by: kind, name, method — never the URL. */
+export function hookKey(link, method) {
+    const verb = method.toLowerCase();
+    return link.kind === 'webhook' ? `webhook ${link.name} ${verb}` : `callback ${link.operation} ${link.name} ${verb}`;
+}

package/dist/workspace/commit-message.d.ts

@@ -8,7 +8,7 @@
  * with `node:path`, which would emit `\` on Windows and break every pattern below.
  */
 /** What kind of entity a tree path belongs to. */
-export type TreeEntityKind = 'workspace' | 'environment' | 'project' | 'interface' | 'request' | 'project-environment' | 'wss' | 'keystores' | 'attachment' | 'definition' | 'other';
+export type TreeEntityKind = 'workspace' | 'environment' | 'project' | 'interface' | 'request' | 'project-environment' | 'wss' | 'keystores' | 'attachment' | 'definition' | 'team-secrets' | 'other';
 /**
  * The entity a tree path belongs to. `key` identifies the entity itself (as opposed to the file):
  * a request's `.request.yaml` and `.xml` share one key, as do every file under one interface's

package/dist/workspace/commit-message.js

@@ -9,7 +9,7 @@
  */
 import { WSS_DIR, REQUEST_SUFFIX } from '../project/paths.js';
 import { KEYSTORES_PATH } from '../project/serialize.js';
-import { WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR } from './paths.js';
+import { TEAM_SECRETS_DIR, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR } from './paths.js';
 /** Last `/`-separated segment of a path. */
 function basename(path) {
     const index = path.lastIndexOf('/');
@@ -89,6 +89,10 @@ export function describeTreePath(relativePath) {
         const rest = projectMatch[2] ?? '';
         return describeProjectPath(projectSlug, rest, relativePath);
     }
+    const teamSecretsMatch = new RegExp(`^${TEAM_SECRETS_DIR}/(?:keys|access|values)/([^/]+)\\.yaml$`).exec(relativePath);
+    if (teamSecretsMatch !== null) {
+        return { kind: 'team-secrets', name: teamSecretsMatch[1] ?? basename(relativePath), key: relativePath };
+    }
     return { kind: 'other', name: basename(relativePath), key: relativePath };
 }
 /** Human-facing label for one entity kind, singular. */
@@ -103,6 +107,7 @@ const LABELS = {
     keystores: 'keystores',
     attachment: 'attachment',
     definition: 'definition',
+    'team-secrets': 'team secrets file',
     other: 'file',
 };
 /** Kinds whose label does not take a plain `s` suffix when the count isn't 1. */