@wtfalch/foundry 0.14.0 → 0.16.0

package/dist/plan/agora.js

@@ -1,3 +1,4 @@
+import { chatUpstreams } from './chat-matrix.js';
 /**
  * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
  * need to agree on for an org's Agora -- the hostname, the values the host
@@ -11,6 +12,31 @@
  * (recorded by `executor.ts`'s `zitadelApp`).
  */
 export const ZITADEL_ORG_SCOPE_KEY = 'zitadel_org';
+/**
+ * The org's ZITADEL messaging project: the audience chat-service requires in
+ * a token's `aud`, and Agora's `messagingProjectId`. `executor.ts`'s
+ * `coolifyChat` finds or creates it (`<slug>-messaging`) and records its id
+ * here; a host value for the same id wins when it supplies one.
+ */
+export const ZITADEL_MESSAGING_PROJECT_SCOPE_KEY = 'zitadel_messaging_project';
+/**
+ * Recorded by `coolifyChat` last, once chat's three apps carry their fixed
+ * internal names: the chat service's address. `desiredAgoraEnv` waits for it
+ * (equal to the address the current slug gives), so Agora is never handed an
+ * address that does not resolve yet.
+ */
+export const CHAT_SERVICE_URL_SCOPE_KEY = 'coolify_chat_service_url';
+/** Whether the recorded marker says chat's apps carry the names the org's current slug gives them. */
+export function chatHasUpstreams(org, recorded) {
+    return recorded[CHAT_SERVICE_URL_SCOPE_KEY] === chatUpstreams(org.slug).chat;
+}
+/** `host` with the recorded messaging project filled in when the host supplies none. */
+export function withRecordedMessagingProject(host, recorded) {
+    return {
+        ...host,
+        messagingProjectId: host.messagingProjectId ?? recorded[ZITADEL_MESSAGING_PROJECT_SCOPE_KEY] ?? null,
+    };
+}
 export const AGORA_CLIENT_ID_SCOPE_KEY = 'agora_client_id';
 /**
  * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
@@ -181,7 +207,8 @@ export function callsServiceHasTokenEnv(host, recorded) {
  * not `host`: present only when calls are on and this org's calls service
  * app carries its internal name ({@link callsServiceHasName}).
  */
