@sanoma-ai/workflows 0.11.6 → 0.11.11

package/src/config.ts

@@ -417,6 +417,11 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       drivers: driversByVendor,
       builtInStore: !config.secrets?.store,
       signingKeyBound: config.secrets?.bindings?.SANOMA_SIGNING_KEY !== undefined,
+      hostEnvironment: Object.fromEntries(
+        Object.entries(config.secrets?.bindings ?? {}).flatMap(([name, binding]) =>
+          binding.host && binding.env !== undefined ? [[binding.env, name]] : [],
+        ),
+      ),
       ...(isOp(config.login?.sender) && { sender: config.login.sender.vendor }),
     });
   if (types.size) {
@@ -744,6 +749,7 @@ async function readDeclared(
     drivers: ReadonlyMap<string, Driver>;
     builtInStore: boolean;
     signingKeyBound: boolean;
+    hostEnvironment: Readonly<Record<string, string>>;
     sender?: string;
   },
 ): Promise<Omit<ApplyDeclared, "rebinds">> {
@@ -765,6 +771,7 @@ async function readDeclared(
       ...(run && { secrets: run.state.secrets }),
       builtInStore: options.builtInStore,
       signingKeyBound: options.signingKeyBound,
+      hostEnvironment: options.hostEnvironment,
       ...(options.sender !== undefined && { sender: options.sender }),
       mint: !!options.mint && !!run && !run.sandbox,
     });

package/src/describe.ts

@@ -189,6 +189,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
           .map((name) => `${id}.${name}`)
           .toSorted(),
         ...(capabilities.length ? { capabilities } : {}),
+        ...(spec.host && { host: { lifetime: spec.host.capabilities.lifetime } }),
       };
     })
     .toSorted((a, b) => a.id.localeCompare(b.id));

package/src/description.ts

@@ -2,6 +2,7 @@
 // types inferred from them. zod only, no Node: a page can parse a description it is sent, and the
 // app extends `ConfigDescriptionSchema` with what it adds (`AppConfigSchema`).
 import { z } from "zod";
+import { LIFETIMES } from "./host.ts";
 import type { Outline } from "./outline.ts";
 import type { ResourceFields } from "./resource.ts";
 import { EFFECTS, FIELD_TYPES } from "./shared.ts";
@@ -322,6 +323,8 @@ export const ResourceTypeEntrySchema = z.strictObject({
   ops: z.array(z.string()),
   /** The contracts it meets (`CAPABILITIES`), in that order; absent when it meets none. */
   capabilities: z.array(z.enum(CAPABILITIES)).optional(),
+  /** For a host (`HostSpec`), how it keeps the runtime up (`HostLifetime`); absent for any other type. */
+  host: z.strictObject({ lifetime: z.enum(LIFETIMES) }).optional(),
 });
 export type ResourceTypeEntry = z.infer<typeof ResourceTypeEntrySchema>;
 

package/src/host-derive.ts

