@sanoma-ai/workflows 0.10.2 → 0.10.6

package/src/ssh-key.ts

@@ -0,0 +1,48 @@
+import { createPrivateKey, createPublicKey, generateKeyPair, type KeyObject } from "node:crypto";
+import { promisify } from "node:util";
+
+// SSH key pairs, as a deploy key needs them: what going live makes (the app's `goLive`) and
+// `sanoma.secret.generate`'s `ssh-rsa` kind.
+
+/** RFC 4253's `string`: the bytes after their length, 32 bits big-endian. */
+function sshString(bytes: Buffer) {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(bytes.length);
+  return Buffer.concat([length, bytes]);
+}
+
+/** RFC 4253's `mpint` of a JWK's integer, unsigned with no leading zero: one first when its top bit is set. */
+function sshMpint(value: string) {
+  const bytes = Buffer.from(value, "base64url");
+  return sshString(bytes[0]! & 0x80 ? Buffer.concat([Buffer.of(0), bytes]) : bytes);
+}
+
+/** An RSA public key in OpenSSH's one-line format, as GitHub takes it: `ssh-rsa`, then the base64 of the strings `ssh-rsa`, `e` and `n`. */
+function openSshLine(publicKey: KeyObject): string {
+  const { e, n } = publicKey.export({ format: "jwk" });
+  const wire = Buffer.concat([sshString(Buffer.from("ssh-rsa")), sshMpint(e!), sshMpint(n!)]);
+  return `ssh-rsa ${wire.toString("base64")}`;
+}
+
+/**
+ * A new deploy key: its private half RSA 3072 in PKCS#1 PEM, which OpenSSH reads as it is (Node
+ * writes no OpenSSH private key, which ed25519 would need), and its public half in OpenSSH's
+ * one-line format (`sshPublicKey`).
+ */
+export async function sourceKeyPair(): Promise<{ privateKey: string; publicKey: string }> {
+  const { privateKey, publicKey } = await promisify(generateKeyPair)("rsa", { modulusLength: 3072 });
+  return {
+    privateKey: privateKey.export({ type: "pkcs1", format: "pem" }).toString(),
+    publicKey: openSshLine(publicKey),
+  };
+}
+
+/** The public half of an RSA private key in PEM, in OpenSSH's one-line format; undefined for anything else. */
+export function sshPublicKey(privateKey: string): string | undefined {
+  try {
+    const key = createPublicKey(createPrivateKey(privateKey));
+    return key.asymmetricKeyType === "rsa" ? openSshLine(key) : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,100 @@
+import { randomUUID } from "node:crypto";
+import type { Pool } from "pg";
+import { API_TOKENS_TABLE as TABLE } from "./db.ts";
+import type { Principal } from "./define.ts";
+import { generateSecret, tokenHash as hashOf } from "./secret.ts";
+
+// The api tokens, in the config's database beside the runtime's other tables: a caller of a
+// public site's api (`callFn`) with `Authorization: Bearer sca_…` is the principal `token:<id>`,
+// a visitor, with the row's groups. Only a token's SHA-256 is kept; the token is shown once, at mint.
+
+/** What every token starts with, so a bearer that is not one is told at a glance. */
+const PREFIX = "sca_";
+
+/** The api tokens' store, `SanomaClient.tokens`. */
+export interface Tokens {
+  /**
+   * Mints a token acting for `subject` (the principal it stands for, such as the account's
+   * `visitor:better-auth:<id>`) in `groups`: its id (`id`, or a new one) and the token, which is
+   * shown only here. An id another token has is refused.
+   */
+  mint(token: { id?: string; subject: string; groups: readonly string[] }): Promise<{ id: string; token: string }>;
+  /** Revokes the token `id`: it resolves to nobody from now on. Revoking one revoked or missing does nothing. */
+  revoke(token: { id: string }): Promise<void>;
+  /**
+   * Who a bearer token is (`token:<id>`, in its row's groups), with the subject it acts for;
+   * undefined for anything not a token minted here, or one revoked.
+   */
+  resolve(token: string): Promise<{ principal: Principal; subject: string } | undefined>;
+  /** The subject the token `id` acts for (a workflow's `ctx.startedBy.subject`); undefined for one revoked or missing. */
+  subjectOf(id: string): Promise<string | undefined>;
+}
+
+export function tokenStore(db: () => Promise<Pool>): Tokens {
+  return {
+    async mint({ id = randomUUID(), subject, groups }) {
+      const token = `${PREFIX}${generateSecret()}`;
+      await (
+        await db()
+      ).query(`INSERT INTO ${TABLE} (id, hash, subject, groups) VALUES ($1, $2, $3, $4::jsonb)`, [
+        id,
+        hashOf(token),
+        subject,
+        JSON.stringify(groups),
+      ]);
+      return { id, token };
+    },
+    async revoke({ id }) {
+      await (await db()).query(`UPDATE ${TABLE} SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL`, [id]);
+    },
+    async resolve(token) {
+      if (!token.startsWith(PREFIX)) return undefined;
+      // Looked up by its hash: the token itself is never stored, so there is nothing to compare it to.
+      const { rows } = await (
+        await db()
+      ).query<{ id: string; subject: string; groups: string[] }>(
+        `SELECT id, subject, groups FROM ${TABLE} WHERE hash = $1 AND revoked_at IS NULL`,
+        [hashOf(token)],
+      );
+      const row = rows[0];
+      if (!row) return undefined;
+      return { principal: { id: `token:${row.id}`, groups: row.groups }, subject: row.subject };
+    },
+    async subjectOf(id) {
+      const { rows } = await (
+        await db()
+      ).query<{ subject: string }>(`SELECT subject FROM ${TABLE} WHERE id = $1 AND revoked_at IS NULL`, [id]);
+      return rows[0]?.subject;
+    },
+  };
+}
+
+/** The api tokens in memory, for a sandbox run's `sanoma.token.*`: the same contract, nothing kept past the process. */
+export function memoryTokens(): Tokens {
+  const rows = new Map<string, { hash: string; subject: string; groups: string[]; revoked: boolean }>();
+  return {
+    async mint({ id = randomUUID(), subject, groups }) {
+      if (rows.has(id)) throw new Error(`A token with the id ${id} exists`);
+      const token = `${PREFIX}${generateSecret()}`;
+      rows.set(id, { hash: hashOf(token), subject, groups: [...groups], revoked: false });
+      return { id, token };
+    },
+    async revoke({ id }) {
+      const row = rows.get(id);
+      if (row) row.revoked = true;
+    },
+    async resolve(token) {
+      const hash = hashOf(token);
+      for (const [id, row] of rows) {
+        if (row.hash === hash && !row.revoked) {
+          return { principal: { id: `token:${id}`, groups: [...row.groups] }, subject: row.subject };
+        }
+      }
+      return undefined;
+    },
+    async subjectOf(id) {
+      const row = rows.get(id);
+      return row && !row.revoked ? row.subject : undefined;
+    },
+  };
+}

package/src/wakeup-service.ts

@@ -1,7 +1,7 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { connectMaking, createTable, type Db, openPool } from "./db.ts";
 import { info, warn } from "./log.ts";
-import { generateSecret } from "./secret.ts";
+import { generateSecret, tokenHash as hashOf } from "./secret.ts";
 import { errorMessage } from "./shared.ts";
 
 /*
@@ -110,12 +110,6 @@ export const WAKEUP_TOKEN = "SANOMA_WAKEUP_TOKEN";
 /** An instance token the service takes: `swi_`, then at least as many base64url characters as a minted one has. */
 export const INSTANCE_TOKEN = /^swi_[\w-]{43,256}$/;
 
-/**
- * The token's sha256, which is all the tables keep: a token is found by its hash (a unique index),
- * so the secret itself is never compared, and a guess's timing says nothing an attacker can steer.
- */
-const hashOf = (token: string) => createHash("sha256").update(token).digest("hex");
-
 /** A date-time as `Date.toISOString` writes one, or with an offset: four-digit years only. */
 const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
 

package/src/wakeup.ts

@@ -11,6 +11,27 @@ import type { DeclaredResource } from "./resources.ts";
 // replaced registration starts a worker that finds nothing to do and stops again. The contract is
 // here; the worker's side is `deadlines.ts`.
 
+/**
+ * A host's own wake route, where a wakeup that the host holds itself takes a registration: `PUT`
+ * with `WakeupRegistration` and the instance's `SANOMA_WAKEUP_TOKEN` as a bearer, answered 204.
+ * The Cloudflare Worker serves it; a hosted instance that declares no wakeup registers there
+ * (`EnvWakeup`).
+ */
+export const WAKE_PATH = "/__sanoma/wake";
+
+/**
+ * The wakeup a hosted instance's environment names, when its data files declare none: its own
+ * host's URL (`SANOMA_HOST_URL`) and its token (`SANOMA_WAKEUP_TOKEN`), which the host gives the
+ * runtime. The worker registers each deadline at `{url}{WAKE_PATH}` itself, with no driver.
+ */
+export interface EnvWakeup {
+  url: string;
+  token: string;
+}
+
+/** Where a host gives the runtime its own URL: the Cloudflare Worker's plain-text binding. */
+export const HOST_URL = "SANOMA_HOST_URL";
+
 /** What a wakeup's state says of it. */
 export interface WakeupOutputs {
   healthy: boolean;

package/src/worker.ts

@@ -2,10 +2,19 @@ import { DBOS, type ScheduledWorkflowFn } from "@dbos-inc/dbos-sdk";
 import { awaitApproval } from "./approvals.ts";
 import { buildCtx, decideStart, isInfrastructureError, startHoldOf } from "./call.ts";
 import { dbosStatusesOf } from "./client.ts";
-import { declaredWakeup, type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
+import { declaredWakeup, envWakeup, type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
 import { configuredSecrets } from "./credentials.ts";
 import { type Db, DBOS_DATABASE_OPTIONS, lazyPool, prepareDatabase, stampVersion } from "./db.ts";
-import { deadlineRegistry, type Deadlines, idle, onOwnQueue, type SelfStop, stopWhenIdle } from "./deadlines.ts";
+import {
+  deadlineRegistry,
+  type Deadlines,
+  declaredRegister,
+  envRegister,
+  idle,
+  onOwnQueue,
+  type SelfStop,
+  stopWhenIdle,
+} from "./deadlines.ts";
 import type { WorkflowDefinition } from "./define.ts";
 import { credentialsOf, unconfigured, unconfiguredSummary } from "./env.ts";
 import { errorInfo, parseOrThrow, PolicyDeniedError } from "./errors.ts";
@@ -79,10 +88,10 @@ export interface WorkerOptions {
    * and other short waits never stop it.
    */
   idleHorizonMs?: number;
-  /** How often a worker whose data files declare a wakeup checks whether it may stop: every 15 s by default. */
+  /** How often a worker with a wakeup (declared, or named by its environment: `envWakeup`) checks whether it may stop: every 15 s by default. */
   stopCheckMs?: number;
   /**
-   * Given, and with a wakeup declared, the worker stops itself when idle (`stopCheckMs`); without
+   * Given, and with a wakeup (declared, or named by the environment), the worker stops itself when idle (`stopCheckMs`); without
    * it, nobody would start another, so it never does. Called once the worker has stopped itself, with the deadline it registered with the
    * wakeup (null for none): a supervisor starts a fresh worker on the next write or wake, since a
    * stopped one cannot launch again.
@@ -108,9 +117,12 @@ export async function startWorker(config: SanomaConfig, options: WorkerOptions =
   setLogLevel(options.logLevel);
   // Read once, when it matters: a worker stops itself, registering its next deadline there, only
   // when its caller hears it stop (`onStopped`).
-  const wakeup = options.onStopped || config.wakeup === true ? await declaredWakeup(config) : undefined;
+  const declared = options.onStopped || config.wakeup === true ? await declaredWakeup(config) : undefined;
+  // Else the one a host Sanoma Cloud made names in the environment, which an instance running the
+  // wakeup service ignores: it must not stop.
+  const wakeup = declared ?? (options.onStopped && config.wakeup !== true ? envWakeup(process.env) : undefined);
   // The wakeup service wakes the instances that stop: one that runs it must not stop with its worker.
-  if (config.wakeup === true && wakeup) {
+  if (config.wakeup === true && declared) {
     throw new Error(
       "The config runs the wakeup service (`wakeup: true`) and declares a wakeup of its own: an instance that runs the service must not stop, so leave out one of them",
     );
@@ -130,6 +142,7 @@ export async function startWorker(config: SanomaConfig, options: WorkerOptions =
     ...(resolved.scenarios && { scenarios: resolved.scenarios }),
     ...(options.source && { source: options.source }),
     types: resolved.types,
+    declaredObjects: resolved.declaredObjects,
     collections: resolved.collections,
     steps: resolved.steps,
     policy: resolved.policy,
@@ -232,14 +245,19 @@ export async function startWorker(config: SanomaConfig, options: WorkerOptions =
       warn(`the policies do not hold, so every call and start is refused:\n  ${resolved.policyProblems.join("\n  ")}`);
     }
     if (wakeup && options.onStopped) {
-      const registerId = wakeup.type.wakeup!.register;
       stopRule = stopWhenIdle({
         // The row is one more of the runtime's tables: the secrets' pool, on the same database.
         db: () => secrets.db(),
-        wakeup: wakeup.binding ?? wakeup.id,
-        // `resolveConfig` checked the operation is the config's (`checkWakeupOps`).
-        register: { op: resolved.ops.get(registerId)!, fn: resolved.drivers.get(registerId) },
-        secrets: state.secrets,
+        register:
+          "type" in wakeup
+            ? declaredRegister({
+                // `resolveConfig` checked the operation is the config's (`checkWakeupOps`).
+                op: resolved.ops.get(wakeup.type.wakeup!.register)!,
+                fn: resolved.drivers.get(wakeup.type.wakeup!.register),
+                secrets: state.secrets,
+                wakeup: wakeup.binding ?? wakeup.id,
+              })
+            : envRegister(wakeup),
         deadlines: state.deadlines,
         idle: () => worker.idle(),
         everyMs: options.stopCheckMs ?? 15_000,