@sanoma-ai/workflows 0.10.1 → 0.10.3

package/src/deadlines.ts

@@ -8,7 +8,7 @@ import { warn } from "./log.ts";
 import type { CallContext, DriverFn, Op } from "./op.ts";
 import type { Secrets } from "./secret.ts";
 import { errorMessage, WAKEUP_AGENT } from "./shared.ts";
-import type { WakeupRegistration } from "./wakeup.ts";
+import { type EnvWakeup, WAKE_PATH, type WakeupRegistration } from "./wakeup.ts";
 
 // What a worker knows of its own runs that DBOS cannot tell it: which are executing and which are
 // blocked in a `ctx` wait, and until when. DBOS sees both as PENDING. A worker that registers a
@@ -133,15 +133,15 @@ export interface SelfStop {
   at: string | null;
 }
 
-/** What the stop rule acts on: the wakeup row, the wakeup's register operation, and the worker. */
+/** Registers a deadline with the instance's wakeup, replacing what it held; throws when it could not. */
+export type RegisterWakeup = (registration: WakeupRegistration) => Promise<void>;
+
+/** What the stop rule acts on: the wakeup row, how a deadline is registered, and the worker. */
 export interface StopRule {
   /** The wakeup row's database. */
   db: () => Promise<Db>;
-  /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
-  wakeup: string;
-  /** The wakeup type's register operation, and its driver (none when the connector attaches none). */
-  register: { op: Op; fn: DriverFn | undefined };
-  secrets: Secrets;
+  /** The declared wakeup's register operation (`declaredRegister`), or the host's own route (`envRegister`). */
+  register: RegisterWakeup;
   deadlines: Deadlines;
   idle: () => Promise<boolean>;
   everyMs: number;
@@ -174,7 +174,7 @@ export function stopWhenIdle(rule: StopRule): { close(): void } {
     const db = await rule.db();
     if (at !== null) {
       try {
-        await registerWakeup(rule, { at });
+        await rule.register({ at });
       } catch (err) {
         const message = errorMessage(err);
         await recordWakeupError(db, message);
@@ -214,18 +214,64 @@ export function stopWhenIdle(rule: StopRule): { close(): void } {
   };
 }
 
+/** A declared wakeup's register operation, and what its call needs. */
+export interface DeclaredRegister {
+  /** The wakeup type's register operation. */
+  op: Op;
+  /** Its driver: none when the connector attaches none. */
+  fn: DriverFn | undefined;
+  /** The instance's secrets, which the driver reads the wakeup's token from. */
+  secrets: Secrets;
+  /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
+  wakeup: string;
+}
+
+/**
+ * Registers through the declared wakeup's register operation, as `SanomaClient.call` calls a
+ * driver: its input parsed, a `CallContext` of the runtime's, and no ledger record, which is a run's.
+ */
+export function declaredRegister({ op, fn, secrets, wakeup }: DeclaredRegister): RegisterWakeup {
+  return async (registration) => {
+    if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
+    // Fresh each time: a repeat of an earlier `at` after another registration must re-arm it, so no
+    // two registrations share a key (real drivers never dedupe on it anyway).
+    const key = `wakeup:${wakeup}:${randomUUID()}`;
+    const context: CallContext = {
+      idempotencyKey: key,
+      runId: key,
+      opId: op.id,
+      attempt: 1,
+      secrets,
+      by: WAKEUP_AGENT,
+    };
+    await fn(op.input.parse(registration), context);
+  };
+}
+
 /**
- * Calls the wakeup's register operation, as `SanomaClient.call` calls a driver: its input parsed,
- * a `CallContext` of the runtime's, and no ledger record, which is a run's.
+ * Registers at the host's own wake route, as the environment names it (`EnvWakeup`): `PUT
+ * {url}/__sanoma/wake` with the token as a bearer and the registration as JSON, no driver and no
+ * secret store. 204 is taken; anything else fails with its status and the route's own `error`.
  */
-export async function registerWakeup(
-  { register: { op, fn }, secrets, wakeup }: Pick<StopRule, "register" | "secrets" | "wakeup">,
-  registration: WakeupRegistration,
-) {
-  if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
-  // Fresh each time: a repeat of an earlier `at` after another registration must re-arm it, so no
-  // two registrations share a key (real drivers never dedupe on it anyway).
-  const key = `wakeup:${wakeup}:${randomUUID()}`;
-  const context: CallContext = { idempotencyKey: key, runId: key, opId: op.id, attempt: 1, secrets, by: WAKEUP_AGENT };
-  await fn(op.input.parse(registration), context);
+export function envRegister({ url, token }: EnvWakeup): RegisterWakeup {
+  return async (registration) => {
+    const where = `PUT ${url}${WAKE_PATH}`;
+    let res: Response;
+    try {
+      res = await fetch(`${url}${WAKE_PATH}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify(registration),
+        // A redirect is no answer of the host's, and would carry the token elsewhere.
+        redirect: "manual",
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (err) {
+      throw new Error(`${where}: no answer (${errorMessage(err)})`, { cause: err });
+    }
+    if (res.status === 204) return;
+    const body: unknown = await res.json().catch(() => undefined);
+    const error = (body as { error?: unknown } | undefined)?.error;
+    throw new Error(`${where} answered ${res.status}${typeof error === "string" ? `: ${error}` : ""}`);
+  };
 }

package/src/define.ts

@@ -18,14 +18,37 @@ export interface Principal {
   groups?: string[];
   /** For an agent: the id of the person whose instruction it carries. */
   onBehalfOf?: string;
+  /**
+   * For a visitor: the email their site's login verified (`LoginHalf.verify`), which the app
+   * passes on. Admission keeps it for a visitor alone; a run's `ctx.startedBy.email`.
+   */
+  email?: string;
+  /**
+   * For an api token (`token:<id>`): the subject its row acts for, which `SanomaClient.start`
+   * reads from the row, never from the caller; a run's `ctx.startedBy.subject`.
+   */
+  subject?: string;
 }
 
 export const Principal: z.ZodType<Principal> = z.object({
   id: z.string().regex(/\S/, "id must not be blank"),
   groups: z.array(z.string()).optional(),
   onBehalfOf: z.string().regex(/\S/, "onBehalfOf must not be blank").optional(),
+  email: z.string().optional(),
+  subject: z.string().optional(),
 });
 
+/**
+ * Who started a run, as its workflow sees it (`ctx.startedBy`): the principal's id (`alice`,
+ * `visitor:<login>:<subject>`, `token:<id>`), with the email a visitor's login verified, and for
+ * an api token the subject its row acts for, so a workflow can tell whose a record is.
+ */
+export interface StartedBy {
+  readonly id: string;
+  readonly email?: string;
+  readonly subject?: string;
+}
+
 /** A built-in a workflow may call, as its description lists them. */
 export type Builtin = WorkflowEntry["builtins"][number];
 export type Use = Op | Builtin;
@@ -227,6 +250,8 @@ interface BaseCtx {
    */
   now(): Promise<number>;
   readonly runId: string;
+  /** Who started the run: read, never called (`StartedBy`). */
+  readonly startedBy: StartedBy;
 }
 
 export type Ctx<U extends readonly Use[]> = BaseCtx &

package/src/deployment-key.ts

@@ -1,10 +1,12 @@
+import { hkdfSync } from "node:crypto";
 import { readFileSync } from "node:fs";
 
+/** The deployment's own keys: bound only to the environment or bootstrap, never written by the runtime. */
+export const DEPLOYMENT_KEYS: readonly string[] = ["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"];
+export type DeploymentKeyName = "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY";
+
 /** Bootstrap only: never resolves through the secret store that the key unlocks. */
-export function deploymentKey(
-  name: "SANOMA_SECRETS_KEY" | "SANOMA_SIGNING_KEY",
-  env: NodeJS.ProcessEnv = process.env,
-): Buffer {
+export function deploymentKey(name: DeploymentKeyName, env: NodeJS.ProcessEnv = process.env): Buffer {
   const value = env[name];
   const file = env[`${name}_FILE`];
   if (value && file) throw new Error(`Set only one of ${name} and ${name}_FILE`);
@@ -16,8 +18,32 @@ export function deploymentKey(
       throw new Error(`${name}_FILE could not be read`);
     }
   }
-  if (!encoded || !/^[A-Za-z0-9+/]{43}=$/.test(encoded) || Buffer.from(encoded, "base64").length !== 32) {
-    throw new Error(`${name} must be 32 random bytes in base64; supply ${name} or ${name}_FILE`);
-  }
-  return Buffer.from(encoded, "base64");
+  const key = encoded ? keyBytes(encoded) : undefined;
+  if (!key) throw new Error(`${name} must be 32 random bytes in base64; supply ${name} or ${name}_FILE`);
+  return key;
+}
+
+/**
+ * The 32 bytes of a key written as text: padded base64 (`sanoma key`), or base64url without
+ * padding (a `secret(..., { generate: true })` marker's value). Anything else is `undefined`.
+ */
+export function keyBytes(text: string): Buffer | undefined {
+  if (/^[A-Za-z0-9+/]{43}=$/.test(text)) return Buffer.from(text, "base64");
+  if (/^[A-Za-z0-9_-]{43}$/.test(text)) return Buffer.from(text, "base64url");
+  return undefined;
 }
+
+/**
+ * A 32-byte key of its own for `purpose`, derived from a deployment's signing key (HKDF-SHA256
+ * over its base64 text), as that deployment derives it from its `SANOMA_SIGNING_KEY`.
+ */
+export const deriveSigningKey = (signingKey: Buffer, purpose: string): Buffer =>
+  Buffer.from(hkdfSync("sha256", signingKey.toString("base64"), "", purpose, 32));
+
+/**
+ * A 32-byte key of its own for `purpose`, derived from `SANOMA_SIGNING_KEY` (`deriveSigningKey`):
+ * each use of the signing key (a login's cookies, the setup's state, sealed values) gets a key no
+ * other use shares.
+ */
+export const signingKeyFor = (purpose: string): Buffer =>
+  deriveSigningKey(deploymentKey("SANOMA_SIGNING_KEY"), purpose);

package/src/describe.ts

@@ -4,7 +4,8 @@ import { type AppEntry, appsAt } from "./apps.ts";
 import { readSource, type SourceFile } from "./ast.ts";
 import { readPolicyFiles } from "./cedar.ts";
 import { recordSchemaOf } from "./collection.ts";
-import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
+import { decideCall } from "./call.ts";
+import { connectorsOf, type ResolvedConfig, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
 import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
 import {
   CAPABILITIES,
@@ -17,6 +18,7 @@ import {
 } from "./description.ts";
 import { isDirect } from "./direct.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
+import { CODE_MAIL } from "./login-code.ts";
 import { lintWorkflow } from "./lint.ts";
 import { fresh, stampOf, stampsOf } from "./load.ts";
 import { LOCKFILE } from "./lockfile.ts";
@@ -27,7 +29,17 @@ import { allowAll, policyOpOf } from "./policy.ts";
 import { type Resource, resourceTypesOf, valueAt } from "./resource.ts";
 import { type DeclaredResource, inAppPeople, loadDataFiles, type ResourceProblem } from "./resources.ts";
 import { apiNameProblem } from "./sdk.ts";
-import { apiNameOf, BUILT_IN_WORKFLOWS, DATA_VENDOR, errorMessage, problemLine } from "./shared.ts";
+import {
+  apiNameOf,
+  BUILT_IN_WORKFLOWS,
+  DATA_VENDOR,
+  errorMessage,
+  LOGIN_AGENT,
+  LOGIN_CODE_WORKFLOW,
+  type PeopleResource,
+  principalOf,
+  problemLine,
+} from "./shared.ts";
 import { readSites, type SiteEntry } from "./sites.ts";
 
 // `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
@@ -282,6 +294,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
       ...appProblems,
       ...appClashes(apps, collections, sites),
       ...domainProblems(dataFiles.resources, resources, sites),
+      ...loginProblems(resolved, dataFiles.resources),
     ],
     apps,
     policy: {
@@ -291,9 +304,33 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
       files: resolved.root === undefined ? [] : readPolicyFiles(resolved.root),
     },
     sites,
+    ...(resolved.login && { login: { sender: resolved.login.sender.id } }),
   };
 }
 
+/**
+ * The policy holding or denying the sign-in code: `login.sender` as the runtime's agent `login`
+ * in a run of `login-code` must be allowed, or nobody receives a code.
+ */
+function loginProblems(resolved: ResolvedConfig, people: readonly PeopleResource[]): ResourceProblem[] {
+  if (!resolved.login || resolved.policyProblems.length) return [];
+  const { sender } = resolved.login;
+  const agent = principalOf(LOGIN_AGENT, people)!;
+  const run = { id: "check", workflow: LOGIN_CODE_WORKFLOW, approvals: [] };
+  const decision = decideCall(resolved.policy, sender, CODE_MAIL, agent, run);
+  if (decision.kind === "allow") return [];
+  const does = decision.kind === "deny" ? "denies" : "holds";
+  const by = decision.reasons?.length ? ` (${decision.reasons.join(", ")})` : "";
+  return [
+    {
+      file: "policies",
+      message:
+        `the policy ${does} ${sender.id} for the sign-in code${by}, so nobody receives one: exempt the runtime's ` +
+        `agent, \`unless { principal == Sanoma::Principal::"${LOGIN_AGENT}" }\``,
+    },
+  ];
+}
+
 /** That the root's `kind` `name`, in `file`, is named as an app is. */
 const appClash = (kind: string, name: string, file: string): ResourceProblem => ({
   file,

package/src/description.ts

@@ -422,5 +422,7 @@ export const ConfigDescriptionSchema = z.strictObject({
    * the config does not have as its problems; none when the root has no `sites/`.
    */
   sites: z.array(SiteEntrySchema),
+  /** The config's `login`: the operation its sign-in codes are sent with, by id. */
+  login: z.strictObject({ sender: z.string() }).optional(),
 });
 export type ConfigDescription = z.infer<typeof ConfigDescriptionSchema>;

package/src/host.ts

@@ -46,8 +46,11 @@ export interface HostSpec {
     source: string;
     /** The branch (or tag) it runs: `main`, never a commit. */
     ref: string;
-    /** The secrets it passes the runtime (`SANOMA_DATABASE_URL`, `SANOMA_SECRETS_KEY`): a write-only field. */
-    secrets: string;
+    /**
+     * The secrets it passes the runtime (`SANOMA_DATABASE_URL`, `SANOMA_SECRETS_KEY`): a write-only
+     * field. Absent for a host that binds its own bootstrap (`bindsBootstrap`).
+     */
+    secrets?: string;
     /** The port the app listens on. */
     port: string;
     /** A public site's domain, by site name: the app serves each site at the root of its domain (`SANOMA_DOMAINS`). */
@@ -58,6 +61,11 @@ export interface HostSpec {
    * file may not declare it, so a merge to `ref` is a change to the host.
    */
   revision: string;
+  /**
+   * True for a host whose vendor mints the instance's bootstrap (its database URL, keys and
+   * tokens) and binds it itself, as Sanoma Cloud's does: such a type takes no `secrets`.
+   */
+  bindsBootstrap?: boolean;
   outputs: (state: Record<string, unknown>) => HostOutputs;
 }
 
@@ -83,8 +91,9 @@ function unwrap(schema: z.ZodType): z.ZodType {
 
 /**
  * Throws what is wrong with a resource type's `host`: an input or `revision` that names no field,
- * `secrets` that is not write-only, a `revision` that is, an unknown lifetime, a type apply cannot
- * change (not `writable`).
+ * `secrets` that is not write-only, missing (unless the host binds its own bootstrap) or given
+ * beside `bindsBootstrap`, a `revision` that is write-only, an unknown lifetime, a type apply
+ * cannot change (not `writable`).
  */
 export function checkHost(
   what: string,
@@ -96,10 +105,17 @@ export function checkHost(
   if (!LIFETIMES.includes(host.capabilities?.lifetime)) {
     problems.push(`capabilities.lifetime is one of ${LIFETIMES.join(", ")}`);
   }
-  for (const [input, path] of [...Object.entries(host.inputs ?? {}), ["revision", host.revision] as const]) {
+  // An input given as undefined is one not given.
+  const given = Object.entries(host.inputs ?? {}).filter(([, path]) => path !== undefined);
+  for (const [input, path] of [...given, ["revision", host.revision] as const]) {
     if (typeof path !== "string" || !hasPath(type.schema, path)) problems.push(`${input} names no field (${path})`);
   }
-  if (!type.fields.writeOnly.includes(host.inputs?.secrets)) problems.push("inputs.secrets must be a write-only field");
+  const secrets = host.inputs?.secrets;
+  if (host.bindsBootstrap) {
+    if (secrets !== undefined) problems.push("inputs.secrets is not taken by a host that binds its own bootstrap");
+  } else if (secrets === undefined || !type.fields.writeOnly.includes(secrets)) {
+    problems.push("inputs.secrets must be a write-only field, unless the host binds its own bootstrap");
+  }
   if (type.fields.writeOnly.includes(host.revision)) problems.push("revision must not be write-only: drift reads it");
   if (typeof host.outputs !== "function") problems.push("outputs must be a function of the state");
   if (problems.length) throw new Error(`${what}: its host: ${problems.join("; ")}`);

package/src/index.ts

@@ -1,6 +1,8 @@
 export {
   type CallContext,
   CLIENT_IP_HEADER,
+  requestOrigin,
+  sameOrigin,
   type Connector,
   type ConnectorSetup,
   type ConnectorVendor,
@@ -12,13 +14,17 @@ export {
   type Effect,
   isOp,
   isSvgElement,
+  INVITE_SECONDS,
   type LoginContext,
   type LoginHalf,
+  type LoginIdentity,
+  type LoginMethod,
   type ModelContext,
   type Op,
   type OpSpec,
   type ResourceGroup,
   retryableStatus,
+  type SignInMethod,
   type VendorInfo,
   withSetup,
 } from "./op.ts";
@@ -33,6 +39,7 @@ export {
   type Builtin,
   type Ctx,
   type SleepRequest,
+  type StartedBy,
   type StepOptions,
   type Trigger,
   type Use,
@@ -56,6 +63,7 @@ export {
 export {
   declaredWakeup,
   defineConfig,
+  envWakeup,
   resolveConfig,
   resolveDatabaseUrl,
   type ResolvedConfig,
@@ -201,9 +209,16 @@ export {
   storeDatabaseUrl,
 } from "./database.ts";
 export type { Chat, Chats } from "./chats.ts";
+export type { Tokens } from "./tokens.ts";
+export { type InviteRequest, openInvite, sealInvite, sealLoginCode } from "./seal.ts";
+export { postInvite, sanoma } from "./runtime-ops.ts";
+export { sourceKeyPair, sshPublicKey } from "./ssh-key.ts";
 export {
   checkWakeup,
   type DeclaredWakeup,
+  type EnvWakeup,
+  HOST_URL,
+  WAKE_PATH,
   type WakeupOutputs,
   type WakeupRegistration,
   type WakeupSpec,
@@ -243,6 +258,8 @@ export {
   principalOf,
   RUNTIME_AGENTS,
   HOST_CHECK_AGENT,
+  LOGIN_AGENT,
+  LOGIN_CODE_WORKFLOW,
   SCHEDULE_AGENT,
   credentialReady,
   DEFAULT_SLEEP_NAME,
@@ -292,12 +309,13 @@ export {
   type AuthenticationProblem,
   type Authentication,
   type AuthenticationIdentity,
+  type AuthenticationContext,
   type CallAuthentication,
 } from "./authentication.ts";
 export { checkSecretStore, type SecretStoreCheck } from "./secret-store-check.ts";
 
 export { postgresSecretStore } from "./credentials.ts";
-export { deploymentKey } from "./deployment-key.ts";
+export { deploymentKey, signingKeyFor } from "./deployment-key.ts";
 
 export {
   defineConnection,