@sanoma-ai/workflows 0.9.1 → 0.10.1

package/dist/client.js

@@ -1,4 +1,6 @@
-import { randomUUID } from "node:crypto";
+import { connectionDriver, connectionTargetSchema, } from "./connection.js";
+import { encodeCredentials, decodeCredentials, verifyAuthentication, AuthenticationError } from "./authentication.js";
+import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
@@ -7,7 +9,7 @@ import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call
 import { chatStore } from "./chats.js";
 import { collectionsDriver } from "./collection.js";
 import { resolveConfig } from "./config.js";
-import { deleteCredential, storeCredential, storedCredentials, storedSecrets } from "./credentials.js";
+import { configuredSecrets } from "./credentials.js";
 import { dbosClient, lazyPool } from "./db.js";
 import { credentialsOf } from "./env.js";
 import { Principal } from "./define.js";
@@ -20,6 +22,7 @@ import { insertRecord, ownedLedger } from "./ledger.js";
 import { warn } from "./log.js";
 import { allowAll } from "./policy.js";
 import { admit, readPeople } from "./resources.js";
+import { SecretStoreError } from "./secret-store.js";
 import { BUILT_IN_WORKFLOWS, CALL_WORKFLOW, CHANGE_EVENT, CHANGE_MERGE, CHANGE_TOPIC, CHANGE_WORKFLOW, changeIdOf, DATA_VENDOR, ENDED_STATUSES, errorMessage, HOST_CHECK_AGENT, isEnded, isVisitor, refusalOf, SCHEDULE_AGENT, WORKFLOW_ACTION, } from "./shared.js";
 import { draftOf } from "./source.js";
 /** Whether two references name one repository: a host's names are compared without case. */
