@sanoma-ai/workflows 0.10.2 → 0.10.3

package/src/runtime-ops.ts

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { keyBytes } from "./deployment-key.ts";
+import { type CallContext, defineConnector, defineDriver, DriverError, retryableStatus } from "./op.ts";
+import { generateSecret, SECRET_NAME } from "./secret.ts";
+import { sealInvite } from "./seal.ts";
+import { errorMessage } from "./shared.ts";
+import { sourceKeyPair, sshPublicKey } from "./ssh-key.ts";
+import { memoryTokens, type Tokens } from "./tokens.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
+// the policy, recorded in the ledger, and never answering a secret's value. `resolveConfig`
+// registers them in every config with their driver (`runtimeDriver`), so a policy may name them;
+// a sandbox run calls `sandboxRuntimeDriver`, over its own secrets and tokens, posting nothing.
+
+/** A secret's name, as the store takes it (upper case), other than the runtime's own (`SANOMA_…`: its keys and credentials). */
+const SecretName = z
+  .string()
+  .regex(SECRET_NAME, "a secret's name: upper case, A-Z, 0-9 and _")
+  .refine((name) => !name.startsWith("SANOMA_"), "a SANOMA_ name is the runtime's own, not a workflow's to use");
+
+/** How long an instance gets to answer `POST /auth/invite`. */
+const INVITE_TIMEOUT_MS = 10_000;
+
+/**
+ * The runtime's own operations a workflow calls: `import { sanoma } from "sanoma"`, then
+ * `uses: [sanoma.secret.generate]` and `ctx.sanoma.secret.generate({ name, kind })`.
+ */
+export const sanoma = defineConnector("sanoma", {
+  secret: {
+    generate: {
+      effect: "write",
+      // A value stored is kept: a retry answers what the first try stored.
+      idempotent: true,
+      description:
+        "Make a secret and store it under a name: a random value, or an RSA key pair whose private half (PEM) is stored and whose public half (OpenSSH) is answered. A name stored already is kept",
+      input: z.object({
+        name: SecretName,
+        kind: z.enum(["random", "ssh-rsa"]).describe("random: 32 random bytes; ssh-rsa: an RSA deploy key"),
+      }),
+      output: z.object({
+        name: z.string(),
+        publicKey: z.string().optional().describe("For ssh-rsa: the public half, `ssh-rsa <base64>`"),
+      }),
+      target: ({ name }: { name: string }) => name,
+      createsSecrets: ({ name }: { name: string }) => [name],
+    },
+    delete: {
+      effect: "write",
+      idempotent: true,
+      description: "Delete a stored secret; one not stored is nothing to do",
+      input: z.object({ name: SecretName }),
+      output: z.object({}),
+      target: ({ name }: { name: string }) => name,
+      createsSecrets: ({ name }: { name: string }) => [name],
+    },
+  },
+  invite: {
+    mint: {
+      effect: "access",
+      // Each try seals a new request (good for `sealInvite`'s few minutes), and the instance's newest
+      // invite for an email replaces the last.
+      idempotent: true,
+      description:
+        "Ask an instance for an invite link that signs a declared person in: a request sealed under the instance's signing key, named by a secret marker, posted to its /auth/invite",
+      input: z.object({
+        host: z.url({ protocol: /^https?$/ }).describe("The instance's address, such as https://acme.sanoma.work"),
+        email: z.email().describe("The email the instance's people file declares"),
+        key: z
+          .strictObject({ $secret: SecretName })
+          .describe('The instance\'s SANOMA_SIGNING_KEY, as stored here: secret("NAME")'),
+      }),
+      output: z.object({ url: z.string().describe("The one-use invite link the instance minted") }),
+      target: ({ host }: { host: string }) => host,
+      // A link that signs someone in: the ledger records that there was one, not what it was.
+      opaque: ["url"],
+    },
+  },
+  token: {
+    mint: {
+      effect: "access",
+      description:
+        "Mint an api token acting for a subject in groups, store it under a name, and answer its id (never the token)",
+      input: z.object({
+        subject: z.string().regex(/^\S+$/, "a principal's id, such as visitor:better-auth:<id>"),
+        groups: z.array(z.string().min(1)),
+        store: SecretName.describe("The secret the token is stored under"),
+      }),
+      output: z.object({ id: z.string() }),
+      target: ({ subject }: { subject: string }) => subject,
+      createsSecrets: ({ store }: { store: string }) => [store],
+    },
+    revoke: {
+      effect: "access",
+      idempotent: true,
+      description: "Revoke an api token: it resolves to nobody from now on",
+      input: z.object({ id: z.string().min(1) }),
+      output: z.object({}),
+      target: ({ id }: { id: string }) => `token:${id}`,
+    },
+  },
+});
+
+/** A `DriverError` that a retry would not change. */
+const refuse = (message: string) => new DriverError(`sanoma: ${message}`, { retryable: false });
+
+/** The token id a call mints, from its idempotency key: the same on every try of one call, so a retry finds its own. */
+function tokenIdOf(call: CallContext) {
+  const hex = createHash("sha256").update(call.idempotencyKey).digest("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/** The 32 bytes of a signing key stored as text (base64, or base64url as `generate` makes one), or a refusal. */
+function signingKeyOf(secret: string, text: string | undefined): Buffer {
+  if (text === undefined) throw refuse(`the secret ${secret} is not set: store the instance's signing key under it`);
+  const key = keyBytes(text);
+  if (!key) throw refuse(`${secret} is not a signing key: 32 bytes in base64`);
+  return key;
+}
+
+/**
+ * Posts the sealed `request` to the instance's `/auth/invite`, and answers the link it minted
+ * (`sanoma.invite.mint`, and going live's sign-in); a `DriverError` otherwise, retryable by status.
+ */
+export async function postInvite(host: string, request: string): Promise<{ url: string }> {
+  const at = new URL("/auth/invite", host);
+  let res: Response;
+  try {
+    res = await fetch(at, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ request }),
+      // A redirect is answered as it is (a 3xx, not retried): the sealed request goes to `host` alone.
+      redirect: "manual",
+      signal: AbortSignal.timeout(INVITE_TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new DriverError(`sanoma: ${at.host} could not be reached: ${errorMessage(err)}`, {
+      retryable: true,
+      cause: err,
+    });
+  }
+  const body = (await res.json().catch(() => undefined)) as { url?: unknown; error?: unknown } | undefined;
+  if (res.ok && typeof body?.url === "string") return { url: body.url };
+  const why = typeof body?.error === "string" ? `: ${body.error}` : res.ok ? ": no url" : "";
+  throw new DriverError(`sanoma: ${at.host} answered ${res.status} to POST /auth/invite${why}`, {
+    retryable: !res.ok && retryableStatus(res.status),
+    status: res.status,
+  });
+}
+
+/**
+ * The driver of the runtime's own operations, over the call's secrets and `tokens` (the config's
+ * database's, `tokenStore`); `invite` posts a sealed request to an instance (`postInvite` by default).
+ */
+export function runtimeDriver({
+  tokens,
+  invite = postInvite,
+}: {
+  tokens: Tokens;
+  invite?: (host: string, request: string, call: CallContext) => Promise<{ url: string }>;
+}) {
+  return defineDriver(sanoma, {
+    secret: {
+      async generate({ name, kind }, call) {
+        if (kind === "random") {
+          await call.secrets.ensure(name, generateSecret);
+          return { name };
+        }
+        // A pair made only when none is stored: the public half is always derived from what is.
+        let stored = await call.secrets.get(name);
+        if (stored === undefined) {
+          const pair = await sourceKeyPair();
+          stored = await call.secrets.ensure(name, () => pair.privateKey);
+        }
+        const publicKey = sshPublicKey(stored);
+        if (!publicKey)
+          throw refuse(`${name} holds a value that is not an RSA private key: delete it, or name another`);
+        return { name, publicKey };
+      },
+      async delete({ name }, call) {
+        await call.secrets.delete(name);
+        return {};
+      },
+    },
+    invite: {
+      async mint({ host, email, key }, call) {
+        const signingKey = signingKeyOf(key.$secret, await call.secrets.get(key.$secret));
+        const request = sealInvite({ email }, signingKey);
+        return invite(host, request, call);
+      },
+    },
+    token: {
+      async mint({ subject, groups, store }, call) {
+        const id = tokenIdOf(call);
+        const held = await call.secrets.get(store);
+        if (held !== undefined) {
+          // This call's own, stored by a try whose answer was lost.
+          if ((await tokens.resolve(held))?.principal.id === `token:${id}`) return { id };
+          throw refuse(`${store} holds a value already: delete it, or store the token under another name`);
+        }
+        let token: string;
+        try {
+          ({ token } = await tokens.mint({ id, subject, groups }));
+        } catch (err) {
+          // A try that minted this id and stopped before storing it left a token nobody holds: revoked here.
+          if ((await tokens.subjectOf(id)) === undefined) throw err;
+          await tokens.revoke({ id });
+          throw refuse(`an earlier try minted token ${id} and stopped before storing it: it is revoked, start again`);
+        }
+        if ((await call.secrets.ensure(store, () => token)) !== token) {
+          await tokens.revoke({ id });
+          throw refuse(`${store} was stored by someone else meanwhile: the token minted is revoked`);
+        }
+        return { id };
+      },
+      async revoke({ id }) {
+        await tokens.revoke({ id });
+        return {};
+      },
+    },
+  });
+}
+
+/**
+ * The runtime's own operations for one sandbox run: the run's secrets (in memory), tokens in
+ * memory, and an invite that posts nothing, answering a link on the host named.
+ */
+export const sandboxRuntimeDriver = () =>
+  runtimeDriver({
+    tokens: memoryTokens(),
+    invite: async (host, _request, call) => ({ url: new URL(`/auth/invite/sandbox-${tokenIdOf(call)}`, host).href }),
+  });

package/src/seal.ts

@@ -0,0 +1,95 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { deriveSigningKey, signingKeyFor } from "./deployment-key.ts";
+
+// Small values sealed under a key of their own, derived from the deployment's SANOMA_SIGNING_KEY
+// for one purpose (HKDF-SHA256): a sign-in code in a `login-code` run's input, and a request for
+// an invite that a holder of the key sends to the instance (`POST /auth/invite`). AES-256-GCM, the
+// purpose as its additional data, so a value sealed for one purpose never opens for another.
+
+const IV = 12;
+const TAG = 16;
+
+/** The key for `purpose`: derived from `signingKey`, a deployment's signing key, else from this process's own. */
+const keyFor = (purpose: string, signingKey?: Buffer) =>
+  signingKey ? deriveSigningKey(signingKey, purpose) : signingKeyFor(purpose);
+
+/**
+ * `value` as JSON, sealed for `purpose` under `signingKey` (this process's own by default): base64url
+ * of the IV, the tag and the ciphertext.
+ */
+function seal(purpose: string, value: unknown, signingKey?: Buffer): string {
+  const iv = randomBytes(IV);
+  const cipher = createCipheriv("aes-256-gcm", keyFor(purpose, signingKey), iv).setAAD(Buffer.from(purpose));
+  const text = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), text]).toString("base64url");
+}
+
+/** What `seal(purpose, …)` sealed, or undefined for anything else: another key, another purpose, a change. */
+function unseal(purpose: string, sealed: string): unknown {
+  const bytes = Buffer.from(sealed, "base64url");
+  if (bytes.length <= IV + TAG) return undefined;
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", keyFor(purpose), bytes.subarray(0, IV))
+      .setAAD(Buffer.from(purpose))
+      .setAuthTag(bytes.subarray(IV, IV + TAG));
+    const text = Buffer.concat([decipher.update(bytes.subarray(IV + TAG)), decipher.final()]);
+    return JSON.parse(text.toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+const CODE = "login code";
+const INVITE = "invite request";
+
+/**
+ * A sign-in code sealed with the email it is for, for a `login-code` run's input, so the run's
+ * input never shows it and a copy of it opens for no one else.
+ */
+export const sealLoginCode = (to: string, code: string): string => seal(CODE, { to, code });
+
+/** The code `sealLoginCode` sealed for `to`; throws for anything else, a code sealed for another email among it. */
+export function openLoginCode(sealed: string, to: string): string {
+  const opened = unseal(CODE, sealed) as { to?: unknown; code?: unknown } | undefined;
+  if (typeof opened?.code !== "string" || opened.to !== to) {
+    throw new Error(`The sign-in code is not one this deployment sealed for ${to}`);
+  }
+  return opened.code;
+}
+
+/** A request for an invite (`POST /auth/invite { request }`): for whom, until when (ms since the epoch), and a nonce. */
+export interface InviteRequest {
+  email: string;
+  exp: number;
+  nonce: string;
+}
+
+/** How long a sealed invite request is good for when `exp` is not given: five minutes. */
+const INVITE_REQUEST_MS = 5 * 60_000;
+
+/**
+ * A request for `email`'s invite, sealed under a key derived from `SANOMA_SIGNING_KEY` (purpose
+ * `invite request`), or from `signingKey`, another deployment's signing key (its 32 bytes): what
+ * a holder of the deployment's signing key sends the instance as `POST /auth/invite { request }`
+ * (going live, and Sanoma Cloud's birth invite, `sanoma.invite.mint`). `exp` defaults to five
+ * minutes from now, `nonce` to 16 random bytes.
+ */
+export function sealInvite(
+  { email, exp, nonce }: { email: string; exp?: number; nonce?: string },
+  signingKey?: Buffer,
+): string {
+  const request = {
+    email,
+    exp: exp ?? Date.now() + INVITE_REQUEST_MS,
+    nonce: nonce ?? randomBytes(16).toString("base64url"),
+  } satisfies InviteRequest;
+  return seal(INVITE, request, signingKey);
+}
+
+/** The request `sealInvite` sealed, while `exp` is after `now`; undefined for anything else, or once it expired. */
+export function openInvite(sealed: string, now = Date.now()): InviteRequest | undefined {
+  const request = unseal(INVITE, sealed) as Partial<InviteRequest> | undefined;
+  if (typeof request?.email !== "string" || typeof request.exp !== "number" || typeof request.nonce !== "string")
+    return undefined;
+  return request.exp > now ? (request as InviteRequest) : undefined;
+}

package/src/secret-store.ts

@@ -1,4 +1,4 @@
-import { deploymentKey } from "./deployment-key.ts";
+import { DEPLOYMENT_KEYS, type DeploymentKeyName, deploymentKey } from "./deployment-key.ts";
 /** Opaque values belong only in trusted runtime code, never workflow history or descriptions. */
 export interface SecretValue {
   value: string;
@@ -65,7 +65,7 @@ export interface SecretStore {
 export type SecretBinding =
   | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never }
   | { env: string; management?: "external"; path?: never; bootstrap?: never }
-  | { bootstrap: "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY"; management?: "external"; env?: never; path?: never };
+  | { bootstrap: DeploymentKeyName; management?: "external"; env?: never; path?: never };
 
 export interface SecretConfiguration {
   /** Omitted: built-in encrypted Postgres, supplied by the runtime. */
@@ -145,10 +145,10 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
     invalid();
   for (const [name, b] of Object.entries(config.bindings ?? {})) {
     if (!namePattern.test(name) || !b || typeof b !== "object") invalid();
-    if (["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
+    if (DEPLOYMENT_KEYS.includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
     if ("bootstrap" in b) {
       if (
-        !["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(b.bootstrap!) ||
+        !DEPLOYMENT_KEYS.includes(b.bootstrap!) ||
         b.path !== undefined ||
         b.env !== undefined ||
         (b.management !== undefined && b.management !== "external")
@@ -194,8 +194,7 @@ export class SecretAccess {
     const binding = Object.hasOwn(this.bindings, name) ? this.bindings[name] : undefined;
     if (binding?.bootstrap !== undefined)
       return { store: "bootstrap", namespace: "", path: binding.bootstrap, management: "external" };
-    if (["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(name) && !binding)
-      throw new SecretStoreError("invalid_configuration");
+    if (DEPLOYMENT_KEYS.includes(name) && !binding) throw new SecretStoreError("invalid_configuration");
     if (binding?.env !== undefined)
       return { store: "environment", namespace: "", path: binding.env, management: "external" };
     return {
@@ -213,7 +212,7 @@ export class SecretAccess {
   async read(name: string): Promise<SecretValue | undefined> {
     const location = this.location(name);
     if (location.store === "bootstrap" && location.namespace === "") {
-      const value = deploymentKey(location.path as "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY").toString("base64");
+      const value = deploymentKey(location.path as DeploymentKeyName).toString("base64");
       return { value, version: "bootstrap" };
     }
     if (location.store === "environment" && location.namespace === "") {
@@ -238,10 +237,14 @@ export class SecretAccess {
     return secretStoreCall(() => this.store.write(location, value, options));
   }
 
-  async delete(name: string, options: { expectedVersion: string; by: string }): Promise<void> {
+  /** Deletes the value at `expectedVersion`; without one, the value stored now, and none stored is nothing to do. */
+  async delete(name: string, options: { expectedVersion?: string; by?: string } = {}): Promise<void> {
     const location = this.writable(name);
     if (this.store.capabilities.deletion === "unsupported") throw new SecretStoreError("unsupported");
-    await secretStoreCall(() => this.store.delete(location, options));
+    const expectedVersion = options.expectedVersion ?? (await this.read(name))?.version;
+    if (expectedVersion === undefined) return;
+    const by = options.by ?? "sanoma";
+    await secretStoreCall(() => this.store.delete(location, { expectedVersion, by }));
   }
 
   async ensure(name: string, make: () => string): Promise<string> {

package/src/secret.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { DriverError } from "./op.ts";
 
 // Secrets are named, never written: `secret("NAME")` in a data file is a marker for a value in
@@ -44,6 +44,8 @@ export interface Secrets {
   get(name: string): Promise<string | undefined>;
   /** The stored value; when there is none, `make()`'s, stored first. */
   ensure(name: string, make: () => string): Promise<string>;
+  /** Deletes the stored value; none stored is nothing to do. The runtime's own `sanoma.secret.delete` calls it. */
+  delete(name: string): Promise<void>;
 }
 
 /** A named call can resolve only the auxiliary secret markers present in its authorized input. */
@@ -72,12 +74,22 @@ export function secretsForInput(input: unknown, secrets: Secrets, creates: reado
       check(name, true);
       return secrets.ensure(name, make);
     },
+    async delete(name) {
+      check(name, true);
+      return secrets.delete(name);
+    },
   };
 }
 
 /** A value for a secret with `generate`: 32 random bytes, base64url. */
 export const generateSecret = (): string => randomBytes(32).toString("base64url");
 
+/**
+ * A bearer token's sha256, hex: all a table keeps of one (the wakeup service's, the api tokens). A
+ * token is found by its hash (a unique index), so the secret itself is never compared.
+ */
+export const tokenHash = (token: string): string => createHash("sha256").update(token).digest("hex");
+
 /** `T` with each secret marker's place holding its value: what `resolveSecrets` returns. */
 export type Resolved<T> = T extends Secret
   ? string
@@ -117,5 +129,8 @@ export function memorySecrets(initial: Record<string, string> = {}): Secrets {
       if (!values.has(name)) values.set(name, make());
       return values.get(name)!;
     },
+    async delete(name) {
+      values.delete(name);
+    },
   };
 }

package/src/shared.ts

@@ -285,12 +285,20 @@ export const CHANGE_TOPIC = "change:event";
 /** Lists the apps on GitHub with Sanoma's claims: the one runtime operation a page may call (`isDirect`). */
 export const APPS_LIST = "sanoma.apps.list";
 
-/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call and change. */
+/**
+ * The built-in workflow that sends a staff or visitor sign-in code through the config's
+ * `login.sender`, started by the runtime's agent `login` (`LOGIN_AGENT`): its input's code is
+ * sealed, and the mail's body is recorded as `<text>` and `<html>`.
+ */
+export const LOGIN_CODE_WORKFLOW = "login-code";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call, change and login-code. */
 export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([
   DRIFT_WORKFLOW,
   APPLY_WORKFLOW,
   CALL_WORKFLOW,
   CHANGE_WORKFLOW,
+  LOGIN_CODE_WORKFLOW,
 ]);
 
 /**
@@ -361,14 +369,22 @@ export const VISITORS = "visitors";
 /** The principal a public page runs as when nobody is signed in: no groups. */
 export const ANONYMOUS = "anonymous";
 
-/** `visitor:<login connector's vendor>:<provider subject>`: the only form a visitor's id takes. */
+/** `visitor:<login connector's vendor>:<provider subject>`: the form a signed-in visitor's id takes. */
 const VISITOR_ID = /^visitor:[^\s:]+:\S+$/;
 
+/** `token:<id>`: a caller of a public site's api with a token (`SanomaClient.tokens`), a visitor too. */
+const TOKEN_ID = /^token:\S+$/;
+
 /**
- * True for `anonymous` and for a visitor's id: a principal no data file declares and the staff
- * logins never admit. Marked by the id alone, since a principal crosses to the worker as JSON.
+ * True for `anonymous`, a visitor's id and a token's (`token:<id>`): a principal no data file
+ * declares and the staff logins never admit. Marked by the id alone, since a principal crosses to
+ * the worker as JSON.
  */
-export const isVisitor = (p: Pick<Principal, "id">): boolean => p.id === ANONYMOUS || VISITOR_ID.test(p.id);
+export const isVisitor = (p: Pick<Principal, "id">): boolean =>
+  p.id === ANONYMOUS || VISITOR_ID.test(p.id) || isToken(p);
+
+/** True for an api token's principal (`token:<id>`), whose groups are its row's. */
+export const isToken = (p: Pick<Principal, "id">): boolean => TOKEN_ID.test(p.id);
 
 /**
  * The visitor a public site's login vouches for: `subject` from the provider behind the `login`
@@ -389,8 +405,16 @@ export const WAKEUP_AGENT = "wakeup";
 export const SCHEDULE_AGENT = "schedule";
 /** The runtime's agent that checks and deploys the hosts: drift's, and apply's after a push to `main` (`SanomaClient.remoteEvent`). */
 export const HOST_CHECK_AGENT = "host-check";
-/** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration), declared whether a data file names them or not. */
-export const RUNTIME_AGENTS: readonly string[] = ["scenarios", HOST_CHECK_AGENT, SCHEDULE_AGENT, WAKEUP_AGENT];
+/** The runtime's agent that sends a sign-in code (`LOGIN_CODE_WORKFLOW`): a company's policy exempts it from its holds on sending. */
+export const LOGIN_AGENT = "login";
+/** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration, sign-in codes), declared whether a data file names them or not. */
+export const RUNTIME_AGENTS: readonly string[] = [
+  "scenarios",
+  HOST_CHECK_AGENT,
+  SCHEDULE_AGENT,
+  WAKEUP_AGENT,
+  LOGIN_AGENT,
+];
 
 /** The declared resources of one of the runtime's people types, by `desired`. */
 const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>

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;
+    },
+  };
+}