-export function desiredAgoraEnv(org, recorded, host) {
+export function desiredAgoraEnv(org, recorded, rawHost) {
+    const host = withRecordedMessagingProject(rawHost, recorded);
     const env = { AGORA_CANONICAL_HOST: agoraHostnameFor(org) };
     const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
     const clientId = recorded[AGORA_CLIENT_ID_SCOPE_KEY];
@@ -200,7 +227,7 @@ export function desiredAgoraEnv(org, recorded, host) {
             organisationId: zitadelOrgId,
             mailProjectId: host.mailProjectId,
             messagingProjectId: host.messagingProjectId,
-            // Chat is not in v1: Agora hides all chat UI unless this is true.
+            // Agora hides all chat UI unless this is true.
             chat: { enabled: org.chat.enabled },
             // Agora draws call buttons only when this is true.
             calls: { enabled: org.calls.enabled },
@@ -214,6 +241,14 @@ export function desiredAgoraEnv(org, recorded, host) {
     if (host.filesUpstream) {
         env.AGORA_FILES_UPSTREAM = host.filesUpstream;
     }
+    // Chat's three upstreams go together: the chat service alone cannot sign a
+    // person in (MAS) or load a room (Synapse).
+    if (org.chat.enabled && chatHasUpstreams(org, recorded)) {
+        const upstreams = chatUpstreams(org.slug);
+        env.AGORA_CHAT_UPSTREAM = upstreams.chat;
+        env.AGORA_MATRIX_UPSTREAM = upstreams.matrix;
+        env.AGORA_MAS_UPSTREAM = upstreams.mas;
+    }
     if (org.calls.enabled && callsServiceHasName(org, recorded)) {
         env.AGORA_CALLS_UPSTREAM = `http://${callsServiceInternalName(org)}:${CALLS_SERVICE_PORT}`;
     }

package/dist/plan/chat-matrix.d.ts

@@ -0,0 +1,99 @@
+import { type CallsDbConnection, type CallsMatrixSecrets, mintCallsMatrixSecrets } from './calls-matrix.js';
+/**
+ * The org's chat stack: pure config generation for Synapse (with the
+ * `wtfalch_chat_gate` module), matrix-authentication-service (MAS) and the
+ * chat service, deployed by `executor.ts`'s `coolifyChat`. It follows
+ * `calls-matrix.ts`: three Coolify-managed Postgres databases (Synapse, MAS,
+ * chat), one config file per Matrix app, and internal Docker-network
+ * addresses only.
+ *
+ * NO PUBLIC HOSTNAME OF ITS OWN
+ * ------------------------------
+ * The org's Agora is the one public origin. Its Caddy proxies `/_chat/*`,
+ * the Matrix client routes and MAS's compat login to the three internal
+ * addresses below (`AGORA_CHAT_UPSTREAM`, `AGORA_MATRIX_UPSTREAM`,
+ * `AGORA_MAS_UPSTREAM`, `agora/apps/agora/Caddyfile`), so neither tunnel
+ * routes nor DNS are needed. The chat service mints Matrix sessions through
+ * MAS's admin API over the internal address and hands clients the Agora URL
+ * as their homeserver (`CHAT_HOMESERVER_URL`).
+ *
+ * Secrets are the same six values the calls stack mints
+ * ({@link mintCallsMatrixSecrets}); they live as envs on the chat MAS app,
+ * the only memory across a re-run (`CHAT_SECRET_ENV_KEYS` in `executor.ts`).
+ */
+export type ChatMatrixSecrets = CallsMatrixSecrets;
+export declare const mintChatMatrixSecrets: typeof mintCallsMatrixSecrets;
+/** The chat repo: the Synapse module and the chat service are both built from it. */
+export declare const CHAT_REPO = "wtfalch/chat";
+/** Synapse plus the `wtfalch_chat_gate` module; built from the repo root. */
+export declare const CHAT_SYNAPSE_DOCKERFILE = "apps/chat-service/synapse-module/Dockerfile";
+/** The chat service, built from the repo root (that Dockerfile's own top comment). */
+export declare const CHAT_SERVICE_DOCKERFILE = "apps/chat-service/Dockerfile";
+export declare const CHAT_SYNAPSE_PORT = "8008";
+export declare const CHAT_MAS_PORT = "8080";
+export declare const CHAT_SERVICE_PORT = "8080";
+/** Fixed internal names, so the three apps and Agora address each other without guessing Coolify's own. */
+export declare function chatInternalNames(orgSlug: string): {
+    synapse: string;
+    mas: string;
+    service: string;
+    synapseDb: string;
+    masDb: string;
+    serviceDb: string;
+};
+/** The three addresses Agora proxies to, as `http://<internal name>:<port>`. */
+export declare function chatUpstreams(orgSlug: string): {
+    chat: string;
+    matrix: string;
+    mas: string;
+};
+/**
+ * Never resolved by DNS and never federates; the identifier Synapse, MAS and
+ * the chat service agree on. A level-1 org's chat lives on this name until a
+ * re-key onto its domain (not built). `.internal` never resolves, so it can
+ * not collide with a hostname some org owns.
+ */
+export declare function chatServerName(orgSlug: string): string;
+/** The Matrix user the chat service acts as (`chat/apps/chat-service/src/workspace.ts`). */
+export declare function chatAdminUser(orgSlug: string): string;
+export interface ChatSynapseHomeserverInput {
+    orgSlug: string;
+    db: CallsDbConnection;
+    masHost: string;
+    masSharedSecret: string;
+}
+/** `homeserver.yaml`: federation and presence off, MAS for auth, the chat gate module on. */
+export declare function chatSynapseHomeserverYaml(input: ChatSynapseHomeserverInput): string;
+export interface ChatMasConfigInput {
+    orgSlug: string;
+    /** The org's Agora hostname: MAS's `public_base`, the origin clients reach it on. */
+    publicHost: string;
+    db: CallsDbConnection;
+    synapseHost: string;
+    sharedSecret: string;
+    clientId: string;
+    clientSecret: string;
+    encryptionKey: string;
+    rsaKeyPem: string;
+    ecKeyPem: string;
+}
+/** MAS `config.yaml`: password login and registration off; the chat service is the one client, with admin. */
+export declare function chatMasConfigYaml(input: ChatMasConfigInput): string;
+export interface ChatServiceEnvInput {
+    orgSlug: string;
+    /** The org's display name: the workspace space's name. */
+    companyName: string;
+    issuer: string;
+    /** The org's ZITADEL messaging project id, required in a token's `aud`. */
+    audience: string;
+    zitadelOrgId: string;
+    agoraHost: string;
+    masClientId: string;
+    masClientSecret: string;
+    databaseUrl: string;
+}
+/** Every variable `chat/apps/chat-service/src/config.ts` requires, plus the internal Synapse address and port. */
+export declare function chatServiceEnvs(input: ChatServiceEnvInput): Array<{
+    key: string;
+    value: string;
+}>;

package/dist/plan/chat-matrix.js

@@ -0,0 +1,194 @@
+import { mintCallsMatrixSecrets, } from './calls-matrix.js';
+export const mintChatMatrixSecrets = mintCallsMatrixSecrets;
+/** The chat repo: the Synapse module and the chat service are both built from it. */
+export const CHAT_REPO = 'wtfalch/chat';
+/** Synapse plus the `wtfalch_chat_gate` module; built from the repo root. */
+export const CHAT_SYNAPSE_DOCKERFILE = 'apps/chat-service/synapse-module/Dockerfile';
+/** The chat service, built from the repo root (that Dockerfile's own top comment). */
+export const CHAT_SERVICE_DOCKERFILE = 'apps/chat-service/Dockerfile';
+export const CHAT_SYNAPSE_PORT = '8008';
+export const CHAT_MAS_PORT = '8080';
+export const CHAT_SERVICE_PORT = '8080';
+/** Fixed internal names, so the three apps and Agora address each other without guessing Coolify's own. */
+export function chatInternalNames(orgSlug) {
+    return {
+        synapse: `${orgSlug}-chat-synapse`,
+        mas: `${orgSlug}-chat-mas`,
+        service: `${orgSlug}-chat-service`,
+        synapseDb: `${orgSlug}-chat-synapse-db`,
+        masDb: `${orgSlug}-chat-mas-db`,
+        serviceDb: `${orgSlug}-chat-service-db`,
+    };
+}
+/** The three addresses Agora proxies to, as `http://<internal name>:<port>`. */
+export function chatUpstreams(orgSlug) {
+    const names = chatInternalNames(orgSlug);
+    return {
+        chat: `http://${names.service}:${CHAT_SERVICE_PORT}`,
+        matrix: `http://${names.synapse}:${CHAT_SYNAPSE_PORT}`,
+        mas: `http://${names.mas}:${CHAT_MAS_PORT}`,
+    };
+}
+/**
+ * Never resolved by DNS and never federates; the identifier Synapse, MAS and
+ * the chat service agree on. A level-1 org's chat lives on this name until a
+ * re-key onto its domain (not built). `.internal` never resolves, so it can
+ * not collide with a hostname some org owns.
+ */
+export function chatServerName(orgSlug) {
+    return `chat-${orgSlug}.internal`;
+}
+/** The Matrix user the chat service acts as (`chat/apps/chat-service/src/workspace.ts`). */
+export function chatAdminUser(orgSlug) {
+    return `@chat-admin:${chatServerName(orgSlug)}`;
+}
+const q = (value) => JSON.stringify(value);
+/** `homeserver.yaml`: federation and presence off, MAS for auth, the chat gate module on. */
+export function chatSynapseHomeserverYaml(input) {
+    return [
+        '# Generated by @wtfalch/foundry (executor.ts, coolify:chat). Do not edit',
+        '# by hand; re-run apply instead -- it will not rotate secrets that exist.',
+        '',
+        `server_name: ${q(chatServerName(input.orgSlug))}`,
+        'pid_file: /data/homeserver.pid',
+        'report_stats: false',
+        '',
+        'listeners:',
+        `  - port: ${CHAT_SYNAPSE_PORT}`,
+        '    type: http',
+        '    tls: false',
+        '    bind_addresses: ["0.0.0.0"]',
+        '    x_forwarded: true',
+        '    resources:',
+        '      - names: [client]',
+        '        compress: false',
+        '',
+        'database:',
+        '  name: psycopg2',
+        '  args:',
+        `    user: ${q(input.db.user)}`,
+        `    password: ${q(input.db.password)}`,
+        `    dbname: ${q(input.db.database)}`,
+        `    host: ${q(input.db.host)}`,
+        `    port: ${input.db.port}`,
+        '    cp_min: 5',
+        '    cp_max: 10',
+        '',
+        '# An empty list is the recommended way of disabling federation.',
+        'federation_domain_whitelist: []',
+        '',
+        '# Presence is out of scope for v1 (foundry#41).',
+        'presence:',
+        '  enabled: false',
+        '',
+        'enable_authenticated_media: true',
+        'max_upload_size: "50M"',
+        'encryption_enabled_by_default_for_room_type: "off"',
+        'auto_join_rooms: []',
+        '',
+        'media_store_path: /data/media_store',
+        'signing_key_path: /data/signing.key',
+        '',
+        'matrix_authentication_service:',
+        '  enabled: true',
+        `  endpoint: ${q(`http://${input.masHost}:${CHAT_MAS_PORT}/`)}`,
+        `  secret: ${q(input.masSharedSecret)}`,
+        '',
+        '# Gates channel creation, invites, joins and encryption (chat repo, MSG-007).',
+        'modules:',
+        '  - module: wtfalch_chat_gate.ChatGate',
+        '    config:',
+        `      admin_user: ${q(chatAdminUser(input.orgSlug))}`,
+        '      allow_encrypted_channels: false',
+        '',
+    ].join('\n');
+}
+/** MAS `config.yaml`: password login and registration off; the chat service is the one client, with admin. */
+export function chatMasConfigYaml(input) {
+    const indentKey = (pem, spaces) => pem
+        .trimEnd()
+        .split('\n')
+        .map((line) => `${' '.repeat(spaces)}${line}`)
+        .join('\n');
+    return [
+        '# Generated by @wtfalch/foundry (executor.ts, coolify:chat). Do not edit by hand.',
+        '',
+        'http:',
+        '  listeners:',
+        '    - name: web',
+        '      resources:',
+        '        - name: discovery',
+        '        - name: human',
+        '        - name: oauth',
+        '        - name: compat',
+        '        - name: graphql',
+        '        - name: assets',
+        '        - name: adminapi',
+        '        - name: health',
+        '      binds:',
+        `        - address: "[::]:${CHAT_MAS_PORT}"`,
+        '      proxy_protocol: false',
+        `  public_base: ${q(`https://${input.publicHost}/`)}`,
+        '  trusted_proxies:',
+        '    - 0.0.0.0/0',
+        '',
+        'database:',
+        `  host: ${q(input.db.host)}`,
+        `  port: ${input.db.port}`,
+        `  username: ${q(input.db.user)}`,
+        `  password: ${q(input.db.password)}`,
+        `  database: ${q(input.db.database)}`,
+        '  ssl_mode: disable',
+        '',
+        'matrix:',
+        '  kind: synapse',
+        `  homeserver: ${q(chatServerName(input.orgSlug))}`,
+        `  endpoint: ${q(`http://${input.synapseHost}:${CHAT_SYNAPSE_PORT}`)}`,
+        `  secret: ${q(input.sharedSecret)}`,
+        '',
+        '# The chat service is the only way in.',
+        'passwords:',
+        '  enabled: false',
+        '',
+        'account:',
+        '  password_registration_enabled: false',
+        '',
+        'clients:',
+        `  - client_id: ${q(input.clientId)}`,
+        '    client_auth_method: client_secret_basic',
+        `    client_secret: ${q(input.clientSecret)}`,
+        '',
+        'policy:',
+        '  data:',
+        '    admin_clients:',
+        `      - ${q(input.clientId)}`,
+        '',
+        'secrets:',
+        `  encryption: ${input.encryptionKey}`,
+        '  keys:',
+        '    - key: |',
+        indentKey(input.rsaKeyPem, 8),
+        '    - key: |',
+        indentKey(input.ecKeyPem, 8),
+        '',
+    ].join('\n');
+}
+/** Every variable `chat/apps/chat-service/src/config.ts` requires, plus the internal Synapse address and port. */
+export function chatServiceEnvs(input) {
+    const upstreams = chatUpstreams(input.orgSlug);
+    return [
+        { key: 'CHAT_ISSUER', value: input.issuer },
+        { key: 'CHAT_AUDIENCE', value: input.audience },
+        { key: 'CHAT_ORGANISATION_ID', value: input.zitadelOrgId },
+        { key: 'CHAT_HOMESERVER_URL', value: `https://${input.agoraHost}` },
+        { key: 'CHAT_INTERNAL_HOMESERVER_URL', value: upstreams.matrix },
+        { key: 'CHAT_SERVER_NAME', value: chatServerName(input.orgSlug) },
+        { key: 'CHAT_COMPANY_NAME', value: input.companyName },
+        { key: 'MAS_URL', value: upstreams.mas },
+        { key: 'MAS_CLIENT_ID', value: input.masClientId },
+        { key: 'MAS_CLIENT_SECRET', value: input.masClientSecret },
+        { key: 'DATABASE_URL', value: input.databaseUrl },
+        { key: 'CHAT_ALLOWED_ORIGINS', value: `https://${input.agoraHost}` },
+        { key: 'PORT', value: CHAT_SERVICE_PORT },
+    ];
+}

package/dist/plan/diff.d.ts

@@ -36,6 +36,8 @@ export interface PlanOrgOptions {
     loginHostBindings?: boolean;
     /** F5: the executor was built with a `broker` port. */
     broker?: boolean;
+    /** F6a, F6b: the clock `planEntryAiKeys` and `planFilesKeys` read for the renewal window. Default `Date.now`. */
+    now?: () => number;
 }
 export interface PlanDetail {
     orgId: OrgId;
@@ -67,7 +69,7 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * `planAiOrganisation`, each planned before its own system's limit step
  * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
  * limit to land, and AI use is switched on, before either limit is ever set.
- * `planOwner` below adds one more singleton, in a different shape from the
+ * `planOwners` below adds one more singleton, in a different shape from the
  * rest: the org's owner, invited by ZITADEL email, idempotent on the
  * *recorded* resource id (`recordedIds`, sourced from
  * `AppliedState.serviceIds`) rather than a live resource, since a human user
@@ -84,9 +86,9 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * Agora). #173 adds one more, gated on `org.hosting.enabled` like
  * {@link planApp} itself: {@link planJobsRegistration}, registering the org's
  * app with the platform's jobs scheduler, idempotent on the *recorded*
- * resource id like {@link planOwner} rather than a live resource, since
+ * resource id like {@link planOwners} rather than a live resource, since
  * nothing in `live` can report a scheduler registration (no reader exists for
- * it). #267 adds one more, right after {@link planOwner} and before every
+ * it). #267 adds one more, right after {@link planOwners} and before every
  * app-creating step below: {@link planLoginHost}, the org's own company
  * login host -- also idempotent on the *recorded* resource id, since
  * `live` has no notion of a ZITADEL trusted domain or a login binding