@@ -88,7 +91,7 @@ export class SanomaClient {
         this.options = options;
         this.audit = ownedLedger(config);
         this.pool = lazyPool(config.databaseUrl, "client");
-        this.storedSecrets = storedSecrets(() => this.db(), "sanoma");
+        this.storedSecrets = configuredSecrets(config.secrets, () => this.db());
         this.chats = chatStore(() => this.db());
     }
     /**
@@ -99,7 +102,15 @@ export class SanomaClient {
     static async connect(config, options = {}) {
         const resolved = resolveConfig(config);
         const dbos = await dbosClient(resolved.databaseUrl, resolved.appName);
-        return new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
+        const client = new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
+        try {
+            await client.storedSecrets.validate();
+            return client;
+        }
+        catch (error) {
+            await client.close();
+            throw error;
+        }
     }
     /**
      * Checks the input against the workflow's schema, then queues a run for the worker. The run
@@ -211,20 +222,26 @@ export class SanomaClient {
         if (!fn)
             throw new SanomaError("invalid_input", `${op.id} has no driver: the connector package must attach one`);
         const parsed = parseOrThrow(op.input, input, `The input to ${op.id} does not match its schema`, { op: op.id });
+        const connection = await this.config.connections.select(op.vendor, options.connection, actor.id);
+        const selected = connection && {
+            $connection: connection.id,
+            vendor: connection.vendor,
+            revision: connection.revision,
+        };
         const runId = `direct:${actor.id}:${id}`;
         const heldId = `call:${actor.id}:${id}`;
-        const held = { input: { op: op.id, input }, startedBy: actor };
+        const held = { input: { op: op.id, input, ...(selected && { connection: selected }) }, startedBy: actor };
         const logged = recorded(op, parsed);
         const write = op.effect !== "read";
         // Only an id the caller gave can have been used: a write made, or held, with it settles it.
         if (write && options.id !== undefined) {
-            const first = (await this.recordedCall(runId, op.id, logged)) ?? (await this.heldCall(op.id, heldId, held));
+            const first = (await this.recordedCall(runId, op.id, logged, connection)) ?? (await this.heldCall(op.id, heldId, held));
             if (first)
                 return first.output;
         }
         const before = await beforeOf(policy, op, parsed, this.config.collections, (get, key) => drivers.get(get)?.({ key }, { idempotencyKey: `${runId}:before`, runId, opId: get, attempt: 1, secrets: this.storedSecrets, by: actor.id }));
         const run = { id: runId, workflow: CALL_WORKFLOW, approvals: [] };
-        const decision = decideCall(policy, op, parsed, actor, run, before);
+        const decision = decideCall(policy, op, parsed, actor, run, { ...before, ...(connection && { connection }) });
         if (decision.kind === "deny")
             throw new PolicyDeniedError(op.id, decision.reason);
         if (decision.kind === "approve") {
@@ -239,7 +256,10 @@ export class SanomaClient {
             attempt: 1,
             secrets: this.storedSecrets,
             by: actor.id,
+            principal: actor,
+            ...(connection && { connection }),
         };
+        await this.config.connections.assertCurrent(connection, actor.id);
         if (!write)
             return outputOf(op, () => fn(parsed, context));
         return this.directWrite({ op, fn, parsed, logged, actor, decision, context });
@@ -255,13 +275,21 @@ export class SanomaClient {
         const { op, parsed, logged, actor, decision, context } = call;
         const { runId } = context;
         const { dataStore, collections, ledger } = this.config;
-        const conn = op.vendor === DATA_VENDOR && !ledger && dataStore ? await (await dataStore.db()).connect() : undefined;
+        const connectionMutation = op.id.startsWith("sanoma.connection.");
+        const transactionStore = connectionMutation
+            ? this.config.connectionPool
+            : op.vendor === DATA_VENDOR
+                ? dataStore
+                : undefined;
+        const conn = !ledger && transactionStore ? await (await transactionStore.db()).connect() : undefined;
         let broken;
         try {
             await conn?.query("BEGIN");
-            // On the transaction's connection, the collection's own driver: it has no `env` to guard.
+            // The metadata or collection driver shares the ledger transaction; neither has an env guard.
             const fn = conn
-                ? collectionsDriver([collections.get(op.resource)], { db: async () => conn }).ops[`${op.resource}.${op.name}`]
+                ? (connectionMutation
+                    ? connectionDriver(this.config.connections.onDatabase(conn))
+                    : collectionsDriver([collections.get(op.resource)], { db: async () => conn })).ops[`${op.resource}.${op.name}`]
                 : call.fn;
             const at = Date.now();
             const record = (outcome) => ({
@@ -278,6 +306,7 @@ export class SanomaClient {
                 effect: op.effect,
                 input: logged,
                 decision,
+                ...(context.connection && { connection: context.connection }),
                 ...outcome,
                 durationMs: Date.now() - at,
             });
@@ -300,7 +329,7 @@ export class SanomaClient {
                 return output;
             }
             await conn.query("ROLLBACK");
-            return (await this.recordedCall(runId, op.id, logged)).output;
+            return (await this.recordedCall(runId, op.id, logged, context.connection)).output;
         }
         catch (err) {
             await conn?.query("ROLLBACK").catch((e) => (broken = e));
@@ -314,11 +343,15 @@ export class SanomaClient {
      * What the direct write recorded as `runId` returned, when one did: refused (`invalid_input`)
      * when it was of another operation or input, and its failure again (`driver_failed`) when it failed.
      */
-    async recordedCall(runId, opId, input) {
+    async recordedCall(runId, opId, input, connection) {
         const first = (await this.audit.store.read(runId)).find((r) => r.type === "op.called");
         if (!first)
             return undefined;
-        const differs = [...(first.op === opId ? [] : ["op"]), ...(sameJson(first.input, input) ? [] : ["input"])];
+        const differs = [
+            ...(first.op === opId ? [] : ["op"]),
+            ...(sameJson(first.input, input) ? [] : ["input"]),
+            ...(sameJson(first.connection ?? null, connection ?? null) ? [] : ["connection"]),
+        ];
         if (differs.length) {
             throw new SanomaError("invalid_input", `Call ${runId} was made already with a different ${differs.join(" and ")}; use another id`, { runId, differs });
         }
@@ -794,7 +827,8 @@ export class SanomaClient {
                 issues: [{ path: ["value"], message: problem, code: "custom" }],
             });
         }
