@wtfalch/foundry 0.31.0 → 0.33.1

package/dist/plan/sign-in-org.d.ts

@@ -0,0 +1,99 @@
+import type { ZitadelPort } from './executor.js';
+/** Scope id: the domain registered as primary on the company's sign-in org. */
+export declare const ZITADEL_ORG_DOMAIN_SCOPE_KEY = "zitadel_org_domain";
+/**
+ * Scope id: the id of the sign-in org whose self-registration foundry closed,
+ * recorded only after `closeSelfRegistration` returned. While it is missing or
+ * names another org, the company plan holds the close step and no owner invite.
+ */
+export declare const ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY = "zitadel_org_registration_closed";
+/** Closes self-registration on the org (idempotent) and records it under `scopeKey`, in that order. */
+export declare function closeSignInOrgRegistration(zitadel: Pick<ZitadelPort, 'closeSelfRegistration'>, orgId: string, recordScopeId: (key: string, id: string) => void, scopeKey?: string): Promise<void>;
+/** Scope id: the domain the sign-in server refused to make primary (its domain policy wants proof). Set instead of failing; the planner reports it as blocked. */
+export declare const ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY = "zitadel_org_domain_blocked";
+/** The fixed text of the blocked item for a refused sign-in domain. No cause, no value but names. */
+export declare function signInDomainBlockedText(orgName: string, domain: string): string;
+/** The domain an org's owners sign in on: its own, or `<slug>.oikos.host` when it has none. */
+export declare function signInOrgDomain(org: {
+    slug: string;
+    domain: string | null;
+}): string;
+/**
+ * Adds `domain` to the ZITADEL org and makes it primary. Both calls are
+ * idempotent. A failure after the add leaves the domain on the org but not
+ * primary, and nothing is recorded, so the next run repeats both.
+ */
+export declare function registerSignInDomain(zitadel: Pick<ZitadelPort, 'addOrgDomain' | 'setPrimaryOrgDomain'>, orgId: string, domain: string): Promise<void>;
+/**
+ * {@link registerSignInDomain}, except that a refusal to make the domain
+ * primary (the sign-in server's domain policy wants proof) is recorded under
+ * `blockedScopeKey` and returns `false` instead of throwing on every apply.
+ * Any other failure throws. Returns `true` when the domain is primary.
+ */
+export declare function registerSignInDomainOrBlock(zitadel: Pick<ZitadelPort, 'addOrgDomain' | 'setPrimaryOrgDomain'>, orgId: string, domain: string, recordScopeId: (key: string, id: string) => void, blockedScopeKey?: string): Promise<boolean>;
+export interface EnsureSignInOrgOptions {
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'addOrgDomain' | 'setPrimaryOrgDomain' | 'closeSelfRegistration'>;
+    /** Where the successful close is recorded (the org id). Absent: not recorded; the caller closes on every run. */
+    registrationClosedScopeKey?: string;
+    /** Defaults to {@link ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY}. */
+    domainBlockedScopeKey?: string;
+    /** The ZITADEL org's name. A company uses its slug, so every caller finds the same org. */
+    name: string;
+    /** The domain to make primary, from {@link signInOrgDomain}. */
+    domain: string;
+    /** Where the ids are recorded. */
+    recordScopeId(key: string, id: string): void;
+    /** Called once the org id is recorded and before the domain is registered, so a crash between them does not lose the org. */
+    persistScopeIds?(): Promise<void>;
+    /** Defaults to `zitadel_org`. */
+    orgScopeKey?: string;
+    /** Defaults to {@link ZITADEL_ORG_DOMAIN_SCOPE_KEY}. */
+    domainScopeKey?: string;
+}
+/**
+ * Finds or creates the company's sign-in organisation by name, registers
+ * `domain` on it and makes it primary, then records the org id and the domain.
+ * The domain is recorded last, only after both calls succeeded.
+ */
+export declare function ensureSignInOrg(options: EnsureSignInOrgOptions): Promise<{
+    orgId: string;
+    created: boolean;
+    domainBlocked?: true;
+}>;
+/** The user metadata key that holds an owner's personal address. */
+export declare const PERSONAL_EMAIL_METADATA_KEY = "personal_email";
+export interface InviteOwnerOptions {
+    zitadel: Pick<ZitadelPort, 'inviteOrgOwner' | 'setUserMetadata' | 'getUserMetadata'>;
+    mail: {
+        send(to: string, link: string): Promise<void>;
+    };
+    /** The sign-in org the account is made in. */
+    orgId: string;
+    /** The platform's login app, where the link lands (it serves `/verify`). */
+    authIssuer: string;
+    owner: {
+        givenName: string;
+        familyName: string;
+        /** The owner's work address: the account signs in as its local part. */
+        mailboxAddress: string;
+        /** Where the first-sign-in link is mailed and what the `personal_email` metadata holds. */
+        personalEmail: string;
+    };
+    /** The user id foundry recorded when it invited this owner before. An existing account with another id, and no personal_email metadata of the owner's, is refused. */
+    invitedUserId?: string;
+    /** Called with the invite code and the whole link before they are mailed, so the caller can mask them. */
+    onSecret?: (value: string) => void;
+    /** Names the step in errors, for example `zitadel:owner for acme`. */
+    label: string;
+}
+/**
+ * Makes the owner's account (username = local part of the work address, email =
+ * the work address), keeps the personal address as metadata, and mails the
+ * first-sign-in link to it. The invite code ZITADEL returns goes only into that
+ * mail (30 second timeout); no error holds it. A failure after the account
+ * exists leaves the account, and the next run finds it by username and mints a
+ * new code.
+ */
+export declare function inviteOwnerWithLink(options: InviteOwnerOptions): Promise<{
+    userId: string;
+}>;

