@dudousxd/nestjs-catalog 0.10.0 → 0.11.0

package/dist/catalog.pipeline.d.ts

@@ -442,13 +442,48 @@ export interface WorkflowGraph {
  * an audit. The limitation is real and worth stating plainly — an edited graph
  * cannot be reconstructed from an old run, only identified as different.
  */
+/**
+ * Whether this graph is still being drawn, or is something somebody declared
+ * finished.
+ *
+ * The distinction exists because validation used to be the gate on *saving*, and
+ * that made an unfinished graph unstorable: `saveWorkflow` refused anything
+ * `validateWorkflow` had an issue with, so a canvas with one node on it could
+ * not be written down at all and closing the tab lost it. Worse, it made the
+ * canvas lie about ordinary work — clicking "+ Sink" produces a node that is
+ * unreachable from any source and names no type, both true and both useless one
+ * second after the click, because a just-added node is unwired by construction.
+ *
+ * So the gate moved rather than loosened. Validation is now the gate on
+ * publishing, and the same `validateWorkflow` still decides — a draft is not a
+ * graph that skipped the rules, it is a graph nobody has claimed is finished
+ * yet. Everything that consumes a workflow asks for `ready`: a connector may
+ * only point at one, and a promotion may only carry one. What crosses an
+ * environment should be something a person declared done.
+ */
+export declare const WORKFLOW_STATUSES: readonly ["draft", "ready"];
+export type WorkflowStatus = (typeof WORKFLOW_STATUSES)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowStatus(value: unknown): value is WorkflowStatus;
 export interface CatalogWorkflow {
     id: string;
     name: string;
     description?: string;
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
-    /** Bumped whenever the graph's behaviour changes. Never on a rename or a move. */
+    /** See {@link WORKFLOW_STATUSES}. A graph is `draft` until somebody publishes it. */
+    status: WorkflowStatus;
+    /**
+     * Bumped whenever the graph's behaviour changes. Never on a rename or a move.
+     *
+     * Bumped on a **draft** edit too, which looks like exactly the inflation this
+     * rule exists to prevent and is not. The counter's job is to make
+     * {@link ConnectorRun.workflowVersion} answer "which shape ran": freezing it
+     * while a graph is drafted would let a run recorded at v4 and a later run also
+     * at v4 mean two different graphs, which is the one thing that field must
+     * never do. Drafting therefore inflates a number nobody reads — cheap — rather
+     * than making a number somebody does read ambiguous.
+     */
     version: number;
     /** Fingerprint of the graph at this version. See {@link workflowGraphHash}. */
     graphHash: string;
@@ -660,7 +695,24 @@ export interface CatalogWorkflowStore {
     listWorkflows(): Promise<CatalogWorkflow[]>;
     getWorkflow(id: string): Promise<CatalogWorkflow | undefined>;
     /**
-     * Validates before it writes, and refuses naming the node.
+     * Writes. Validates only what it must.
+     *
+     * A **draft** is written without validating, which is the whole of the change
+     * and the reason {@link WORKFLOW_STATUSES} exists: a graph you have not
+     * finished has to be storable, or closing the tab loses it. A **ready**
+     * workflow is still validated on every save, because it is the one that runs.
+     *
+     * `status` is not an input. A save cannot promote a draft to ready — that is
+     * {@link publishWorkflow}, which exists so there is one place that validates
+     * and one place that can explain why it refused. A save of an already-ready
+     * workflow keeps it ready, and **refuses an edit that would make it invalid**
+     * rather than quietly demoting it to draft. Demotion was the other option and
+     * it is the one that loses a running pipeline silently: a connector may only
+     * point at a ready graph, so a save that dropped the status would disable a
+     * scheduled load with nothing said to anybody. Refusing puts the error in
+     * front of the person who is editing, at the moment they edit. To park a
+     * broken idea on a live graph, {@link unpublishWorkflow} it first and be told
+     * which connectors that stops.
      *
      * `version`, `graphHash` and `targetType` are not inputs: the first two are
      * derived from the graph and the third from the sink, and accepting them from
@@ -670,6 +722,34 @@ export interface CatalogWorkflowStore {
         id?: string;
         description?: string;
     }, createdBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Declare a graph finished: validate it, and make it `ready`.
+     *
+     * A transition rather than a field on save, and the argument is that this is
+     * the only shape with somewhere to put the refusal. "Ready" is a claim that
+     * has to be checked, and a check that fails owes an explanation naming the
+     * nodes — `validateWorkflow` produces exactly that, and a boolean field on a
+     * save request has nowhere to return it that is not an error on an operation
+     * the caller thought was about something else. It also makes the audit
+     * question answerable: publishing is an act with an actor, and a field set in
+     * passing during an autosave is not.
+     *
+     * Idempotent on an already-ready graph, because the honest answer to "publish
+     * this thing that is published" is the graph, not an error.
+     */
+    publishWorkflow(id: string, publishedBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Take a graph back to `draft`.
+     *
+     * **Refuses while any connector still runs it**, exactly as
+     * {@link deleteWorkflow} does and for the same reason: a connector may only
+     * point at a ready graph, so unpublishing one out from under a schedule breaks
+     * a load that was working, and the operator needs to know *which* connectors
+     * to point elsewhere first. Refusing here rather than cascading is deliberate —
+     * disabling somebody's connectors as a side effect of an edit to something
+     * else is precisely the silent action this status exists to prevent.
+     */
+    unpublishWorkflow(id: string, unpublishedBy: string): Promise<CatalogWorkflow>;
     /** Refuses while any connector still runs it. */
     deleteWorkflow(id: string): Promise<boolean>;
     /** Which connectors run it. Named, so a refusal can say. */

package/dist/catalog.pipeline.js

@@ -9,10 +9,11 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
+exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isTransformLanguage = isTransformLanguage;
 exports.isWorkflowNodeKind = isWorkflowNodeKind;
+exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
 exports.validateWorkflow = validateWorkflow;
 exports.workflowRunOrder = workflowRunOrder;
@@ -136,6 +137,57 @@ function isWorkflowNodeKind(value) {
  * separator would let one node read another's rows.
  */
 exports.WORKFLOW_NODE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * An authored graph of steps ending in one commit.
+ *
+ * Versioned the way {@link CatalogTransform} is, and for the same question: a
+ * load that produced surprising numbers is investigated afterwards, and "what
+ * ran" is the first thing asked. For a single-transform connector that means
+ * the code; for a workflow it means the code *and* the wiring, so both the
+ * graph version and the per-node transform versions are recorded on the run.
+ *
+ * Like a transform, only the latest shape is kept. Storing every past graph was
+ * the alternative and was rejected for consistency: transforms already answer
+ * "which code ran" with a number and no history, and a model where the graph is
+ * fully recoverable but the code inside it is not would give false confidence in
+ * an audit. The limitation is real and worth stating plainly — an edited graph
+ * cannot be reconstructed from an old run, only identified as different.
+ */
+/**
+ * Whether this graph is still being drawn, or is something somebody declared
+ * finished.
+ *
+ * The distinction exists because validation used to be the gate on *saving*, and
+ * that made an unfinished graph unstorable: `saveWorkflow` refused anything
+ * `validateWorkflow` had an issue with, so a canvas with one node on it could
+ * not be written down at all and closing the tab lost it. Worse, it made the
+ * canvas lie about ordinary work — clicking "+ Sink" produces a node that is
+ * unreachable from any source and names no type, both true and both useless one
+ * second after the click, because a just-added node is unwired by construction.
+ *
+ * So the gate moved rather than loosened. Validation is now the gate on
+ * publishing, and the same `validateWorkflow` still decides — a draft is not a
+ * graph that skipped the rules, it is a graph nobody has claimed is finished
+ * yet. Everything that consumes a workflow asks for `ready`: a connector may
+ * only point at one, and a promotion may only carry one. What crosses an
+ * environment should be something a person declared done.
+ */
+exports.WORKFLOW_STATUSES = [
+    /**
+     * Being drawn. Saves without validating, and cannot run, be scheduled, or be
+     * promoted. An incomplete node here is the normal state rather than an alarm.
+     */
+    'draft',
+    /**
+     * Declared finished, and validated at the moment it was declared. This is the
+     * only status a connector may point at and the only one a promotion carries.
+     */
+    'ready',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowStatus(value) {
+    return exports.WORKFLOW_STATUSES.some((status) => status === value);
+}
 /**
  * How a workflow run is executed here.
  *
@@ -634,7 +686,13 @@ function isWorkflowEdge(value) {
 function supportsWorkflows(store) {
     return (typeof store.listWorkflows === 'function' &&
         typeof store.getWorkflow === 'function' &&
-        typeof store.saveWorkflow === 'function');
+        typeof store.saveWorkflow === 'function' &&
+        // Asked for by name like the rest, rather than assumed to come with
+        // `saveWorkflow`. Promotion publishes what it saves, so a store that has the
+        // save and not the transition would narrow cleanly here and then fail one
+        // call later, in the middle of an apply that has already written types and
+        // transforms into the target.
+        typeof store.publishWorkflow === 'function');
 }
 function supportsWorkflowStages(store) {
     return typeof store.writeStage === 'function' && typeof store.readStage === 'function';

package/dist/catalog.secrets.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Encrypting the credential that has to rest in `catalog_connection.config`.
+ *
+ * `config-secrets.ts` in the pipeline package closed the HTTP half of this: a
+ * connection URL is a password with an address attached, `config` is served by
+ * `GET pipeline/connections` under `catalog:read`, and the redaction stopped it
+ * travelling in a response. `MySqlPipelineStore` closed the write half: a
+ * password-bearing URL that is not already stored is refused, with a message
+ * naming `secretEnvVar`.
+ *
+ * Neither touches the thing this file is about. A redaction protects a reader
+ * coming through the API. It does nothing at all for a database dump, a read
+ * replica, a nightly backup, or anybody holding `SELECT` on the RDS instance —
+ * and for those, `config` is still a list of every password the catalog knows.
+ * `allowInlineCredentials` makes that population larger on purpose, which is
+ * precisely why encryption becomes worth building at the same time as the flag
+ * that needs it.
+ *
+ * ## A seam, not an implementation
+ *
+ * There is no cipher in this file and there must not be one. A library that
+ * shipped AES with a key read from an environment variable would have moved the
+ * problem from one column to one variable, and would have to answer for key
+ * rotation, per-environment separation, and an audit trail — all of which the
+ * host's KMS, Vault, or HSM already answers for, and none of which this package
+ * can answer for on its behalf. What is here is the shape of the question, so a
+ * provider can be written against it: {@link CatalogSecretVault}.
+ *
+ * The library never inspects a ciphertext, never chooses a key, and never
+ * decides an algorithm. It decides *which values* are secrets, *when* they are
+ * sealed, and *what happens when the vault cannot be reached* — three questions
+ * a provider should not have to have an opinion about.
+ *
+ * ## What the default does
+ *
+ * Refuses. {@link RefusingSecretVault} throws on `seal`, naming the token to
+ * bind. A default that quietly stored plaintext would be the worst shape
+ * available here: a host would turn `encryptCredentials` on, see saves succeed,
+ * and have exactly the same column contents as before with a docblock now
+ * claiming otherwise. Every other refusing default in this codebase exists for
+ * the same reason — `CATALOG_LOAD_EXPECTATIONS` unbound means incremental loads
+ * are refused rather than silently unpoliced.
+ */
+/**
+ * What a vault hands back. Stored verbatim; opaque to this library.
+ *
+ * Three fields and no fourth, because everything a rotation needs is here and
+ * nothing a reader could misuse is: the ciphertext says nothing without the
+ * vault, and the vault says nothing without the key. It is a plain JSON object
+ * so that it can sit in the same `json` column the plaintext sat in — no
+ * migration, no second table, and a column that may hold either form for as
+ * long as it takes a deployment to move over. {@link isSealedSecret} is what
+ * tells the two apart on the way out.
+ */
+export interface SealedSecret {
+    /** Which vault sealed it — `CatalogSecretVault.name`. */
+    vault: string;
+    /** Which key, in whatever form that vault names keys. */
+    keyId: string;
+    /**
+     * An opaque string the vault chose. **Not base64, and never decoded here.**
+     *
+     * This said "base64" first, and both provider implementations proved it
+     * wrong from opposite directions: HashiCorp Transit returns
+     * `vault:v1:<base64>`, which has two colons and is not decodable as base64 at
+     * all. The provider stores that verbatim and is right to — the `v1` is the
+     * row's only self-description of which key version sealed it, and
+     * `transit/rewrap` takes exactly that string back.
+     *
+     * The claim was harmless while nothing acted on it, which is what makes it
+     * worth correcting now rather than later: the day something takes it
+     * literally — a base64 `CHECK` constraint, a JSON-schema `contentEncoding`, a
+     * `Buffer.from(value, 'base64')` round trip — it breaks **silently**, because
+     * `Buffer.from` does not throw on input it cannot read. It returns different
+     * bytes.
+     *
+     * So the only rule is: non-empty, and given back to the vault exactly as it
+     * came. {@link isSealedSecret} checks that it is a non-empty string and must
+     * never be tightened past that — any narrower test encodes one vault's format
+     * as the contract and silently rejects the next one's rows.
+     */
+    ciphertext: string;
+}
+/**
+ * Where a secret is being used, so a vault can scope or audit by it.
+ *
+ * Passed to `open` as well as to `seal`, and that is the interesting half: a
+ * KMS provider can put this in an encryption context so a ciphertext sealed for
+ * `connection/abc/url` cannot be replayed as `connector/xyz/url`, and a Vault
+ * provider can write an audit line naming the row somebody's credential was
+ * read for. Neither is possible if the seam only carries bytes.
+ */
+export interface SecretContext {
+    /** `connection` or `connector`. */
+    kind: string;
+    /**
+     * The row's id. Present and stable whenever `MySqlPipelineStore` is the
+     * caller, including on a first save.
+     *
+     * This said "absent on a first save", and both provider implementations
+     * independently left `id` out of their encryption context because of it —
+     * correctly, given what it said. A context that is absent on create and
+     * present on update seals under one context and opens under another, and the
+     * failure lands at the first connector run rather than at the save.
+     *
+     * So the store was changed rather than the providers: it mints the row's id
+     * *before* sealing instead of inside `em.create`, which costs one hoisted
+     * `randomUUID()` and makes the binding property real. A provider may now put
+     * this in an encryption context and get what the seam always claimed —
+     * `connection/abc/url` is not replayable as `connection/xyz/url`.
+     *
+     * Two things this does NOT make true, both worth stating before somebody
+     * relies on them:
+     *
+     *  - It is still optional in the type, because a host calling a vault
+     *    directly is not obliged to have a row. A provider that binds it must
+     *    decide what an absent `id` means for its own callers.
+     *  - **Rows sealed before this existed were sealed without it.** A provider
+     *    that starts binding `id` on a deployment that already has sealed rows
+     *    strands every one of them. Binding it is safe on a new deployment, and
+     *    on an existing one only behind a re-seal.
+     */
+    id?: string;
+    /** The config key being sealed — `url`, `password`. */
+    field: string;
+}
+/**
+ * The seam a host binds to make credentials unreadable in the catalog's own
+ * database.
+ *
+ * Both methods are async and both are expected to fail sometimes: they are
+ * network calls to something outside this process. What each failure *means*
+ * is not symmetric, and the store treats them differently — see
+ * {@link SecretSealFailedError} and {@link SecretOpenFailedError}.
+ */
+export interface CatalogSecretVault {
+    /**
+     * Stable, stored on every SealedSecret so a rotation can find its own.
+     *
+     * Stable across deployments and releases, not merely across a process: it is
+     * written into rows. Renaming it strands every row already sealed under the
+     * old name, which the store refuses loudly rather than guessing at — a bound
+     * vault whose name does not match the row's is not asked to try.
+     */
+    readonly name: string;
+    seal(plaintext: string, context: SecretContext): Promise<SealedSecret>;
+    open(sealed: SealedSecret, context: SecretContext): Promise<string>;
+}
+/**
+ * The token a host binds one vault — or several — to.
+ *
+ * **Several is the supported shape, and it is what makes rotation possible.**
+ * Bind `CatalogSecretVault[]` and the store seals with the *first* and opens
+ * with whichever one's `name` matches the row. Moving from one vault to another
+ * is then: bind `[next, current]`, let saves reseal under `next`, and drop
+ * `current` when nothing is sealed under it any more. With a single vault that
+ * transition has no middle — the moment `next` is bound, every row sealed by
+ * `current` is unreadable — and a library that made rotation require an outage
+ * would be a library whose keys never got rotated.
+ *
+ * `@Optional()` where it is injected, so a host that binds nothing still boots.
+ * It then gets {@link RefusingSecretVault}, which costs nothing until something
+ * actually asks for a seal.
+ */
+export declare const CATALOG_SECRET_VAULT: unique symbol;
+/**
+ * Whether a value that came back out of a JSON column is a sealed secret.
+ *
+ * A runtime guard and not a cast, because this is a `json` column: MikroORM
+ * hands back whatever is in it, and what is in it may have been written by a
+ * different release, by a hand-run `UPDATE`, or by a host's own seeder. The
+ * same argument `WorkflowRow.nodes` makes for being typed `unknown[]`.
+ *
+ * Deliberately strict about emptiness. A `{ vault: '', keyId: '', ciphertext:
+ * '' }` is not a sealed secret and must not be treated as one — treating it as
+ * one sends it to a vault that will refuse it, and the operator is told their
+ * vault is broken when the row is. An empty ciphertext falls through as an
+ * ordinary config value instead, which is what it is.
+ *
+ * Deliberately loose about everything else, and that is the harder half to
+ * hold. `ciphertext` is tested for "non-empty string" and must never be tested
+ * for more — not base64, not a length, not a prefix. Two vaults already
+ * disagree about its shape: KMS hands back base64, Transit hands back
+ * `vault:v1:<base64>`. Any tighter check would encode one of them as the
+ * contract and start silently refusing the other's rows, which surfaces as
+ * "this credential is not encrypted" for a value that is.
+ *
+ * What it cannot distinguish is a config value a host deliberately authored as
+ * an object with exactly these three non-empty string fields. Nothing prevents
+ * that and nothing sensible produces it; saying so is better than adding a
+ * marker field that would then have to be defended against forgery it also
+ * could not detect.
+ */
+export declare function isSealedSecret(value: unknown): value is SealedSecret;
+/** The name {@link RefusingSecretVault} answers to. No row can carry it: it never seals. */
+export declare const UNCONFIGURED_VAULT = "unconfigured";
+/**
+ * The default: a vault that will not pretend.
+ *
+ * Bound whenever `CATALOG_SECRET_VAULT` is not, which is every host that has
+ * not thought about this. It costs nothing until `encryptCredentials` is turned
+ * on — the store only reaches a vault when there is something to seal or
+ * something sealed to open — so the refusal lands on the deployment that asked
+ * for encryption and did not say with what, and lands at the first save rather
+ * than at the first run.
+ *
+ * The alternative shapes were both considered and are both worse. A default
+ * that stored plaintext would make `encryptCredentials: true` a no-op with a
+ * reassuring name. A default that base64-encoded would be worse still: it looks
+ * sealed, `isSealedSecret` would agree, and a dump would be trivially reversed
+ * by anybody who noticed.
+ */
+export declare class RefusingSecretVault implements CatalogSecretVault {
+    readonly name = "unconfigured";
+    seal(_plaintext: string, context: SecretContext): Promise<SealedSecret>;
+    open(sealed: SealedSecret, context: SecretContext): Promise<string>;
+}
+/**
+ * Nothing is bound, or nothing bound answers to the name a row carries.
+ *
+ * `retryable = false`, and that field is not decoration. A connector run is
+ * dispatched as a durable step, and the dispatch boundary serialises a throw
+ * into `{message, code, retryable}` — `retryable` is the only field the engine
+ * reads on the way back in, and its predicate is `error?.retryable !== false`.
+ * A missing token will be exactly as missing on the third attempt as on the
+ * first, so this must not burn fifteen minutes of exponential backoff before
+ * saying so. `connector-run.steps.ts` documents that mechanism at length and
+ * this is the same use of it.
+ */
+export declare class SecretVaultNotConfiguredError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    readonly retryable = false;
+    readonly code = "secret_vault_not_configured";
+    constructor(message: string);
+}
+/**
+ * A save could not seal a credential, so the save did not happen.
+ *
+ * Which is the correct outcome and worth being explicit about: the fallback a
+ * reasonable person reaches for — write it in plaintext and log a warning — is
+ * the one thing this feature exists to make impossible. A deployment that
+ * turned `encryptCredentials` on and then, during a vault outage, quietly wrote
+ * three passwords in the clear would have no way to find out which three.
+ *
+ * Deliberately not a `BadRequestException`. The caller's URL is fine; the vault
+ * is down. A 400 sends somebody to edit a field that is correct.
+ */
+export declare class SecretSealFailedError extends Error {
+    readonly code = "secret_seal_failed";
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A read could not open a sealed credential.
+ *
+ * **This is the one whose class matters**, because a connector run is a durable
+ * step and the step decides whether to retry from the error it catches. Two
+ * things had to be got right here and both are load-bearing:
+ *
+ *  - It is **not** a `NotFoundException` or a `BadRequestException`.
+ *    `ConnectorRunSteps.runConnector` catches exactly those two around the
+ *    runner and converts them to `UnavailableConnectorError`, which carries
+ *    `retryable = false`. A vault that timed out would then be filed under
+ *    `connector_unavailable` and never retried — and an operator filtering a
+ *    failed-run list on that code would go looking for a connector somebody
+ *    deleted. That is precisely the confusion `UnmetLoadExpectationError` was
+ *    split into its own class to avoid.
+ *  - `retryable` is **true by default**. A vault being briefly unreachable is
+ *    the same kind of failure as a source being briefly unreachable, which is
+ *    exactly what that step's `retries: 3, backoff exp 60s…900s` policy exists
+ *    for. It is set false only when waiting provably cannot help: nothing is
+ *    bound, or nothing bound answers to the name the row carries.
+ */
+export declare class SecretOpenFailedError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    readonly retryable: boolean;
+    readonly code = "secret_open_failed";
+    constructor(message: string, options: {
+        retryable: boolean;
+        cause?: unknown;
+    });
+}

package/dist/catalog.secrets.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Encrypting the credential that has to rest in `catalog_connection.config`.
+ *
+ * `config-secrets.ts` in the pipeline package closed the HTTP half of this: a
+ * connection URL is a password with an address attached, `config` is served by
+ * `GET pipeline/connections` under `catalog:read`, and the redaction stopped it
+ * travelling in a response. `MySqlPipelineStore` closed the write half: a
+ * password-bearing URL that is not already stored is refused, with a message
+ * naming `secretEnvVar`.
+ *
+ * Neither touches the thing this file is about. A redaction protects a reader
+ * coming through the API. It does nothing at all for a database dump, a read
+ * replica, a nightly backup, or anybody holding `SELECT` on the RDS instance —
+ * and for those, `config` is still a list of every password the catalog knows.
+ * `allowInlineCredentials` makes that population larger on purpose, which is
+ * precisely why encryption becomes worth building at the same time as the flag
+ * that needs it.
+ *
+ * ## A seam, not an implementation
+ *
+ * There is no cipher in this file and there must not be one. A library that
+ * shipped AES with a key read from an environment variable would have moved the
+ * problem from one column to one variable, and would have to answer for key
+ * rotation, per-environment separation, and an audit trail — all of which the
+ * host's KMS, Vault, or HSM already answers for, and none of which this package
+ * can answer for on its behalf. What is here is the shape of the question, so a
+ * provider can be written against it: {@link CatalogSecretVault}.
+ *
+ * The library never inspects a ciphertext, never chooses a key, and never
+ * decides an algorithm. It decides *which values* are secrets, *when* they are
+ * sealed, and *what happens when the vault cannot be reached* — three questions
+ * a provider should not have to have an opinion about.
+ *
+ * ## What the default does
+ *
+ * Refuses. {@link RefusingSecretVault} throws on `seal`, naming the token to
+ * bind. A default that quietly stored plaintext would be the worst shape
+ * available here: a host would turn `encryptCredentials` on, see saves succeed,
+ * and have exactly the same column contents as before with a docblock now
+ * claiming otherwise. Every other refusing default in this codebase exists for
+ * the same reason — `CATALOG_LOAD_EXPECTATIONS` unbound means incremental loads
+ * are refused rather than silently unpoliced.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretOpenFailedError = exports.SecretSealFailedError = exports.SecretVaultNotConfiguredError = exports.RefusingSecretVault = exports.UNCONFIGURED_VAULT = exports.CATALOG_SECRET_VAULT = void 0;
+exports.isSealedSecret = isSealedSecret;
+/**
+ * The token a host binds one vault — or several — to.
+ *
+ * **Several is the supported shape, and it is what makes rotation possible.**
+ * Bind `CatalogSecretVault[]` and the store seals with the *first* and opens
+ * with whichever one's `name` matches the row. Moving from one vault to another
+ * is then: bind `[next, current]`, let saves reseal under `next`, and drop
+ * `current` when nothing is sealed under it any more. With a single vault that
+ * transition has no middle — the moment `next` is bound, every row sealed by
+ * `current` is unreadable — and a library that made rotation require an outage
+ * would be a library whose keys never got rotated.
+ *
+ * `@Optional()` where it is injected, so a host that binds nothing still boots.
+ * It then gets {@link RefusingSecretVault}, which costs nothing until something
+ * actually asks for a seal.
+ */
+exports.CATALOG_SECRET_VAULT = Symbol('CATALOG_SECRET_VAULT');
+/**
+ * Whether a value that came back out of a JSON column is a sealed secret.
+ *
+ * A runtime guard and not a cast, because this is a `json` column: MikroORM
+ * hands back whatever is in it, and what is in it may have been written by a
+ * different release, by a hand-run `UPDATE`, or by a host's own seeder. The
+ * same argument `WorkflowRow.nodes` makes for being typed `unknown[]`.
+ *
+ * Deliberately strict about emptiness. A `{ vault: '', keyId: '', ciphertext:
+ * '' }` is not a sealed secret and must not be treated as one — treating it as
+ * one sends it to a vault that will refuse it, and the operator is told their
+ * vault is broken when the row is. An empty ciphertext falls through as an
+ * ordinary config value instead, which is what it is.
+ *
+ * Deliberately loose about everything else, and that is the harder half to
+ * hold. `ciphertext` is tested for "non-empty string" and must never be tested
+ * for more — not base64, not a length, not a prefix. Two vaults already
+ * disagree about its shape: KMS hands back base64, Transit hands back
+ * `vault:v1:<base64>`. Any tighter check would encode one of them as the
+ * contract and start silently refusing the other's rows, which surfaces as
+ * "this credential is not encrypted" for a value that is.
+ *
+ * What it cannot distinguish is a config value a host deliberately authored as
+ * an object with exactly these three non-empty string fields. Nothing prevents
+ * that and nothing sensible produces it; saying so is better than adding a
+ * marker field that would then have to be defended against forgery it also
+ * could not detect.
+ */
+function isSealedSecret(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const vault = Reflect.get(value, 'vault');
+    const keyId = Reflect.get(value, 'keyId');
+    const ciphertext = Reflect.get(value, 'ciphertext');
+    return (typeof vault === 'string' &&
+        vault.length > 0 &&
+        typeof keyId === 'string' &&
+        typeof ciphertext === 'string' &&
+        ciphertext.length > 0);
+}
+/** The name {@link RefusingSecretVault} answers to. No row can carry it: it never seals. */
+exports.UNCONFIGURED_VAULT = 'unconfigured';
+/**
+ * The default: a vault that will not pretend.
+ *
+ * Bound whenever `CATALOG_SECRET_VAULT` is not, which is every host that has
+ * not thought about this. It costs nothing until `encryptCredentials` is turned
+ * on — the store only reaches a vault when there is something to seal or
+ * something sealed to open — so the refusal lands on the deployment that asked
+ * for encryption and did not say with what, and lands at the first save rather
+ * than at the first run.
+ *
+ * The alternative shapes were both considered and are both worse. A default
+ * that stored plaintext would make `encryptCredentials: true` a no-op with a
+ * reassuring name. A default that base64-encoded would be worse still: it looks
+ * sealed, `isSealedSecret` would agree, and a dump would be trivially reversed
+ * by anybody who noticed.
+ */
+class RefusingSecretVault {
+    name = exports.UNCONFIGURED_VAULT;
+    seal(_plaintext, context) {
+        return Promise.reject(new SecretVaultNotConfiguredError(`encryptCredentials is on, so ${context.kind}.config.${context.field} has to be sealed, and no vault is bound to seal it with. Bind CATALOG_SECRET_VAULT to a CatalogSecretVault — an AWS KMS or HashiCorp Vault provider, or your own — or turn encryptCredentials off and decide what allowInlineCredentials should be instead.`));
+    }
+    open(sealed, context) {
+        // Reachable only through a row this instance did not write, since `seal`
+        // never returns — so the useful thing to say is the name the row is asking
+        // for, which is the one the operator has to go and bind.
+        return Promise.reject(new SecretVaultNotConfiguredError(`${context.kind}.config.${context.field} was sealed by the "${sealed.vault}" vault and no vault is bound to open it. Bind CATALOG_SECRET_VAULT to that provider; nothing else can read this value.`));
+    }
+}
+exports.RefusingSecretVault = RefusingSecretVault;
+/**
+ * Nothing is bound, or nothing bound answers to the name a row carries.
+ *
+ * `retryable = false`, and that field is not decoration. A connector run is
+ * dispatched as a durable step, and the dispatch boundary serialises a throw
+ * into `{message, code, retryable}` — `retryable` is the only field the engine
+ * reads on the way back in, and its predicate is `error?.retryable !== false`.
+ * A missing token will be exactly as missing on the third attempt as on the
+ * first, so this must not burn fifteen minutes of exponential backoff before
+ * saying so. `connector-run.steps.ts` documents that mechanism at length and
+ * this is the same use of it.
+ */
+class SecretVaultNotConfiguredError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    retryable = false;
+    code = 'secret_vault_not_configured';
+    constructor(message) {
+        super(message);
+        this.name = 'SecretVaultNotConfiguredError';
+    }
+}
+exports.SecretVaultNotConfiguredError = SecretVaultNotConfiguredError;
+/**
+ * A save could not seal a credential, so the save did not happen.
+ *
+ * Which is the correct outcome and worth being explicit about: the fallback a
+ * reasonable person reaches for — write it in plaintext and log a warning — is
+ * the one thing this feature exists to make impossible. A deployment that
+ * turned `encryptCredentials` on and then, during a vault outage, quietly wrote
+ * three passwords in the clear would have no way to find out which three.
+ *
+ * Deliberately not a `BadRequestException`. The caller's URL is fine; the vault
+ * is down. A 400 sends somebody to edit a field that is correct.
+ */
+class SecretSealFailedError extends Error {
+    code = 'secret_seal_failed';
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SecretSealFailedError';
+    }
+}
+exports.SecretSealFailedError = SecretSealFailedError;
+/**
+ * A read could not open a sealed credential.
+ *
+ * **This is the one whose class matters**, because a connector run is a durable
+ * step and the step decides whether to retry from the error it catches. Two
+ * things had to be got right here and both are load-bearing:
+ *
+ *  - It is **not** a `NotFoundException` or a `BadRequestException`.
+ *    `ConnectorRunSteps.runConnector` catches exactly those two around the
+ *    runner and converts them to `UnavailableConnectorError`, which carries
+ *    `retryable = false`. A vault that timed out would then be filed under
+ *    `connector_unavailable` and never retried — and an operator filtering a
+ *    failed-run list on that code would go looking for a connector somebody
+ *    deleted. That is precisely the confusion `UnmetLoadExpectationError` was
+ *    split into its own class to avoid.
+ *  - `retryable` is **true by default**. A vault being briefly unreachable is
+ *    the same kind of failure as a source being briefly unreachable, which is
+ *    exactly what that step's `retries: 3, backoff exp 60s…900s` policy exists
+ *    for. It is set false only when waiting provably cannot help: nothing is
+ *    bound, or nothing bound answers to the name the row carries.
+ */
+class SecretOpenFailedError extends Error {
+    /** The field the dispatch boundary serialises and the engine acts on. */
+    retryable;
+    code = 'secret_open_failed';
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = 'SecretOpenFailedError';
+        this.retryable = options.retryable;
+    }
+}
+exports.SecretOpenFailedError = SecretOpenFailedError;

package/dist/client.d.ts

@@ -93,5 +93,6 @@ export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge,
  * `WORKFLOW_NODE_ID_PATTERN` and `WORKFLOW_NODE_KINDS` are what a palette and an
  * id field should be built from rather than from a second copy that drifts.
  */
-export { validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, workflowGraphHash, workflowRunOrder, isWorkflowExecutionMode, isWorkflowNodeKind, } from './catalog.pipeline';
+export { validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, workflowGraphHash, workflowRunOrder, isWorkflowExecutionMode, isWorkflowNodeKind, isWorkflowStatus, } from './catalog.pipeline';
+export type { WorkflowStatus } from './catalog.pipeline';
 export type { CatalogTrace, CatalogTraceList, CatalogTraceOutcome, CatalogTraceSpan, TraceQuery, } from './catalog.workspace';

package/dist/client.js

@@ -11,7 +11,7 @@
  * types are.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = void 0;
+exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = void 0;
 /**
  * Builds the paths the catalog controller serves, relative to wherever it was
  * mounted. Kept as string builders rather than a fetch wrapper so the host
@@ -87,7 +87,15 @@ Object.defineProperty(exports, "WORKFLOW_EXECUTION_MODES", { enumerable: true, g
 Object.defineProperty(exports, "WORKFLOW_ISSUE_CODES", { enumerable: true, get: function () { return catalog_pipeline_2.WORKFLOW_ISSUE_CODES; } });
 Object.defineProperty(exports, "WORKFLOW_NODE_ID_PATTERN", { enumerable: true, get: function () { return catalog_pipeline_2.WORKFLOW_NODE_ID_PATTERN; } });
 Object.defineProperty(exports, "WORKFLOW_NODE_KINDS", { enumerable: true, get: function () { return catalog_pipeline_2.WORKFLOW_NODE_KINDS; } });
+// The draft/ready pair, for the same reason as the list above: a canvas that
+// cannot see it restates it, and the copy is what drifts. Without this the
+// editor could not tell a graph it is allowed to store from one the server
+// would refuse — so it told everybody the second, which is wrong for every
+// draft and is exactly the kind of confident-and-false sentence this codebase
+// keeps removing.
+Object.defineProperty(exports, "WORKFLOW_STATUSES", { enumerable: true, get: function () { return catalog_pipeline_2.WORKFLOW_STATUSES; } });
 Object.defineProperty(exports, "workflowGraphHash", { enumerable: true, get: function () { return catalog_pipeline_2.workflowGraphHash; } });
 Object.defineProperty(exports, "workflowRunOrder", { enumerable: true, get: function () { return catalog_pipeline_2.workflowRunOrder; } });
 Object.defineProperty(exports, "isWorkflowExecutionMode", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowExecutionMode; } });
 Object.defineProperty(exports, "isWorkflowNodeKind", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowNodeKind; } });
+Object.defineProperty(exports, "isWorkflowStatus", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowStatus; } });

package/dist/index.d.ts

@@ -3,11 +3,12 @@ export { CATALOG_EVENT_PHASE, CATALOG_EVENT_PHASE_FALLBACK, CATALOG_EVENTS, CATA
 export { CatalogModule } from './catalog.module';
 export { assertReadOnlyShape, type CatalogQueryRelation, type CatalogQueryRequest, type CatalogQueryResult, type CatalogQueryStore, isQueryStore, } from './catalog.query';
 export { CATALOG_OPTIONS, type CatalogModuleOptions } from './catalog.options';
+export * from './catalog.secrets';
 export { type CatalogOverlayStore, FileCatalogOverlayStore, InMemoryCatalogOverlayStore, } from './catalog.overlay-store';
 export { CATALOG_OVERLAY_STORE } from './catalog.overlay-store.token';
 export { MikroOrmCatalogRegistry } from './catalog.registry';
 export { CatalogRegistry } from './catalog.registry.base';
-export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, isConnectorKind, isPipelineStore, isTransformLanguage, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
+export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, isConnectorKind, isPipelineStore, isTransformLanguage, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
 export * from './catalog.environment';
 export { QueryCache, toCsv } from './catalog.query-cache';
 export { SubprocessTransformRunner, type TransformRunnerOptions, } from './transform-runner';

package/dist/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.searchCatalog = exports.maySearch = exports.emptySearch = exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isPipelineStore = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.CATALOG_PIPELINE_STORE = exports.CatalogRegistry = exports.MikroOrmCatalogRegistry = exports.CATALOG_OVERLAY_STORE = exports.InMemoryCatalogOverlayStore = exports.FileCatalogOverlayStore = exports.CATALOG_OPTIONS = exports.isQueryStore = exports.assertReadOnlyShape = exports.CatalogModule = exports.emitCatalog = exports.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = exports.CATALOG_LIB = exports.CATALOG_EVENTS = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CatalogType = exports.CatalogProperty = void 0;
-exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.supportsCarryForward = exports.isWriteStore = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertNoColumnCollisions = exports.StaticKeyPrincipalResolver = exports.readableObjectPage = exports.mayWrite = exports.mayRead = exports.maySeeClassification = exports.PRINCIPAL_ACTOR_SEPARATOR = exports.parsePrincipalId = exports.hasScope = exports.expandScopes = exports.delegatePrincipal = exports.composePrincipalId = exports.CATALOG_PRINCIPAL_RESOLVER = exports.traceOutcomeFilter = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.visibleToPrincipal = void 0;
+exports.emptySearch = exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isPipelineStore = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.CATALOG_PIPELINE_STORE = exports.CatalogRegistry = exports.MikroOrmCatalogRegistry = exports.CATALOG_OVERLAY_STORE = exports.InMemoryCatalogOverlayStore = exports.FileCatalogOverlayStore = exports.CATALOG_OPTIONS = exports.isQueryStore = exports.assertReadOnlyShape = exports.CatalogModule = exports.emitCatalog = exports.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = exports.CATALOG_LIB = exports.CATALOG_EVENTS = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CatalogType = exports.CatalogProperty = void 0;
+exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.supportsCarryForward = exports.isWriteStore = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertNoColumnCollisions = exports.StaticKeyPrincipalResolver = exports.readableObjectPage = exports.mayWrite = exports.mayRead = exports.maySeeClassification = exports.PRINCIPAL_ACTOR_SEPARATOR = exports.parsePrincipalId = exports.hasScope = exports.expandScopes = exports.delegatePrincipal = exports.composePrincipalId = exports.CATALOG_PRINCIPAL_RESOLVER = exports.traceOutcomeFilter = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = void 0;
 var catalog_decorators_1 = require("./catalog.decorators");
 Object.defineProperty(exports, "CatalogProperty", { enumerable: true, get: function () { return catalog_decorators_1.CatalogProperty; } });
 Object.defineProperty(exports, "CatalogType", { enumerable: true, get: function () { return catalog_decorators_1.CatalogType; } });
@@ -36,6 +36,14 @@ Object.defineProperty(exports, "assertReadOnlyShape", { enumerable: true, get: f
 Object.defineProperty(exports, "isQueryStore", { enumerable: true, get: function () { return catalog_query_1.isQueryStore; } });
 var catalog_options_1 = require("./catalog.options");
 Object.defineProperty(exports, "CATALOG_OPTIONS", { enumerable: true, get: function () { return catalog_options_1.CATALOG_OPTIONS; } });
+// Everything, deliberately, and here more than anywhere: this is a seam two
+// separate provider packages are being written against. A barrel that shipped
+// `CATALOG_SECRET_VAULT` and `CatalogSecretVault` but not `SealedSecret` or
+// `SecretContext` — the return type and the argument of the two methods a
+// provider implements — would be the exact gap `index.barrel.spec.ts` was
+// written after, reproduced on the one surface where a third party compiles
+// against it.
+__exportStar(require("./catalog.secrets"), exports);
 var catalog_overlay_store_1 = require("./catalog.overlay-store");
 Object.defineProperty(exports, "FileCatalogOverlayStore", { enumerable: true, get: function () { return catalog_overlay_store_1.FileCatalogOverlayStore; } });
 Object.defineProperty(exports, "InMemoryCatalogOverlayStore", { enumerable: true, get: function () { return catalog_overlay_store_1.InMemoryCatalogOverlayStore; } });
@@ -55,6 +63,7 @@ Object.defineProperty(exports, "isWorkflowEdge", { enumerable: true, get: functi
 Object.defineProperty(exports, "isWorkflowExecutionMode", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowExecutionMode; } });
 Object.defineProperty(exports, "isWorkflowNode", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowNode; } });
 Object.defineProperty(exports, "isWorkflowNodeKind", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowNodeKind; } });
+Object.defineProperty(exports, "isWorkflowStatus", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowStatus; } });
 Object.defineProperty(exports, "supportsWorkflows", { enumerable: true, get: function () { return catalog_pipeline_1.supportsWorkflows; } });
 Object.defineProperty(exports, "supportsWorkflowStages", { enumerable: true, get: function () { return catalog_pipeline_1.supportsWorkflowStages; } });
 Object.defineProperty(exports, "TRANSFORM_RUNNER", { enumerable: true, get: function () { return catalog_pipeline_1.TRANSFORM_RUNNER; } });
@@ -64,6 +73,7 @@ Object.defineProperty(exports, "WORKFLOW_EXECUTION_MODES", { enumerable: true, g
 Object.defineProperty(exports, "WORKFLOW_ISSUE_CODES", { enumerable: true, get: function () { return catalog_pipeline_1.WORKFLOW_ISSUE_CODES; } });
 Object.defineProperty(exports, "WORKFLOW_NODE_ID_PATTERN", { enumerable: true, get: function () { return catalog_pipeline_1.WORKFLOW_NODE_ID_PATTERN; } });
 Object.defineProperty(exports, "WORKFLOW_NODE_KINDS", { enumerable: true, get: function () { return catalog_pipeline_1.WORKFLOW_NODE_KINDS; } });
+Object.defineProperty(exports, "WORKFLOW_STATUSES", { enumerable: true, get: function () { return catalog_pipeline_1.WORKFLOW_STATUSES; } });
 Object.defineProperty(exports, "workflowGraphHash", { enumerable: true, get: function () { return catalog_pipeline_1.workflowGraphHash; } });
 Object.defineProperty(exports, "workflowRunOrder", { enumerable: true, get: function () { return catalog_pipeline_1.workflowRunOrder; } });
 // The environment surface: which catalog database a call is served from, and

package/dist/transform-runner.d.ts

@@ -15,11 +15,28 @@ export interface TransformRunnerOptions {
 /**
  * Runs a transform in a child process, with a clock on it.
  *
- * **This is not a security boundary.** It stops accidents — an infinite loop, a
- * runaway allocation, a stray read of `process.env.DATABASE_PASSWORD` — because
- * the child gets a timeout and an empty environment. It does not stop code
- * written to escape it: a child process can still open sockets and read the
- * filesystem as whatever user the service runs as.
+ * **This is not a security boundary, and the trimmed environment is not one
+ * either.** It stops accidents — an infinite loop, a runaway allocation, a stray
+ * read of `process.env.DATABASE_PASSWORD` — because the child gets a timeout and
+ * an environment of `{PATH, NODE_ENV}`. It does not stop code written to escape
+ * it, and it is worth being exact about how thin the allowlist is rather than
+ * leaving a reader to assume it holds:
+ *
+ * - the child inherits nothing of the parent's environment **through `env`**,
+ *   and reads all of it anyway from `/proc/<ppid>/environ`, which is readable
+ *   because parent and child run as the same uid;
+ * - it runs in a working directory of this runner's choosing but on the host's
+ *   filesystem, so a service account token under
+ *   `/var/run/secrets/kubernetes.io/serviceaccount/` is an absolute path away;
+ * - it can open sockets, as whatever user the service runs as.
+ *
+ * So the allowlist is a guard rail against the accident, and the reachability of
+ * everything it names is a property of the process boundary, not a leak to be
+ * patched. **Running a transform is running code in this pod.** Who is allowed
+ * to is therefore an authorisation question and not a sandboxing one, and it is
+ * answered at the HTTP surface — see the "Running a transform is running code"
+ * section of `@dudousxd/nestjs-catalog-pipeline`'s README, which is where a host
+ * can actually read it, and `pipeline.controller.ts` for the checks themselves.
  *
  * That is a deliberate trade for the case this is built for, where transforms
  * are written by the same people who already have database access. A catalog

package/dist/transform-runner.js

@@ -13,10 +13,50 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SubprocessTransformRunner = void 0;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const common_1 = require("@nestjs/common");
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/**
+ * How much of the child's stderr is held, and why it is a different number from
+ * {@link MAX_OUTPUT_BYTES} with a different consequence.
+ *
+ * It had no bound at all, which is the one shape a capture must never have when
+ * the thing filling it is user code: `stderr += chunk` ran for the whole timeout
+ * window, so a transform whose only line is a loop writing to fd 2 grew the
+ * **parent's** heap — not the child's — at whatever rate the pipe would carry,
+ * and took the pod out with it. The timeout is no answer to that: thirty seconds
+ * of an unthrottled writer is gigabytes, and the process that dies is the one
+ * serving every other request.
+ *
+ * Bounded rather than killed, which is the opposite of what stdout overflow
+ * does, and the asymmetry is the point. Stdout *is* the result channel — past
+ * {@link MAX_OUTPUT_BYTES} there is no readable JSON line at the end of it and
+ * the run has already failed, so killing costs nothing. Stderr is only ever the
+ * diagnostic: a transform that writes a great deal to it and then returns a
+ * perfectly good array of rows is a working transform, and killing it would turn
+ * a noisy dependency's warnings into a failed load.
+ *
+ * The **head** is kept, because the head is what is read. Both places that
+ * consume this take `stderr.slice(0, 500)` — the first line of a traceback, the
+ * import error, the thing that says what went wrong — so dropping the tail
+ * discards exactly the part nobody was going to see. 64 KiB is far more than any
+ * of those and small enough that the ceiling is not itself a memory decision.
+ */
+const MAX_CAPTURED_STDERR_BYTES = 64 * 1024;
+/**
+ * Whether the child is put in its own process group, so that stopping it stops
+ * what it started.
+ *
+ * POSIX only, because the mechanism is POSIX: `detached` there makes the child a
+ * process-group leader and `process.kill(-pid)` signals the whole group, which
+ * is the only way to reach a grandchild. On Windows `detached` means something
+ * else entirely (a new console) and a negative pid is not a group, so the
+ * platform gets the single-process kill it always had rather than a call that
+ * would throw on every timeout.
+ */
+const KILL_PROCESS_GROUP = process.platform !== 'win32';
 /**
  * How much of what a transform logged is carried back, on both axes.
  *
@@ -73,11 +113,28 @@ const REPORTED_PACKAGES = ['pandas', 'numpy', 'pyarrow', 'requests'];
 /**
  * Runs a transform in a child process, with a clock on it.
  *
- * **This is not a security boundary.** It stops accidents — an infinite loop, a
- * runaway allocation, a stray read of `process.env.DATABASE_PASSWORD` — because
- * the child gets a timeout and an empty environment. It does not stop code
- * written to escape it: a child process can still open sockets and read the
- * filesystem as whatever user the service runs as.
+ * **This is not a security boundary, and the trimmed environment is not one
+ * either.** It stops accidents — an infinite loop, a runaway allocation, a stray
+ * read of `process.env.DATABASE_PASSWORD` — because the child gets a timeout and
+ * an environment of `{PATH, NODE_ENV}`. It does not stop code written to escape
+ * it, and it is worth being exact about how thin the allowlist is rather than
+ * leaving a reader to assume it holds:
+ *
+ * - the child inherits nothing of the parent's environment **through `env`**,
+ *   and reads all of it anyway from `/proc/<ppid>/environ`, which is readable
+ *   because parent and child run as the same uid;
+ * - it runs in a working directory of this runner's choosing but on the host's
+ *   filesystem, so a service account token under
+ *   `/var/run/secrets/kubernetes.io/serviceaccount/` is an absolute path away;
+ * - it can open sockets, as whatever user the service runs as.
+ *
+ * So the allowlist is a guard rail against the accident, and the reachability of
+ * everything it names is a property of the process boundary, not a leak to be
+ * patched. **Running a transform is running code in this pod.** Who is allowed
+ * to is therefore an authorisation question and not a sandboxing one, and it is
+ * answered at the HTTP surface — see the "Running a transform is running code"
+ * section of `@dudousxd/nestjs-catalog-pipeline`'s README, which is where a host
+ * can actually read it, and `pipeline.controller.ts` for the checks themselves.
  *
  * That is a deliberate trade for the case this is built for, where transforms
  * are written by the same people who already have database access. A catalog
@@ -179,7 +236,21 @@ let SubprocessTransformRunner = SubprocessTransformRunner_1 = class SubprocessTr
             const child = (0, node_child_process_1.spawn)(command, args, {
                 // An empty environment, not the parent's. A transform has no business
                 // reading the database password, and inheriting env is how it would.
+                // Read the class docblock before treating this as containment: the same
+                // values are a `/proc/<ppid>/environ` read away, and this is a guard
+                // rail against the accidental read rather than a boundary.
                 env: { PATH: process.env.PATH ?? '', NODE_ENV: 'production' },
+                // Not the parent's, which is a running service's directory and holds
+                // the `.env` the allowlist above exists to withhold — a transform whose
+                // first line is `readFileSync(".env")` was reading the host application's
+                // configuration by relative path. A temporary directory keeps the file
+                // writes a transform may legitimately want working while making the one
+                // path it can name without knowing anything about the deployment
+                // uninteresting. Absolute paths are unaffected, and cannot be.
+                cwd: (0, node_os_1.tmpdir)(),
+                // Its own process group, so the timeout below can reach a grandchild.
+                // See {@link KILL_PROCESS_GROUP}.
+                detached: KILL_PROCESS_GROUP,
                 stdio: ['pipe', 'pipe', 'pipe'],
             });
             let stdout = '';
@@ -189,16 +260,22 @@ let SubprocessTransformRunner = SubprocessTransformRunner_1 = class SubprocessTr
                 if (settled)
                     return;
                 settled = true;
-                child.kill('SIGKILL');
+                stop(child);
                 reject(new Error(`The transform ran for longer than ${timeoutMs}ms and was stopped.`));
             }, timeoutMs);
             child.stdout.on('data', (chunk) => {
                 stdout += chunk.toString();
                 if (stdout.length > MAX_OUTPUT_BYTES)
-                    child.kill('SIGKILL');
+                    stop(child);
             });
             child.stderr.on('data', (chunk) => {
-                stderr += chunk.toString();
+                // Appended only while there is room, rather than appended and trimmed:
+                // trimming after the fact still materialises the whole chunk into the
+                // parent's heap, which is the thing being bounded. See
+                // {@link MAX_CAPTURED_STDERR_BYTES} for why this bounds rather than kills.
+                if (stderr.length >= MAX_CAPTURED_STDERR_BYTES)
+                    return;
+                stderr += chunk.toString().slice(0, MAX_CAPTURED_STDERR_BYTES - stderr.length);
             });
             child.on('error', (error) => {
                 if (settled)
@@ -228,7 +305,12 @@ let SubprocessTransformRunner = SubprocessTransformRunner_1 = class SubprocessTr
             return this.pythonPath;
         const venv = this.options.pythonVenv ?? process.env.CATALOG_PYTHON_VENV;
         if (venv) {
-            const candidate = (0, node_path_1.join)(venv, 'bin', 'python');
+            // Absolute, and it has to be: a child now runs in a temporary directory
+            // rather than the parent's, so a relative `CATALOG_PYTHON_VENV` — which
+            // `existsSync` here resolves against the *parent's* cwd — would pass this
+            // check and then fail to spawn. Resolved once, at the point the two cwds
+            // are still the same.
+            const candidate = (0, node_path_1.resolve)((0, node_path_1.join)(venv, 'bin', 'python'));
             if ((0, node_fs_1.existsSync)(candidate)) {
                 this.pythonPath = candidate;
                 this.logger.log(`Python transforms run in the venv at ${venv}`);
@@ -256,6 +338,41 @@ exports.SubprocessTransformRunner = SubprocessTransformRunner = SubprocessTransf
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [Object])
 ], SubprocessTransformRunner);
+/**
+ * Stop the transform, and everything the transform started.
+ *
+ * `child.kill()` signals one pid. A transform that double-forks — two lines of
+ * `child_process.spawn` with `detached` and an `unref` — leaves a grandchild
+ * that the direct child's death says nothing about, so the timeout expired, the
+ * caller was told the run had been stopped, and the work carried on
+ * indefinitely. That is not a hypothetical: it is the standard way a timeout on
+ * a process is escaped, and a bound that a caller can opt out of is not a bound.
+ *
+ * So the child leads its own process group and the negative pid signals the
+ * group, which is every descendant that has not deliberately left it. Leaving
+ * one is possible (`setsid` again) and there is no answer to that short of a
+ * cgroup or a container — the same place the class docblock's honesty about the
+ * boundary ends up, for the same reason.
+ *
+ * Falls through to the single-process kill whenever the group kill cannot be the
+ * one that happens: on Windows, where a negative pid is not a group, and on an
+ * `ESRCH` where the group is already gone and the direct kill is a harmless
+ * no-op. A throw here would replace a timeout error — which says something true
+ * and useful — with an unhandled one that says nothing.
+ */
+function stop(child) {
+    const pid = child.pid;
+    if (KILL_PROCESS_GROUP && pid !== undefined) {
+        try {
+            process.kill(-pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // Already gone, or never grouped. The direct kill below covers both.
+        }
+    }
+    child.kill('SIGKILL');
+}
 /**
  * The traceback, plus the tail of what the code printed on its way to it.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A metadata registry for NestJS: object types, properties and relations, derived from your ORM and enriched with decorators.",
   "license": "MIT",
   "author": "Davide Carvalho",