@sanoma-ai/workflows 0.10.2 → 0.10.6

package/src/ledger.ts

@@ -1,5 +1,6 @@
 import type { ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -8,7 +9,7 @@ import { type Db, LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
 import type { Approver, Principal } from "./define.ts";
 import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
 import { shown, warn } from "./log.ts";
-import type { Effect } from "./op.ts";
+import type { Effect, SignInMethod } from "./op.ts";
 import type { RecordedDecision } from "./policy.ts";
 import type { Run } from "./run.ts";
 import { errorMessage } from "./shared.ts";
@@ -137,8 +138,58 @@ export type LedgerRecord = {
   | { type: "run.finished"; output: unknown }
   /** `error` as for `op.called`. */
   | { type: "run.failed"; error: ErrorInfo }
+  /**
+   * A declared person signed in to the staff login, by `method`; written outside any run, in the
+   * person's own `signin:<person>` (`signInRecord`), its `at` when.
+   */
+  | { type: "signin.recorded"; person: string; method: SignInMethod }
+  /** `by` minted an invite for the declared `person`, good until `expiresAt` (ISO 8601); in `invite:<person>`, outside any run. */
+  | { type: "invite.minted"; person: string; by: string; expiresAt: string }
 );
 
+/** What a sign-in's or an invite's record names as its workflow: the staff login, which is no run. */
+const LOGIN = "login";
+
+/**
+ * The record of a sign-in or an invite, written outside any run (`SanomaClient.recordSignIn`,
+ * `recordInvite`): in the run `signin:<person>` or `invite:<person>`, each with an id of its own,
+ * `seq` 0, so a person's records read in the order they were written.
+ */
+export function loginRecord(
+  app: string,
+  actor: Principal,
+  body: Extract<LedgerBody, { type: "signin.recorded" | "invite.minted" }>,
+  at = Date.now(),
+): LedgerRecord {
+  const runId = `${body.type === "signin.recorded" ? "signin" : "invite"}:${body.person}`;
+  return {
+    v: 1,
+    app,
+    id: `${runId}:${body.type}:${at}:${randomUUID()}`,
+    runId,
+    seq: 0,
+    at,
+    actor,
+    workflow: LOGIN,
+    ...body,
+  } as LedgerRecord;
+}
+
+/** When each of `people` last signed in, and how, by id: from their `signin:<person>` records; one who never did is left out. */
+export async function lastSignIns(
+  store: LedgerStore,
+  people: readonly string[],
+): Promise<Record<string, { at: number; method: SignInMethod }>> {
+  const last = await Promise.all(
+    people.map(async (person) => {
+      const records = await store.read(`signin:${person}`);
+      const latest = records.reduce<LedgerRecord | undefined>((a, r) => (a && a.at > r.at ? a : r), undefined);
+      return latest?.type === "signin.recorded" ? [[person, { at: latest.at, method: latest.method }] as const] : [];
+    }),
+  );
+  return Object.fromEntries(last.flat());
+}
+
 /**
  * The `ctx.all` member a record was written in. `id` is `all:<seq>`, the run's next `seq` when
  * the `ctx.all` began, so a replay names it the same; `index` is the member's position, `size`

package/src/login-code.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import type { Op } from "./op.ts";
+import { openLoginCode } from "./seal.ts";
+import type { LOGIN_CODE_WORKFLOW } from "./shared.ts";
+
+// The built-in `login-code` workflow: one mail with a sign-in code, through the config's
+// `login.sender`. The app starts it as the runtime's agent `login` (`LOGIN_AGENT`) with the code
+// sealed (`sealLoginCode`), so neither the run's input nor the ledger shows it: the call is
+// recorded with its body as `<text>` (`recorded` in `call.ts`). It is a workflow like any other:
+// the call goes through `ctx`, under the policy, in the ledger.
+
+/** An operation on `ctx`. */
+type OpCall = (input: unknown) => Promise<unknown>;
+
+/** The workflow's input: to whom, and the code, sealed. */
+const LoginCodeInput = z.object({ to: z.string().min(1), code: z.string().min(1) });
+
+/** What a sign-in code is sent as, for checks before any is: a sender must take it, and the policy is asked about it. */
+export const CODE_MAIL = { to: "person@example.com", subject: "Your sign-in code", text: "<text>" };
+
+/** The mail's text: the code, what it is for, and how long it lasts; nothing else, and no link. */
+const textOf = (company: string, code: string) =>
+  `Your sign-in code for ${company} is ${code}.\n\n` +
+  "It works once, for five minutes. If you did not ask for it, ignore this mail.\n";
+
+/** The login-code workflow for a config: it sends through `sender`, saying it is `company`'s. */
+export function loginCodeWorkflow(
+  sender: Op,
+  company: string,
+): WorkflowDefinition<readonly Op[], typeof LoginCodeInput> {
+  return defineWorkflow({
+    // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+    name: "login-code" satisfies typeof LOGIN_CODE_WORKFLOW,
+    title: "Send a sign-in code",
+    trigger: "manual",
+    input: LoginCodeInput,
+    uses: [sender],
+    run: async (ctx, input) => {
+      const { vendor, resource, name } = sender;
+      const mail = {
+        to: input.to,
+        subject: `Your ${company} sign-in code`,
+        text: textOf(company, openLoginCode(input.code, input.to)),
+      };
+      // `ctx` called directly, so the outline places the call.
+      return (ctx as unknown as Record<string, Record<string, Record<string, OpCall>>>)[vendor]![resource]![name]!(
+        mail,
+      );
+    },
+  });
+}

package/src/op.ts

@@ -360,12 +360,36 @@ export interface ConnectorSetup {
 /** What the app gives a connector's model half (`ConnectorSetup.model`): the secrets, as a login half reads them. */
 export type ModelContext = Pick<LoginContext, "secrets">;
 
-/** What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it for a public site. */
+/**
+ * What a login vouches for about who is asking: a name they gave (`id`, the loopback's), a
+ * verified email, a GitHub login. The app admits the declared person they match (`personOf`).
+ */
+export interface LoginIdentity {
+  id?: string;
+  email?: string;
+  github?: string;
+}
+
+/** How a login half lets a person in: an email code, GitHub, an invite link, an email and a password. */
+export type LoginMethod = "code" | "github" | "invite" | "password";
+
+/** How a person signed in to the staff login, which the ledger records (`signin.recorded`): all but a password. */
+export type SignInMethod = Exclude<LoginMethod, "password">;
+
+/** The company's own OAuth clients, as a login takes them: GitHub's is its GitHub App's client. */
+export interface SocialClients {
+  github?: { clientId: string; clientSecret: string };
+}
+
+/**
+ * What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it: for a
+ * public site, once per site; for the staff login, once, with `staff`.
+ */
 export interface LoginContext {
   /** The company's database (`resolved.databaseUrl`), where a login like Better Auth keeps its users. */
   databaseUrl: string;
   /**
-   * A 32-byte key derived from the deployment's `SANOMA_SECRETS_KEY` for this login (HKDF-SHA256,
+   * A 32-byte key derived from the deployment's `SANOMA_SIGNING_KEY` for this login (HKDF-SHA256,
    * purpose `login <connector>`), hex; a login signs its cookies with it and never asks a person for a secret.
    */
   key: string;
@@ -377,9 +401,29 @@ export interface LoginContext {
   /**
    * The origins the site answers on, scheme included and `:*` for any port:
    * `["http://www.localhost:*", "https://sanoma.example"]`; a login needs the protocol for its
-   * cookies and allowed hosts.
+   * cookies and allowed hosts. Empty for the staff login, which answers on any host the app does.
    */
   origins: readonly string[];
+  /**
+   * Sends a sign-in code to an email, through the config's `login.sender` (a run of the built-in
+   * `login-code` workflow, as the runtime's agent `login`); absent when the config names no
+   * sender, and then the login offers no code.
+   */
+  sendCode?(email: string, code: string): Promise<void>;
+  /**
+   * For a public site's login: the company's own OAuth clients (its GitHub App's), each a method
+   * when given, by which a visitor signs in or, signed in, links that account (`LoginIdentity.github`).
+   */
+  social?: SocialClients;
+  /** For the staff login only: who it may let in, the company's social clients, and where it tells of a sign-in. */
+  staff?: {
+    /** Whether the people files declare the person `identity` names; a login never makes a user for anyone else. */
+    admits(identity: LoginIdentity): boolean;
+    /** The company's own OAuth clients, each a method when given. */
+    social: SocialClients;
+    /** Tells the app of a sign-in by `method` of the person `identity` names, which the ledger records. Must not throw. */
+    record(method: SignInMethod, identity: LoginIdentity): Promise<void>;
+  };
 }
 
 /**
@@ -390,23 +434,62 @@ export interface LoginContext {
 export const CLIENT_IP_HEADER = "x-sanoma-client-ip";
 
 /**
- * A connector's login half: how a public site tells who a visitor is. The app makes one with
- * `login(context)` once per public site, when it starts; a login that keeps tables in the
- * database migrates them itself there, serialized and idempotent. It answers the provider's
- * subject only; the app makes the principal from it (`visitor:<connector>:<subject>`, in
- * `visitors`), so a connector never sets a visitor's groups. A visitor's address, for rate
- * limits, is the `CLIENT_IP_HEADER` header.
+ * A request's origin, https when a proxy that ends TLS says so (`x-forwarded-proto: https`), as
+ * Start's `getRequestUrl({ xForwardedProto: true })` reads it: the absolute URLs a page or an invite writes, and a login's cookies, take it.
+ */
+export function requestOrigin(request: Request): string {
+  const url = new URL(request.url);
+  if (request.headers.get("x-forwarded-proto") === "https") url.protocol = "https:";
+  return url.origin;
+}
+
+/** Whether a change comes from the page's own origin (a login's CSRF check): the browser says so, or its `Origin` names the request's host. */
+export function sameOrigin(request: Request): boolean {
+  const site = request.headers.get("sec-fetch-site");
+  if (site !== null) return site === "same-origin";
+  const origin = URL.parse(request.headers.get("origin") ?? "");
+  return origin !== null && origin.host === request.headers.get("host");
+}
+
+/**
+ * A connector's login half: how a public site tells who a visitor is, and, made with
+ * `LoginContext.staff`, how the app's staff sign in. The app makes one with `login(context)` once
+ * per public site (and once for staff), when it starts; a login that keeps tables in the database
+ * migrates them itself there, serialized and idempotent. It answers the provider's subject and
+ * what it verified; the app makes the principal from it (`visitor:<connector>:<subject>`, in
+ * `visitors`, or the declared person the identity matches), so a connector never sets groups. A
+ * visitor's address, for rate limits, is the `CLIENT_IP_HEADER` header.
  */
 export interface LoginHalf {
-  /** Who signed in, as the provider's stable subject, or null; never throws for a missing or bad cookie. */
-  verify(request: Request): Promise<{ subject: string } | null>;
+  /**
+   * Who signed in, as the provider's stable subject, with their email when the provider verified
+   * it and their GitHub login when they signed in with GitHub or linked it; null for a missing or
+   * bad cookie, for which it never throws.
+   */
+  verify(request: Request): Promise<{ subject: string; email?: string; github?: string } | null>;
   /** Answers its own routes, `/auth/<vendor>/*`; undefined for any other request. */
   handle(request: Request): Promise<Response | undefined>;
   /** The path a page POSTs to sign out, which `handle` serves; the app's own Sign out POSTs it with no body. */
   signOut?: string;
+  /** How a person may sign in now: what the sign-in page offers. */
+  methods?: readonly LoginMethod[];
+  /**
+   * A staff login's invite for `email`, a declared person's: a one-use token, good for
+   * `INVITE_SECONDS`, which replaces the last one minted for that email. `request` is the
+   * request that asked for it, on the host the invite is for.
+   */
+  invite?(email: string, request: Request): Promise<string>;
+  /**
+   * The invite a token is, while it is good: for whom, and the path (on the login's routes) that
+   * signs them in with it, using it up.
+   */
+  invitation?(token: string): Promise<{ email: string; path: string } | undefined>;
   close?(): Promise<void>;
 }
 
+/** How long an invite lasts: 24 hours. */
+export const INVITE_SECONDS = 24 * 60 * 60;
+
 /**
  * The connector with `setup` laid over what it already carries, as a connector package exports
  * it: `export const ghost = withSetup(ghostOps, { driver: ghostDriver, fake: fakeGhost, steps: ghostSteps })`. A

package/src/outline.ts

@@ -193,7 +193,7 @@ const PARAM =
   "run must take ctx as its first parameter, by one name: destructured, its calls cannot be read into the graph";
 const CTX_USE =
   "ctx is only called, directly (`await ctx.<vendor>.<resource>.<op>(…)`, `ctx.approval(…)`, `ctx.sleep(…)`, " +
-  "`ctx.all([…])`) or read for ctx.runId: passed on, aliased or destructured, its calls are not in the graph";
+  "`ctx.all([…])`) or read for ctx.runId or ctx.startedBy: passed on, aliased or destructured, its calls are not in the graph";
 const CTX_CALL = (what: string) =>
   `ctx.${what} is not a call the graph can draw: an operation is ctx.<vendor>.<resource>.<op>(…), ` +
   "and the built-ins are ctx.approval(…), ctx.sleep(…), ctx.all([…]) and ctx.now()";
@@ -237,7 +237,7 @@ interface Where {
 }
 
 /** The members of `ctx` that are read, not placed: no record, no node. */
-const READS = new Set(["now", "runId"]);
+const READS = new Set(["now", "runId", "startedBy"]);
 
 /**
  * The nodes of `fn`'s body (`run`'s, or a callback's the outline reads), each with an empty `path`
@@ -282,7 +282,7 @@ export function outlineBody(
     return uses;
   };
 
-  /** `ctx.runId`, read. */
+  /** `ctx.runId` or `ctx.startedBy`, read. */
   const isRead = (member: Node) =>
     !member.computed &&
     unwrap(member.object)?.type === "Identifier" &&

package/src/provisioning-identity.ts

@@ -0,0 +1,106 @@
+import { Compute } from "google-auth-library";
+import { enrollmentBroker } from "./identity-broker.ts";
+import type { IdentityAudit, IdentityEnrollments } from "./cloud-identity.ts";
+
+/** Fixed by the trusted provisioning issuer deployment, never by a request or company config. */
+export interface ProvisioningIdentity {
+  serviceAccount: string;
+  /** Google's immutable numeric uniqueId for the source service account. */
+  subject: string;
+  /** Exact WIF provider audience whose trust condition pins this subject. */
+  audience: string;
+}
+export interface ProvisioningIdToken {
+  idToken: string;
+  expiresAt: number;
+}
+
+const ACCOUNT = /^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/;
+const AUDIENCE =
+  /^\/\/iam\.googleapis\.com\/projects\/[1-9][0-9]+\/locations\/global\/workloadIdentityPools\/[a-z][a-z0-9-]+\/providers\/[a-z][a-z0-9-]+$/;
+const SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const fail = () => new Error("Provisioning identity unavailable");
+
+function identityOf(identity: ProvisioningIdentity): ProvisioningIdentity {
+  if (
+    !ACCOUNT.test(identity.serviceAccount) ||
+    !/^[1-9][0-9]+$/.test(identity.subject) ||
+    !AUDIENCE.test(identity.audience)
+  )
+    throw fail();
+  return { serviceAccount: identity.serviceAccount, subject: identity.subject, audience: identity.audience };
+}
+
+// The issuer calls Google's authenticated HTTPS endpoint. Check its fixed claims and expiry;
+// signature verification of the returned Google token remains Google's STS responsibility.
+function tokenExpiry(idToken: string, identity: ProvisioningIdentity, now: number): number {
+  try {
+    if (typeof idToken !== "string" || idToken.length > 8192) throw fail();
+    const parts = idToken.split(".");
+    if (parts.length !== 3 || !parts.every((part) => /^[A-Za-z0-9_-]+$/.test(part))) throw fail();
+    const claims = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf8"));
+    if (
+      claims.iss !== "https://accounts.google.com" ||
+      claims.sub !== identity.subject ||
+      claims.aud !== identity.audience ||
+      claims.email !== identity.serviceAccount ||
+      claims.email_verified !== true ||
+      !Number.isSafeInteger(claims.iat) ||
+      !Number.isSafeInteger(claims.exp) ||
+      claims.iat * 1000 > now + 30_000 ||
+      claims.exp <= claims.iat ||
+      claims.exp - claims.iat > 3600 ||
+      claims.exp * 1000 <= now + 60_000 ||
+      claims.exp * 1000 > now + 3_630_000
+    )
+      throw fail();
+    return claims.exp * 1000;
+  } catch {
+    throw fail();
+  }
+}
+
+/** Dedicated Cloud Run attached identity with getOpenIdToken on the fixed source account only. */
+export function attachedGoogleIdTokenIssuer(configuration: ProvisioningIdentity): () => Promise<ProvisioningIdToken> {
+  const identity = identityOf(configuration);
+  const auth = new Compute({ scopes: [SCOPE] });
+  return async () => {
+    try {
+      const response = await auth.request<{ token: string }>({
+        url: `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${identity.serviceAccount}:generateIdToken`,
+        method: "POST",
+        data: { audience: identity.audience, includeEmail: true },
+        timeout: 10_000,
+      });
+      const idToken = response.data.token;
+      return { idToken, expiresAt: tokenExpiry(idToken, identity, Date.now()) };
+    } catch {
+      throw fail();
+    }
+  };
+}
+
+/**
+ * GET /identity for a separate provisioning credential source. Deploy with its own enrollment
+ * reader and attached issuer, outside the runtime broker. OIDC tokens last up to one hour:
+ * revocation must remove federation/impersonation trust as well as stopping new issuance.
+ */
+export function provisioningIdentityBroker(options: {
+  identity: ProvisioningIdentity;
+  enrollments: IdentityEnrollments;
+  /** Trusted Google issuer. The request cannot select subject, audience or token lifetime. */
+  issue(): Promise<ProvisioningIdToken>;
+  audit(event: IdentityAudit): Promise<void>;
+}): (request: Request) => Promise<Response> {
+  const identity = identityOf(options.identity);
+  return enrollmentBroker({
+    path: "/identity",
+    method: "GET",
+    enrollments: options.enrollments,
+    accept: (enrollment) => enrollment.serviceAccount === identity.serviceAccount,
+    issue: () => options.issue(),
+    valid: (token, now) => token.expiresAt === tokenExpiry(token.idToken, identity, now),
+    body: (token) => ({ idToken: token.idToken, expiresAt: token.expiresAt }),
+    audit: options.audit,
+  });
+}