package/dist/plan/sign-in-org.js

@@ -0,0 +1,133 @@
+/** Scope id: the domain registered as primary on the company's sign-in org. */
+export const ZITADEL_ORG_DOMAIN_SCOPE_KEY = 'zitadel_org_domain';
+/**
+ * Scope id: the id of the sign-in org whose self-registration foundry closed,
+ * recorded only after `closeSelfRegistration` returned. While it is missing or
+ * names another org, the company plan holds the close step and no owner invite.
+ */
+export const ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY = 'zitadel_org_registration_closed';
+/** Closes self-registration on the org (idempotent) and records it under `scopeKey`, in that order. */
+export async function closeSignInOrgRegistration(zitadel, orgId, recordScopeId, scopeKey = ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY) {
+    await zitadel.closeSelfRegistration(orgId);
+    recordScopeId(scopeKey, orgId);
+}
+/** Scope id: the domain the sign-in server refused to make primary (its domain policy wants proof). Set instead of failing; the planner reports it as blocked. */
+export const ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY = 'zitadel_org_domain_blocked';
+/** The fixed text of the blocked item for a refused sign-in domain. No cause, no value but names. */
+export function signInDomainBlockedText(orgName, domain) {
+    return `${orgName}'s sign-in domain ${domain} is blocked, not planned: the sign-in server refused to make it primary because its domain policy wants proof of ownership. Set the policy ValidateOrgDomains to false (and UserLoginMustBeDomain to true) on the sign-in server, then remove the recorded key ${ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY}`;
+}
+/** True for the providers' "domain is not verified" refusal of `setPrimaryOrgDomain`. */
+function isPrimaryDomainRefused(error) {
+    return error instanceof Error && /is not verified/.test(error.message);
+}
+/** The domain an org's owners sign in on: its own, or `<slug>.oikos.host` when it has none. */
+export function signInOrgDomain(org) {
+    return (org.domain ?? `${org.slug}.oikos.host`).toLowerCase();
+}
+/**
+ * Adds `domain` to the ZITADEL org and makes it primary. Both calls are
+ * idempotent. A failure after the add leaves the domain on the org but not
+ * primary, and nothing is recorded, so the next run repeats both.
+ */
+export async function registerSignInDomain(zitadel, orgId, domain) {
+    await zitadel.addOrgDomain(orgId, domain);
+    await zitadel.setPrimaryOrgDomain(orgId, domain);
+}
+/**
+ * {@link registerSignInDomain}, except that a refusal to make the domain
+ * primary (the sign-in server's domain policy wants proof) is recorded under
+ * `blockedScopeKey` and returns `false` instead of throwing on every apply.
+ * Any other failure throws. Returns `true` when the domain is primary.
+ */
+export async function registerSignInDomainOrBlock(zitadel, orgId, domain, recordScopeId, blockedScopeKey = ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY) {
+    try {
+        await registerSignInDomain(zitadel, orgId, domain);
+        return true;
+    }
+    catch (error) {
+        if (!isPrimaryDomainRefused(error))
+            throw error;
+        recordScopeId(blockedScopeKey, domain);
+        return false;
+    }
+}
+/**
+ * Finds or creates the company's sign-in organisation by name, registers
+ * `domain` on it and makes it primary, then records the org id and the domain.
+ * The domain is recorded last, only after both calls succeeded.
+ */
+export async function ensureSignInOrg(options) {
+    const { zitadel, name, domain, recordScopeId } = options;
+    const { org, created } = await zitadel.findOrCreateOrg(name);
+    recordScopeId(options.orgScopeKey ?? 'zitadel_org', org.id);
+    await options.persistScopeIds?.();
+    // Before any owner invite can run: a stranger must not register the owner's
+    // username on an org that still inherits the instance's open registration.
+    // A failure here stops the step with the org recorded and no close recorded:
+    // the company plan then holds the close step and no invite until it succeeds.
+    await zitadel.closeSelfRegistration(org.id);
+    if (options.registrationClosedScopeKey) {
+        recordScopeId(options.registrationClosedScopeKey, org.id);
+    }
+    const registered = await registerSignInDomainOrBlock(zitadel, org.id, domain, recordScopeId, options.domainBlockedScopeKey);
+    if (!registered)
+        return { orgId: org.id, created, domainBlocked: true };
+    recordScopeId(options.domainScopeKey ?? ZITADEL_ORG_DOMAIN_SCOPE_KEY, domain);
+    return { orgId: org.id, created };
+}
+/** The user metadata key that holds an owner's personal address. */
+export const PERSONAL_EMAIL_METADATA_KEY = 'personal_email';
+/** How long the owner invite mail may take before the step gives up on it. */
+const OWNER_INVITE_MAIL_TIMEOUT_MS = 30_000;
+async function withTimeout(work, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Makes the owner's account (username = local part of the work address, email =
+ * the work address), keeps the personal address as metadata, and mails the
+ * first-sign-in link to it. The invite code ZITADEL returns goes only into that
+ * mail (30 second timeout); no error holds it. A failure after the account
+ * exists leaves the account, and the next run finds it by username and mints a
+ * new code.
+ */
+export async function inviteOwnerWithLink(options) {
+    const { zitadel, mail, orgId, authIssuer, owner, label } = options;
+    const { userId, created, inviteCode } = await zitadel.inviteOrgOwner(orgId, {
+        givenName: owner.givenName,
+        familyName: owner.familyName,
+        email: owner.mailboxAddress,
+        username: owner.mailboxAddress.slice(0, owner.mailboxAddress.indexOf('@')),
+    }, undefined, true);
+    if (!created && !inviteCode && userId !== options.invitedUserId) {
+        // An account that already has a sign-in method and no record of ours: not adopted.
+        // `personal_email` is written only by this function, through the admin API.
+        const metadata = await zitadel.getUserMetadata(orgId, userId, PERSONAL_EMAIL_METADATA_KEY);
+        if (metadata?.toLowerCase() !== owner.personalEmail.toLowerCase()) {
+            throw new Error(`${label}: in ZITADEL org ${orgId} an account with this username already exists and was not invited by foundry`);
+        }
+    }
+    await zitadel.setUserMetadata(orgId, userId, PERSONAL_EMAIL_METADATA_KEY, owner.personalEmail);
+    if (inviteCode) {
+        const link = `${authIssuer}/verify?userId=${encodeURIComponent(userId)}&code=${encodeURIComponent(inviteCode)}&organization=${encodeURIComponent(orgId)}&invite=true`;
+        options.onSecret?.(inviteCode);
+        options.onSecret?.(link);
+        try {
+            await withTimeout(mail.send(owner.personalEmail, link), OWNER_INVITE_MAIL_TIMEOUT_MS);
+        }
+        catch (_cause) {
+            // The mail port's own error may carry the link, and the link carries the code.
+            throw new Error(`${label}: the invite mail could not be sent; the account ${userId} exists and the next apply sends a new link`);
+        }
+    }
+    return { userId };
+}

