@wtfalch/foundry 0.4.0 → 0.6.0

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

@@ -1,10 +1,14 @@
 import type { PlanApply } from '../apply.js';
 import type { DeclaredOrg, OrgId } from '../org.js';
-import type { Plan } from '../plan.js';
+import type { Plan, PlanStep } from '../plan.js';
+import type { DeclaredPlatform } from '../platform.js';
 import type { AppliedState } from '../state.js';
-import type { DeclaredOrgStore } from '../store.js';
+import type { DeclaredOrgStore, PlatformStore } from '../store.js';
+import { type AgoraHostPort } from './agora.js';
 import { type StepAction } from './diff.js';
-import { type LiveReaders, type LiveResource } from './live.js';
+import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
+import { type HeldKeyResolver } from './platform-org.js';
+import type { CallsSfuConnectionPort } from './platform-sfu.js';
 /** Who did it, for `@wtfalch/audit`'s "who, when, the plan, the result" (#9, #19). */
 export interface AuditActor {
     readonly id: string;
@@ -27,6 +31,8 @@ export interface AuditLog {
         actor: AuditActor;
         orgId: OrgId;
         plan: Plan;
+        /** `'platform'` for the shared platform's plan (#167), whose `orgId` is the owner org's; absent for an org's own. */
+        target?: 'platform';
         at: Date;
     }): Promise<void>;
     recordApply(entry: {
@@ -35,6 +41,8 @@ export interface AuditLog {
         plan: Plan;
         outcome: 'applied' | 'refused' | 'failed';
         reason?: string;
+        /** `'platform'` for the shared platform's apply (#167), whose `orgId` is the owner org's; absent for an org's own. */
+        target?: 'platform';
         at: Date;
     }): Promise<void>;
     /** `FoundryPlanApply.destroy`'s own record -- no `Plan` involved, so this is its own entry shape rather than a reuse of `recordApply`'s. */
@@ -61,6 +69,13 @@ export interface AuthzGate {
      * own permission rather than reusing `canApply`.
      */
     canDestroy(actor: AuditActor, orgId: OrgId): Promise<boolean>;
+    /**
+     * Gates `applyPlatform` (#167): changing the shared platform every org
+     * runs on is a stronger action than applying one org, so it is its own
+     * permission. Optional so an existing host that only gates orgs keeps
+     * compiling; a gate without it refuses every platform apply.
+     */
+    canApplyPlatform?(actor: AuditActor): Promise<boolean>;
 }
 /**
  * What {@link StepExecutor.execute} needs beyond the {@link StepAction}
@@ -108,6 +123,13 @@ export interface StepExecutionContext {
      * scope key can never collide with the `system:kind:key` form.
      */
     recordScopeId(key: string, id: string): void;
+    /**
+     * Writes every id recorded so far to the store now, not only at the end of
+     * the run. For an id that must survive a crash mid-step: the ai key's id
+     * between its mint and its delivery. The end-of-run write is a superset of
+     * this one, since both write the same map.
+     */
+    persistScopeIds(): Promise<void>;
 }
 /**
  * Makes one {@link StepAction} true against a real system. No implementation
@@ -121,6 +143,63 @@ export interface StepExecutor {
         resourceId?: string;
     } | undefined>;
 }
+/**
+ * #167: {@link StepExecutionContext}'s platform-scoped counterpart -- what
+ * {@link PlatformStepExecutor.execute} needs beyond the {@link StepAction}
+ * itself, for the shared platform (`platform.ts`'s `DeclaredPlatform`) rather
+ * than one `DeclaredOrg`. A separate type rather than a reuse of
+ * `StepExecutionContext`: that type's `org` field is read directly by every
+ * real executor method in `executor.ts`, so widening it to also carry a
+ * platform would touch that whole file, which is out of scope here -- #167
+ * ships the plan/apply frame only, proven against fakes, the same way #19
+ * shipped org plan/apply before #20 wired `FoundryStepExecutor` against it.
+ */
+export interface PlatformStepExecutionContext {
+    readonly platform: DeclaredPlatform;
+    /** {@link StepExecutionContext.recordedIds}, for the platform's own run. */
+    recordedIds(): Readonly<Record<string, string>>;
+    /** {@link StepExecutionContext.recordScopeId}, for the platform's own run. */
+    recordScopeId(key: string, id: string): void;
+    /**
+     * Writes every id recorded so far to the platform's applied state now,
+     * rather than when the run ends or throws, so a crash between two calls
+     * cannot lose an id a provider already created. Optional: a caller that
+     * builds its own context (tests) may omit it.
+     */
+    persist?(): Promise<void>;
+}
+/** {@link StepExecutor}, for the platform (#167) rather than an org. */
+export interface PlatformStepExecutor {
+    /**
+     * Steps this executor cannot run, as fixed text (part of the stale-plan
+     * comparison, so it must not vary per call). The planner reports each as an
+     * unmanaged item and plans no step for it, the way a blocked Agora is
+     * reported, instead of planning a step that throws on every apply.
+     */
+    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;
+        archon?: string;
+        mail?: string;
+    }>;
+    /**
+     * Steps whose live state differs from the declared one in a way the recorded
+     * ids cannot show, read from the live system on each plan.
+     */
+    driftedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
+        archon?: boolean;
+        auth?: boolean;
+    }>;
+    execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
+        resourceId?: string;
+    } | undefined>;
+}
 /**
  * One resource `FoundryPlanApply.destroy` has decided to tear down: an entry
  * from `AppliedState.serviceIds` (`resourceKey`'s `system:kind:key` form, or
@@ -168,6 +247,22 @@ export declare class NotAuthorizedError extends Error {
 export declare class NotATestOrgError extends Error {
     constructor(orgId: OrgId);
 }
+/** #167: {@link DeclaredOrgNotFoundError}, for the platform's own singleton record (#166). */
+export declare class DeclaredPlatformNotFoundError extends Error {
+    constructor();
+}
+/** #167: {@link StalePlanError}, for `planPlatform`/`applyPlatform`. */
+export declare class PlatformStalePlanError extends Error {
+    constructor();
+}
+/**
+ * #167: {@link ConfirmationRequiredError}, for `applyPlatform` -- typed as
+ * the literal word `platform` rather than a declared name, since
+ * {@link DeclaredPlatform} has no `displayName` of its own to type (#166).
+ */
+export declare class PlatformConfirmationRequiredError extends Error {
+    constructor();
+}
 export interface FoundryPlanApplyOptions {
     store: DeclaredOrgStore;
     readers: LiveReaders;
@@ -177,8 +272,51 @@ export interface FoundryPlanApplyOptions {
     authz: AuthzGate;
     /** The operator running this plan/apply — every audit row's "who" (#9, #19). */
     actor: AuditActor;
+    /** Host-supplied Agora values (#164). Optional: without it, or if it throws, the Agora is reported blocked and every other step still plans. */
+    agora?: AgoraHostPort;
+    /**
+     * #173: true when the host's executor was built with a `jobsScheduler`
+     * port. Optional, and false without it: each hosted org's registration with
+     * the jobs scheduler is then reported blocked instead of planned, so the
+     * step never runs (and fails) where no scheduler is deployed.
+     */
+    jobsScheduler?: boolean;
+    /**
+     * #177: true when the host's executor was built with its own `filesOrganisation`
+     * / `aiOrganisation` port. Without one, the org step needs the platform's
+     * key, so it is blocked while `platform.heldKeys` is absent or does not hold it.
+     */
+    filesOrganisation?: boolean;
+    aiOrganisation?: boolean;
     /** Overridable for tests; defaults to `() => new Date()`. */
     now?: () => Date;
+    /**
+     * #167: dependencies for planning/applying the shared platform (#166)
+     * alongside an org. Optional so an org-only caller — every #19-era caller,
+     * including every existing org test in this file — is unaffected;
+     * `planPlatform`/`applyPlatform` throw a plain `Error` if called without
+     * this set.
+     */
+    platform?: {
+        store: PlatformStore;
+        readers: PlatformLiveReaders;
+        executor: PlatformStepExecutor;
+        /**
+         * #170: read-only look at the held SFU connection. When the platform
+         * declares the SFU but this is absent, or resolves `null`, the plan
+         * reports the SFU as blocked (in `unmanaged`) instead of planning a step
+         * that would throw and halt every step after it.
+         */
+        sfuConnection?: CallsSfuConnectionPort;
+        /**
+         * #177: Archon's held keys. An org plan resolves the platform's files,
+         * AI and jobs keys through it and blocks the org step (naming the ref,
+         * never a value) while one is not held. Absent: every service without a
+         * host-supplied port is blocked (`filesOrganisation`, `aiOrganisation`,
+         * `jobsScheduler` on the options), never planned to fail at apply.
+         */
+        heldKeys?: HeldKeyResolver;
+    };
 }
 /**
  * The #19 implementation of {@link PlanApply}: computes a plan against live
@@ -194,10 +332,30 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly audit;
     private readonly authz;
     private readonly actor;
+    private readonly agora;
+    private readonly jobsScheduler;
+    private readonly hostFiles;
+    private readonly hostAi;
     private readonly now;
+    private readonly platformDeps;
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    /**
+     * #167: {@link plan}, for the shared platform (#166) rather than an org --
+     * there is no id to pass, since `DeclaredPlatform` is one singleton record.
+     */
+    planPlatform(): Promise<Plan>;
+    /**
+     * #167: {@link apply}, for the platform. `plan.orgId` is the platform's own
+     * `ownerOrgId` (`toPlatformPlan`'s own doc comment), so the same
+     * `AuditLog`/`AuthzGate` seams `apply` uses need no platform-specific
+     * shape of their own. `confirmedName` must be the literal word `platform`
+     * rather than a declared name -- `DeclaredPlatform` has none.
+     */
+    applyPlatform(plan: Plan, confirmedName: string): Promise<{
+        serviceIds: Record<string, string>;
+    }>;
     /**
      * Deletes every resource foundry recorded for `id`, in reverse creation
      * order, then the declared org and its applied state themselves (goal
@@ -211,7 +369,43 @@ export declare class FoundryPlanApply implements PlanApply {
      */
     destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
     private refuse;
+    private refusePlatform;
     private refuseDestroy;
     private runSteps;
     private computeFreshPlan;
+    /**
+     * #177: an org's plan reads the shared platform's own addresses and
+     * readiness through the very `platform` deps `planPlatform`/`applyPlatform`
+     * already use. With no platform wired or declared, {@link
+     * DEFAULT_ORG_PLATFORM_READINESS} reports every service not ready, so every
+     * org step that needs one is blocked.
+     */
+    private orgPlatformReadiness;
+    /**
+     * #177: `AgoraHostValues` from the applied platform, the same
+     * `platformDeps` {@link orgPlatformReadiness} reads -- but only when the
+     * host supplies no `agora` port of its own. An explicit `agora` (#164)
+     * always wins, unchanged, so a host that already has its own values
+     * (perhaps not yet wired to this platform) keeps them.
+     */
+    private orgAgoraHost;
+    /** #167: `FoundryPlanApplyOptions.platform`, or a plain `Error` naming what's missing. */
+    private requirePlatformDeps;
+    private computeFreshPlatformPlan;
+    private sfuBlockedReason;
+    /**
+     * {@link runSteps}, for the platform. The ids the steps return are recorded
+     * in `PlatformStore`'s applied state (`system:kind:key`, like an org's
+     * `serviceIds`), so a later plan finds a resource by its recorded id even
+     * when a provider's list has not caught up with a create.
+     */
+    private runPlatformSteps;
 }
+/**
+ * #9 (resolved): whether any step in a plan needs its name typed before
+ * `apply` runs it. Shared by `apply` (the org's `displayName`) and
+ * `applyPlatform` (the literal word `platform`, #167) so the platform gets
+ * the identical gate an org already has, proven end-to-end above, rather
+ * than a second copy that could drift from it.
+ */
+export declare function planNeedsConfirmation(steps: readonly PlanStep[]): boolean;