-        await storeCredential(await this.db(), { name, value, setBy });
+        const current = await this.storedSecrets.read(name);
+        await this.storedSecrets.write(name, value, { expectedVersion: current?.version ?? null, by: setBy });
     }
     /**
      * Deletes the stored value of a declared variable, and tells the workers, which unset it unless
@@ -804,7 +838,9 @@ export class SanomaClient {
     async clearCredential(name, options) {
         await this.admittedBy(options);
         this.declared(name, () => undefined);
-        await deleteCredential(await this.db(), name);
+        const current = await this.storedSecrets.read(name);
+        if (current)
+            await this.storedSecrets.delete(name, { expectedVersion: current.version, by: options.by });
     }
     /**
      * Stores a secret as `by`, and tells the workers: a value under any variable's name, declared by
@@ -822,50 +858,239 @@ export class SanomaClient {
             const path = VARIABLE.test(name) ? "value" : "name";
             throw new SanomaError("invalid_input", problem, { issues: [{ path: [path], message: problem, code: "custom" }] });
         }
-        await storeCredential(await this.db(), { name, value, setBy });
+        const current = await this.storedSecrets.read(name);
+        await this.storedSecrets.write(name, value, { expectedVersion: current?.version ?? null, by: setBy });
+    }
+    /** Removes a logical secret from the selected store; external bindings remain read-only. */
+    async clearSecret(name, options) {
+        const by = await this.admittedBy(options);
+        if (!VARIABLE.test(name)) {
+            const message = "That is not a variable name";
+            throw new SanomaError("invalid_input", message, {
+                issues: [{ path: ["name"], message, code: "custom" }],
+            });
+        }
+        const current = await this.storedSecrets.read(name);
+        if (current)
+            await this.storedSecrets.delete(name, { expectedVersion: current.version, by });
+    }
+    connectionAuthorization() {
+        return createHash("sha256")
+            .update(JSON.stringify({
+            version: this.config.version,
+            policies: this.config.policies,
+            problems: this.config.policyProblems,
+        }))
+            .digest("hex");
+    }
+    /** Safe account cards, scoped to the admitted principal. No provider or secret reads. */
+    async connections(options) {
+        const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+        return this.config.connections.cards(actor.id);
+    }
+    /** Creation choices are scoped by code to the admitted person's current groups. */
+    async connectionRules(options) {
+        const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+        return [...this.config.connections.catalog.rules]
+            .filter(([, rule]) => rule.createBy.some((by) => (typeof by === "string" ? by === actor.id : actor.groups?.includes(by.group))))
+            .map(([id, rule]) => ({ id, rule }));
+    }
+    /** Readiness only, without reading or listing any credential. The adapter's bootstrap
+     * authority is checked by validate; provider details never escape this boundary. */
+    async secretStoreStatus(options) {
+        await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+        const { store, namespace } = this.storedSecrets;
+        let problem;
+        try {
+            await this.storedSecrets.validate();
+        }
+        catch (error) {
+            problem = error.code;
+        }
+        return {
+            store: store.id,
+            namespace,
+            capabilities: { ...store.capabilities },
+            ready: !problem,
+            ...(problem && { problem }),
+        };
+    }
+    /** Secure intake endpoint, never a workflow operation. Only its metadata-only prepare gate
+     * enters policy/approval history; callers keep the value in a password form while reviewing. */
+    async previewConnection(target, credentials, options) {
+        const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+        const id = parseOrThrow(z.string().min(1).max(200), options.id, "Name the setup request");
+        target = parseOrThrow(connectionTargetSchema, target, "Select a declared connection or creation rule");
+        const setup = await this.config.connections.setup(target, actor, id);
+        const authorized = (await this.call("sanoma.connection.prepare", {
+            target,
+            requestId: id,
+            definition: setup.definition,
+            authorization: this.connectionAuthorization(),
+        }, { actor, id: `connection-prepare:${id}` }));
+        if (!isDeepStrictEqual(authorized, setup))
+            throw new SanomaError("invalid_input", "The connection changed; start a new review");
+        const method = this.config.connections.catalog.methods.get(setup.vendor)[setup.method];
+        const external = method.kind !== "workload-identity" &&
+            (setup.location?.management === "external" || !this.storedSecrets.store.capabilities.writable);
+        if (!external &&
+            method.kind !== "workload-identity" &&
+            this.storedSecrets.store.capabilities.conditionalWrites === "none")
+            throw new SecretStoreError("unsupported");
+        if (credentials !== undefined && (external || method.kind === "workload-identity"))
+            throw new SecretStoreError("read_only");
+        const existing = setup.credential ? await this.storedSecrets.read(setup.credential) : undefined;
+        if (external && !existing)
+            throw new SecretStoreError("unavailable");
+        const encoded = method.kind === "workload-identity"
+            ? undefined
+            : external
+                ? existing.value
+                : encodeCredentials(method, credentials);
+        const identity = await verifyAuthentication(method, encoded === undefined ? undefined : decodeCredentials(method, encoded));
+        if (setup.expectedAccount && setup.expectedAccount !== identity.account)
+            throw new AuthenticationError("wrong_account");
+        if (setup.requiredScopes.some((scope) => !identity.scopes.includes(scope)))
+            throw new AuthenticationError("scope_changed");
+        return {
+            ...setup,
+            requestId: id,
+            authorization: this.connectionAuthorization(),
+            account: identity.account,
+            scopes: [...identity.scopes],
+            credentialVersion: existing?.version ?? null,
+            ...(identity.expiresAt !== undefined && { expiresAt: identity.expiresAt }),
+        };
+    }
+    /** Reverify the reviewed authority, reserve its metadata under policy, then write the bundle
+     * outside durable execution. Activation has its own policy gate and verifies what was saved. */
+    async connectConnection(review, credentials, options) {
+        const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+        if (review.authorization !== this.connectionAuthorization())
+            throw new SanomaError("invalid_input", "The policy changed; start a new connection review");
+        const setup = await this.config.connections.setup(review.target, actor, review.requestId);
+        for (const field of ["id", "vendor", "method", "definition", "credential", "location"]) {
+            if (!isDeepStrictEqual(setup[field], review[field]))
+                throw new SanomaError("invalid_input", "The destination changed; review it again before saving");
+        }
+        // Reuse only the metadata gate, never a cached credential or verification result.
+        await this.call("sanoma.connection.prepare", {
+            target: review.target,
+            requestId: review.requestId,
+            definition: setup.definition,
+            authorization: review.authorization,
+        }, { actor, id: `connection-prepare:${review.requestId}` });
+        const method = this.config.connections.catalog.methods.get(setup.vendor)[setup.method];
+        const external = method.kind !== "workload-identity" &&
+            (setup.location?.management === "external" || !this.storedSecrets.store.capabilities.writable);
+        if (!external &&
+            method.kind !== "workload-identity" &&
+            this.storedSecrets.store.capabilities.conditionalWrites === "none")
+            throw new SecretStoreError("unsupported");
+        if (credentials !== undefined && (external || method.kind === "workload-identity"))
+            throw new SecretStoreError("read_only");
+        const existing = setup.credential ? await this.storedSecrets.read(setup.credential) : undefined;
+        if (external && (!existing || existing.version !== review.credentialVersion))
+            throw new SecretStoreError("conflict");
+        if (setup.expectedRevision === review.expectedRevision && (existing?.version ?? null) !== review.credentialVersion)
+            throw new SecretStoreError("conflict");
+        const encoded = method.kind === "workload-identity"
+            ? undefined
+            : external
+                ? existing.value
+                : encodeCredentials(method, credentials);
+        const identity = await verifyAuthentication(method, encoded === undefined ? undefined : decodeCredentials(method, encoded));
+        if (identity.account !== review.account)
+            throw new AuthenticationError("wrong_account");
+        if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(review.scopes)].toSorted()))
+            throw new AuthenticationError("scope_changed");
+        const selected = (await this.call("sanoma.connection.configure", {
+            target: review.target,
+            requestId: review.requestId,
+            expectedRevision: review.expectedRevision,
+            definition: review.definition,
+            account: identity.account,
+            scopes: [...identity.scopes],
+        }, { actor, id: `connection-configure:${review.requestId}` }));
+        const ref = { vendor: selected.vendor, $connection: selected.id };
+        if ((await this.config.connections.setupState(selected, actor)) === "pending" &&
+            !external &&
+            encoded !== undefined) {
+            let written = false;
+            try {
+                const receipt = await this.config.connections.storedVersion(selected.id, selected.revision);
+                if (receipt) {
+                    if (existing?.version !== receipt || existing.value !== encoded)
+                        throw new SecretStoreError("conflict");
+                }
+                else {
+                    const stored = await this.storedSecrets.write(setup.credential, encoded, {
+                        expectedVersion: review.credentialVersion,
+                        by: actor.id,
+                    });
+                    written = true;
+                    await this.config.connections.recordStoredVersion(selected.id, selected.revision, stored.version);
+                }
+            }
+            catch (error) {
+                if (written || error?.code === "unavailable")
+                    await this.config.connections.uncertain(ref, selected.revision, actor.id);
+                throw error;
+            }
+        }
+        const connected = (await this.call("sanoma.connection.activate", {
+            connection: ref,
+            expectedRevision: selected.revision,
+        }, { actor, id: `connection-activate:${review.requestId}` }));
+        await this.config.connections.assertCurrent(connected, actor.id);
+        return connected;
     }
     /**
-     * The values of these secrets, as a driver's `secrets.get` reads them: this process's
-     * environment, which wins, else the stored value, with who set it and when. A name with neither
-     * is left out. For server code: a page is told whether one is set, never its value.
+     * Values resolved through the selected store and explicit bindings, with version and change
+     * metadata. Missing names are left out. Server code only; pages receive status, never values.
      */
     async secrets(names) {
-        const rows = await storedCredentials(await this.db(), names);
         const found = new Map();
         for (const name of names) {
-            const env = process.env[name];
-            const row = rows.get(name);
-            if (env && env !== row?.value)
-                found.set(name, { value: env, source: "environment" });
-            else if (row)
-                found.set(name, { ...row, source: "stored" });
+            const row = await this.storedSecrets.read(name);
+            const location = this.storedSecrets.location(name);
+            if (row)
+                found.set(name, {
+                    value: row.value,
+                    source: location.store === "environment" ? "environment" : "stored",
+                    version: row.version,
+                    location,
+                    ...(row.updatedBy && { setBy: row.updatedBy }),
+                    ...(row.updatedAt && { setAt: row.updatedAt }),
+                });
         }
         return found;
     }