@@ -78,6 +78,8 @@ export interface HostFacts {
   unbound?: ReadonlyMap<string, readonly string[]>;
   /** True when the config binds `SANOMA_SIGNING_KEY`: the host is given that key, else its own (`HOST_SIGNING_KEY`). */
   signingKeyBound?: boolean;
+  /** Explicit environment delivery: destination variable to logical secret name, never values. */
+  hostEnvironment?: Readonly<Record<string, string>>;
   /**
    * While the config has no deploy-key type, the GitHub repositories a host may clone (`origin`'s,
    * a declared `source`'s) that GitHub shows to no one: private (or not there). One GitHub does
@@ -352,10 +354,17 @@ export function deriveHosts(
     ]);
     const carried = [...vendors].flatMap((vendor) => facts.carried.get(vendor) ?? []);
     for (const name of [...carried, ...facts.githubApp]) secrets[name] = secret(name);
+    for (const [environment, name] of Object.entries(facts.hostEnvironment ?? {})) {
+      if (Object.hasOwn(secrets, environment) && secrets[environment]!.$secret !== name)
+        problem(`${environment} has a derived host binding and cannot be replaced by ${name}`);
+      else if (!Object.hasOwn(secrets, environment))
+        Object.defineProperty(secrets, environment, { value: secret(name), enumerable: true });
+    }
     // One the driver reads here from the environment alone would be left off the host, and a
     // Worker updated without it would lose it.
     for (const vendor of vendors) {
       for (const name of facts.unbound?.get(vendor) ?? []) {
+        if (Object.hasOwn(facts.hostEnvironment ?? {}, name)) continue;
         problem(
           `${name} is read from the environment here, and has no binding, so the host would not be given it: bind it in sanoma.config.ts, \`secrets: { bindings: { ${name}: { env: "${name}" } } }\`, or store it on the ${vendor} connector page`,
         );
@@ -428,6 +437,7 @@ export async function hostFacts(options: {
   builtInStore: boolean;
   /** True when the config binds `SANOMA_SIGNING_KEY` (`{ env }` or `{ bootstrap }`). */
   signingKeyBound?: boolean;
+  hostEnvironment?: Readonly<Record<string, string>>;
   sender?: string;
   mint: boolean;
 }): Promise<HostFacts | undefined> {
@@ -484,6 +494,7 @@ export async function hostFacts(options: {
     carried,
     ...(unbound.size > 0 && { unbound }),
     ...(options.signingKeyBound && { signingKeyBound: true }),
+    ...(options.hostEnvironment && { hostEnvironment: options.hostEnvironment }),
     ...(options.sender !== undefined && { sender: options.sender }),
     githubApp,
     ...(sourceKey !== undefined && { sourceKey }),

package/src/host.ts

@@ -130,7 +130,8 @@ export const UNNAMED = "(the repository's name)";
 /** The port the runtime image's app listens on (its `PORT`): a host that derives runs it there. */
 export const RUNTIME_PORT = 3000;
 
-const LIFETIMES: readonly HostLifetime[] = ["long-lived", "stops-when-quiet"];
+/** Every `HostLifetime`, for a schema of one. */
+export const LIFETIMES = ["long-lived", "stops-when-quiet"] as const satisfies readonly HostLifetime[];
 
 /** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
 export function hasPath(schema: z.ZodType, path: string): boolean {

package/src/ledger.ts

@@ -190,6 +190,18 @@ export async function lastSignIns(
   return Object.fromEntries(last.flat());
 }
 
+/** Who minted the latest invite for `person`, and until when (ms since the epoch): from their `invite:<person>` records; undefined when none was. */
+export async function lastInvite(
+  store: LedgerStore,
+  person: string,
+): Promise<{ by: string; at: number; expiresAt: number } | undefined> {
+  const records = await store.read(`invite:${person}`);
+  const latest = records.reduce<LedgerRecord | undefined>((a, r) => (a && a.at > r.at ? a : r), undefined);
+  return latest?.type === "invite.minted"
+    ? { by: latest.by, at: latest.at, expiresAt: Date.parse(latest.expiresAt) }
+    : undefined;
+}
+
 /**
  * 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/runtime-ops.ts

@@ -6,7 +6,7 @@ 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";
+import { memoryTokens, newApiToken, type Tokens } from "./tokens.ts";
 import type { InspectRun } from "./run-status.ts";
 import {
   identityProvisioningCode,
@@ -26,11 +26,17 @@ import {
 // 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");
+const StoredSecretName = z.string().regex(SECRET_NAME, "a secret's name: upper case, A-Z, 0-9 and _");
+/** Generation destinations exclude the runtime's keys and credentials. */
+const SecretName = StoredSecretName.refine(
+  (name) => !name.startsWith("SANOMA_"),
+  "a SANOMA_ name is the runtime's own, not a workflow's to use",
+);
+/** Database exports are stored values a lifecycle workflow can retire; bootstrap keys remain protected. */
+const DeletableSecretName = StoredSecretName.refine(
+  (name) => !name.startsWith("SANOMA_") || /^SANOMA_DATABASE_URL_[A-Z0-9_]+$/.test(name),
+  "a SANOMA_ name may be deleted only when it is an exported database URL",
+);
 
 /** How long an instance gets to answer `POST /auth/invite`. */
 const INVITE_TIMEOUT_MS = 10_000;
@@ -143,8 +149,9 @@ export const sanoma = defineConnector("sanoma", {
     delete: {
       effect: "write",
       idempotent: true,
-      description: "Delete a stored secret; one not stored is nothing to do",
-      input: z.object({ name: SecretName }),
+      description:
+        "Delete a stored secret or exported database URL; one not stored is nothing to do. Runtime bootstrap secrets remain protected",
+      input: z.object({ name: DeletableSecretName }),
       output: z.object({}),
       target: ({ name }: { name: string }) => name,
       createsSecrets: ({ name }: { name: string }) => [name],
@@ -174,13 +181,23 @@ export const sanoma = defineConnector("sanoma", {
   token: {
     mint: {
       effect: "access",
+      idempotent: true,
       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"),
-      }),
+      input: z
+        .object({
+          id: z.guid().optional().describe("A recorded UUID-shaped token ID for recovery across workflow runs"),
+          reference: z
+            .string()
+            .min(1)
+            .max(1024)
+            .optional()
+            .describe("A stable non-secret provisioning reference, recorded before minting; alternative to id"),
+          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"),
+        })
+        .refine(({ id, reference }) => id === undefined || reference === undefined, "Pass id or reference, not both"),
       output: z.object({ id: z.string() }),
       target: ({ subject }: { subject: string }) => subject,
       createsSecrets: ({ store }: { store: string }) => [store],
@@ -199,9 +216,10 @@ export const sanoma = defineConnector("sanoma", {
 /** 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");
+/** Stable identity from a recorded reference, or this call's idempotency key when none was supplied. */
+function tokenIdOf(call: CallContext, reference?: string) {
+  const key = reference === undefined ? call.idempotencyKey : JSON.stringify(["sanoma.token.reference", reference]);
+  const hex = createHash("sha256").update(key).digest("hex");
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
@@ -334,27 +352,19 @@ export function runtimeDriver({
       },
     },
     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;
+      async mint({ id: requestedId, reference, subject, groups, store }, call) {
+        const id = requestedId ?? tokenIdOf(call, reference);
+        // Persist the bearer before registration. A lost store or database response can then
+        // retry the same value; no live token is created whose only copy was in this process.
+        const token = await call.secrets.ensure(store, newApiToken);
+        if (!/^sca_[A-Za-z0-9_-]{43}$/.test(token)) throw refuse(`${store} holds a value that is not an api token`);
+        let registered: boolean;
         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`);
+          registered = await tokens.register({ id, token, subject, groups });
+        } catch {
+          throw new DriverError("sanoma: token registration unavailable", { retryable: true });
         }
+        if (!registered) throw refuse(`${store} holds a token with conflicting or revoked registration`);
         return { id };
       },
       async revoke({ id }) {

package/src/secret-store.ts

@@ -79,9 +79,16 @@ export const isSecretStoreFactory = (store: SecretStore | SecretStoreFactory): s
   "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 }
-  | { bootstrap: DeploymentKeyName; management?: "external"; env?: never; path?: never };
+  | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never; host?: never }
+  | {
+      env: string;
+      /** Deliver this binding to declared deriving hosts under its environment name. */
+      host?: boolean;
+      management?: "external";
+      path?: never;
+      bootstrap?: never;
+    }
+  | { bootstrap: DeploymentKeyName; management?: "external"; env?: never; path?: never; host?: never };
 
 export interface SecretConfiguration {
   /** Omitted: built-in encrypted Postgres, supplied by the runtime. */
@@ -161,8 +168,10 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
     (!config.bindings || typeof config.bindings !== "object" || Array.isArray(config.bindings))
   )
     invalid();
+  const hostEnvironment = new Set<string>();
   for (const [name, b] of Object.entries(config.bindings ?? {})) {
     if (!namePattern.test(name) || !b || typeof b !== "object") invalid();
+    if (b.host !== undefined && (typeof b.env !== "string" || typeof b.host !== "boolean")) invalid();
     if (DEPLOYMENT_KEYS.includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
     if ("bootstrap" in b) {
       if (
@@ -180,6 +189,10 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
         (b.management !== undefined && b.management !== "external")
       )
         invalid();
+      if (b.host) {
+        if (hostEnvironment.has(b.env!)) invalid();
+        hostEnvironment.add(b.env!);
+      }
     } else if (!nonempty(b.path) || !["sanoma", "external"].includes(b.management)) invalid();
   }
 }

package/src/shared.ts

@@ -387,6 +387,9 @@ export function refusalOf(
 /** A declared resource as the people functions read it: only the runtime's people types count. */
 export type PeopleResource = Pick<DeclaredResource, "vendor" | "type" | "desired">;
 
+/** The group the runtime holds a change to the rules for, and the one that hands out invite links. */
+export const ADMIN = "admin";
+
 /** The group every agent is in, the runtime's own among them: no data file declares it. */
 export const AGENTS = "agents";
 

package/src/source.ts

@@ -322,6 +322,8 @@ export interface RemoteHalf {
   webhook?(request: Request, context: RemoteContext): Promise<RemoteEvent[]>;
   /** The accounts the company's app on the host is installed on: where it acts with no person's token. */
   owners?(context: RemoteContext): Promise<{ login: string; kind: "user" | "organization" }[]>;
+  /** The permissions the company's app on the host holds, by name (`contents: "write"`), as the host lists them; undefined without the app's keys. */
+  permissions?(context: RemoteContext): Promise<Record<string, string> | undefined>;
 }
 
 /** The remote half among `remotes` (`ResolvedConfig.remotes`) whose host `url` is on, with its vendor and the repository. */

package/src/tokens.ts

@@ -11,6 +11,22 @@ import { generateSecret, tokenHash as hashOf } from "./secret.ts";
 /** What every token starts with, so a bearer that is not one is told at a glance. */
 const PREFIX = "sca_";
 
+/** Register only a generated bearer retained by trusted provisioning, never a workflow value. */
+export interface TokenRegistration {
+  id: string;
+  token: string;
+  subject: string;
+  groups: readonly string[];
+}
+
+export const newApiToken = () => `${PREFIX}${generateSecret()}`;
+const groupsOf = (groups: readonly string[]) => [...new Set(groups)].toSorted();
+const registrationOf = (input: TokenRegistration) => {
+  if (!input.id || !input.subject || !/^sca_[A-Za-z0-9_-]{43}$/.test(input.token))
+    throw new Error("Invalid token registration");
+  return { ...input, hash: hashOf(input.token), groups: groupsOf(input.groups) };
+};
+
 /** The api tokens' store, `SanomaClient.tokens`. */
 export interface Tokens {
   /**
@@ -19,6 +35,8 @@ export interface Tokens {
    * shown only here. An id another token has is refused.
    */
   mint(token: { id?: string; subject: string; groups: readonly string[] }): Promise<{ id: string; token: string }>;
+  /** Register a saved bearer, or confirm the identical active registration. Conflicts and revocation return false. */
+  register(token: TokenRegistration): Promise<boolean>;
   /** Revokes the token `id`: it resolves to nobody from now on. Revoking one revoked or missing does nothing. */
   revoke(token: { id: string }): Promise<void>;
   /**
@@ -33,7 +51,7 @@ export interface Tokens {
 export function tokenStore(db: () => Promise<Pool>): Tokens {
   return {
     async mint({ id = randomUUID(), subject, groups }) {
-      const token = `${PREFIX}${generateSecret()}`;
+      const token = newApiToken();
       await (
         await db()
       ).query(`INSERT INTO ${TABLE} (id, hash, subject, groups) VALUES ($1, $2, $3, $4::jsonb)`, [
@@ -44,6 +62,27 @@ export function tokenStore(db: () => Promise<Pool>): Tokens {
       ]);
       return { id, token };
     },
+    async register(input) {
+      const { id, hash, subject, groups } = registrationOf(input);
+      try {
+        const result = await (
+          await db()
+        ).query(
+          `INSERT INTO ${TABLE} (id, hash, subject, groups) VALUES ($1,$2,$3,$4::jsonb)
+           ON CONFLICT (id) DO UPDATE SET id=EXCLUDED.id
+           WHERE ${TABLE}.hash=EXCLUDED.hash AND ${TABLE}.subject=EXCLUDED.subject
+             AND ${TABLE}.groups @> EXCLUDED.groups AND ${TABLE}.groups <@ EXCLUDED.groups
+             AND ${TABLE}.revoked_at IS NULL
+           RETURNING id`,
+          [id, hash, subject, JSON.stringify(groups)],
+        );
+        return result.rowCount === 1;
+      } catch (error) {
+        // A bearer already registered under another ID cannot acquire a second identity.
+        if ((error as { code?: string }).code === "23505") return false;
+        throw error;
+      }
+    },
     async revoke({ id }) {
       await (await db()).query(`UPDATE ${TABLE} SET revoked_at = now() WHERE id = $1 AND revoked_at IS NULL`, [id]);
     },
@@ -75,10 +114,24 @@ export function memoryTokens(): Tokens {
   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()}`;
+      const token = newApiToken();
       rows.set(id, { hash: hashOf(token), subject, groups: [...groups], revoked: false });
       return { id, token };
     },
+    async register(input) {
+      const { id, hash, subject, groups } = registrationOf(input);
+      const row = rows.get(id);
+      if (row)
+        return (
+          !row.revoked &&
+          row.hash === hash &&
+          row.subject === subject &&
+          JSON.stringify(groupsOf(row.groups)) === JSON.stringify(groups)
+        );
+      if ([...rows.values()].some((other) => other.hash === hash)) return false;
+      rows.set(id, { hash, subject, groups, revoked: false });
+      return true;
+    },
     async revoke({ id }) {
       const row = rows.get(id);
       if (row) row.revoked = true;