@wtfalch/foundry 0.5.0 → 0.6.0

package/dist/plan/mail-copy.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Copies an org's old mail into Stalwart before its `received` -> `hosted`
+ * MX cutover (#113), using `@wtfalch/email/postmaster`'s `mailCopyPlan` to
+ * build the exact Vandelay `import`/`export` commands and nothing more --
+ * this module decides when to run them and what to do with the result, the
+ * same split `calls-sfu.ts` draws between a pure plan builder and the apply
+ * logic around it.
+ *
+ * Three things this step needs and never invents itself, mirroring
+ * `plan/platform-sfu.ts`'s own "a host supplies real clients" rule:
+ *
+ * - {@link MailCopyPort.resolveAccounts}: which accounts to copy, and where
+ *   each one's mail lands in Stalwart. Foundry tracks only an org's owner
+ *   mailbox (`org.mail.ownerMailboxAddress`) -- it has no roster of every
+ *   mailbox a Google Workspace or Microsoft 365 tenant holds, so the full
+ *   list is a fact a human supplies, read back here exactly the way a held
+ *   SSH key or API credential already is elsewhere in this package.
+ * - {@link MailCopyPort.resolveSourceToken}: the org's own admin bearer
+ *   token for its old provider, a per-org held key (#113 "Decided",
+ *   2026-09-30) -- never an environment variable this package sets itself.
+ * - {@link MailCopyPort.resolveStalwartToken}: the platform's own Stalwart
+ *   export credential (the admin key `impersonate` already covers,
+ *   `plan/platform-providers.ts`'s `provisionPlatformMail`), read back by
+ *   the host rather than minted again here.
+ *
+ * {@link MailCopyPort.run} is the fourth port: running one Vandelay command
+ * to completion in a one-off container (#113 "Decided": Coolify) and
+ * reporting how it went. Never throws on a non-zero exit -- the caller
+ * checks `exitCode`, the same "write a file, run a command, the caller
+ * checks it" shape `CallsSfuHostPort.exec` already uses, for the same
+ * reason: every value a real implementation might echo into stdout/stderr
+ * is the host's to redact, never this function's problem.
+ *
+ * **No new step type.** #113's first decision (2026-09-30) asked for a
+ * resumable step type of its own; the second (2026-10-01) replaced it with
+ * "keep foundry's one step contract": this step runs once per `apply`, the
+ * same as every other, and resumes only because `runMailCopyStep` is
+ * idempotent -- skip an account already recorded done, stop at the first
+ * one that fails this round, and let the *planner* (`plan/diff.ts`'s
+ * `planMailCopy`) decide whether to show the step again next time. "Rely on
+ * Vandelay's own rate limit for the Gmail daily cap" (#113 "Decided") means
+ * this function never inspects *why* an account failed -- a provider's
+ * daily transfer cap and a real failure look the same from here, so it
+ * always just stops and lets the next apply retry, rather than guessing.
+ */
+import type { MailCopyAccount, MailCopyProvider } from '@wtfalch/email/postmaster';
+import type { DeclaredOrg } from '../org.js';
+/** Scope id: a JSON array of account `source` addresses already fully copied for this org. Read by `plan/diff.ts`'s `planMailCopy` to report progress, and by `executor.ts`'s `mailCopy` to skip a finished account on the next apply. */
+export declare const MAIL_COPY_COMPLETED_SCOPE_KEY = "mail_copy_completed_accounts";
+/** Scope id: set to `'1'` once every account in the resolved plan has copied cleanly. `plan/diff.ts`'s `planMail` gates the `received` -> `hosted` mode flip on this being set. */
+export declare const MAIL_COPY_DONE_SCOPE_KEY = "mail_copy_done";
+/**
+ * Parses {@link MAIL_COPY_COMPLETED_SCOPE_KEY}'s recorded value back into
+ * the set of account addresses already copied. `[]` for anything that is
+ * not a JSON array of strings -- absent, corrupt, or a shape from before
+ * this existed -- the same "a malformed record reads as unapplied, never
+ * throws" rule `platform-diff.ts`'s `parseBrokerDeployRecord` already
+ * follows, and for the same reason: this is a planning read, not a
+ * validation boundary.
+ */
+export declare function parseMailCopyCompleted(raw: string | undefined): string[];
+/**
+ * Everything {@link mailCopyPlan} needs beyond the provider: the resolved
+ * account list and their Vandelay target mapping, the Stalwart JMAP base
+ * URL, and the archive directory the one-off container keeps its Vandelay
+ * SQLite archives in between runs (the host's own choice -- it also
+ * implements {@link MailCopyPort.run}, so it alone knows where that
+ * container's persistent storage is mounted).
+ */
+export interface MailCopyJob {
+    readonly provider: MailCopyProvider;
+    readonly accounts: readonly MailCopyAccount[];
+    readonly stalwartUrl: string;
+    readonly archiveDir: string;
+}
+export interface MailCopyPort {
+    /** `null` until a human has declared this org's accounts (#113's own "Decide" is silent on how; this package never guesses a roster). */
+    resolveAccounts(org: DeclaredOrg): Promise<MailCopyJob | null>;
+    /** `null` until a human has stored this org's admin token as a held key. */
+    resolveSourceToken(org: DeclaredOrg): Promise<string | null>;
+    /** `null` until the platform's own Stalwart export credential is held. */
+    resolveStalwartToken(): Promise<string | null>;
+    /** Runs one Vandelay command (`accountPlan.importArgv`/`exportArgv`) to completion, `VANDELAY_TOKEN` set to `token` for that one launch. */
+    run(argv: readonly string[], token: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class MissingMailCopyAccountsError extends Error {
+    constructor(orgSlug: string);
+}
+export declare class MissingMailCopySourceTokenError extends Error {
+    constructor(orgSlug: string);
+}
+export declare class MissingMailCopyStalwartTokenError extends Error {
+    constructor(orgSlug: string);
+}
+export interface MailCopyStepResult {
+    /** Every account copied so far, this apply's newly-finished ones included -- what the executor records under {@link MAIL_COPY_COMPLETED_SCOPE_KEY}. */
+    readonly completed: readonly string[];
+    /** `true` once the job names at least one account and every one of them has copied cleanly. */
+    readonly done: boolean;
+    /** Why this apply stopped early, absent when nothing failed. */
+    readonly failure?: MailCopyFailure;
+}
+/** The account and phase a copy stopped at, and what Vandelay said -- never a token. */
+export interface MailCopyFailure {
+    readonly account: string;
+    readonly phase: 'import' | 'export';
+    /** Absent when `port.run` threw instead of returning an exit code. */
+    readonly exitCode?: number;
+    /** The last {@link STDERR_TAIL_LENGTH} characters of stderr (or the thrown error's message), with both tokens replaced. */
+    readonly detail: string;
+}
+/**
+ * Runs this apply's share of one org's mail copy: resolve the job and its
+ * credentials, skip whatever {@link alreadyCompleted} already names, then
+ * import and export each remaining account in turn, stopping at the first
+ * one that fails (import or export) rather than guessing whether that is a
+ * provider's daily cap or a real problem. Never throws for a Vandelay
+ * failure -- only for a missing port answer, which is a configuration gap,
+ * not something a retry fixes on its own.
+ */
+export declare function runMailCopyStep(org: DeclaredOrg, port: MailCopyPort, alreadyCompleted: ReadonlySet<string>): Promise<MailCopyStepResult>;

package/dist/plan/mail-copy.js

@@ -0,0 +1,166 @@
+/**
+ * Copies an org's old mail into Stalwart before its `received` -> `hosted`
+ * MX cutover (#113), using `@wtfalch/email/postmaster`'s `mailCopyPlan` to
+ * build the exact Vandelay `import`/`export` commands and nothing more --
+ * this module decides when to run them and what to do with the result, the
+ * same split `calls-sfu.ts` draws between a pure plan builder and the apply
+ * logic around it.
+ *
+ * Three things this step needs and never invents itself, mirroring
+ * `plan/platform-sfu.ts`'s own "a host supplies real clients" rule:
+ *
+ * - {@link MailCopyPort.resolveAccounts}: which accounts to copy, and where
+ *   each one's mail lands in Stalwart. Foundry tracks only an org's owner
+ *   mailbox (`org.mail.ownerMailboxAddress`) -- it has no roster of every
+ *   mailbox a Google Workspace or Microsoft 365 tenant holds, so the full
+ *   list is a fact a human supplies, read back here exactly the way a held
+ *   SSH key or API credential already is elsewhere in this package.
+ * - {@link MailCopyPort.resolveSourceToken}: the org's own admin bearer
+ *   token for its old provider, a per-org held key (#113 "Decided",
+ *   2026-09-30) -- never an environment variable this package sets itself.
+ * - {@link MailCopyPort.resolveStalwartToken}: the platform's own Stalwart
+ *   export credential (the admin key `impersonate` already covers,
+ *   `plan/platform-providers.ts`'s `provisionPlatformMail`), read back by
+ *   the host rather than minted again here.
+ *
+ * {@link MailCopyPort.run} is the fourth port: running one Vandelay command
+ * to completion in a one-off container (#113 "Decided": Coolify) and
+ * reporting how it went. Never throws on a non-zero exit -- the caller
+ * checks `exitCode`, the same "write a file, run a command, the caller
+ * checks it" shape `CallsSfuHostPort.exec` already uses, for the same
+ * reason: every value a real implementation might echo into stdout/stderr
+ * is the host's to redact, never this function's problem.
+ *
+ * **No new step type.** #113's first decision (2026-09-30) asked for a
+ * resumable step type of its own; the second (2026-10-01) replaced it with
+ * "keep foundry's one step contract": this step runs once per `apply`, the
+ * same as every other, and resumes only because `runMailCopyStep` is
+ * idempotent -- skip an account already recorded done, stop at the first
+ * one that fails this round, and let the *planner* (`plan/diff.ts`'s
+ * `planMailCopy`) decide whether to show the step again next time. "Rely on
+ * Vandelay's own rate limit for the Gmail daily cap" (#113 "Decided") means
+ * this function never inspects *why* an account failed -- a provider's
+ * daily transfer cap and a real failure look the same from here, so it
+ * always just stops and lets the next apply retry, rather than guessing.
+ */
+import { mailCopyPlan } from '@wtfalch/email/postmaster';
+/** Scope id: a JSON array of account `source` addresses already fully copied for this org. Read by `plan/diff.ts`'s `planMailCopy` to report progress, and by `executor.ts`'s `mailCopy` to skip a finished account on the next apply. */
+export const MAIL_COPY_COMPLETED_SCOPE_KEY = 'mail_copy_completed_accounts';
+/** Scope id: set to `'1'` once every account in the resolved plan has copied cleanly. `plan/diff.ts`'s `planMail` gates the `received` -> `hosted` mode flip on this being set. */
+export const MAIL_COPY_DONE_SCOPE_KEY = 'mail_copy_done';
+/**
+ * Parses {@link MAIL_COPY_COMPLETED_SCOPE_KEY}'s recorded value back into
+ * the set of account addresses already copied. `[]` for anything that is
+ * not a JSON array of strings -- absent, corrupt, or a shape from before
+ * this existed -- the same "a malformed record reads as unapplied, never
+ * throws" rule `platform-diff.ts`'s `parseBrokerDeployRecord` already
+ * follows, and for the same reason: this is a planning read, not a
+ * validation boundary.
+ */
+export function parseMailCopyCompleted(raw) {
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed) || !parsed.every((v) => typeof v === 'string'))
+        return [];
+    return parsed;
+}
+export class MissingMailCopyAccountsError extends Error {
+    constructor(orgSlug) {
+        super(`coolify:mail-copy for ${orgSlug}: no accounts are declared for this org's mail copy yet (#113)`);
+        this.name = 'MissingMailCopyAccountsError';
+    }
+}
+export class MissingMailCopySourceTokenError extends Error {
+    constructor(orgSlug) {
+        super(`coolify:mail-copy for ${orgSlug}: no admin token is held for this org's old mail provider yet (#113 "Decided", 2026-09-30)`);
+        this.name = 'MissingMailCopySourceTokenError';
+    }
+}
+export class MissingMailCopyStalwartTokenError extends Error {
+    constructor(orgSlug) {
+        super(`coolify:mail-copy for ${orgSlug}: no Stalwart export credential is held yet`);
+        this.name = 'MissingMailCopyStalwartTokenError';
+    }
+}
+const STDERR_TAIL_LENGTH = 500;
+/** Replaces every occurrence of each token, then keeps the tail: a real implementation may echo `VANDELAY_TOKEN` into stderr, and this must not carry it into a message. */
+function redactTail(text, tokens) {
+    let out = text;
+    for (const token of tokens)
+        out = out.split(token).join('[redacted]');
+    return out.slice(-STDERR_TAIL_LENGTH);
+}
+/**
+ * Runs this apply's share of one org's mail copy: resolve the job and its
+ * credentials, skip whatever {@link alreadyCompleted} already names, then
+ * import and export each remaining account in turn, stopping at the first
+ * one that fails (import or export) rather than guessing whether that is a
+ * provider's daily cap or a real problem. Never throws for a Vandelay
+ * failure -- only for a missing port answer, which is a configuration gap,
+ * not something a retry fixes on its own.
+ */
+export async function runMailCopyStep(org, port, alreadyCompleted) {
+    const job = await port.resolveAccounts(org);
+    if (!job)
+        throw new MissingMailCopyAccountsError(org.slug);
+    const sourceToken = await port.resolveSourceToken(org);
+    if (!sourceToken)
+        throw new MissingMailCopySourceTokenError(org.slug);
+    const stalwartToken = await port.resolveStalwartToken();
+    if (!stalwartToken)
+        throw new MissingMailCopyStalwartTokenError(org.slug);
+    const plan = mailCopyPlan({
+        provider: job.provider,
+        accounts: job.accounts,
+        stalwartUrl: job.stalwartUrl,
+        archiveDir: job.archiveDir,
+    });
+    const tokens = [sourceToken, stalwartToken];
+    const completed = new Set(alreadyCompleted);
+    let failure;
+    for (const accountPlan of plan.accounts) {
+        if (completed.has(accountPlan.source))
+            continue;
+        const phases = [
+            { phase: 'import', argv: accountPlan.importArgv, token: sourceToken },
+            { phase: 'export', argv: accountPlan.exportArgv, token: stalwartToken },
+        ];
+        for (const { phase, argv, token } of phases) {
+            try {
+                const ran = await port.run(argv, token);
+                if (ran.exitCode !== 0) {
+                    failure = {
+                        account: accountPlan.source,
+                        phase,
+                        exitCode: ran.exitCode,
+                        detail: redactTail(ran.stderr, tokens),
+                    };
+                }
+            }
+            catch (error) {
+                // A thrown run is a failed run: stop here, but keep what this apply finished.
+                failure = {
+                    account: accountPlan.source,
+                    phase,
+                    detail: redactTail(error instanceof Error ? error.message : String(error), tokens),
+                };
+            }
+            if (failure)
+                break;
+        }
+        if (failure)
+            break;
+        completed.add(accountPlan.source);
+    }
+    // `completed` may still hold a stale address no longer in the plan, so
+    // done is checked against the plan's own accounts, never `completed.size`.
+    const done = plan.accounts.length > 0 && plan.accounts.every((account) => completed.has(account.source));
+    return { completed: [...completed], done, ...(failure ? { failure } : {}) };
+}

package/dist/plan/mail-identity-allowlist.d.ts

@@ -0,0 +1,50 @@
+/**
+ * #34: a matching `requireAudience` value says nothing about *who* carries
+ * it.
+ *
+ * ZITADEL puts a project's own id into the default audience of any sign-in
+ * to that project, so every JWT app in the org's audience project mints a
+ * token Stalwart's OIDC directory accepts, whether or not that app has
+ * anything to do with mail. Two real instances were found by hand rather
+ * than by any check: `manage` shared the audience project and its sign-in
+ * tokens opened the signed-in person's mailbox until it moved to its own
+ * project (wtfalch/agora#100); `operator` was added to the same project
+ * later and has the same hole today (wtfalch/operator#11).
+ *
+ * {@link checkMailAppsAllowlist} faults on every JWT app in the audience
+ * project that is not on the org's own declared allow-list, naming the app
+ * and its client id -- the same way `org.ts`'s validators name the value
+ * they refuse. Decided by William (2026-09-30): only listed apps may read
+ * a person's mail; each org's declared config holds its own list
+ * ({@link MailConfig.mailApps} in `../org.js`, defaulting to
+ * {@link DEFAULT_MAIL_APPS} when the org declares none of its own).
+ *
+ * An exported pure function, the same "host calls it" shape #33's
+ * `checkMailIdentityAudience` (`./mail-identity.js`) takes. This module
+ * declares its own narrow app shape rather than importing that one's, so
+ * the two land independently of each other -- a host composing both checks
+ * adapts the same live app list to each. Deliberately silent on
+ * opaque-token apps: #33's check already names those on its own, and an
+ * app this function cannot classify is reported separately rather than
+ * folded into either list.
+ */
+export interface MailAllowlistApp {
+    /** ZITADEL's own app id. */
+    id: string;
+    /** The OIDC client id ZITADEL issued -- what a fault names, never a secret. */
+    clientId: string;
+    name: string;
+    /**
+     * How ZITADEL mints this app's access token. `undefined` means unknown
+     * (an `api` app, or a caller that cannot yet tell) and is never treated
+     * as `'jwt'` -- an app this function cannot classify as a JWT app is
+     * never faulted as an unlisted one.
+     */
+    accessTokenType?: 'jwt' | 'opaque';
+}
+/**
+ * Faults on every JWT app in `apps` that is not on `declaredMailApps`,
+ * naming the app and its client id. Empty means every JWT app the audience
+ * project holds is on the list (or there are no JWT apps at all).
+ */
+export declare function checkMailAppsAllowlist(apps: readonly MailAllowlistApp[], declaredMailApps: readonly string[]): string[];

package/dist/plan/mail-identity-allowlist.js

@@ -0,0 +1,11 @@
+/**
+ * Faults on every JWT app in `apps` that is not on `declaredMailApps`,
+ * naming the app and its client id. Empty means every JWT app the audience
+ * project holds is on the list (or there are no JWT apps at all).
+ */
+export function checkMailAppsAllowlist(apps, declaredMailApps) {
+    const allowed = new Set(declaredMailApps);
+    return apps
+        .filter((app) => app.accessTokenType === 'jwt' && !allowed.has(app.name))
+        .map((app) => `${app.name} (${app.clientId}) is not on the declared mail-apps list but mints a JWT Stalwart's audience rule accepts`);
+}

package/dist/plan/mail-identity.d.ts

@@ -0,0 +1,68 @@
+/**
+ * #33: whether Stalwart's OIDC directory audience rule actually binds the
+ * app that is carrying a token, not just whether the configured value looks
+ * right.
+ *
+ * The retired `checkMailIdentity` (app-template's `bootstrap/mail-
+ * identity.ts`) confirmed the directory's `requireAudience` matched what
+ * bootstrap configured, and that read as "the audience rule is enforced."
+ * It is not, for every app: Stalwart's OIDC directory lookup only enforces
+ * `requireAudience` on the JWT path (`authenticate_jwt`). A bearer token
+ * that is opaque instead goes through `authenticate_opaque`, which calls
+ * userinfo and builds the account -- checking neither audience nor scope at
+ * all (measured against `stalwartlabs/stalwart` `d9dee0a`,
+ * `crates/directory/src/backend/oidc/lookup.rs`). An app whose ZITADEL
+ * `accessTokenType` is opaque mints tokens that skip the rule entirely, no
+ * matter what the value check says.
+ *
+ * So {@link checkMailIdentityAudience} checks the audience *value* only --
+ * its name says so -- and separately names every opaque-minting app, so a
+ * clean value match stops reading as "and therefore enforced" for apps it
+ * never binds. Which apps are *allowed* to hold a JWT the rule does accept
+ * is a declared allow-list, out of scope here (#34).
+ *
+ * An exported pure function, decided in #33: the host supplies the live
+ * `requireAudience` value, the audience this org expects, and the apps in
+ * the audience project. This module reads no live state and calls nothing
+ * -- `apps` takes its own narrow shape rather than importing
+ * `@wtfalch/providers/zitadel`'s `ZitadelApp`, the same way `executor.ts`'s
+ * `ZitadelPort.listApps` already declares its own shape for a real
+ * `ZitadelClient` to satisfy structurally.
+ */
+export interface MailIdentityApp {
+    /** ZITADEL's own app id. */
+    id: string;
+    /** The OIDC client id ZITADEL issued -- what a fault names, never a secret. */
+    clientId: string;
+    name: string;
+    /**
+     * How ZITADEL mints this app's access token. `undefined` means unknown
+     * (an `api` app, which has no `oidcConfig` at all, or a caller that
+     * cannot yet tell) and is never treated as either value -- an app this
+     * function cannot classify is reported on its own, not folded into
+     * "safe".
+     */
+    accessTokenType?: 'jwt' | 'opaque';
+}
+export interface MailIdentityAudienceCheck {
+    /** `null` when the directory's `requireAudience` matches `expectedAudience`; otherwise the reason it does not. */
+    audienceMismatch: string | null;
+    /**
+     * One line per app in the audience project that mints an opaque access
+     * token, naming the app and its client id -- Stalwart's audience rule
+     * never binds it, whatever `audienceMismatch` says. Empty means every app
+     * this function was given mints a JWT (or none were given).
+     */
+    opaqueApps: string[];
+    /**
+     * One line per app this function could not classify at all (an
+     * `accessTokenType` of neither `'jwt'` nor `'opaque'`) -- worth a human
+     * look, since it is reported as neither enforced nor refused.
+     */
+    unknownAccessTokenApps: string[];
+}
+export declare function checkMailIdentityAudience(input: {
+    requireAudience: string;
+    expectedAudience: string;
+    apps: readonly MailIdentityApp[];
+}): MailIdentityAudienceCheck;

package/dist/plan/mail-identity.js

@@ -0,0 +1,17 @@
+export function checkMailIdentityAudience(input) {
+    const { requireAudience, expectedAudience, apps } = input;
+    const audienceMismatch = requireAudience === expectedAudience
+        ? null
+        : `requireAudience is '${requireAudience}', expected '${expectedAudience}'`;
+    const opaqueApps = [];
+    const unknownAccessTokenApps = [];
+    for (const app of apps) {
+        if (app.accessTokenType === 'opaque') {
+            opaqueApps.push(`${app.name} (${app.clientId}) mints an opaque access token -- Stalwart's requireAudience does not bind it`);
+        }
+        else if (app.accessTokenType !== 'jwt') {
+            unknownAccessTokenApps.push(`${app.name} (${app.clientId}) has an unknown access token type`);
+        }
+    }
+    return { audienceMismatch, opaqueApps, unknownAccessTokenApps };
+}

package/dist/plan/plan-apply.d.ts

@@ -178,6 +178,10 @@ export interface PlatformStepExecutor {
      */
     blockedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
         auth?: string;
+        /** #211 round 6: see `PlanPlatformOptions.blocked.authExecutorMissing`. */
+        authExecutorMissing?: boolean;
+        /** #216 round 5: see `PlanPlatformOptions.blocked.authOtherInputsMissing`. */
+        authOtherInputsMissing?: string[];
         files?: string;
         integrations?: string;
         ai?: string;
@@ -190,6 +194,7 @@ export interface PlatformStepExecutor {
      */
     driftedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
+        auth?: boolean;
     }>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;