@sanoma-ai/workflows 0.10.7 → 0.10.12

package/src/config.ts

@@ -1,5 +1,9 @@
 import { configuredSecrets } from "./credentials.ts";
-import type { IdentityProvisioning } from "./identity-provisioning.ts";
+import {
+  configuredIdentityProvisioning,
+  type IdentityProvisioning,
+  type IdentityProvisioningDatabase,
+} from "./identity-provisioning.ts";
 import { secretsForInput } from "./secret.ts";
 import { isRunControlError } from "./errors.ts";
 import { currentRun } from "./run.ts";
@@ -109,7 +113,7 @@ export interface SanomaConfig {
   /** Credential storage and explicit bindings. Omitted: encrypted Postgres, no environment fallback. */
   secrets?: SecretConfiguration;
   /** Trusted control plane only: separate broker enrollment writer. Absent in company runtimes. */
-  identityProvisioning?: IdentityProvisioning;
+  identityProvisioning?: IdentityProvisioning | IdentityProvisioningDatabase;
   connections?: readonly ConnectionDefinition[];
   connectionRules?: readonly ConnectionRule[];
   /** Postgres for the runtime. Defaults to `SANOMA_DATABASE_URL`, then `DEFAULT_DATABASE_URL`. */
@@ -159,6 +163,7 @@ export interface ResolvedConfig {
   secrets: SecretConfiguration;
   connections: ConnectionRegistry;
   connectionPool: LazyPool;
+  identityProvisioning: ReturnType<typeof configuredIdentityProvisioning>;
   /**
    * Scopes workflows, queues and versions in the system database: the `name` of
    * `<root>/package.json` when it names one, else "sanoma".
@@ -331,6 +336,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   // Built-in: the collections' operations, `data.<name>.<op>`, on the config's database.
   const databaseUrl = resolveDatabaseUrl(config);
   const connectionPool = lazyPool(databaseUrl, "connections");
+  const identityProvisioning = configuredIdentityProvisioning(config.identityProvisioning);
   const connections = new ConnectionRegistry(
     connectionCatalog(config.connectors, config.connections, config.connectionRules),
     () => connectionPool.db(),
@@ -361,7 +367,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       changeDriver(remotes),
       connectionDriver(connections),
       appsListDriver,
-      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()), identities: config.identityProvisioning }),
+      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()), identities: identityProvisioning.store }),
       ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
@@ -413,6 +419,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     secrets: config.secrets ?? {},
     connections,
     connectionPool,
+    identityProvisioning,
     appName,
     databaseUrl,
     // The built-in's code and operations are part of the app's version, like the config's own.

package/src/connection.ts

@@ -300,6 +300,11 @@ export class ConnectionRegistry {
     this.secrets = secrets;
   }
 
+  /** Release runtime-owned storage clients; the caller owns the database connection. */
+  async close(): Promise<void> {
+    await this.secrets?.close();
+  }
+
   /** A direct metadata write uses the same transaction as its default ledger record. */
   onDatabase(db: Db): ConnectionRegistry {
     return new ConnectionRegistry(this.catalog, async () => db, this.secrets);

package/src/credentials.ts

@@ -3,6 +3,8 @@ import { CREDENTIALS_TABLE as TABLE, type Db } from "./db.ts";
 import {
   SecretAccess,
   SecretStoreError,
+  checkSecretConfiguration,
+  isSecretStoreFactory,
   type SecretAddress,
   type SecretConfiguration,
   type SecretStore,
@@ -105,5 +107,30 @@ export function postgresSecretStore(db: () => Promise<Db>): SecretStore {
   };
 }
 
-export const configuredSecrets = (config: SecretConfiguration, db: () => Promise<Db>): SecretAccess =>
-  new SecretAccess(config, postgresSecretStore(db));
+export function configuredSecrets(config: SecretConfiguration, db: () => Promise<Db>): SecretAccess {
+  checkSecretConfiguration(config);
+  const selected = config.store;
+  if (!selected || !isSecretStoreFactory(selected)) return new SecretAccess(config, postgresSecretStore(db));
+  try {
+    const store = selected.create({ database: db });
+    checkSecretConfiguration({ store });
+    if (
+      isSecretStoreFactory(store) ||
+      (store.close !== undefined && typeof store.close !== "function") ||
+      store.id !== selected.id ||
+      (Object.keys(selected.capabilities) as (keyof typeof selected.capabilities)[]).some(
+        (key) => store.capabilities[key] !== selected.capabilities[key],
+      )
+    )
+      throw new SecretStoreError("invalid_configuration");
+    return new SecretAccess(
+      { ...config, store },
+      postgresSecretStore(db),
+      undefined,
+      () => store.close?.() ?? Promise.resolve(),
+    );
+  } catch {
+    // Config construction may otherwise leak a provider's bootstrap/database diagnostics.
+    throw new SecretStoreError("invalid_configuration");
+  }
+}

package/src/identity-provisioning.ts

@@ -1,4 +1,4 @@
-import type { Pool, PoolClient } from "pg";
+import { Pool, type PoolClient } from "pg";
 import type { IdentityEnrollment } from "./cloud-identity.ts";
 
 export type DeploymentIdentity = Omit<IdentityEnrollment, "generation">;
@@ -14,6 +14,69 @@ export interface IdentityProvisioning {
   revoke(input: DeploymentIdentity): Promise<void>;
 }
 
+/** Trusted control-plane configuration; the runtime owns this separate writer connection. */
+export interface IdentityProvisioningDatabase {
+  databaseUrl: string;
+  maxValidityMs: number;
+}
+
+/** Resolve without I/O. Explicit adapters remain caller-owned; database configuration is runtime-owned. */
+export function configuredIdentityProvisioning(
+  config: IdentityProvisioning | IdentityProvisioningDatabase | undefined,
+): { store?: IdentityProvisioning; close(): Promise<void> } {
+  if (!config) return { close: async () => {} };
+  if (!("databaseUrl" in config)) return { store: config, close: async () => {} };
+  let url: URL;
+  try {
+    url = new URL(config.databaseUrl);
+    if (
+      !["postgres:", "postgresql:"].includes(url.protocol) ||
+      !url.hostname ||
+      !url.username ||
+      !url.password ||
+      !/^\/[^/]+$/.test(url.pathname) ||
+      url.hash ||
+      [...url.searchParams.keys()].some((key) => !["sslmode", "channel_binding"].includes(key))
+    )
+      fail("invalid");
+    if (!["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) url.searchParams.set("sslmode", "verify-full");
+  } catch {
+    throw new IdentityProvisioningError("invalid");
+  }
+  const connectionString = url.href;
+  let pool: Pool | undefined;
+  let closed = false;
+  let closing: Promise<void> | undefined;
+  const store = postgresIdentityProvisioning(async () => {
+    if (closed) throw new IdentityProvisioningError("unavailable");
+    if (!pool) {
+      pool = new Pool({ connectionString, max: 5, connectionTimeoutMillis: 10_000, query_timeout: 15_000 });
+      pool.on("error", () => {});
+    }
+    // The control plane needs enrollment writes, never schema or database administration.
+    const { rows } = await pool.query<{ allowed: boolean }>(`SELECT
+      NOT EXISTS (SELECT FROM pg_roles WHERE rolname=current_user AND (rolsuper OR rolcreatedb OR rolcreaterole OR rolbypassrls))
+      AND has_schema_privilege('sanoma_identity','USAGE') AND NOT has_schema_privilege('sanoma_identity','CREATE')
+      AND has_table_privilege('sanoma_identity.deployments','SELECT')
+      AND has_table_privilege('sanoma_identity.deployments','INSERT')
+      AND has_table_privilege('sanoma_identity.deployments','UPDATE')
+      AND has_table_privilege('sanoma_identity.credentials','SELECT')
+      AND has_table_privilege('sanoma_identity.credentials','INSERT')
+      AND has_table_privilege('sanoma_identity.credentials','UPDATE')
+      AND NOT has_table_privilege('sanoma_identity.deployments','DELETE,TRUNCATE,REFERENCES,TRIGGER')
+      AND NOT has_table_privilege('sanoma_identity.credentials','DELETE,TRUNCATE,REFERENCES,TRIGGER') AS allowed`);
+    if (!rows[0]?.allowed) fail("invalid");
+    return pool;
+  }, config);
+  return {
+    store,
+    close() {
+      closed = true;
+      return (closing ??= pool?.end() ?? Promise.resolve());
+    },
+  };
+}
+
 export class IdentityProvisioningError extends Error {
   readonly retryable: boolean;
   readonly code: "invalid" | "conflict" | "unavailable";

package/src/identity-service.ts

@@ -139,7 +139,7 @@ export async function startIdentityService(options: IdentityServiceOptions): Pro
         res.end('{"error":"invalid_request"}');
         return;
       }
-      if (req.url === "/healthz" && (req.method === "GET" || req.method === "HEAD")) {
+      if (req.url === "/health" && (req.method === "GET" || req.method === "HEAD")) {
         res.writeHead(200, { "Content-Type": "text/plain", "Cache-Control": "no-store" });
         res.end("ok\n");
         return;

package/src/index.ts

@@ -296,6 +296,7 @@ export {
   type SecretConfiguration,
   type SecretLocation,
   type SecretStore,
+  type SecretStoreFactory,
   type SecretStoreCapabilities,
   type SecretStoreErrorCode,
   type SecretValue,

package/src/kms-secrets.ts

@@ -2,7 +2,14 @@ import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:
 import type { protos } from "@google-cloud/kms";
 import crc32c from "crc-32/crc32c.js";
 import type { Db } from "./db.ts";
-import { SecretStoreError, type SecretAddress, type SecretStore, type SecretValue } from "./secret-store.ts";
+import { cloudIdentityAuth } from "./cloud-identity.ts";
+import {
+  SecretStoreError,
+  type SecretAddress,
+  type SecretStore,
+  type SecretStoreFactory,
+  type SecretValue,
+} from "./secret-store.ts";
 
 /** Install with a privileged connection; runtime needs only SELECT/INSERT/UPDATE/DELETE on its company database. */
 export const KMS_SECRETS_SQL = `
@@ -47,8 +54,8 @@ export interface KmsPostgresOptions {
   decryptKeyNames?: readonly string[];
   /** Explicit client under a company-scoped IAM identity, never fleet credentials. Caller owns its lifecycle. */
   kms: GcpKmsClient;
-  /** Company-scoped database access. Caller owns connection lifecycle; never shared admin authority. */
-  database: () => Promise<Db>;
+  /** Omit in config to use the runtime's database. An explicit connection remains caller-owned. */
+  database?: () => Promise<Db>;
 }
 
 interface Envelope {
@@ -68,6 +75,13 @@ interface Row {
 }
 const FORMAT = "sanoma-gcp-kms-v1";
 const MAX_BYTES = 65_536;
+const capabilities = Object.freeze({
+  writable: true,
+  maxBytes: MAX_BYTES,
+  conditionalWrites: "atomic" as const,
+  deletion: "destroy" as const,
+  changeDetection: "read" as const,
+});
 const keyName =
   /^projects\/[a-zA-Z0-9-]+\/locations\/[a-z0-9-]+\/keyRings\/[a-zA-Z0-9_-]+\/cryptoKeys\/[a-zA-Z0-9_-]+$/;
 const nonempty = (v: string) =>
@@ -110,12 +124,81 @@ const versionOf = (name: unknown, key: string): name is string =>
   /^[1-9][0-9]{0,19}$/.test(name.slice(`${key}/cryptoKeyVersions/`.length));
 const checksum = (value: Uint8Array) => crc32c.buf(value) >>> 0;
 
+function checkedKeys(options: Pick<KmsPostgresOptions, "company" | "keyName" | "decryptKeyNames">): Set<string> {
+  const keys = new Set([options.keyName, ...(options.decryptKeyNames ?? [])]);
+  if (!nonempty(options.company) || [...keys].some((key) => !nonempty(key) || !keyName.test(key)))
+    throw new SecretStoreError("invalid_configuration");
+  return keys;
+}
+
+export type ManagedKmsOptions = Pick<KmsPostgresOptions, "company" | "keyName" | "decryptKeyNames"> & {
+  /** Fixed deployment broker; the callback reads protected bootstrap again on renewal. */
+  identity: { endpoint: string; credential(): Promise<string> };
+};
+
+/** Config composition for managed Cloud. Each runtime owns its lazily opened SDK client and database binding. */
+export function managedKmsStore(options: ManagedKmsOptions): SecretStoreFactory {
+  const keys = checkedKeys(options);
+  const { company, keyName: writeKey } = options;
+  const identity = { ...options.identity };
+  if (typeof identity.credential !== "function") throw new SecretStoreError("invalid_configuration");
+  return Object.freeze({
+    kind: "runtime",
+    id: "kms-postgres",
+    capabilities,
+    create({ database }: { database: () => Promise<Db> }) {
+      const authClient = cloudIdentityAuth(identity);
+      let closed = false;
+      let pending: Promise<GcpKmsClient & { close(): Promise<void> }> | undefined;
+      const client = () => {
+        if (closed) throw new SecretStoreError("unavailable");
+        return (pending ??= import("@google-cloud/kms").then(
+          ({ KeyManagementServiceClient }) => new KeyManagementServiceClient({ authClient }),
+        ));
+      };
+      const kms: GcpKmsClient = {
+        encrypt: async (request) => (await client()).encrypt(request),
+        decrypt: async (request) => (await client()).decrypt(request),
+      };
+      return {
+        ...kmsPostgresStore({ company, keyName: writeKey, decryptKeyNames: [...keys], database, kms }),
+        async close() {
+          if (closed) return;
+          closed = true;
+          if (pending) await (await pending).close();
+        },
+      };
+    },
+  });
+}
+
 /** Versioned envelope encryption; no plaintext/data-key cache, no SANOMA_SECRETS_KEY and no Secrets Manager. */
-export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore {
+export function kmsPostgresStore(options: KmsPostgresOptions & { database: () => Promise<Db> }): SecretStore;
+export function kmsPostgresStore(options: KmsPostgresOptions & { database?: undefined }): SecretStoreFactory;
+export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | SecretStoreFactory;
+export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | SecretStoreFactory {
   const { company, keyName: writeKey, kms, database } = options;
-  const keys = new Set([writeKey, ...(options.decryptKeyNames ?? [])]);
-  if (!nonempty(company) || [...keys].some((k) => !nonempty(k) || !keyName.test(k)))
+  const keys = checkedKeys(options);
+  if (
+    typeof kms?.encrypt !== "function" ||
+    typeof kms?.decrypt !== "function" ||
+    (database !== undefined && typeof database !== "function")
+  )
     throw new SecretStoreError("invalid_configuration");
+  if (!database)
+    return Object.freeze({
+      kind: "runtime",
+      id: "kms-postgres",
+      capabilities,
+      create: ({ database: runtimeDatabase }: { database: () => Promise<Db> }) =>
+        kmsPostgresStore({
+          company,
+          keyName: writeKey,
+          decryptKeyNames: [...keys],
+          kms,
+          database: runtimeDatabase,
+        }),
+    });
   const context = (address: SecretAddress, version: string) => {
     if (!nonempty(address.namespace) || !nonempty(address.path)) throw new SecretStoreError("invalid_configuration");
     return { company, namespace: address.namespace, path: address.path, version, format: FORMAT };
@@ -209,13 +292,7 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore {
   };
   return {
     id: "kms-postgres",
-    capabilities: Object.freeze({
-      writable: true,
-      maxBytes: MAX_BYTES,
-      conditionalWrites: "atomic",
-      deletion: "destroy",
-      changeDetection: "read",
-    }),
+    capabilities,
     validate: (namespace) =>
       safe(async () => {
         const address = { namespace, path: "__validation__" },

package/src/runtime-ops.ts

@@ -12,6 +12,12 @@ import {
   memoryIdentityProvisioning,
   type IdentityProvisioning,
 } from "./identity-provisioning.ts";
+import {
+  prepareSecretStore,
+  memoryStorageProvisioning,
+  storageProvisioningCode,
+  type PrepareStorage,
+} from "./storage-provisioning.ts";
 
 // What a workflow cannot do itself and the runtime does for it, as operations of the vendor
 // `sanoma` (`sanoma.secret.*`, `sanoma.invite.mint`, `sanoma.token.*`): named in `uses`, decided by
@@ -53,6 +59,24 @@ async function identityWrite(write: () => Promise<void>): Promise<void> {
  * `uses: [sanoma.secret.generate]` and `ctx.sanoma.secret.generate({ name, kind })`.
  */
 export const sanoma = defineConnector("sanoma", {
+  secretStore: {
+    prepare: {
+      effect: "access",
+      idempotent: true,
+      description:
+        "Prepare a company/environment KMS Postgres schema and restricted runtime login; store its database URL without returning credentials",
+      input: z.object({
+        company: z.string().min(1).max(256),
+        environment: z.string().min(1).max(256),
+        database: z.strictObject({ $secret: z.string().regex(SECRET_NAME) }),
+        store: SecretName,
+      }),
+      output: z.object({ company: z.string(), environment: z.string(), role: z.string(), store: z.string() }),
+      target: ({ company, environment }: { company: string; environment: string }) =>
+        JSON.stringify([company, environment]),
+      createsSecrets: ({ store }: { store: string }) => [store],
+    },
+  },
   identity: {
     enroll: {
       effect: "access",
@@ -211,13 +235,25 @@ export async function postInvite(host: string, request: string): Promise<{ url:
 export function runtimeDriver({
   tokens,
   identities,
+  storage = prepareSecretStore,
   invite = postInvite,
 }: {
   tokens: Tokens;
   identities?: IdentityProvisioning;
+  storage?: PrepareStorage;
   invite?: (host: string, request: string, call: CallContext) => Promise<{ url: string }>;
 }) {
   return defineDriver(sanoma, {
+    secretStore: {
+      async prepare(input, call) {
+        try {
+          return await storage(input, call.secrets);
+        } catch (error) {
+          const code = storageProvisioningCode(error) ?? "unavailable";
+          throw new DriverError(`Storage provisioning: ${code}`, { retryable: code === "unavailable" });
+        }
+      },
+    },
     identity: {
       async enroll({ store, ...input }, call) {
         if (!identities) throw refuse("identity provisioning is not configured");
@@ -309,5 +345,6 @@ export const sandboxRuntimeDriver = () =>
   runtimeDriver({
     tokens: memoryTokens(),
     identities: memoryIdentityProvisioning(),
+    storage: memoryStorageProvisioning(),
     invite: async (host, _request, call) => ({ url: new URL(`/auth/invite/sandbox-${tokenIdOf(call)}`, host).href }),
   });

package/src/secret-store.ts

@@ -1,4 +1,5 @@
 import { DEPLOYMENT_KEYS, type DeploymentKeyName, deploymentKey } from "./deployment-key.ts";
+import type { Db } from "./db.ts";
 /** Opaque values belong only in trusted runtime code, never workflow history or descriptions. */
 export interface SecretValue {
   value: string;
@@ -62,6 +63,21 @@ export interface SecretStore {
   delete(address: SecretAddress, options: { expectedVersion: string; by: string }): Promise<void>;
 }
 
+/** Bind a fresh adapter to each runtime's existing database; create must perform no I/O or allocate owned clients. */
+export interface SecretStoreFactory {
+  readonly kind: "runtime";
+  readonly id: string;
+  readonly capabilities: Readonly<SecretStoreCapabilities>;
+  /** The runtime owns this connection. Never close it or retain it outside the returned adapter. */
+  create(context: { database: () => Promise<Db> }): SecretStore & {
+    /** Close only clients this adapter opens lazily; never the supplied database. */
+    close?(): Promise<void>;
+  };
+}
+
+export const isSecretStoreFactory = (store: SecretStore | SecretStoreFactory): store is SecretStoreFactory =>
+  "kind" in store && store.kind === "runtime";
+
 export type SecretBinding =
   | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never }
   | { env: string; management?: "external"; path?: never; bootstrap?: never }
@@ -69,7 +85,7 @@ export type SecretBinding =
 
 export interface SecretConfiguration {
   /** Omitted: built-in encrypted Postgres, supplied by the runtime. */
-  store?: SecretStore;
+  store?: SecretStore | SecretStoreFactory;
   /** Defaults to `default`. Choose a distinct namespace and identity for each deployment. */
   namespace?: string;
   /** Names without a binding resolve to the same name in this namespace. */
@@ -134,7 +150,9 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
       !["atomic", "coordinated", "none"].includes(c.conditionalWrites) ||
       !["destroy", "soft-delete", "unsupported"].includes(c.deletion) ||
       !["read", "watch"].includes(c.changeDetection) ||
-      [s.validate, s.read, s.write, s.delete].some((fn) => typeof fn !== "function")
+      (isSecretStoreFactory(s)
+        ? typeof s.create !== "function"
+        : [s.validate, s.read, s.write, s.delete].some((fn) => typeof fn !== "function"))
     )
       invalid();
   }
@@ -173,15 +191,21 @@ export class SecretAccess {
   private readonly bindings: Readonly<Record<string, SecretBinding>>;
 
   private readonly env: (name: string) => string | undefined;
+  private closing?: Promise<void>;
+  private readonly onClose?: () => Promise<void>;
 
   constructor(
     config: SecretConfiguration,
     defaultStore: SecretStore,
     env: (name: string) => string | undefined = (name) => process.env[name],
+    onClose?: () => Promise<void>,
   ) {
     this.env = env;
+    this.onClose = onClose;
     checkSecretConfiguration(config);
-    this.store = config.store ?? defaultStore;
+    const store = config.store ?? defaultStore;
+    if (isSecretStoreFactory(store)) throw new SecretStoreError("invalid_configuration");
+    this.store = store;
     checkSecretConfiguration({ store: this.store });
     this.namespace = config.namespace ?? "default";
     this.bindings = Object.fromEntries(
@@ -189,6 +213,13 @@ export class SecretAccess {
     );
   }
 
+  /** Only runtime-factory adapters are owned here; configured standalone stores remain caller-owned. */
+  close(): Promise<void> {
+    return (this.closing ??= secretStoreCall(async () => {
+      await this.onClose?.();
+    }));
+  }
+
   location(name: string): SecretLocation {
     if (!namePattern.test(name)) throw new SecretStoreError("invalid_configuration");
     const binding = Object.hasOwn(this.bindings, name) ? this.bindings[name] : undefined;

package/src/shared.ts

@@ -613,6 +613,6 @@ export type OpFn<I, O> = (input: I) => Promise<O>;
 export interface CollectionApi<R> {
   get: OpFn<{ key: string }, Saved<R> | null>;
   list(query?: ListQuery<R>): Promise<Saved<R>[]>;
-  save: OpFn<{ record: R }, Saved<R>>;
+  save: OpFn<{ record: R; ifAbsent?: boolean; ifRecord?: Record<string, unknown> }, Saved<R>>;
   delete: OpFn<{ key: string }, { deleted: boolean }>;
 }