-    /**
-     * Each vendor's declared variables and their statuses now: from this process's environment,
-     * which wins, else from the stored credentials, with `source` saying which (a value equal to
-     * the stored one, as a worker in this process loads it, is `stored`), and who set a stored one
-     * and when. Never a value.
-     */
+    /** Non-secret statuses for the selected store and declared bindings. */
     async credentials() {
         const names = [...credentialsOf(this.drivers, () => undefined).values()].flat().map((c) => c.name);
-        if (!names.length)
-            return new Map();
-        const rows = await storedCredentials(await this.db(), names);
-        const statuses = credentialsOf(this.drivers, (name) => process.env[name] || rows.get(name)?.value);
-        const sourced = (c) => {
-            const row = rows.get(c.name);
-            const env = process.env[c.name];
-            // A worker in this process loads the stored values into its environment: those are stored.
-            if (env && env !== row?.value)
-                return { ...c, source: "environment" };
-            return row ? { ...c, source: "stored", setBy: row.setBy, setAt: row.setAt } : c;
-        };
-        return new Map([...statuses].map(([vendor, list]) => [vendor, list.map(sourced)]));
+        const rows = await this.secrets(names);
+        const statuses = credentialsOf(this.drivers, (name) => rows.get(name)?.value);
+        return new Map([...statuses].map(([vendor, list]) => [
+            vendor,
+            list.map((c) => {
+                const row = rows.get(c.name);
+                return {
+                    ...c,
+                    location: this.storedSecrets.location(c.name),
+                    ...(row && { source: row.source, setBy: row.setBy, setAt: row.setAt }),
+                };
+            }),
+        ]));
     }
     async close() {
-        await Promise.all([this.dbos.destroy(), this.pool.close(), this.audit.close(), this.config.dataStore?.close()]);
+        await Promise.all([
+            this.dbos.destroy(),
+            this.pool.close(),
+            this.audit.close(),
+            this.config.dataStore?.close(),
+            this.config.connectionPool.close(),
+        ]);
     }
     /**
      * The name's statuses with `lookup`'s value, one per vendor whose drivers declare it, or
@@ -988,7 +1213,7 @@ const asJson = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v
 /** True when the two are the same JSON, whatever the order of their keys. */
 const sameJson = (a, b) => isDeepStrictEqual(asJson(a), asJson(b));
 /** What an environment variable's name looks like. */
-const VARIABLE = /^[A-Z_][A-Z0-9_]*$/;
+const VARIABLE = /^[A-Z][A-Z0-9_]*$/;
 const alreadyDecided = (runId, a) => new SanomaError("already_decided", a.status === "withdrawn"
     ? `${a.id} on run ${runId} was already withdrawn: ${a.withdrawnReason}`
     : `${a.id} on run ${runId} was already ${a.status} by ${a.decidedBy}`, {