package/dist/plan/version-status.d.ts

@@ -21,8 +21,7 @@ import type { VersionChangeItem } from '../plan.js';
  * `coolifyApplicationUuid` is the id `plan/diff.ts`'s `appStepKey` keys an
  * org's hosting entry under in `AppliedState.serviceIds`
  * (`` `coolify:app:${appStepKey(org, entry.key)}` ``, `org.ts`); `repo` is
- * `HostingEntry.repo`, falling back to whatever default an app with none
- * declared resolves to (`plan/executor.ts`'s own `DEFAULT_APP_REPO`).
+ * `HostingEntry.repo`.
  */
 export interface OrgAppVersionRef {
     orgId: OrgId;

package/dist/plan.d.ts

@@ -62,6 +62,24 @@ export interface Plan {
      * this type with none.
      */
     versionChanges?: VersionChangeItem[];
+    /**
+     * Things a person should see that block no step: an optional credential not
+     * held yet. Never in `unmanaged`, so a plan with no steps and no blocked
+     * item still reads as settled. Optional: a consumer that does not know it
+     * loses only the notes.
+     */
+    notes?: PlanNote[];
+}
+/**
+ * One advisory line of a {@link Plan}. It never stops a step and is never a
+ * {@link PlanStep}. It names a credential, never a value.
+ */
+export interface PlanNote {
+    /** Stable, e.g. `uptime:CHAT_ACCESS_TOKEN`. */
+    key: string;
+    /** The service or step this is about, e.g. `uptime`. */
+    service: string;
+    description: string;
 }
 /**
  * The action kind a {@link VersionChangeItem} carries -- a distinct, typed
@@ -99,4 +117,16 @@ export interface VersionChangeItem {
     /** The service this line is about, e.g. 'mail', 'archon', 'zitadel'. */
     service: string;
     description: string;
+    /** The version running or last applied; absent when that is unknown. */
+    from?: string;
+    /** The version the declaration or the foundry pin now asks for. */
+    to?: string;
+    /**
+     * True when `apply` and `applyPlatform` refuse the plan until
+     * `confirmUpgrade` names {@link service}: any change on a stateful service
+     * (`plan/confirm-upgrade.ts`), or a major or minor jump on any service. An
+     * unknown running version is never a change, so it is false. So is a line
+     * `apply` does not act on ("not applied by foundry").
+     */
+    needsConfirmation: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.31.0",
+  "version": "0.33.1",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",