Compare commits

...
Author SHA1 Message Date
joshua ce1c978f21 Merge branch 'feat/frp-config-and-port-probe' 2026-11-21 11:08:15 +02:00
joshuaandClaude Opus 5.5 8542d19be0 Agent 1.4.0 + contracts 1.15.0: frp config anywhere, edited from the Hub; ports probed before installs
- The agent finds frps/frpc's config (Hub path, systemd -c, usual places) and reads INI and TOML.
- New jobs frp-read, frp-write (secrets kept on the server, verify, backup, restart, roll back)
  and probe-ports (which ports are free here), on central and church servers.
- Stats report frpConfigPath; crosscode gets FRPC_INI on church servers.
- Website plan versions move up to contracts 1.16.0 and Hub 2.12.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 11:07:50 +02:00
joshua 4cc30c1445 Merge branch 'docs/website-plan-confirmed' 2026-11-21 00:16:01 +02:00
joshuaandClaude Opus 5.5 d91d956e78 docs: Website 1.0 plan decisions confirmed; full storage stops uploads
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:16:00 +02:00
joshua 9f07ecf0dd Merge branch 'docs/website-1.0-plan' 2026-11-21 00:13:10 +02:00
joshuaandClaude Opus 5.5 74df4aa7b5 docs: plan the Church Website 1.0.0 (phase 5)
WEBSITE-1.0-PLAN.md: templates with section variants, style settings and custom
pages; one Publish after a clickable preview; Coming soon; contact details only;
messages from YouTube or by link; brand style and footer shared with Events 3.7;
no address moves in 1.0. ROADMAP decisions 40-47, §6, §9, §10, §11.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:13:10 +02:00
joshua 72a6283024 Merge branch 'docs/deployed-and-phase-5' 2026-11-21 00:00:56 +02:00
joshuaandClaude Opus 5.5 86711699cf docs: everything up to the 2026-11-20 releases deployed; phase 5 (Website) next
HANDOVER phase table and Next up, VERSIONS deployed table, and the Website/ui
placeholders now say phase 5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 00:00:55 +02:00
joshua d28029e96e Merge branch 'fix/accounts-backups-local-changes' 2026-11-20 15:55:08 +02:00
joshuaandClaude Opus 5.5 e65e26202a crosscode script: Accounts' pre-deploy dumps don't stop a deploy
The dump made before each Accounts deploy (apps/accounts/backend/backups/)
counted as a file added by hand on Accounts below 1.3.0, which has no
.gitignore for it, so the next deploy stopped. Untracked files in that
folder no longer count (CROSSCODE_OWN_DIRS in lib/common.sh).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 15:55:07 +02:00
joshua ca55142f6f Merge branch 'docs/hub-2.10.0' 2026-11-20 14:44:52 +02:00
joshuaandClaude Opus 5.5 1b94814f67 docs: Hub 2.10.0 (emails, FastPanel ^~ /api/) in HANDOVER, VERSIONS and AGENT-1.0-PLAN §11
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 14:44:52 +02:00
joshua 0b70a87669 Merge branch 'fix/branding-upload-routing' 2026-11-20 14:28:16 +02:00
joshuaandClaude Opus 5.5 ead07ef932 docs: Events 3.6.1 in CHANGELOG, VERSIONS and HANDOVER (FastPanel sites)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 14:28:15 +02:00
joshuaandClaude Opus 5.5 d8312f4b33 Events 3.6.1: branding uploads work behind a proxy with extension rules
The logo/favicon upload succeeded, but the check that the site can show it
got a 404: on events-demo every /api/... path ending in a file extension
(.png, .ico, .pdf, .json) went to Next.js instead of the backend.

- next.config.ts: /api/* and /uploads/* that reach the site are passed to
  the backend (beforeFiles rewrites) via the new BACKEND_INTERNAL_URL
  (http://127.0.0.1:<apiPort>, from env.template.json on deploy). The e2e
  E2E_API_PROXY uses the same rewrites.
- nginx written by both installers and shown in DEPLOYMENT.md: /api/ and
  /uploads/ use location ^~ so no regex location can take them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 14:08:11 +02:00
joshua a9239d429a Merge branch 'feat/signin-notices' 2026-11-20 13:54:04 +02:00
39 changed files with 1856 additions and 178 deletions
+31
View File
@@ -2,6 +2,37 @@
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
## agent@1.4.0 + contracts@1.15.0 - 2026-11-21
- **Agent 1.4.0: frp's config, wherever it is.** The agent no longer assumes
`/etc/frp/frps.ini`: it uses the path set on the Hub, else the `-c` in the frps/frpc systemd
unit, else the usual places (`/etc/frp`, `/usr/local/frp`, `/opt/frp` …), and reads TOML
(`proxyBindAddr`, `allowPorts = [{ start, end }]`) as well as INI. The central server's check
after an install failed with "No frps.ini at /etc/frp/frps.ini" on a server that keeps it
elsewhere. Stats say which file it uses (`frpConfigPath`). `crosscode` gets `FRPC_INI` for it
on church servers.
- **New jobs** (both modes): `frp-read` (the config, secrets hidden), `frp-write` (secrets put
back, `frp* verify`, backup, restart, the old file back if frp doesn't start) and
`probe-ports` (which of these ports are free here). Contracts 1.15.0: the job arguments,
`frpReadResultSchema`, `probePortsResultSchema`, `FRP_JOBS_MIN_AGENT`, `FRP_HIDDEN`,
`agentStats.frpConfigPath`. The Hub needs agent 1.4.0 on a server for these (Hub 2.11.0).
- The Church Website plan's versions move up one: contracts 1.16.0, Hub 2.12.0.
## crosscode script - 2026-11-20 (no tag: servers run `main`)
- **Fix:** the database dump made before each Accounts deploy (`apps/accounts/backend/backups/`)
counted as a file added by hand on Accounts below 1.3.0 (no `.gitignore` for it yet), so the
next deploy stopped with "changed or added by hand". Untracked files in that folder no longer
count (`CROSSCODE_OWN_DIRS` in `lib/common.sh`).
## events@3.6.1 - 2026-11-20
- **Events 3.6.1 (fix):** uploading a logo or favicon failed with "uploaded, but the site can't
show it yet" behind a proxy with a file-extension rule (FastPanel's static-file handling sent
`/api/uploads/…png` to the frontend). The site now passes `/api/*` and `/uploads/*` that reach
it on to the backend (new `BACKEND_INTERNAL_URL`, added on deploy).
- **crosscode script:** the nginx site it writes uses `location ^~ /api/` and `^~ /uploads/`.
## accounts@1.6.0 - 2026-11-20
- **Accounts 1.6.0:** a "New sign-in" email (and WhatsApp for a verified number) after every
+3 -2
View File
@@ -13,8 +13,9 @@ curl -fsSL https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/ma
| sudo bash -s -- --hub https://hub.crosscode.co.za --token <token>
```
Add `--central` on the central (FastPanel) server: there the agent is read-only and only runs
`check-ports` and `status`. The script installs Node 24 if needed, the agent in
Add `--central` on the central (FastPanel) server: there the agent only runs `check-ports`,
`probe-ports`, `status`, `update-agent`, and `frp-read` / `frp-write` (frps's config, from the
server's page on the Hub; agent 1.4.0+). The script installs Node 24 if needed, the agent in
`/opt/crosscode/agent/releases/<version>` (with `current` pointing at it), the `crosscode` script in
`/opt/crosscode/tools` (church servers), makes the server's two key pairs, joins, and starts
`crosscode-agent.service`.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/agent",
"version": "1.3.1",
"version": "1.4.0",
"private": true,
"description": "The server agent: runs the crosscode script for signed jobs from Cross Code Hub, reports stats (docs/AGENT-1.0-PLAN.md)",
"license": "UNLICENSED",
+17 -48
View File
@@ -1,51 +1,15 @@
import { execFile } from "node:child_process";
import fs from "node:fs";
import { paths } from "./paths";
import type { FrpSettings } from "./frp";
import { portAllowed } from "./frp";
export { parseFrpsIni, portAllowed } from "./frp";
/**
* The central server (AGENT-1.0-PLAN §6): read-only checks of frps for `check-ports`. Nothing on
* the central server is ever changed: no frps edits, no firewall, no FastPanel.
* The central server (AGENT-1.0-PLAN §6): the `check-ports` job after an install. Are the new
* tunnel's ports allowed by frps, open, and bound to 127.0.0.1 only? frps's config is found and
* read by ./frp.ts (INI or TOML, wherever it is).
*/
export interface FrpsSettings {
proxyBindAddr: string | null;
allowPorts: string | null;
}
/** frps.ini's [common] proxy_bind_addr and allow_ports (null when not set or no file). */
export function parseFrpsIni(text: string): FrpsSettings {
let inCommon = false;
const out: FrpsSettings = { proxyBindAddr: null, allowPorts: null };
for (const raw of text.split(/\r?\n/)) {
const line = raw.trim();
if (/^\[.*\]$/.test(line)) { inCommon = line === "[common]"; continue; }
if (!inCommon || line.startsWith("#") || line.startsWith(";")) continue;
const m = /^([a-z_]+)\s*=\s*(.*)$/.exec(line);
if (!m) continue;
if (m[1] === "proxy_bind_addr") out.proxyBindAddr = m[2]!.trim() || null;
if (m[1] === "allow_ports") out.allowPorts = m[2]!.trim() || null;
}
return out;
}
export function readFrps(file = paths.frpsIni): FrpsSettings | null {
try {
return parseFrpsIni(fs.readFileSync(file, "utf8"));
} catch {
return null;
}
}
/** Whether a port is inside allow_ports ("2000-3000,3001,4000-5000"); no allow_ports allows all. */
export function portAllowed(port: number, allowPorts: string | null): boolean {
if (!allowPorts) return true;
return allowPorts.split(",").map((s) => s.trim()).filter(Boolean).some((range) => {
const [a, b] = range.split("-").map((n) => Number(n.trim()));
if (!Number.isFinite(a)) return false;
return b === undefined ? port === a : Number.isFinite(b) && port >= a! && port <= b;
});
}
/** Listening TCP sockets from `ss -ltnH`: port → local addresses. */
export function parseSs(text: string): Map<number, string[]> {
const out = new Map<number, string[]>();
@@ -72,11 +36,16 @@ export interface PortCheck {
ok: boolean;
}
export function checkPorts(ports: number[], frps: FrpsSettings | null, listening: Map<number, string[]>): { ports: PortCheck[]; proxyBindAddr: string | null; warnings: string[] } {
export function checkPorts(
ports: number[],
frps: Pick<FrpSettings, "proxyBindAddr" | "allowPorts"> | null,
listening: Map<number, string[]>,
configPath: string | null = null,
): { ports: PortCheck[]; proxyBindAddr: string | null; configPath: string | null; warnings: string[] } {
const warnings: string[] = [];
if (!frps) warnings.push(`No frps.ini at ${paths.frpsIni}.`);
if (!frps) warnings.push(configPath ? `frps's config isn't at ${configPath} (Hub → the central server → frp config).` : "frps's config wasn't found (Hub → the central server → frp config: set where it is).");
const bind = frps?.proxyBindAddr ?? null;
if (frps && (!bind || !LOOPBACK.has(bind))) warnings.push(`proxy_bind_addr is ${bind ? `"${bind}"` : "not set"}: tunnels can be reached straight from the internet. Set proxy_bind_addr = 127.0.0.1 in frps.ini.`);
if (frps && (!bind || !LOOPBACK.has(bind))) warnings.push(`proxy_bind_addr is ${bind ? `"${bind}"` : "not set"}: tunnels can be reached straight from the internet. Set proxy_bind_addr = 127.0.0.1 (frps.toml: proxyBindAddr = "127.0.0.1") in ${configPath ?? "frps's config"}.`);
const results = ports.map((port) => {
const addrs = listening.get(port) ?? [];
const allowed = portAllowed(port, frps?.allowPorts ?? null);
@@ -86,9 +55,9 @@ export function checkPorts(ports: number[], frps: FrpsSettings | null, listening
for (const r of results) {
if (!r.allowed) warnings.push(`Port ${r.port} isn't in allow_ports.`);
else if (!r.listening) warnings.push(`Port ${r.port} isn't open in frps (is the church server's frpc connected?).`);
else if (!r.loopbackOnly) warnings.push(`Port ${r.port} is open on more than 127.0.0.1.`);
else if (!r.loopbackOnly) warnings.push(`Port ${r.port} is open on more than 127.0.0.1 (${(listening.get(r.port) ?? []).join(", ")}).`);
}
return { ports: results, proxyBindAddr: bind, warnings };
return { ports: results, proxyBindAddr: bind, configPath, warnings };
}
export function listeningNow(): Promise<Map<number, string[]>> {
+4 -1
View File
@@ -3,7 +3,7 @@ import type { agent } from "@crosscode/contracts";
/**
* The `crosscode` arguments for a job (AGENT-1.0-PLAN §4): built from the checked arguments only,
* as an array passed straight to the process (never through a shell). Jobs the agent handles
* itself (update-agent, check-ports) have none.
* itself (update-agent, check-ports, frp-read, frp-write, probe-ports) have none.
*
* `--config <file>` is added by the runner when the job brings config; `--json` always.
*/
@@ -71,6 +71,9 @@ export function crosscodeArgs(job: agent.AgentJob, opts: { exportFile?: string }
return ["status", ...(job.args.church ? [job.args.church] : []), "--no-fetch"];
case "update-agent":
case "check-ports":
case "frp-read":
case "frp-write":
case "probe-ports":
return null;
}
}
+454
View File
@@ -0,0 +1,454 @@
import { execFile } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { agent } from "@crosscode/contracts";
import { paths } from "./paths";
/**
* frp's config on this server (agent 1.4.0): frps's on the central server, frpc's on a church
* server. The agent finds the file itself (the path set from the Hub, else the systemd unit's
* `-c`, else a usual place), reads frp's two formats (INI and TOML), hides secret values before
* anything leaves the server, and writes a new file from the Hub the careful way: secrets put
* back, `verify`, a backup, a restart, and the old file back when the service doesn't come up.
*/
export type FrpService = "frps" | "frpc";
export type FrpSource = (typeof agent.FRP_CONFIG_SOURCES)[number];
export const serviceFor = (mode: agent.AgentMode): FrpService => (mode === "central" ? "frps" : "frpc");
// ─── Where the file is ────────────────────────────────────────────────────────
/** frps.toml, frpc.ini, frps-main.toml … */
const FRP_FILE = /^frp[A-Za-z0-9._-]*\.(ini|toml)$/;
const rememberedFile = () => path.join(paths.stateDir, "frp.json");
/** The path set from the Hub (an `frp-read` with a path), if any. */
export function rememberedPath(): string | null {
try {
const p = JSON.parse(fs.readFileSync(rememberedFile(), "utf8")).path;
return typeof p === "string" && path.isAbsolute(p) && FRP_FILE.test(path.basename(p)) ? p : null;
} catch {
return null;
}
}
export function rememberPath(p: string): void {
fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
fs.writeFileSync(rememberedFile(), `${JSON.stringify({ path: p, at: new Date().toISOString() })}\n`, { mode: 0o600 });
}
/** `-c <file>`, `-c=<file>`, `--config <file>` or `--config=<file>` in a command line. */
export function configFromCommand(argv: string): string | null {
const parts = argv.trim().split(/\s+/);
for (let i = 0; i < parts.length; i++) {
const a = parts[i]!;
const eq = /^(?:-c|--config)=(.+)$/.exec(a);
if (eq) return eq[1]!;
if ((a === "-c" || a === "--config") && parts[i + 1]) return parts[i + 1]!;
}
return null;
}
/** The config and the binary from `systemctl show <unit> -p ExecStart --value` ("{ path=… ; argv[]=… ; … }"). */
export function parseExecStart(text: string): { config: string | null; bin: string | null } {
const argv = /argv\[\]=([^;]*)/.exec(text)?.[1]?.trim() ?? text.trim();
const bin = argv.split(/\s+/)[0] || null;
return { config: configFromCommand(argv), bin: bin && bin.startsWith("/") ? bin : null };
}
function execText(cmd: string, args: string[], timeout = 10_000): Promise<{ ok: boolean; out: string; err: string; missing: boolean }> {
return new Promise((resolve) => {
execFile(cmd, args, { timeout }, (err, stdout, stderr) => resolve({
ok: !err, out: String(stdout ?? ""), err: String(stderr ?? "") || (err ? err.message : ""), missing: (err as NodeJS.ErrnoException | null)?.code === "ENOENT",
}));
});
}
async function fromSystemd(service: FrpService): Promise<{ config: string | null; bin: string | null }> {
const r = await execText("systemctl", ["show", service, "-p", "ExecStart", "--value"]);
return r.ok ? parseExecStart(r.out) : { config: null, bin: null };
}
/** Where frp is usually kept, in the order the agent looks. */
export function usualPlaces(service: FrpService): string[] {
const dirs = ["/etc/frp", `/etc/${service}`, "/usr/local/etc/frp", "/usr/local/frp", "/opt/frp", `/opt/${service}`, "/root/frp"];
return dirs.flatMap((d) => [`${d}/${service}.toml`, `${d}/${service}.ini`]);
}
export interface FoundConfig {
path: string | null;
source: FrpSource | null;
/** frps / frpc as the systemd unit runs it (for `verify`), else the name on PATH. */
bin: string;
looked: string[];
}
const exists = (f: string) => { try { return fs.statSync(f).isFile(); } catch { return false; } };
let cache: { at: number; mode: agent.AgentMode; found: FoundConfig } | null = null;
/** The config this server's frp uses. The Hub's path wins (even when the file isn't there: the Hub then says so). */
export async function findConfig(mode: agent.AgentMode, opts: { fresh?: boolean } = {}): Promise<FoundConfig> {
if (!opts.fresh && cache && cache.mode === mode && Date.now() - cache.at < 5 * 60_000) return cache.found;
const service = serviceFor(mode);
const unit = await fromSystemd(service);
const bin = unit.bin ?? service;
const looked: string[] = [];
let found: FoundConfig | null = null;
const hub = rememberedPath();
// The old setting (agent 1.0–1.3) still works, for a server that set it in the unit.
const env = mode === "central" ? process.env.CROSSCODE_FRPS_INI : process.env.CROSSCODE_FRPC_INI;
if (hub) found = { path: hub, source: "hub", bin, looked };
else if (env) found = { path: env, source: "hub", bin, looked };
else {
const candidates: Array<[string, FrpSource]> = [];
if (unit.config) candidates.push([unit.config, "systemd"]);
for (const p of usualPlaces(service)) candidates.push([p, "usual-place"]);
for (const [p, source] of candidates) {
looked.push(p);
if (exists(p)) { found = { path: p, source, bin, looked: [] }; break; }
}
}
const result = found ?? { path: null, source: null, bin, looked: looked.slice(0, 20) };
cache = { at: Date.now(), mode, found: result };
return result;
}
export function forgetFound(): void {
cache = null;
}
// ─── Reading INI and TOML ─────────────────────────────────────────────────────
export type FrpFormat = "ini" | "toml";
export const formatOf = (file: string, text = ""): FrpFormat => (file.endsWith(".toml") ? "toml" : file.endsWith(".ini") ? "ini" : /^\s*\[common\]/m.test(text) ? "ini" : "toml");
interface Line {
/** `[common]`, `[[proxies]]`: the header the line is under ("" before any), with how many came before it. */
section: string;
sectionIndex: number;
key: string;
/** The value as written, after `=` (quotes kept, comments after it dropped for TOML). */
raw: string;
/** The value without quotes. */
value: string;
/** Where `raw` starts and ends in the line. */
start: number;
end: number;
}
function unquote(v: string): string {
const t = v.trim();
if ((t.startsWith('"') && t.endsWith('"') && t.length >= 2) || (t.startsWith("'") && t.endsWith("'") && t.length >= 2)) return t.slice(1, -1);
return t;
}
/** Each `key = value` line, with the section it's in. */
export function lines(text: string, format: FrpFormat): Array<Line | null> {
let section = "";
const seen = new Map<string, number>();
let sectionIndex = 0;
return text.split("\n").map((rawLine) => {
const line = rawLine.replace(/\r$/, "");
const t = line.trim();
if (!t || t.startsWith("#") || t.startsWith(";")) return null;
const header = /^(\[\[?[^\]]+\]\]?)\s*(#.*)?$/.exec(t);
if (header) {
section = header[1]!.replace(/\s+/g, "");
sectionIndex = seen.get(section) ?? 0;
seen.set(section, sectionIndex + 1);
return null;
}
const m = /^(\s*)([A-Za-z0-9_.-]+|"[^"]+")(\s*=\s*)(.*)$/.exec(line);
if (!m) return null;
let raw = m[4]!;
if (format === "toml") {
// A comment after the value (outside quotes).
let q: string | null = null;
for (let i = 0; i < raw.length; i++) {
const c = raw[i]!;
if (q) { if (c === q && raw[i - 1] !== "\\") q = null; continue; }
if (c === '"' || c === "'") q = c;
else if (c === "#") { raw = raw.slice(0, i); break; }
}
}
raw = raw.replace(/\s+$/, "");
const start = m[1]!.length + m[2]!.length + m[3]!.length;
return { section, sectionIndex, key: m[2]!.replace(/"/g, ""), raw, value: unquote(raw), start, end: start + raw.length };
});
}
export interface FrpSettings {
proxyBindAddr: string | null;
allowPorts: string | null;
/** Ports frpc's proxies use (remote and local), or frps's own ports (bind, dashboard …). */
usedPorts: number[];
}
/** TOML's allowPorts = [{ start = 2000, end = 3000 }, { single = 3001 }] → "2000-3000,3001". */
export function tomlAllowPorts(text: string): string | null {
const m = /^\s*allowPorts\s*=\s*\[([\s\S]*?)\]\s*$/m.exec(text);
if (!m) return null;
const out: string[] = [];
for (const obj of m[1]!.matchAll(/\{([^}]*)\}/g)) {
const single = /single\s*=\s*(\d+)/.exec(obj[1]!)?.[1];
const start = /start\s*=\s*(\d+)/.exec(obj[1]!)?.[1];
const end = /end\s*=\s*(\d+)/.exec(obj[1]!)?.[1];
if (single) out.push(single);
else if (start && end) out.push(`${start}-${end}`);
else if (start) out.push(start);
}
return out.length ? out.join(",") : null;
}
const PORT_KEYS = /^(remote_?port|remotePort|local_?port|localPort|bind_?port|bindPort|kcp_?bind_?port|kcpBindPort|quic_?bind_?port|quicBindPort|vhost_?http_?port|vhostHTTPPort|vhost_?https_?port|vhostHTTPSPort|dashboard_?port|admin_?port|webServer\.port|port|tcpmux_?httpconnect_?port|tcpmuxHTTPConnectPort)$/;
export function parseSettings(text: string, format: FrpFormat): FrpSettings {
const all = lines(text, format).filter((l): l is Line => !!l);
const used = new Set<number>();
for (const l of all) {
if (!PORT_KEYS.test(l.key)) continue;
// INI: `remote_port = 6000`; frpc's `local_port` of a proxy is a port on the server too.
for (const n of l.value.split(/[,\s]+/)) if (/^\d+$/.test(n)) used.add(Number(n));
}
if (format === "ini") {
const common = all.filter((l) => l.section === "[common]");
const get = (k: string) => common.find((l) => l.key === k)?.value || null;
return { proxyBindAddr: get("proxy_bind_addr"), allowPorts: get("allow_ports"), usedPorts: [...used].sort((a, b) => a - b) };
}
const top = all.filter((l) => l.section === "");
return {
proxyBindAddr: top.find((l) => l.key === "proxyBindAddr")?.value || null,
allowPorts: tomlAllowPorts(text),
usedPorts: [...used].sort((a, b) => a - b),
};
}
/** Keeps the old helper's shape (agent ≤ 1.3 tests and stats). */
export function parseFrpsIni(text: string): { proxyBindAddr: string | null; allowPorts: string | null } {
const s = parseSettings(text, "ini");
return { proxyBindAddr: s.proxyBindAddr, allowPorts: s.allowPorts };
}
// ─── Secrets ──────────────────────────────────────────────────────────────────
/** token, auth.token, dashboard_pwd, webServer.password, oidc client secret, privilege_token … */
const SECRET_KEY = /(token|pwd|passw(or)?d|secret|private_?key|privateKey|credential)/i;
export const isSecretKey = (key: string): boolean => SECRET_KEY.test(key);
/** A secret key, or an inline table with one in it (auth = { token = "…" }). */
const INLINE_SECRET = /[{,]\s*[A-Za-z0-9_.]*(token|pwd|passw(or)?d|secret|private_?key|credential)[A-Za-z0-9_]*\s*=/i;
const isSecretLine = (l: Line): boolean => isSecretKey(l.key) || INLINE_SECRET.test(l.raw);
const idOf = (l: Line) => `${l.section}#${l.sectionIndex}/${l.key}`;
const nameOf = (l: Line) => (l.section && !l.section.startsWith("[[") && l.section !== "[common]" ? `${l.section.replace(/[[\]]/g, "")}.${l.key}` : l.key);
function hiddenRaw(raw: string): string {
const t = raw.trim();
if (t.startsWith('"')) return `"${agent.FRP_HIDDEN}"`;
if (t.startsWith("'")) return `'${agent.FRP_HIDDEN}'`;
return agent.FRP_HIDDEN;
}
/** The file with secret values replaced, and their names. */
export function hideSecrets(text: string, format: FrpFormat): { content: string; hidden: string[] } {
const hidden: string[] = [];
const src = text.split("\n");
lines(text, format).forEach((l, i) => {
if (!l || !isSecretLine(l) || !l.value) return;
const line = src[i]!;
src[i] = line.slice(0, l.start) + hiddenRaw(l.raw) + line.slice(l.end);
hidden.push(nameOf(l));
});
return { content: src.join("\n"), hidden: [...new Set(hidden)].slice(0, 50) };
}
/**
* A file from the Hub with the server's secret values put back. Refused when it changes a secret,
* or has a hidden value the server's file has no value for.
*/
export function restoreSecrets(incoming: string, current: string, format: FrpFormat): { ok: true; content: string } | { ok: false; message: string } {
const now = new Map<string, Line>();
for (const l of lines(current, format)) if (l && isSecretLine(l)) now.set(idOf(l), l);
const src = incoming.split("\n");
const parsed = lines(incoming, format);
for (let i = 0; i < parsed.length; i++) {
const l = parsed[i];
if (!l || !isSecretLine(l)) continue;
const old = now.get(idOf(l));
if (l.value === agent.FRP_HIDDEN) {
if (!old) return { ok: false, message: `${nameOf(l)} shows ${agent.FRP_HIDDEN}, but the file on the server has no value for it there. Secrets are set on the server.` };
src[i] = src[i]!.slice(0, l.start) + old.raw + src[i]!.slice(l.end);
} else if (l.value && (!old || old.value !== l.value)) {
return { ok: false, message: `${nameOf(l)} is a secret: it can't be set or changed from the Hub. Change it on the server.` };
}
}
return { ok: true, content: src.join("\n") };
}
// ─── Read, write ──────────────────────────────────────────────────────────────
/** systemd's view of a unit: true / false, or null when there's no systemctl. */
export async function serviceActive(unit: string): Promise<boolean | null> {
const r = await execText("systemctl", ["is-active", unit]);
if (r.missing) return null;
return r.out.trim() === "active";
}
export interface FrpDeps {
/** For tests: systemctl and `frp* verify`. */
exec?: (cmd: string, args: string[]) => Promise<{ ok: boolean; out: string; err: string; missing: boolean }>;
wait?: (ms: number) => Promise<void>;
}
export async function readConfig(mode: agent.AgentMode, opts: { path?: string } = {}, deps: FrpDeps = {}): Promise<agent.FrpReadResult> {
const service = serviceFor(mode);
if (opts.path) {
if (exists(opts.path)) rememberPath(opts.path);
forgetFound();
}
const found = opts.path ? { ...(await findConfig(mode, { fresh: true })), ...(exists(opts.path) ? {} : { path: opts.path, source: "hub" as const }) } : await findConfig(mode, { fresh: true });
const exec = deps.exec ?? execText;
const running = await (async () => { const r = await exec("systemctl", ["is-active", service]); return r.missing ? null : r.out.trim() === "active"; })();
const base = { service, path: found.path, source: found.source, serviceRunning: running, readAt: new Date().toISOString() };
let text: string | null = null;
if (found.path) {
try {
const st = fs.statSync(found.path);
if (st.size > agent.FRP_CONFIG_MAX) throw new Error(`${found.path} is ${st.size} bytes; the Hub shows files up to ${agent.FRP_CONFIG_MAX}.`);
text = fs.readFileSync(found.path, "utf8");
} catch (e) {
if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
}
}
if (text === null) {
return { ...base, found: false, format: null, content: null, hidden: [], proxyBindAddr: null, allowPorts: null, looked: found.path ? [found.path] : found.looked };
}
const format = formatOf(found.path!, text);
const settings = parseSettings(text, format);
const { content, hidden } = hideSecrets(text, format);
return {
...base, found: true, format, content, hidden,
proxyBindAddr: service === "frps" ? settings.proxyBindAddr : null,
allowPorts: service === "frps" ? settings.allowPorts : null,
};
}
export interface WriteOutcome {
status: agent.JobStatus;
message?: string;
steps: agent.ReportStep[];
result: Record<string, unknown>;
}
const stamp = () => new Date().toISOString().replace(/[-:]/g, "").replace(/\..*$/, "");
export async function writeConfig(mode: agent.AgentMode, args: { path: string; content: string; restart: boolean }, deps: FrpDeps = {}): Promise<WriteOutcome> {
const exec = deps.exec ?? execText;
const wait = deps.wait ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
const service = serviceFor(mode);
const steps: agent.ReportStep[] = [];
const step = (name: string, outcome: agent.ReportStep["outcome"], detail?: string) => {
const at = new Date().toISOString();
steps.push({ name, startedAt: at, finishedAt: at, outcome, ...(detail ? { detail: detail.slice(0, 2000) } : {}) });
};
const refuse = (message: string): WriteOutcome => ({ status: "refused", message, steps, result: {} });
const found = await findConfig(mode, { fresh: true });
if (found.path !== args.path) return refuse(`This server's ${service} config is ${found.path ?? "not found"}, not ${args.path}. Read it again on the Hub first.`);
if (!path.basename(args.path).startsWith(service)) return refuse(`${args.path} isn't ${service}'s config (the name must start with ${service}).`);
let current: string;
try { current = fs.readFileSync(args.path, "utf8"); } catch { return refuse(`There's no file at ${args.path} to replace.`); }
const format = formatOf(args.path, current);
const restored = restoreSecrets(args.content.replace(/\r\n/g, "\n"), current, format);
if (!restored.ok) return refuse(restored.message);
const next = restored.content.endsWith("\n") ? restored.content : `${restored.content}\n`;
if (next === current) {
step("Compare", "skipped", "The file is already like this; nothing changed.");
return { status: "succeeded", message: "Nothing changed: the file is already like this.", steps, result: await readConfig(mode, {}, deps) as unknown as Record<string, unknown> };
}
const dir = path.dirname(args.path);
const tmp = path.join(dir, `.${path.basename(args.path)}.crosscode-${process.pid}${path.extname(args.path)}`);
const mode0 = fs.statSync(args.path).mode & 0o777;
fs.writeFileSync(tmp, next, { mode: mode0 });
try {
const v = await exec(found.bin, ["verify", "-c", tmp]);
if (v.missing) { step(`${service} verify`, "failed", `${found.bin} wasn't found.`); return { status: "failed", message: `${found.bin} wasn't found, so the new config couldn't be checked; nothing changed.`, steps, result: {} }; }
if (!v.ok) { step(`${service} verify`, "failed", `${v.out}\n${v.err}`.trim()); return { status: "failed", message: `${service} verify refused the new config, so nothing changed: ${(v.err || v.out).trim().slice(0, 500)}`, steps, result: {} }; }
step(`${service} verify`, "ok");
} catch (e) {
fs.rmSync(tmp, { force: true });
throw e;
}
const backups = path.join(dir, "backups");
fs.mkdirSync(backups, { recursive: true, mode: 0o700 });
const backup = path.join(backups, `${path.basename(args.path)}.${stamp()}`);
fs.copyFileSync(args.path, backup);
fs.chmodSync(backup, mode0);
fs.renameSync(tmp, args.path);
step("Replace the config", "ok", `Backup: ${backup}`);
if (!args.restart) {
step(`Restart ${service}`, "skipped", "Not asked: the new config is used when frp next starts.");
return { status: "succeeded", steps, result: { ...(await readConfig(mode, {}, deps)), backup } };
}
const restart = await exec("systemctl", ["restart", service]);
await wait(3000);
const up = (await exec("systemctl", ["is-active", service])).out.trim() === "active";
if (restart.ok && up) {
step(`Restart ${service}`, "ok");
return { status: "succeeded", steps, result: { ...(await readConfig(mode, {}, deps)), backup } };
}
step(`Restart ${service}`, "failed", restart.err || `${service} isn't running after the restart.`);
fs.copyFileSync(backup, args.path);
await exec("systemctl", ["restart", service]);
await wait(3000);
const back = (await exec("systemctl", ["is-active", service])).out.trim() === "active";
step("Put the old config back", back ? "rolled-back" : "failed", back ? `${service} runs with the old config again.` : `${service} isn't running with the old config either: look at it on the server (journalctl -u ${service}).`);
return {
status: back ? "rolled-back" : "failed",
message: back ? `${service} didn't start with the new config, so the old one was put back.` : `${service} didn't start with the new config, and isn't running after putting the old one back either.`,
steps,
result: { ...(await readConfig(mode, {}, deps)), backup },
};
}
// ─── Free ports (probe-ports) ─────────────────────────────────────────────────
/** Whether a port is inside allow_ports ("2000-3000,3001,4000-5000"); no allow_ports allows all. */
export function portAllowed(port: number, allowPorts: string | null): boolean {
if (!allowPorts) return true;
return allowPorts.split(",").map((s) => s.trim()).filter(Boolean).some((range) => {
const [a, b] = range.split("-").map((n) => Number(n.trim()));
if (!Number.isFinite(a)) return false;
return b === undefined ? port === a : Number.isFinite(b) && port >= a! && port <= b;
});
}
export function probePorts(ports: number[], mode: agent.AgentMode, settings: FrpSettings | null, listening: Map<number, string[]>, configPath: string | null): agent.ProbePortsResult {
const used = new Set(settings?.usedPorts ?? []);
return {
configPath,
ports: ports.map((port) => {
const addrs = listening.get(port);
if (addrs?.length) return { port, free: false, reason: `In use: something listens on ${[...new Set(addrs)].join(", ")}.` };
if (mode === "central" && settings && !portAllowed(port, settings.allowPorts)) return { port, free: false, reason: "Not in frps's allow_ports." };
if (used.has(port)) return { port, free: false, reason: `Used in ${mode === "central" ? "frps" : "frpc"}'s config.` };
return { port, free: true, reason: null };
}),
};
}
/** The settings of the config this server uses, or null when there's none. */
export async function currentSettings(mode: agent.AgentMode): Promise<{ path: string | null; settings: FrpSettings | null }> {
const found = await findConfig(mode);
if (!found.path) return { path: null, settings: null };
try {
const text = fs.readFileSync(found.path, "utf8");
return { path: found.path, settings: parseSettings(text, formatOf(found.path, text)) };
} catch {
return { path: found.path, settings: null };
}
}
+23 -3
View File
@@ -2,7 +2,8 @@ import fs from "node:fs";
import path from "node:path";
import { agent } from "@crosscode/contracts";
import { encryptExport } from "@crosscode/contracts/signing";
import { checkPorts, listeningNow, readFrps } from "./central";
import { checkPorts, listeningNow } from "./central";
import { currentSettings, findConfig, probePorts, readConfig, writeConfig } from "./frp";
import { crosscodeArgs } from "./command";
import type { AgentConfig, Keys } from "./config";
import { type HubClient, HubRequestError } from "./hub";
@@ -153,10 +154,25 @@ export class Agent {
return { status: u.status, steps: u.steps, result: u.result, message: u.message, log: [], startedAt, finishedAt: new Date().toISOString(), restart: u.restart };
}
case "check-ports": {
const res = checkPorts(job.args.ports, readFrps(), await listeningNow());
const { path: configPath, settings } = await currentSettings("central");
const res = checkPorts(job.args.ports, settings, await listeningNow(), configPath);
const ok = res.ports.every((p) => p.ok) && res.warnings.length === 0;
return { status: ok ? "succeeded" : "failed", steps: [], result: res as unknown as Record<string, unknown>, message: res.warnings.join(" ") || undefined, log: [], startedAt, finishedAt: new Date().toISOString() };
}
case "frp-read": {
const result = await readConfig(this.deps.config.mode, { path: job.args.path });
const message = result.found ? undefined : `No ${result.service} config found${result.path ? ` at ${result.path}` : ""}.`;
return { status: result.found ? "succeeded" : "failed", steps: [], result: result as unknown as Record<string, unknown>, message, log: [], startedAt, finishedAt: new Date().toISOString() };
}
case "frp-write": {
const w = await writeConfig(this.deps.config.mode, job.args);
return { status: w.status, steps: w.steps, result: w.result, message: w.message, log: [], startedAt, finishedAt: new Date().toISOString() };
}
case "probe-ports": {
const { path: configPath, settings } = await currentSettings(this.deps.config.mode);
const result = probePorts(job.args.ports, this.deps.config.mode, settings, await listeningNow(), configPath);
return { status: "succeeded", steps: [], result: result as unknown as Record<string, unknown>, log: [], startedAt, finishedAt: new Date().toISOString() };
}
case "export":
return await this.runExport(job, limit);
case "status":
@@ -181,7 +197,11 @@ export class Agent {
private run(args: string[], job: agent.AgentJob, limit: number): Promise<RunResult> {
if (this.deps.run) return this.deps.run(args, job);
return runCrosscode({ args, sealedConfig: job.config ?? null, x25519Pem: this.deps.keys.x25519Pem, timeLimitMinutes: limit });
return (async () => {
// crosscode edits frpc's config on installs: tell it where the file is (agent 1.4.0).
const frpc = this.deps.config.mode === "church" ? (await findConfig("church").catch(() => null))?.path : null;
return runCrosscode({ args, sealedConfig: job.config ?? null, x25519Pem: this.deps.keys.x25519Pem, timeLimitMinutes: limit, env: frpc ? { FRPC_INI: frpc } : {} });
})();
}
/**
-2
View File
@@ -15,8 +15,6 @@ export const paths = {
get crosscode() { return env("CROSSCODE_BIN", "/usr/local/bin/crosscode"); },
/** Agent releases: releases/<version>/ (checkouts), current → the running one, previous. */
get agentRoot() { return env("CROSSCODE_AGENT_ROOT", "/opt/crosscode/agent"); },
/** frps.ini on the central server. */
get frpsIni() { return env("CROSSCODE_FRPS_INI", "/etc/frp/frps.ini"); },
/** The churches on a church server. */
get sites() { return env("CROSSCODE_SITES", "/var/www/sites"); },
};
+3 -1
View File
@@ -27,6 +27,8 @@ export interface RunOptions {
sealedConfig?: agent.Sealed | null;
x25519Pem: string;
timeLimitMinutes: number;
/** Extra environment for crosscode (FRPC_INI). */
env?: Record<string, string>;
/** For tests. */
bin?: string;
}
@@ -59,7 +61,7 @@ export async function runCrosscode(opts: RunOptions): Promise<RunResult> {
const child = spawn(opts.bin ?? paths.crosscode, args, {
detached: true,
stdio: ["ignore", "pipe", "pipe"],
env: { ...process.env, CROSSCODE_NO_UPDATE: process.env.CROSSCODE_NO_UPDATE ?? "", LC_ALL: "C.UTF-8" },
env: { ...process.env, ...opts.env, CROSSCODE_NO_UPDATE: process.env.CROSSCODE_NO_UPDATE ?? "", LC_ALL: "C.UTF-8" },
});
let timedOut = false;
const timer = setTimeout(() => {
+5 -4
View File
@@ -3,7 +3,7 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import type { agent } from "@crosscode/contracts";
import { readFrps } from "./central";
import { currentSettings, serviceActive } from "./frp";
import { paths } from "./paths";
/**
@@ -12,7 +12,7 @@ import { paths } from "./paths";
* the tools that are there; anything missing is null rather than an error.
*/
export const AGENT_VERSION = "1.3.1";
export const AGENT_VERSION = "1.4.0";
function run(cmd: string, args: string[], timeoutMs = 10_000): Promise<string | null> {
return new Promise((resolve) => {
@@ -159,9 +159,10 @@ export async function collectStats(mode: agent.AgentMode): Promise<agent.AgentSt
frpcRunning,
processes,
};
const frp = await currentSettings(mode).catch(() => ({ path: null, settings: null }));
stats.frpConfigPath = frp.path;
if (mode === "central") {
const frps = readFrps();
stats.central = { proxyBindAddr: frps?.proxyBindAddr ?? null, allowPorts: frps?.allowPorts ?? null, frpsRunning: await active("frps") };
stats.central = { proxyBindAddr: frp.settings?.proxyBindAddr ?? null, allowPorts: frp.settings?.allowPorts ?? null, frpsRunning: await serviceActive("frps") };
}
return stats;
}
+167
View File
@@ -0,0 +1,167 @@
import fs from "node:fs";
import path from "node:path";
import { agent } from "@crosscode/contracts";
import {
configFromCommand, findConfig, forgetFound, hideSecrets, parseExecStart, parseSettings, probePorts, readConfig, restoreSecrets, writeConfig,
} from "../src/frp";
import { tempState } from "./helpers";
const H = agent.FRP_HIDDEN;
const TOML = `bindPort = 7000
proxyBindAddr = "127.0.0.1"
auth.token = "s3cret-token" # the shared token
allowPorts = [
{ start = 20000, end = 29999 },
{ single = 3001 },
]
[webServer]
port = 7500
password = 'dash-pass'
`;
const FRPC_INI = `[common]
server_addr = 203.0.113.10
server_port = 7000
token = abc123
[hope-events-web]
type = tcp
local_ip = 127.0.0.1
local_port = 20010
remote_port = 20010
`;
const noSystemd = async () => ({ ok: false, out: "", err: "", missing: true });
describe("finding frp's config", () => {
it("reads -c from the systemd unit", () => {
expect(configFromCommand("/usr/local/bin/frps -c /usr/local/frp/frps.toml")).toBe("/usr/local/frp/frps.toml");
expect(configFromCommand("/usr/bin/frps --config=/etc/frps/frps.ini")).toBe("/etc/frps/frps.ini");
expect(configFromCommand("/usr/bin/frps")).toBeNull();
expect(parseExecStart("{ path=/usr/local/bin/frps ; argv[]=/usr/local/bin/frps -c /opt/frp/frps.toml ; ignore_errors=no ; start_time=[n/a] }"))
.toEqual({ config: "/opt/frp/frps.toml", bin: "/usr/local/bin/frps" });
});
it("the path from the Hub wins, and is remembered", async () => {
const dir = tempState();
const file = path.join(dir, "frps.toml");
fs.writeFileSync(file, TOML);
forgetFound();
const exec = async () => ({ ok: true, out: "active\n", err: "", missing: false });
const r = await readConfig("central", { path: file }, { exec });
expect(r).toMatchObject({ found: true, source: "hub", path: file, format: "toml", proxyBindAddr: "127.0.0.1", allowPorts: "20000-29999,3001", serviceRunning: true });
forgetFound();
expect((await findConfig("central", { fresh: true })).path).toBe(file);
});
it("a path that isn't there is reported, not remembered", async () => {
const dir = tempState();
forgetFound();
const r = await readConfig("central", { path: path.join(dir, "nope", "frps.ini") }, { exec: noSystemd });
expect(r).toMatchObject({ found: false, content: null });
expect(fs.existsSync(path.join(dir, "frp.json"))).toBe(false);
});
});
describe("frp settings, INI and TOML", () => {
it("TOML", () => {
expect(parseSettings(TOML, "toml")).toMatchObject({ proxyBindAddr: "127.0.0.1", allowPorts: "20000-29999,3001" });
expect(parseSettings(TOML, "toml").usedPorts).toEqual(expect.arrayContaining([7000, 7500]));
});
it("INI: frpc's tunnels use their ports", () => {
expect(parseSettings(FRPC_INI, "ini").usedPorts).toEqual([20010]);
});
});
describe("secrets never leave the server", () => {
it("are hidden in TOML and INI, keeping the quotes", () => {
const t = hideSecrets(TOML, "toml");
expect(t.content).toContain(`auth.token = "${H}" # the shared token`);
expect(t.content).toContain(`password = '${H}'`);
expect(t.content).not.toMatch(/s3cret|dash-pass/);
expect(t.hidden).toEqual(["auth.token", "webServer.password"]);
const i = hideSecrets(FRPC_INI, "ini");
expect(i.content).toContain(`token = ${H}`);
expect(i.content).not.toContain("abc123");
});
it("in inline tables too", () => {
expect(hideSecrets(`auth = { method = "token", token = "zzz" }\n`, "toml").content).not.toContain("zzz");
});
it("are put back on write, and can't be changed from the Hub", () => {
const shown = hideSecrets(TOML, "toml").content.replace("bindPort = 7000", "bindPort = 7001");
const back = restoreSecrets(shown, TOML, "toml");
expect(back.ok && back.content).toBe(TOML.replace("bindPort = 7000", "bindPort = 7001"));
expect(restoreSecrets(shown.replace(`"${H}"`, '"new"'), TOML, "toml")).toMatchObject({ ok: false, message: expect.stringMatching(/auth.token is a secret/) });
expect(restoreSecrets(`${shown}\n[extra]\ntoken = "${H}"\n`, TOML, "toml")).toMatchObject({ ok: false });
});
});
describe("writing the config", () => {
const setup = () => {
const dir = tempState();
const file = path.join(dir, "frps.toml");
fs.writeFileSync(file, TOML);
fs.writeFileSync(path.join(dir, "frp.json"), JSON.stringify({ path: file }));
forgetFound();
return { dir, file };
};
const shown = () => hideSecrets(TOML, "toml").content;
it("verify, backup, replace, restart", async () => {
const { dir, file } = setup();
const calls: string[] = [];
const exec = async (cmd: string, args: string[]) => { calls.push(`${cmd} ${args.join(" ")}`); return { ok: true, out: "active", err: "", missing: false }; };
const r = await writeConfig("central", { path: file, content: shown().replace("bindPort = 7000", "bindPort = 7001"), restart: true }, { exec, wait: async () => {} });
expect(r.status).toBe("succeeded");
expect(fs.readFileSync(file, "utf8")).toContain("bindPort = 7001");
expect(fs.readFileSync(file, "utf8")).toContain("s3cret-token");
expect(fs.readdirSync(path.join(dir, "backups"))).toHaveLength(1);
expect(calls.some((c) => / verify -c /.test(c))).toBe(true);
expect(calls).toContain("systemctl restart frps");
expect(JSON.stringify(r.result)).not.toContain("s3cret");
});
it("verify refuses: nothing changes", async () => {
const { file } = setup();
const exec = async (cmd: string) => ({ ok: cmd === "systemctl", out: "", err: "bad key", missing: false });
const r = await writeConfig("central", { path: file, content: "nonsense = [", restart: true }, { exec, wait: async () => {} });
expect(r.status).toBe("failed");
expect(fs.readFileSync(file, "utf8")).toBe(TOML);
});
it("frps doesn't come back: the old file is put back", async () => {
const { file } = setup();
let restarts = 0;
const exec = async (_cmd: string, args: string[]) => {
if (args[0] === "restart") restarts++;
if (args[0] === "is-active") return { ok: true, out: restarts >= 2 ? "active" : "failed", err: "", missing: false };
return { ok: true, out: "", err: "", missing: false };
};
const r = await writeConfig("central", { path: file, content: shown().replace("bindPort = 7000", "bindPort = 7001"), restart: true }, { exec, wait: async () => {} });
expect(r.status).toBe("rolled-back");
expect(fs.readFileSync(file, "utf8")).toBe(TOML);
});
it("only the file the agent uses", async () => {
const { dir } = setup();
const r = await writeConfig("central", { path: path.join(dir, "frpc.toml"), content: "x = 1", restart: false }, { exec: noSystemd });
expect(r.status).toBe("refused");
});
});
describe("free ports before an install", () => {
it("central: not listening and inside allow_ports", () => {
const listening = new Map([[20001, ["0.0.0.0"]]]);
const r = probePorts([20000, 20001, 30000], "central", parseSettings(TOML, "toml"), listening, "/etc/frp/frps.toml");
expect(r.ports.map((p) => [p.port, p.free])).toEqual([[20000, true], [20001, false], [30000, false]]);
});
it("church: not listening and not in frpc's tunnels", () => {
const r = probePorts([20010, 20011], "church", parseSettings(FRPC_INI, "ini"), new Map(), "/etc/frp/frpc.ini");
expect(r.ports.map((p) => [p.port, p.free])).toEqual([[20010, false], [20011, true]]);
});
it("with no config found, listening is all it can check", () => {
expect(probePorts([20010], "central", null, new Map(), null).ports[0]!.free).toBe(true);
});
});
+17
View File
@@ -5,6 +5,23 @@ All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project follows [Semantic Versioning](https://semver.org/).
## [3.6.1] - 2026-11-20
### Fixed
- **Uploading a logo or favicon under Settings → Branding failed on some servers** with "The logo was
uploaded, but the site can't show it yet". The upload worked, but on a server whose proxy has a
rule for file extensions (static-file caching) every `/api/…` path ending in `.png`, `.ico`,
`.pdf`, `.json` and so on went to the site (Next.js), which answered 404. So the check after the
upload failed, as did pictures, certificate PDFs and `/api/v2/openapi.json`. Two changes:
- The site passes `/api/*` and `/uploads/*` that reach it on to the backend
(`next.config.ts` rewrites, `beforeFiles`). New frontend setting `BACKEND_INTERNAL_URL`
(`http://127.0.0.1:<apiPort>`, added to `.env.production` on deploy). Unset, nothing is
passed on, as before. The end-to-end tests' `E2E_API_PROXY` uses the same rewrites.
- The nginx site the installers write (and DEPLOYMENT.md) sends `/api/` and `/uploads/` to the
backend with `location ^~`, so no regex location can take them. Existing servers keep their
nginx file: change it by hand (DEPLOYMENT.md §4).
## [3.6.0] - 2026-11-20
Works with any Accounts; the people check needs Accounts 1.5.0 (with an older one it's skipped).
+26 -15
View File
@@ -127,13 +127,17 @@ server {
access_log /var/log/nginx/hope-events.access.log hope_proxy;
# Visitors only reach this through the VPS over HTTPS, so tell the app so.
location ~ ^/(api|uploads|health|docs)(/|$) {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
# For the backend locations below ("location /" sets its own).
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
# The API and uploaded files go to the backend. Keep the ^~: without it, any regex location
# (e.g. one that caches *.png or *.css) wins and sends /api/uploads/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:5000; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:5000; }
location ~ ^/(api|uploads|health|docs)(/|$) { proxy_pass http://127.0.0.1:5000; }
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
@@ -147,7 +151,10 @@ server {
```
The VPS nginx/Caddy must redirect plain HTTP to HTTPS and pass the `Host` header through to frps
unchanged (frps picks the site by its host name). For nginx on the VPS, roughly:
unchanged (frps picks the site by its host name). Send every path through as it is: no
`location ~* \.(png|css|js…)$` caching rules for this site on the VPS, which would send
`/api/uploads/…/logo.png` to the site instead of the backend. (Since 3.6.1 the site passes such
requests on to the backend itself, but they're slower that way.) For nginx on the VPS, roughly:
```nginx
server {
@@ -188,13 +195,17 @@ server {
client_max_body_size 25m;
access_log /var/log/nginx/hope-events.access.log hope_proxy;
location ~ ^/(api|uploads|health|docs)(/|$) {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
# For the backend locations below ("location /" sets its own).
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
# The API and uploaded files go to the backend. Keep the ^~: without it, any regex location
# (e.g. one that caches *.png or *.css) wins and sends /api/uploads/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:5000; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:5000; }
location ~ ^/(api|uploads|health|docs)(/|$) { proxy_pass http://127.0.0.1:5000; }
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
+6
View File
@@ -12,6 +12,12 @@ Write for church admins, not developers: no environment variables, endpoints or
developer log is CHANGELOG.md. A tagged version without a section here shows "No details given".
-->
## 3.6.1
- **Fix:** uploading a logo or site icon under Settings → Branding could fail with "uploaded, but
the site can't show it yet", depending on how the server is set up. Uploaded pictures, certificate
downloads and the like now show on those servers too.
## 3.6.0
- **People's details are checked every night.** Cross Events compares everyone's name, email,
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-backend",
"version": "3.6.0",
"version": "3.6.1",
"description": "Event Management System Backend",
"main": "src/index.js",
"scripts": {
+6
View File
@@ -108,6 +108,12 @@
"layer": "install",
"from": "https://{domain}",
"required": true
},
{
"name": "BACKEND_INTERNAL_URL",
"layer": "install",
"from": "http://127.0.0.1:{apiPort}",
"description": "The backend on this server: requests for /api or /uploads that reach the site are passed to it (3.6.1)"
}
]
}
+23 -4
View File
@@ -1,6 +1,15 @@
import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";
// Requests for the backend (/api, /uploads) that reach the site anyway are passed to it (3.6.1).
// On a server nginx sends those paths to the backend, but a proxy in front can send some to the
// site instead: one with a rule for file extensions (static-file caching) sent every
// /api/uploads/…png here, so an uploaded logo never showed. BACKEND_INTERNAL_URL is the backend on
// this server (http://127.0.0.1:<port>), never the public address, which would come straight back
// here. The end-to-end tests set E2E_API_PROXY (3.0.0): the site and its API on one address, as
// nginx does, so Accounts' sign-in comes back to <site>/api/auth/callback.
const backend = (process.env.BACKEND_INTERNAL_URL || process.env.E2E_API_PROXY || "").replace(/\/+$/, "");
const nextConfig: NextConfig = {
// The end-to-end tests run their own dev server; a separate build folder keeps it
// from clashing with one already running.
@@ -12,10 +21,20 @@ const nextConfig: NextConfig = {
compiler: {
removeConsole: process.env.NODE_ENV === 'production',
},
// The end-to-end tests only (3.0.0): the site and its API on one address, as nginx does on a
// server, so Accounts' sign-in comes back to <site>/api/auth/callback. Unset everywhere else.
...(process.env.E2E_API_PROXY
? { async rewrites() { return [{ source: '/api/:path*', destination: `${process.env.E2E_API_PROXY}/api/:path*` }]; } }
...(backend
? {
// beforeFiles: ahead of every page, so a dynamic route like /[redirectUrl] never catches them.
async rewrites() {
return {
beforeFiles: [
{ source: '/api/:path*', destination: `${backend}/api/:path*` },
{ source: '/uploads/:path*', destination: `${backend}/uploads/:path*` },
],
afterFiles: [],
fallback: [],
};
},
}
: {}),
};
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events-frontend",
"version": "3.6.0",
"version": "3.6.1",
"private": true,
"scripts": {
"dev": "next dev",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/events",
"version": "3.6.0",
"version": "3.6.1",
"main": "index.js",
"scripts": {
"dev:backend": "cd backend && npm run dev",
+11 -8
View File
@@ -116,7 +116,7 @@ else
echo " backend/.env exists — kept"
fi
if [ ! -f "$DIR/frontend/.env.production" ]; then
echo "NEXT_PUBLIC_API_URL=$SITE_URL" > "$DIR/frontend/.env.production"
printf 'NEXT_PUBLIC_API_URL=%s\nBACKEND_INTERNAL_URL=http://127.0.0.1:%s\n' "$SITE_URL" "$API_PORT" > "$DIR/frontend/.env.production"
fi
if [ ! -f "$DIR/ecosystem.config.js" ]; then
sed -e "s/'hope-events-backend'/'$NAME-backend'/" -e "s/'hope-events-frontend'/'$NAME-frontend'/" -e "s/-p 3000/-p $WEB_PORT/" \
@@ -140,14 +140,17 @@ server {
server_name $DOMAIN;
client_max_body_size 25m;
# For the backend locations below ("location /" sets its own).
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
# The API, uploaded files, health and API docs go to the backend; everything else to the site.
location ~ ^/(api|uploads|health|docs)(/|\$) {
proxy_pass http://127.0.0.1:$API_PORT;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
# ^~ so a regex location added later (e.g. caching *.png) can't send /api/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:$API_PORT; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:$API_PORT; }
location ~ ^/(api|uploads|health|docs)(/|\$) { proxy_pass http://127.0.0.1:$API_PORT; }
location / {
proxy_pass http://127.0.0.1:$WEB_PORT;
proxy_http_version 1.1;
+1 -1
View File
@@ -1,3 +1,3 @@
# Church Website
Placeholder: the church's public website and its admin. Built in phase 4 of ROADMAP-v3 (see §6 there).
Placeholder: the church's public website and its admin. Built in phase 5 of ROADMAP-v3 (see §6 there).
+1 -1
View File
@@ -2,5 +2,5 @@
"name": "@crosscode/website",
"version": "0.0.0",
"private": true,
"description": "Placeholder: Church Website, built in phase 4 (ROADMAP-v3 §6)"
"description": "Placeholder: Church Website, built in phase 5 (ROADMAP-v3 §6)"
}
+2 -1
View File
@@ -354,6 +354,7 @@ Confirmed by Joshua on 2026-11-18 (1, 4, 5 and 6 asked directly; the rest as pro
## Still open
- Whether the Website's admin edits the church profile through Accounts' API (as proposed in §7)
or Accounts' own screen is the only place. Decide with the Website plan (phase 5).
or Accounts' own screen is the only place. Decide with the Website plan (phase 5). **Decided 2026-11-21 (WEBSITE-1.0-PLAN decision 10):**
through Accounts' API, live at once.
- Session lengths (30 days with "Keep me signed in") are a starting point; check them with Joshua
before release.
+40 -12
View File
@@ -83,7 +83,8 @@ build differs from this plan, see [Changes while building](#changes-while-buildi
- **Polling:** every 30 s `POST /api/agent/v1/poll` (signed) with a short status; the reply holds
any jobs due. Every 60 s the stats (§10). Requests back off when the Hub doesn't answer.
- **Modes:** `church` (default) and `central` (§6). The central agent can't run any job but
`check-ports` and `status`.
`check-ports`, `status` and `update-agent`, and from agent 1.4.0 `frp-read`, `frp-write` and
`probe-ports` (below).
- **Updating itself:** an `update-agent` job checks out the newest `agent@…` tag, builds it next
to the running copy, switches the systemd unit over and reports its new version. If the new one
doesn't poll within 2 minutes, a systemd timer starts the previous one again.
@@ -246,7 +247,25 @@ remote_port = 20011
- The `.ini` format is deprecated in newer frp versions in favour of TOML. The agent reads the
format the server has; moving to TOML is a separate job for later.
**The central agent** (`--central`, on the FastPanel server, read-only) answers `check-ports`:
**frp's config from the Hub (agent 1.4.0, Hub 2.11.0).** frps and frpc aren't always in
`/etc/frp/*.ini`: the agent finds the file itself (the path set on the Hub for that server, else
the `-c` in the systemd unit's ExecStart, else the usual places) and reads INI and TOML. The
server's page on the Hub shows it (`frp-read`) and can change it (`frp-write`, with two-factor):
secret values (token, passwords) never leave the server (shown as `***hidden***`, put back on
write, and can't be changed from the Hub), the new file is checked with `frps verify` /
`frpc verify`, a backup is kept in `<dir>/backups/`, the service is restarted, and the old file
goes back if it doesn't come up. **This ends "the central agent is read-only":** it can change
frps's config, and nothing else (no FastPanel, no firewall).
**Ports checked before an install (agent 1.4.0, Hub 2.11.0).** A new install reserves a few
candidate ports and sends `probe-ports` to every central server and to the church server. The
central agent says which are free (nothing listening, inside allow_ports); the church agent says
which are free there (nothing listening, not in frpc's config). The install waits (scheduled) and
then runs on the first pair free on both; busy ports go in the port list as taken. Too few free:
another round with new ports (3 rounds), then the install is called off and its ports freed.
With an agent older than 1.4.0 on either server, the install runs as before, with a warning.
**The central agent** (`--central`, on the FastPanel server) answers `check-ports` after an install:
- the port is inside `allow_ports` in `frps.ini`,
- frps has the tunnel open (the port is listening; frps's dashboard API is used if it's enabled
@@ -280,7 +299,8 @@ It changes nothing on the central server: no frps edits, no firewall changes, no
with the Hub using its licence.
5. **On failure** anything this job created is removed again (PM2 processes, frpc block, database
and role, folder), in reverse order, and the report says what failed and what was cleaned up.
6. **Central check:** the Hub asks the central agent to `check-ports` for both ports.
6. **Central check:** the Hub asks the central agent to `check-ports` for both ports. (From Hub
2.11.0 the ports were already checked free on both servers before step 1; see §6.)
7. **Emails to Joshua:** the install report and, if everything passed, the **FastPanel email**
(§11). The install shows **Waiting for proxy** in the Hub.
8. Joshua sets up FastPanel by hand and clicks **Proxy done**. The Hub checks the public URLs
@@ -382,16 +402,24 @@ All in the Hub (Jobs page, with the full report) and by email:
```
Set up in FastPanel: events.hope.co.za (Hope Family Church, Cross Events)
1. Add the site events.hope.co.za.
2. Proxy:
/api → http://127.0.0.1:20011 (backend; Events 2.2.0+, older
releases also need /uploads, /health, /docs)
everything else → http://127.0.0.1:20010 (frontend)
Pass the Host header and X-Forwarded-For / X-Forwarded-Proto: https.
Allow uploads up to 25 MB.
1. Add the site events.hope.co.za as a proxy to http://127.0.0.1:20010 (the frontend). Pass the
Host header and X-Forwarded-For / X-Forwarded-Proto: https, and allow uploads up to 25 MB.
2. Send /api to the backend: add this to the site's nginx configuration. Keep the ^~: without
it FastPanel's static-file rule sends every /api path with a file extension to the frontend.
location ^~ /api/ {
proxy_pass http://127.0.0.1:20011;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
location = /api { proxy_pass http://127.0.0.1:20011; }
3. Turn on Let's Encrypt for the site.
4. DNS: events.hope.co.za → <central server IP> (checked: ✅ points there / ⚠ not yet)
5. Then click "Proxy done" in the Hub: <link>
4. DNS: events.hope.co.za → <central server IP> (checked: points there / not yet)
5. Click "Proxy done" in the Hub. It checks the site, its /api and a file under /api, then
makes it live: <link>
Central check: both ports are open in frps and only on 127.0.0.1.
```
+50 -31
View File
@@ -1,6 +1,6 @@
# Handover — Cross Code, all products
Last updated: 2026-11-20. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
Last updated: 2026-11-21. **The plan is [ROADMAP-v3.md](./ROADMAP-v3.md)** (decided 2026-11-03,
decisions table near the end). This file says where each phase stands and what comes next.
Product-specific notes (where the code lives, known gaps) stay with each product: Cross Events'
are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and the Hub's are in
@@ -25,51 +25,70 @@ every release).
| Phase | What | State |
|-------|------|-------|
| 0 | contracts 1.0.0 / 1.1.0 | **Released** 2026-11-04. Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
| 1 | Hub 2.0.x | **Released** (`v2.0.0` 2026-11-05, `v2.0.1` AI tokens and `v2.0.2` refunds / voiding refunded invoices, 2026-11-17). **Not deployed yet:** `events-hub/deployment.md` → "Upgrading to 2.0" (run `check-hub2` first). Deploy straight to the latest 2.1.x (below) |
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released** 2026-11-17 (`events@2.2.0`, with AI use in tokens and the backend under `/api`). **VM tested 2026-11-17** (EVENTS-2.2-PLAN §6, all passing after fixes). **Not rolled out:** servers still run `hope-events` `v2.1.1` until each install is adopted |
| 1c | Cross Events 2.3.x: authenticator app 2FA (TOTP + recovery codes) | **Released** 2026-11-17 (`events@2.3.0`). **`events@2.3.1`** 2026-11-18: Next.js 16.4.6 (security advisories for 16.2.0–16.4.4), so roll out 2.3.1, not 2.3.0. crosscode-site `v1.3.0` lists it (merged and tagged, **not deployed**) |
| 1d | Agent 1.0.x + Hub 2.1.x (+ contracts 1.3.0) | **Released** 2026-11-17 (`agent@1.0.0`, `contracts@1.3.0`, Hub `v2.1.0`). **VM tested** end to end (AGENT-1.0-PLAN §13: joins, installs behind frp, scheduled / batch / missed updates, uninstall with export and purge, forged and replayed jobs). 2026-11-18: **`agent@1.0.1`** (the agent answers status on the central server itself) and Hub **`v2.1.1`** (adopt passes the church's address; Link takes the short name as a name). **Not rolled out**: use agent 1.0.1 and Hub 2.1.1 |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` (+ contracts 1.4.0, Hub 2.2.0) | **Released** 2026-11-18 (`events@2.4.0`, `contracts@1.4.0`, Hub `v2.2.0`, crosscode-site `v1.4.0`; [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). **Before any church gets it:** the Events e2e run on Postgres and the VM test (EVENTS-2.4-PLAN §8) |
| 3 | Accounts 1.0.0 (+ contracts 1.5.0, agent 1.1.0, Hub 2.3.0) | **Released** 2026-11-18 (`accounts@1.0.0`, `contracts@1.5.0`, `agent@1.1.0`, Hub `v2.3.0`, crosscode-site `v1.5.0`; [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)). 37 backend and 8 Playwright tests pass without Postgres. **Before installing it for a church:** the VM test and a run on real Postgres; a Hub release source for `accounts@` tags |
| 4 | Cross Events 3.0.0: sign-in through Accounts, users migrated with their password hashes and 2FA | **Released** 2026-11-19 (`events@3.0.0`, `accounts@1.1.0`, `contracts@1.8.0`, Hub `v2.5.0`, crosscode-site `v1.6.0`; [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md)). Tested on Postgres 18: both migrations, `test:accounts` on real databases (14/14), the Events e2e suite (111, incl. `sign-in-accounts.spec.ts`). **Not VM tested yet.** Roll out: Hub 2.5.0 deployed first, then per church Accounts 1.1.0 → Events 3.0 → Move (MIGRATING-TO-3.md); crosscode-site 1.6.0 once the first church has moved |
| 4+ | Running it: jobs from the dashboard, styled Accounts emails, .env from the Hub, sign-in health, the nightly people check | **Released** 2026-11-20 (see below). Unit, bats and full `npm run check` passing; **not VM tested, not deployed** |
| 5–7 | Website 1.0.0 → App 1.0.0 → App 1.x | Not started |
| 0 | contracts 1.0.0 → 1.14.0 | **Released and in use.** Not published to a registry (decision 22): the Hub gets a packed release committed to its repo (`backend/vendor/`) |
| 1 | Hub 2.0 → 2.10.0 | **Released, deployed and tested** (Hub `v2.10.0`) |
| 1b | Cross Events 2.2.0: moved here as `apps/events`, the `crosscode` script | **Released, rolled out and tested.** Every install adopted onto the monorepo |
| 1c | Cross Events 2.3.x: authenticator app 2FA | **Released and rolled out** (carried into Accounts in phase 4) |
| 1d | Agent 1.x + Hub 2.1+ | **Released, rolled out and tested** (agent `1.3.1` on every server; from agent 1.4.0 the central server's agent can also read and change frps's config from the Hub) |
| 2 | Cross Events 2.4.0: protocol v2, Linked products, event feed, `packages/seo` | **Released, rolled out and tested** ([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)) |
| 3 | Accounts 1.0.0 | **Released, rolled out and tested** (now `accounts@1.6.0`; [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)) |
| 4 | Cross Events 3.0.0: sign-in through Accounts | **Released, rolled out and tested** (now `events@3.6.1`; [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md)). Churches sign in through their Accounts; crosscode-site `v1.6.0` deployed |
| 4+ | Running it: jobs from the dashboard, styled emails, .env from the Hub, sign-in health, the nightly people check | **Released, deployed and tested** 2026-11-20 (below) |
| 5 | Church Website 1.0.0 | **Planned** 2026-11-21: [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md) (all decisions confirmed). Not started |
| 6–7 | App 1.0.0 → App 1.x | Not started |
## Released 2026-11-20
All tagged and pushed; nothing deployed yet. Details in [CHANGELOG.md](../CHANGELOG.md), the apps' CHANGELOGs
All tagged, pushed, deployed and tested (confirmed by Joshua 2026-11-21). Details in [CHANGELOG.md](../CHANGELOG.md), the apps' CHANGELOGs
and What's New, and [VERSIONS.md](./VERSIONS.md).
| Release | What |
|---------|------|
| `events@3.4.0`, `accounts@1.4.0`, `contracts@1.12.0`, `agent@1.3.0`, Hub `v2.8.0` | Background jobs switched on/off and rescheduled from each site's admin (saved in `job_overrides`, wins over the .env, applies at once; Accounts gets an Admin → Background jobs page). Accounts' emails styled as Events' (`src/lib/emails.ts`). The Hub reads and changes an install's .env (`env-read` / `env-set` jobs → `crosscode env`; secrets never leave the server; the file is put back if the site doesn't start; the frontend's file triggers a rebuild) |
| `events@3.5.0`, `contracts@1.13.0`, `agent@1.3.1`, Hub `v2.9.0` | **Fix:** "Load demo data" deleted the Accounts link (`set-demo.js` truncated `ProductLink`), so events-demo couldn't sign anyone in (`ACCOUNTS_UNAVAILABLE`). Demo data keeps the link; a site in Accounts mode without a link reconnects at its next heartbeat. Heartbeat `stats.signIn`; Hub alerts: not linked (critical), wrong Accounts, sign-in failing, an Accounts nothing links to. **Agent 1.3.0 reported itself as 1.2.0**: use 1.3.1 |
| `accounts@1.6.0` | A "New sign-in" email (and WhatsApp) after every sign-in; Sign-in settings → `signin_notices` turns it off |
| Hub `v2.10.0` | Every Hub email laid out as Events' and Accounts' (`src/utils/emailLayout.js`: header with the logo, button, notes, job steps, code blocks; plain text kept). The FastPanel email gives `location ^~ /api/` as config to paste; Proxy done checks a file under `/api` reaches the backend. Billing emails unchanged |
| `events@3.6.1` | **Fix:** logo/favicon uploads failed on events-demo ("uploaded, but the site can't show it yet"). FastPanel's static-file rule sent every `/api/…` path with a file extension (`.png`, `.pdf`, …) to the frontend. The site now passes `/api/*` and `/uploads/*` on to the backend (`BACKEND_INTERNAL_URL`); the installers' nginx uses `location ^~`. Change each FastPanel site too (below) |
| `events@3.6.0`, `accounts@1.5.0`, `contracts@1.14.0` | The nightly people check (`accounts-people-check`, 04:30): `people.check` 500 subs at a time; fixes out-of-date copies, handles deleted accounts as `user.deleted`, stops (changing nothing) when most people are unknown. Skipped with an Accounts before 1.5.0 |
**To fix events-demo before it's updated:** its Settings → Linked products → Connect the church's
Accounts (or update it to Events 3.5.0+, which reconnects within ~15 minutes).
## FastPanel sites (central server)
FastPanel's nginx on the central server is the only router for sites behind frp: the church
server has no nginx. Its static-file handling adds a regex location for file extensions
(`png|jpg|ico|svg|css|js|pdf|txt|…`) that falls back to the site's main proxy, the frontend. A
plain `location /api` loses to it, so `/api/uploads/…/logo.png` reached Next.js and got a 404
(fixed in the site by Events 3.6.1, but slower and without the visitor's IP). In each Events
site's nginx config in FastPanel, the backend locations must be `^~` (a prefix match that no
regex can override):
```nginx
location ^~ /api/ {
proxy_pass http://127.0.0.1:<api port>;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
location = /api { proxy_pass http://127.0.0.1:<api port>; }
```
Since **Hub 2.10.0** the FastPanel email (AGENT-1.0-PLAN §11) gives this block to paste, and
**Proxy done** refuses a site whose `/api/proxy-check.png` reaches the frontend. Sites set up
before that need the change by hand, and so does the Hub's own site (`events-hub`,
`/api/…/statement.pdf`; its deployment.md §8). Check after a change:
`curl -sI https://<domain>/api/health.png` must not say `X-Powered-By: Next.js` (a 404 is fine).
## Next up
Nothing from phase 1 onwards is rolled out yet (VERSIONS.md, "Deployed / rolled out"), so roll out
straight to the latest releases rather than each one in turn.
Everything up to and including the 2026-11-20 releases is deployed, rolled out and tested
(VERSIONS.md, "Deployed / rolled out").
1. **VM test the latest releases** before any church gets them (the 2026-11-17 VM test covered
Events 2.2 and agent 1.0; Events 2.4+, Accounts and Events 3.x haven't been on it): Events 3.x
with Accounts and the move (MIGRATING-TO-3.md), the event feed and Linked products
(EVENTS-2.4-PLAN §8), and today's: the Hub's .env panel (read; a backend URL with restart; a
frontend value with rebuild; a value that stops the site, so it's put back), the job switches,
a demo load (the Accounts link stays) and the people check. Also the Events e2e suite on Postgres.
2. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md), with the latest releases:
**Hub 2.9.0** (make and back up the job-signing key first; 2.4.0 onwards have migrations) → the
central server's agent (check `proxy_bind_addr = 127.0.0.1`) → each church server's agent
(**1.3.1**, never 1.3.0) → **adopt** the demo site, then each church (Link existing → Move onto the
monorepo) → per church **Accounts 1.5.0 before Events 3.6.0**, then the move to Accounts
(MIGRATING-TO-3.md) → a throwaway New install to prove FASTPANEL, DNS and Let's Encrypt.
3. **Deploy crosscode-site.** `v1.3.0`–`v1.5.0` are tagged but not recorded as deployed;
`v1.6.0` (one sign-in through Accounts) once the first church has moved.
4. **Archive `hope-events`** once every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7).
1. **Phase 5, Church Website 1.0.0** (ROADMAP §6, §9). Planned in
[WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md): decisions all confirmed 2026-11-21. Order:
contracts 1.16.0 → Accounts 1.7.0 → Events 3.7.0 (shared fonts and footer) → Hub 2.12.0 →
`website@1.0.0` → Hope Family Church → a second church → crosscode-site 1.7.0.
2. **Archive `hope-events`** if it isn't yet (every install now reports 2.2.0 or later;
EVENTS-2.2-PLAN §7).
## The VM test (2026-11-17)
+40 -8
View File
@@ -29,6 +29,12 @@ change decisions 10 and 23.
**Updated 2026-11-19:** phases 4 and 5 swapped: **Cross Events 3.0.0** (sign-in through Accounts)
comes before the **Church Website** (§9, decision 38).
**Updated 2026-11-21:** the Church Website (phase 5) is planned in
[WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md): more room to customise each template, one Publish for
the whole site after a clickable preview, Coming soon until then, a brand style and footer shared
with Cross Events (3.7), and no address moves or redirects in 1.0 (§6, §9, §10, §11; decisions
40–48).
---
## Contents
@@ -398,6 +404,11 @@ picks one; its **logo and colours come from the church profile** (`crosscode.chu
release for every church using them. More templates can be added in later releases.
- Every template meets the same bar: tested in Playwright (layout at phone / tablet / desktop,
axe accessibility) and with the §11 SEO checks.
- **Room to make it their own** (decision 40): every section type comes in two or three
**variants** (e.g. the hero as photo, video, collage, split or text only), **style settings**
(font pairing, corners, section colour, spacing, buttons, image treatment, header) and **custom
pages** built from blocks. No free layout or custom CSS. The font pairing and corners are part of
the church's shared brand style (decision 47). Details in WEBSITE-1.0-PLAN §3.
### Admin (`www.church.co.za/admin`, signed in through Accounts)
@@ -407,13 +418,18 @@ picks one; its **logo and colours come from the church profile** (`crosscode.chu
- Pages and sections, About, Leadership, Ministries, Messages, Media library, Contact and
service times, Navigation, Settings (including SEO and search engine verification, §11).
- **Events:** simple events, plus the feed settings (§4) and sync health.
- **Draft → preview → publish**, archive instead of delete, an audit log of who changed what.
- **Draft → preview → publish** (decision 41): every change is a draft; the preview is the whole
site, fully clickable, at phone / tablet / desktop width, and can be shared by link; **one
Publish** puts every change live; every published version is kept and can be restored. Until the
first publish the site shows **Coming soon** (decision 42). Archive instead of delete, an audit
log of who changed what.
- **Roles:** Owner, Admin, Editor, Ministry leader (own ministry only), Viewer.
### Not in the first release
Prayer requests and other forms with personal information (they belong in the App), a member
directory, online giving processing.
Prayer requests and other forms with personal information (they belong in the App; the Contact
page is contact details only, decision 43), a member directory, online giving processing, moving
to the church's own domain with redirects (decision 45).
---
@@ -625,7 +641,7 @@ Planned in [AGENT-1.0-PLAN.md](./AGENT-1.0-PLAN.md). In short:
| 2 | **Cross Events 2.4.0** | Reports `product: "events"` (protocol v2), **Linked products**, the event feed (publish + show events from siblings), `packages/seo` (§11) with canonical links for imported events. **Planned and built 2026-11-18:** [EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md) (also needs contracts 1.4.0 and Hub 2.2.0, for a public key in the v2 heartbeat); not tagged yet | Small; ready for when the Website exists |
| 3 | **Accounts 1.0.0** | OIDC provider, sign-in, 2FA (email, WhatsApp, authenticator app), password reset, consent and notice, export / delete fan-out, admin, install script. [ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md) (with contracts 1.5.0, `packages/auth-client`, Hub 2.3.0). **Released 2026-11-18** (`accounts@1.0.0`, 1.0.1 on 2026-11-19); the VM test and a run on real Postgres are still to do before a church gets it | Every later product signs in through it |
| 4 | **Cross Events 3.0.0** | Sign-in moves to Accounts; user migration keeping password hashes; migration guide. **Planned 2026-11-19:** [EVENTS-3.0-PLAN.md](./EVENTS-3.0-PLAN.md) (with contracts 1.8.0, Accounts 1.1.0, Hub 2.5.0; decisions confirmed 2026-11-19) | Breaking change, so a major version. **Moved before the Website on 2026-11-19** (decision 38): Events is the product churches use today, so Accounts is proven on real users first, and the Website then starts with a church whose people already have accounts |
| 5 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats | More churches need a website than an app; it also covers the "website only" case. Built on Accounts from day one |
| 5 | **Church Website 1.0.0** | Public site with the **four templates** (§6), admin, simple events + feed, SEO (§11), Hope Family Church as the first church, then a second test church on a different template to prove it repeats. **Planned 2026-11-21:** [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md) (with contracts 1.16.0, Accounts 1.7.0, Events 3.7.0 for the shared fonts and footer, Hub 2.12.0) | More churches need a website than an app; it also covers the "website only" case. Built on Accounts from day one |
| 6 | **Church App 1.0.0** | Foundation (PWA, branding, Accounts), House of Prayer, announcements, devotionals, events (simple + feed) | Starts with shared users and the feed already in place |
| 7 | Church App 1.x | Reading plans, sermons, groups, pastoral care, serving, giving links, directory | After House of Prayer is in use |
@@ -695,7 +711,7 @@ charged **once per church**, not per product.
| Option | Price | What it means |
|--------|-------|---------------|
| **Own domain** | R0 | The church already has a domain (e.g. `hopefamily.co.za`). They, or whoever manages it, add the DNS records we send. We look after the certificates |
| **Cross Code address** | **+R10 / month** | For churches that don't want a domain of their own: `hopefamily.crosscode.co.za`, with the products at `events.hopefamily.crosscode.co.za`, `app.hopefamily.crosscode.co.za` and so on. Can move to a domain of their own at any time (old addresses redirect for 12 months). Trials use this address for free |
| **Cross Code address** | **+R10 / month** | For churches that don't want a domain of their own: `hopefamily.crosscode.co.za`, with the products at `events.hopefamily.crosscode.co.za`, `app.hopefamily.crosscode.co.za` and so on. Can move to a domain of their own (old addresses redirect for 12 months; not before Website 1.0, decision 45). Trials use this address for free |
| **Domain included** | **+R25 / month** | We register a `.co.za` or `.org.za` **in the church's name**, renew it every year and manage the DNS. Other endings (`.com`, `.church`, `.org`) are charged at cost on top. If the church leaves, the domain is transferred to them, free |
### Church Website: one price plus storage
@@ -709,7 +725,8 @@ charged **once per church**, not per product.
Uploads are photos, documents and sermon notes. Sermon audio and video are linked (YouTube,
Spotify, SoundCloud…) rather than uploaded, so most churches never need extra storage. Admins see
how much they've used in the website's settings and get an email at 80%. Storage is counted per
church and reported to the Hub, which bills the add-on.
church and reported to the Hub, which bills the add-on. **When it's full, uploads stop** until more
is bought (decision 48); what's already uploaded keeps showing.
### Church App: on active members
@@ -783,7 +800,8 @@ data from the same `crosscode.event/1` and `crosscode.church/1`. Cross Events mo
When a church moves from the Cross Code address to its own domain (§10), every old URL
**301-redirects** to the same page on the new domain for 12 months, so it keeps its search
ranking.
ranking. **Not in Website 1.0** (decision 45): moving addresses, with a Hub job for all of a
church's products, comes in a later release.
### Checks (in every product's tests)
@@ -859,7 +877,21 @@ ranking.
| 38 | Order after Accounts | **Cross Events 3.0.0 (sign-in through Accounts) is phase 4, the Church Website phase 5** (swapped). Events is what churches use today, so Accounts is proven on real users and their migrated passwords and 2FA first; the Website then starts with a church whose people already have accounts |
| 39 | Emergency updates now | An emergency update (reason and 2FA, as before) can run **as soon as possible**, at the agent's next poll (within a minute), as well as at a time at least 15 minutes away. The church is told it's happening now. When the church's Events heartbeat shows an event on now (a session or a one-day event, or check-ins in the last hour), the Hub names it and needs a second "yes". Hub 2.7.0, Events 3.2.0 |
**Added 2026-11-21** (phase 5, [WEBSITE-1.0-PLAN.md](./WEBSITE-1.0-PLAN.md))
| # | Question | Decision |
|---|----------|----------|
| 40 | Enough customisation | Keep **four templates**, each with **section variants**, **style settings** and **custom pages from blocks**, within limits that keep every site designed, accessible and fast. No free layout, custom CSS or custom fonts. More templates can come in 1.x, but not instead of this |
| 41 | Publishing | Every change is a draft. A **fully clickable preview** of the whole site (shareable by a 7-day link) and **one Publish for the whole site**; any pending change can be discarded; every published version is kept and can be restored |
| 42 | Before the first publish | The public address shows a **Coming soon** page from the church profile (logo, service times, contact, links to Events), `noindex` |
| 43 | Contact page | **Contact details only**, no form |
| 44 | Shared vs Website-only content | The church profile (`crosscode.church/1`) gains the **brand style** (font pairing, corners). Leaders, ministries, About, giving and messages are **Website-only for now**; the App plan decides whether they move into the profile |
| 45 | Moving to the church's own domain | **Not in Website 1.0**, and no Hub "Change address" job yet (§10, §11 "Moving addresses") |
| 46 | Messages | **From a YouTube channel or playlist automatically** (latest video as the latest message), or **by hand** with a YouTube or Spotify link |
| 47 | Feeling like one church | The **brand style and footer are shared**: the Website, Accounts' pages and **Cross Events 3.7**'s public pages use the church's fonts, corners and one `ChurchFooter`, with links between the products |
| 48 | Full storage | Admins are emailed at 80% and 100%; at 100% **uploads stop** until more storage is bought (Get more storage asks the Hub; the new limit arrives with the licence) |
## Still open
Nothing. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the
Nothing for the roadmap. WEBSITE-1.0-PLAN lists its own proposals still to confirm. crosscode-site is updated at the end of each phase (§9, "Updating crosscode-site"); the
Website and App move from "coming later" to their own pages and prices when they ship.
+32 -12
View File
@@ -1,6 +1,6 @@
# Versions — the latest release of everything
Last updated: 2026-11-20. Taken from the git tags, which is what a release is here (branch → merge →
Last updated: 2026-11-21. Taken from the git tags, which is what a release is here (branch → merge →
tag → push, see [HANDOVER.md](./HANDOVER.md) "Releasing"). **Update this file with every release.**
"Released" means tagged and pushed. Whether a release is **deployed** or rolled out is recorded
@@ -10,13 +10,13 @@ separately below; the two often differ.
| What | Repo | Latest | Tag | Released |
|------|------|--------|-----|----------|
| Cross Events | `crosscode-platform` (`apps/events`) | **3.6.0** | `events@3.6.0` | 2026-11-20 |
| Cross Events | `crosscode-platform` (`apps/events`) | **3.6.1** | `events@3.6.1` | 2026-11-20 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.6.0** | `accounts@1.6.0` | 2026-11-20 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.3.1** | `agent@1.3.1` | 2026-11-20 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.14.0** | `contracts@1.14.0` | 2026-11-20 |
| Cross Code Hub | `events-hub` | **2.9.0** | `v2.9.0` | 2026-11-20 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.4.0** | `agent@1.4.0` | 2026-11-21 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.15.0** | `contracts@1.15.0` | 2026-11-21 |
| Cross Code Hub | `events-hub` | **2.11.0** | `v2.11.0` | 2026-11-21 |
| crosscode.co.za | `crosscode-site` | **1.6.0** | `v1.6.0` | 2026-11-19 |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-20 (last change: `crosscode env`) |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-20 (last change: Accounts' pre-deploy dumps don't stop a deploy) |
The `crosscode` script has no version: every server's copy (`/opt/crosscode/tools`) pulls `main`
on each run, so merging to `main` and pushing releases it. Its changes are listed in
@@ -29,7 +29,7 @@ on each run, so merging to `main` and pushing releases it. Its changes are liste
| `@crosscode/auth-client` | `packages/auth-client` | 1.1.0 (released with Events 3.0.0 and Accounts 1.1.0) |
| `@crosscode/seo` | `packages/seo` | 1.0.0 (released with Events 2.4.0) |
| `@crosscode/ui` | `packages/ui` | 0.1.0 |
| Website | `apps/website` | 0.0.0 (not started, phase 5) |
| Website | `apps/website` | 0.0.0 (phase 5, being planned) |
| App | `apps/app` | 0.0.0 (not started, phase 6) |
These shared packages ship inside the apps that use them, from the same checkout, so they don't
@@ -37,6 +37,25 @@ need their own tags until something outside this repo depends on them.
## What each latest release was for
- **Agent 1.4.0 + contracts 1.15.0 + Hub 2.11.0:** the agent finds frps's / frpc's config wherever
it is (the path set on the Hub, the systemd unit's `-c`, the usual places) and reads TOML too;
each server's Hub page reads and changes that config (secrets stay on the server, `verify`,
backup, restart, put back if frp doesn't start, two-factor); a new install first checks its
ports are free on the central server and the church server (`probe-ports`) and runs on a pair
free on both. Update the agents first (central and church), then deploy the Hub (migration
`20261121110000_server_frp_config`). With older agents the Hub installs as before, with a warning.
- **`crosscode` script (2026-11-20, later):** the database dump made before each Accounts deploy
(`backend/backups/`) no longer stops the next deploy as "added by hand" on Accounts below 1.3.0.
Released by pushing `main`; the next Hub job pulls it.
- **Hub 2.10.0:** every Hub email (job reports, alerts, emails to church admins, notices) laid out
as Events' and Accounts' are. The FastPanel email gives `location ^~ /api/` to paste, and Proxy
done refuses a site whose `/api` files reach the frontend. No migration.
- **Events 3.6.1 (fix):** logo and favicon uploads failed on events-demo: FastPanel's static-file
rule sent every `/api/…` path with a file extension to the frontend. The site now passes those on
to the backend. Also change the FastPanel site (HANDOVER.md, "FastPanel sites"). No migration.
- **Accounts 1.6.0:** a "New sign-in" email (and WhatsApp) after every sign-in, as Cross Events'
own sign-in sends; admins can turn it off. No migration.
@@ -128,8 +147,9 @@ you deploy one.
| What | Running | Since | Notes |
|------|---------|-------|-------|
| Hub | 2.x (exact version not recorded) | | It runs agent jobs (installs on church-server1, 2026-11-18), so it's past 2.1. **2.4.0 not deployed yet** (it has a migration) |
| Agent on church-server1 | not recorded | | |
| Agent on the central server | not recorded | | |
| Cross Events (churches) | not recorded | | `hope-events` and `cross-events-demo` heartbeat as 2.1.1 and 2.3.1 |
| crosscode.co.za | not recorded | | Handover: `v1.3.0` was merged and tagged but not deployed |
| Hub | 2.10.0 | 2026-11-20 | |
| Agent on church-server1 | 1.3.1 | 2026-11-20 | |
| Agent on the central server | 1.3.1 | 2026-11-20 | Read-only (decision 35) |
| Cross Events (churches) | 3.6.1 | 2026-11-20 | Every install adopted onto the monorepo and signing in through Accounts |
| Accounts (churches) | 1.6.0 | 2026-11-20 | |
| crosscode.co.za | 1.6.0 | 2026-11-20 | |
+399
View File
@@ -0,0 +1,399 @@
# Church Website 1.0.0 — the church's own public site
Phase **5** of [ROADMAP-v3.md](./ROADMAP-v3.md) (§6, §9, §10, §11; decisions 19, 20, 40–47).
Written 2026-11-21. **All decisions confirmed by Joshua on 2026-11-21** (12 changed: a full
storage stops uploads). Not started.
**What the Website is:** the church's public site at `www.<church's address>` (or
`<church>.crosscode.co.za` on the Cross Code address), plus its admin at `/admin`. Admins sign in
through the church's Accounts. The church picks one of **four templates** and makes it its own with
section layouts, style settings and its own pages. Changes are drafts until an admin **previews**
the whole site and presses **Publish**. Until the first publish, visitors see a **Coming soon**
page. The Website, Cross Events and (later) the App share the church's **brand style** (colours,
logo, fonts, corners) and **footer**, so the three feel like one church.
**Who uses 1.0:** Hope Family Church first, then a second test church on a different template, to
prove it repeats. Then it goes on sale (crosscode-site, ROADMAP §9).
**Done when:**
- `website@1.0.0`, `contracts@1.16.0`, `accounts@1.7.0`, `events@3.7.0` and Hub `v2.12.0` are
tagged; the Hub installs the Website from New install (after Accounts) and lists its releases.
- All four templates pass the same checks (§13) at phone, tablet and desktop sizes: layout, axe, the
§11 SEO checks, and Lighthouse (SEO 100, accessibility 95+, performance 90+).
- An editor can change anything, preview the whole site as a visitor would, share the preview, and
publish it all at once. An earlier version can be restored.
- Switching template keeps all content, and the preview shows the switch before it goes live.
- Cross Events' public pages use the church's fonts and the shared footer.
- Hope Family Church and a second church are live on different templates.
- crosscode-site sells it (ROADMAP §9, "Updating crosscode-site").
## Contents
1. [The shape](#1-the-shape)
2. [Content: shared and Website-only](#2-content-shared-and-website-only)
3. [Templates and customisation](#3-templates-and-customisation)
4. [Drafts, preview and publish](#4-drafts-preview-and-publish)
5. [Coming soon](#5-coming-soon)
6. [Pages](#6-pages)
7. [Messages](#7-messages)
8. [Events](#8-events)
9. [Connected with Events and the App](#9-connected-with-events-and-the-app)
10. [Admin, roles and storage](#10-admin-roles-and-storage)
11. [Hub, licence and servers](#11-hub-licence-and-servers)
12. [What changes in each repo](#12-what-changes-in-each-repo)
13. [Testing](#13-testing)
14. [Releasing and rolling it out](#14-releasing-and-rolling-it-out)
15. [Decisions](#decisions)
16. [Still open](#still-open)
## 1. The shape
`apps/website`, the same stack as Events and Accounts (decision 8 in the roadmap): an **Express +
Prisma + pg-boss backend** (TypeScript) and a **Next.js frontend**, one PostgreSQL database, served
on one address with `/api` to the backend (`location ^~ /api/` in FastPanel, HANDOVER "FastPanel
sites").
```
visitor ─► www.hopefamily.co.za ─► Next.js (server-rendered from the published version, cached)
│ template + section variants + style → HTML
editor ──► /admin (signed in through Accounts, @crosscode/auth-client)
edits the working copy ─► /admin/preview: the whole site from the working copy
Publish ─► a new SiteVersion (snapshot) ─► public pages revalidated
backend: content API (/api/v1/admin/…), public API (/api/v1/site/…), uploads (/api/uploads/…),
event feed (/api/links/v1/*, as Events 2.4), Hub client (protocol v2, product "website"),
jobs (YouTube feed, storage count, sitemap, feed sync)
Accounts ── crosscode.church/1 (name, logo, colours, service times, contact, social, brand style)
Events ──── crosscode.event/1 (the event feed, both directions)
```
- **Rendering:** public pages are server components rendered from the **latest published
version** and cached; Publish revalidates them. Preview renders the same components from the
**working copy**, uncached. Visitors and the preview run the same code, so the preview is exactly
what will go live.
- **Shared packages:** `@crosscode/ui` (branded shell, footer, fonts, form fields, now also the
public site's building blocks), `@crosscode/seo` (meta, JSON-LD, sitemap), `@crosscode/auth-client`
(sign-in), `@crosscode/contracts`.
## 2. Content: shared and Website-only
**The rule:** facts that more than one product shows live in the **church profile**
(`crosscode.church/1`, owned by Accounts). How the Website presents them, and anything only the
Website shows, lives in the **Website's own database**. Leaders, ministries, About, giving and
messages stay **Website-only for now** (decision 5), and can move into the profile when the App needs
them (phase 6–7).
| Shared: `crosscode.church/1` | Website-only |
|---|---|
| Already there: name, short name, logo, icon, colours, campuses, service times, contact, social, links | Template, section variants, style settings other than fonts and corners (§3), homepage order |
| **New in contracts 1.16.0:** `branding.style`: `fontPairing` (an id from the shared list, §3) and `corners` (`sharp` / `soft` / `round`). Optional and additive, so a minor version | Pages, sections and blocks, navigation, custom pages |
| | About (story, mission, vision, values, beliefs), Plan your visit, Leaders, Ministries, Give |
| | Messages and series (§7), simple events (§8), media library, per-page SEO |
| | Drafts, published versions, preview links |
- **Editing shared facts from the Website** (decision 10): the Website's admin shows the profile's
fields where they're used (service times on the Service times screen, the logo on Branding) and
saves them through **Accounts' API** with the admin's token, as ACCOUNTS-1.0-PLAN §7 proposed.
Accounts → Church profile stays the other way in.
- **Shared facts aren't drafts:** Accounts has no draft state, and Events shows the profile too.
A change to a shared fact goes live in every product straight away, and the Website's screens
say so ("Changes here show on all your church's sites at once"). The preview always shows the
current profile.
- **Legal pages:** the privacy notice is Accounts' (the version people agreed to), linked from the
footer. The Website adds its own terms and safeguarding pages from starter text.
- **Content is never tied to a template.** Every section stores its data (validated with a zod
schema per section type) and its chosen variant. Switching template keeps the data, and each
template maps every variant to its nearest look.
## 3. Templates and customisation
Four templates, decided in decision 19: **Heritage, Bold, Community, Clean** (ROADMAP §6). Rather
than adding more templates (more looks, but churches on the same one still look the same), each
template has room to vary in four ways, within limits that keep every site designed, accessible
and fast (decision 1).
**1. Template = structure.** The header and navigation style, the page rhythm, the default homepage
order and which variant each section starts with.
**2. Section variants.** Every section type comes in two or three layouts, and every template can
render every variant in its own style.
| Section | Variants |
|---|---|
| Hero | Photo · Video (muted, with a still for phones and reduced motion) · Collage · Split (image and text) · Text only |
| Service times and location | Panel · Inline strip · With map |
| Welcome / introduction | Text · Image and text · With pastor's photo and quote |
| Ministries | Cards · List · Alternating bands |
| Team / leaders | Faces grid · List · Featured (one large, rest small) |
| Upcoming events | Cards · List · Calendar strip |
| Latest message | Large video · Card · Compact |
| Invitation (call to action) | Banner · Centred · Image background |
**3. Style settings**, on one screen with a live preview:
| Setting | Options | Shared? |
|---|---|---|
| Font pairing | 8 pairings in a shared list (self-hosted, no Google Fonts requests); each template marks 3 as recommended, all 8 work everywhere | **Shared** (Events, Accounts, App) |
| Corners | Sharp · Soft · Round | **Shared** |
| Colours | From the profile (primary, accent); tints and shades built and contrast-checked (WCAG AA, darkened or lightened automatically, with a note why) | **Shared** (already) |
| Section colour | Light · Tinted (the church colour as a soft background) · Mixed with dark bands | Website |
| Spacing | Airy · Compact | Website |
| Buttons | Solid · Outline · Pill | Website |
| Image treatment | Natural · Black and white · Duotone in the church colour | Website |
| Header | Each template's options (e.g. Bold: transparent over the hero, or solid) | Website |
**4. Pages from blocks.** Besides the fixed pages (§6), churches add **custom pages** (Youth camp,
Our history, Kids…) from blocks: text, image and text, gallery, quote, video, FAQ, map, people
cards, call to action, divider. Blocks come in the same variants and follow the style settings.
**Not in 1.0:** free drag-and-drop layout, custom CSS, custom fonts. Each would break phone
layouts, accessibility or speed for some churches, and create support work. More templates can come
in 1.x (they're part of the product, ROADMAP §1 rule 3).
**Photos:** the setup checklist explains what photos work (people, not buildings; landscape for
heroes). The duotone treatment makes uneven photos look consistent. Every image needs alt text.
Uploads are resized into responsive sizes (WebP and JPEG).
## 4. Drafts, preview and publish
Decision 2: **one Publish for the whole site.**
- **The working copy** is the content tables the admin edits. **A published version** is an
immutable snapshot of all of them (`SiteVersion`: JSON, who, when, an optional note). Visitors
always see the latest published version.
- **Pending changes:** the admin header shows "N changes not published". The Publish screen lists
each change (page, section, setting; who made it, when), and any one can be **discarded** (back
to its published value).
- **Preview** (`/admin/preview`, or the Preview button anywhere): the whole site from the working
copy, **fully clickable** (navigation, events, messages, video), with a bar on top: phone /
tablet / desktop width, "Back to editing", the change count and **Publish**. The bar is outside
the page, so the page is laid out exactly as it will be.
- **Share a preview:** a link (`/preview/<token>`) for someone without an account, e.g. the pastor.
It expires after 7 days (or when revoked), shows the working copy as it is when opened, sends
`noindex`, and can't edit or publish.
- **Version history:** every publish is kept. **Restore** copies a version back into the working
copy, so it's previewed and published like any other change; nothing is lost.
- **Two editors at once:** one shared working copy, saved per field. A field changed by someone else
since it was opened warns before it's overwritten. Publish publishes everyone's changes, and the
list shows whose they are.
- **What doesn't wait for Publish** (decision 9): simple events and messages are things that happen
rather than the site's design, so each has its own Publish (and messages found automatically on
YouTube appear on their own, §7). Changes to shared profile facts go live straight away (§2).
- **Template switch:** the new template is a pending change like any other, so the whole site can be
previewed in it before publishing.
- Every publish, discard and restore is in the audit log.
## 5. Coming soon
Decision 3: until the site's **first publish**, the public address shows a **Coming soon** page, not
an empty site.
- From the church profile: logo, name, colours and fonts, service times and address, contact
details, social links, and buttons to the church's Events (and App) when they're linked. A short
"Our new website is on its way" line the admin can change.
- `noindex`, an empty sitemap, `robots.txt` as usual. Real HTTP 200, so the church's details are
still useful to someone who finds the address.
- Signed-in admins see a banner on it: "Your site isn't published yet. Preview it or publish it."
- After the first publish there is no going back to Coming soon in 1.0 (unpublishing isn't needed).
## 6. Pages
As ROADMAP §6, with these changes:
- **Contact:** **contact details only** (decision 4): address with a map, phone, email, WhatsApp,
service times, social links. No contact form (personal information belongs in the App, §6 "Not in
the first release").
- **Give:** information and the church's provider links (SnapScan, Zapper, PayFast page, bank
details as text). No giving processed.
- **Events:** list, detail, calendar, past (§8).
- **Messages:** list, series, detail (§7).
- **Home:** the sections in the template's order; the church can reorder, hide and show them.
- Every page: unique title and description, canonical, Open Graph image (generated from the logo and
colours when the page has none), JSON-LD (`Church` on home and contact, `Event`, `VideoObject`,
`BreadcrumbList`), exactly one `<h1>`, `lang="en-ZA"`. Slug changes get a 301 to the new slug
(within the site; moving domains is decision 6).
## 7. Messages
Decision 7: two ways in, chosen in **Messages → Settings**:
- **From YouTube, automatically.** The admin gives the church's **channel** or a **playlist** (a
playlist is better when the channel has other uploads). A job reads YouTube's public feed
(`youtube.com/feeds/videos.xml?channel_id=…` / `?playlist_id=…`, no API key) every hour, and each
new video becomes a message (title, date, thumbnail, video). Admins can add the speaker, series,
Bible passage and notes afterwards, or hide one. The newest is the home page's **Latest message**.
- **By hand.** Add a message with a **YouTube or Spotify link** (episode or show) and the same
details.
Both can be used together. Embeds load only when clicked (a thumbnail first), use
`youtube-nocookie.com`, and set `VideoObject` (or `PodcastEpisode` for Spotify) JSON-LD. Audio and
video are never uploaded (ROADMAP §10), so they don't count towards storage.
## 8. Events
- **Simple events** made in the Website (title, date and time, place, description, image, an
optional link). Only Cross Events takes registrations and payments (roadmap decision 4).
- **The event feed** as Events 2.4: Settings → Linked products, "Publish my events" and "Show events
from". Events from Cross Events show in the template's event cards and link through to Cross
Events for registering.
- **Imported events** carry `<link rel="canonical">` to the origin's page and aren't in the
Website's sitemap (ROADMAP §11). A source that's down keeps its last events showing.
## 9. Connected with Events and the App
Decision 8. The three products look like one church without looking like each other:
- **Brand style is shared** (§2, §3): the same colours, logo, font pairing and corners in the
Website, in Cross Events' public pages and Accounts' sign-in pages, and later in the App.
- **One footer.** `@crosscode/ui` gets a `ChurchFooter` built from the profile (logo, service times,
address, contact, social, links to the church's Website, Events and App, the privacy notice). The
Website uses it in every template (styled by the template), Events 3.7 and Accounts 1.7 use it on
their public pages.
- **Links between products:** each product's header has a link to the others that exist (from the
profile's `links`): "Events", "Website", later "App".
- **One sign-in and account menu** (already, through Accounts).
- **Events 3.7.0:** public pages (event list and detail, registration, the church's home) use the
shared fonts, corners and footer. Admin and staff screens stay as they are. Nothing else changes.
## 10. Admin, roles and storage
**Admin** (`/admin`, as ROADMAP §6): dashboard with the setup checklist ("Choose your template"
first, previewed with the church's own logo, colours and content, or sample content), pending
changes and recent edits; Template and style; Pages; About; Leaders; Ministries; Messages; Events;
Media library; Contact and service times; Navigation; Settings (SEO, search engine verification,
linked products, email); Version history; Audit log. Each field shows the Google-style snippet
preview and SEO warnings where they apply (ROADMAP §11).
**Roles** (per product, held in the Website; proposed in decision 11):
| Role | Can |
|---|---|
| Owner | Everything, including roles and the licence |
| Admin | Everything but the licence and Owners |
| Editor | Edit everything, preview, share previews, **publish** |
| Ministry leader | Edit their own ministry's page and events; their changes wait for an Editor or above to publish |
| Viewer | See the admin and the preview, change nothing |
Admin roles can require 2FA through Accounts (`acr_values=mfa`, ACCOUNTS-1.0-PLAN decision 8): on by
default for Owner and Admin.
**Storage** (ROADMAP §10): 5 GB of uploads included. Settings shows what's used; admins get an email
at 80% and at 100%. **When it's full, uploads stop** (decision 12) until more storage is bought:
the media library and every upload field say so, with **Get more storage** (Settings → Storage).
That asks the Hub, as Request update does, and the Hub emails Joshua. Once he adds a 5 GB step to the
licence, the new limit reaches the site with the next heartbeat answer (within a minute or so) and
uploads work again. Everything already uploaded keeps showing; only new uploads are refused. The
limit is the licence's (5 GB plus the steps bought), never the site's own setting. An upload is
only freed when neither the working copy nor the last 10 published versions use it.
## 11. Hub, licence and servers
- **Hub protocol v2, product `website`.** The heartbeat's `websiteStatsSchema` is already in the
contracts (pages, messages, events, editors, storage). A Website licence needs the church's
Accounts, installed first (as Events 3.x).
- **Hub 2.12.0:** New install offers the Website; release sync for `website@` tags and
`apps/website/WHATS-NEW.md`; its env template; the Website's price (R99) and the storage add-on
(R20 per extra 5 GB, sent to the site with the licence as its storage limit, and the "Get more storage"
request with its email to Joshua) in `frontend/src/lib/tiers.ts` and `backend/src/utils/billing/tiers.js`, in
step with crosscode-site; the FastPanel email for `www.` (and the bare domain sent to `www.` with a
301, for an own domain) or `<church>.crosscode.co.za`.
- **`crosscode`:** `scripts/products/website.sh` with the same hooks as Events and Accounts (`website`
is already in `PRODUCT_ORDER`), `website.env.template.json`, `crosscode add <church> website`. The
env template in three places, plus any value rules (HANDOVER, "A new .env variable").
- **Agent:** none expected. The job schemas already take `website` (`releaseTagSchema`, `PRODUCTS`).
The frp port list gets the Website's two ports.
- **Accounts 1.7.0:** `branding.style` on the church profile (and Accounts → Church profile), the
Website as a client through Connect (as Events), the profile API allowing the Website's admins to
save, the shared fonts and footer on its pages.
- **Uninstall:** the church export (`crosscode.church-export/1`) gets a `website` section (content,
versions' notes, messages, events) and the uploaded media, as Events' export does its uploads.
- **Demo church:** `npm run demo` loads a fictional church (fictional people and photos only) into
each template, for the crosscode-site screenshots and the Hub's demo sites.
## 12. What changes in each repo
| Repo | Change | Version |
|------|--------|---------|
| `crosscode-platform` `apps/website` | New (§1–§11), with `CHANGELOG.md`, `WHATS-NEW.md`, `env.template.json`, e2e, demo data | `website@1.0.0` |
| `crosscode-platform` `packages/contracts` | `branding.style` (`fontPairing`, `corners`) on `crosscode.church/1`, the font pairing ids, a `website` part of the church export | `contracts@1.16.0` |
| `crosscode-platform` `packages/ui` | Fonts (self-hosted), the theme from the profile (colours, fonts, corners as CSS variables), `ChurchFooter`, links between products, the public site's building blocks | workspace |
| `crosscode-platform` `packages/seo` | `Church`, `VideoObject`, `PodcastEpisode`, `BreadcrumbList` builders, the generated share image | workspace |
| `crosscode-platform` `apps/accounts` | `branding.style` in the church profile, the shared fonts and footer, the Website's admins saving the profile | `accounts@1.7.0` |
| `crosscode-platform` `apps/events` | Public pages with the shared fonts, corners and footer | `events@3.7.0` |
| `crosscode-platform` `scripts/` | `products/website.sh`, `website.env.template.json`, bats tests | — |
| `events-hub` | Website in New install, its releases, env template, prices and storage add-on, FastPanel email | Hub `v2.12.0` |
| `crosscode-site` | Church Website on sale (ROADMAP §9): its page, prices, a page per template, screenshots of the demo church, FAQ, `SoftwareApplication` JSON-LD | `v1.7.0` |
## 13. Testing
- **Unit (Jest):** section schemas and variants, the palette builder and contrast fixes, publish /
discard / restore, pending change lists, preview tokens (expiry, revoke, no edit rights), roles
(a Ministry leader can't publish or edit another ministry), the YouTube feed parser (channel,
playlist, duplicates, a removed video), storage counting, uploads refused when full (and allowed again when the licence's limit goes
up), uploads kept by older versions.
- **Playwright, every template at phone / tablet / desktop:** the demo church's pages look right
(screenshots compared), axe has no violations, the §11 checks (title, description, canonical,
`og:image`, one `<h1>`, JSON-LD parses, sitemap, `robots.txt`, `noindex` where it should be).
- **Playwright, the flows:** Coming soon before the first publish; edit → preview (click through
the site) → publish → the public site changes; discard one change; a shared preview link works
signed out and stops after revoking; restore an older version; switch template in preview and
back without losing anything; sign in from a deep admin page and land back on it (through 2FA).
- **Lighthouse (mobile):** home, an event and a message in each template: SEO 100,
accessibility 95+, performance 90+.
- **Events 3.7:** the e2e suite still passes, and its public pages show the church's fonts and the
shared footer.
- **The release checks** (ROADMAP §9) for the Website, and the **VM test**: install the Website
next to Accounts and Events through the agent, update it, uninstall it with its export.
## 14. Releasing and rolling it out
1. `contracts@1.16.0`, then `accounts@1.7.0` (the profile's brand style), then `events@3.7.0`.
2. Hub `v2.12.0` (vendored contracts 1.16.0) deployed.
3. `website@1.0.0` tagged after the e2e, Lighthouse and VM runs.
4. **Hope Family Church:** Accounts 1.7.0 and Events 3.7.0 first, then New install → Website. The
site shows Coming soon while the church builds it, and goes live with its first publish.
5. **A second test church** on a different template.
6. crosscode-site `v1.7.0`: the Website on sale.
## Decisions
Made by Joshua on 2026-11-21:
1. **Customisation within limits:** four templates, each with section variants, style settings and
custom pages from blocks (§3). No free layout, custom CSS or custom fonts. More templates later,
not instead.
2. **One Publish for the whole site,** after a fully clickable preview (§4), with a shareable preview
link and version history.
3. **Coming soon** until the first publish (§5).
4. **Contact page: details only,** no form (§6).
5. **Leaders, ministries, About, giving and messages are Website-only** for now (§2). Only the brand
style (font pairing, corners) is added to the shared profile.
6. **No address move or redirects in 1.0,** and no Hub "Change address" job yet. Moving to the
church's own domain (ROADMAP §10, §11 "Moving addresses") comes later.
7. **Messages from a YouTube channel or playlist automatically, or by hand with a YouTube or
Spotify link** (§7).
8. **The three products feel connected:** shared brand style and footer, and **Events 3.7** uses the
shared fonts and footer on its public pages (§9).
Proposed and confirmed on 2026-11-21 (12 changed):
9. **Simple events and messages publish on their own,** not with the site's Publish; YouTube messages
appear automatically (§4, §7).
10. **The Website's admin edits shared profile facts through Accounts' API,** and they go live
straight away (§2). Answers ACCOUNTS-1.0-PLAN's "Still open".
11. **Editors can publish; Ministry leaders' changes wait** for an Editor or above (§10).
12. **A full storage stops uploads** until more is bought (admins emailed at 80% and 100%; "Get more
storage" asks the Hub; §10). Changed from the proposal, which let uploads carry on and billed
afterwards.
13. **Fonts are self-hosted** (no Google Fonts requests, for POPIA and speed), from a shared list of 8
pairings (§3).
14. **Coming soon is a real page (HTTP 200) with `noindex`,** not a 503 (§5).
## Still open
- The 8 font pairings and the exact variants per template: settled with the template designs, early
in the build.
- Whether the App (phase 6) moves leaders, ministries and giving into `crosscode.church/1` or reads
them from the Website. Decide with the App plan.
+4 -4
View File
@@ -109,7 +109,7 @@
},
"apps/agent": {
"name": "@crosscode/agent",
"version": "1.3.1",
"version": "1.4.0",
"license": "UNLICENSED",
"dependencies": {
"@crosscode/contracts": "*",
@@ -128,7 +128,7 @@
},
"apps/events/backend": {
"name": "@crosscode/events-backend",
"version": "3.6.0",
"version": "3.6.1",
"hasInstallScript": true,
"dependencies": {
"@cj-tech-master/excelts": "^10.2.0",
@@ -178,7 +178,7 @@
},
"apps/events/frontend": {
"name": "@crosscode/events-frontend",
"version": "3.6.0",
"version": "3.6.1",
"dependencies": {
"@crosscode/contracts": "*",
"@crosscode/seo": "*",
@@ -21276,7 +21276,7 @@
},
"packages/contracts": {
"name": "@crosscode/contracts",
"version": "1.14.0",
"version": "1.15.0",
"license": "UNLICENSED",
"dependencies": {
"zod": "^4.6.7"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.14.0",
"version": "1.15.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED",
"type": "commonjs",
+314
View File
@@ -1675,6 +1675,320 @@
"args"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.agent-job/1"
},
"id": {
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]{8,64}$"
},
"serverId": {
"type": "string",
"pattern": "^srv_[A-Za-z0-9_-]{8,64}$"
},
"config": {
"anyOf": [
{
"type": "object",
"properties": {
"alg": {
"type": "string",
"const": "x25519-hkdf-sha256-aes-256-gcm"
},
"epk": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
},
"iv": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16}$"
},
"ciphertext": {
"type": "string",
"maxLength": 200000,
"pattern": "^[A-Za-z0-9_-]+$"
}
},
"required": [
"alg",
"epk",
"iv",
"ciphertext"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"notBefore": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"signature": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{86}$"
},
"type": {
"type": "string",
"const": "frp-read"
},
"args": {
"type": "object",
"properties": {
"path": {
"type": "string",
"maxLength": 255,
"allOf": [
{
"pattern": "^\\/(?!.*\\/\\.\\.?(\\/|$))[A-Za-z0-9._/-]+$"
},
{
"pattern": "\\/frp[A-Za-z0-9._-]*\\.(ini|toml)$"
}
]
}
},
"additionalProperties": false
}
},
"required": [
"schema",
"id",
"serverId",
"notBefore",
"expiresAt",
"signature",
"type",
"args"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.agent-job/1"
},
"id": {
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]{8,64}$"
},
"serverId": {
"type": "string",
"pattern": "^srv_[A-Za-z0-9_-]{8,64}$"
},
"config": {
"anyOf": [
{
"type": "object",
"properties": {
"alg": {
"type": "string",
"const": "x25519-hkdf-sha256-aes-256-gcm"
},
"epk": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
},
"iv": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16}$"
},
"ciphertext": {
"type": "string",
"maxLength": 200000,
"pattern": "^[A-Za-z0-9_-]+$"
}
},
"required": [
"alg",
"epk",
"iv",
"ciphertext"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"notBefore": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"signature": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{86}$"
},
"type": {
"type": "string",
"const": "frp-write"
},
"args": {
"type": "object",
"properties": {
"path": {
"type": "string",
"maxLength": 255,
"allOf": [
{
"pattern": "^\\/(?!.*\\/\\.\\.?(\\/|$))[A-Za-z0-9._/-]+$"
},
{
"pattern": "\\/frp[A-Za-z0-9._-]*\\.(ini|toml)$"
}
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 64000
},
"restart": {
"type": "boolean"
}
},
"required": [
"path",
"content",
"restart"
],
"additionalProperties": false
}
},
"required": [
"schema",
"id",
"serverId",
"notBefore",
"expiresAt",
"signature",
"type",
"args"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "crosscode.agent-job/1"
},
"id": {
"type": "string",
"pattern": "^job_[A-Za-z0-9_-]{8,64}$"
},
"serverId": {
"type": "string",
"pattern": "^srv_[A-Za-z0-9_-]{8,64}$"
},
"config": {
"anyOf": [
{
"type": "object",
"properties": {
"alg": {
"type": "string",
"const": "x25519-hkdf-sha256-aes-256-gcm"
},
"epk": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
},
"iv": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{16}$"
},
"ciphertext": {
"type": "string",
"maxLength": 200000,
"pattern": "^[A-Za-z0-9_-]+$"
}
},
"required": [
"alg",
"epk",
"iv",
"ciphertext"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"notBefore": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
},
"signature": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{86}$"
},
"type": {
"type": "string",
"const": "probe-ports"
},
"args": {
"type": "object",
"properties": {
"ports": {
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "integer",
"minimum": 1024,
"maximum": 65535
}
}
},
"required": [
"ports"
],
"additionalProperties": false
}
},
"required": [
"schema",
"id",
"serverId",
"notBefore",
"expiresAt",
"signature",
"type",
"args"
],
"additionalProperties": false
}
]
}
@@ -31,6 +31,9 @@
"uninstall",
"purge",
"update-agent",
"frp-read",
"frp-write",
"probe-ports",
"check-ports",
"status"
]
@@ -280,6 +280,17 @@
"type": "null"
}
]
},
"frpConfigPath": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
]
}
},
"required": [
+80 -3
View File
@@ -81,6 +81,25 @@ export const isSecretEnvName = (name: string): boolean => SECRET_ENV_NAME.test(n
/** At most this many changes in one `env-set` job. */
export const ENV_SET_MAX = 50;
/** The first agent that runs `frp-read`, `frp-write` and `probe-ports` jobs (an older one refuses the unknown types). */
export const FRP_JOBS_MIN_AGENT = "1.4.0";
/**
* Where frps (central server) or frpc (church server) keeps its config: an absolute path to a file
* whose name starts with `frp` and ends in `.ini` or `.toml` (`/etc/frp/frps.toml`).
*/
export const frpConfigPathSchema = serverPathSchema.regex(/\/frp[A-Za-z0-9._-]*\.(ini|toml)$/, "Expected the path of frps's or frpc's config: a file named frp….ini or frp….toml");
/** The longest frp config the Hub reads or writes. */
export const FRP_CONFIG_MAX = 64_000;
/**
* Secret values in an frp config (token, passwords) never leave the server: `frp-read` shows them
* as this, and `frp-write` puts the server's own value back where it finds it. A secret can't be
* changed from the Hub.
*/
export const FRP_HIDDEN = "***hidden***";
/** Each job type and the arguments it takes. Unknown keys are refused, not stripped. */
export const jobArgsSchemas = {
/** `crosscode install <church> --products … --frp --json` */
@@ -151,6 +170,24 @@ export const jobArgsSchemas = {
purge: z.strictObject({ church: shortNameSchema }),
/** The agent updates itself to that tag. */
"update-agent": z.strictObject({ version: agentTagSchema }),
/**
* frps's config (central server) or frpc's (church server), secrets hidden: an {@link frpReadResultSchema}.
* With `path`, the agent uses (and remembers) that file instead of the one it finds itself.
*/
"frp-read": z.strictObject({ path: frpConfigPathSchema.optional() }),
/**
* Replaces frps's or frpc's config: secrets put back from the file on the server, checked with
* `frps verify` / `frpc verify`, a backup kept, then (with `restart`) the service restarted. When
* it doesn't come back, the old file is put back (`rolled-back`). `path` must be the file the
* agent uses now (what the last `frp-read` showed).
*/
"frp-write": z.strictObject({ path: frpConfigPathSchema, content: z.string().min(1).max(FRP_CONFIG_MAX), restart: z.boolean() }),
/**
* Before an install: which of these ports are free here? On the central server: nothing listens
* on it and frps's allow_ports has it. On a church server: nothing listens on it and frpc's config
* doesn't use it. The result is a {@link probePortsResultSchema}.
*/
"probe-ports": z.strictObject({ ports: z.array(portSchema).min(1).max(50) }),
/** Central server only: are these ports allowed, open and bound to 127.0.0.1? */
"check-ports": z.strictObject({ ports: z.array(portSchema).min(1).max(50) }),
/** `crosscode status [<church>] --json` */
@@ -163,12 +200,13 @@ export const jobTypeSchema = z.enum(JOB_TYPES as [JobType, ...JobType[]]);
export type JobArgs<T extends JobType> = z.infer<(typeof jobArgsSchemas)[T]>;
/** The only jobs a central agent runs (§3). */
export const CENTRAL_JOB_TYPES: readonly JobType[] = ["check-ports", "status", "update-agent"];
export const CENTRAL_JOB_TYPES: readonly JobType[] = ["check-ports", "status", "update-agent", "frp-read", "frp-write", "probe-ports"];
/** Time limits per job type, in minutes (§3). A job past it is stopped and reported as failed. */
export const JOB_TIME_LIMIT_MINUTES: Record<JobType, number> = {
install: 30, "add-product": 30, deploy: 20, adopt: 30, "adopt-undo": 15, restart: 5, "seed-demo": 15, "env-read": 2, "env-set": 20, export: 20,
uninstall: 20, purge: 10, "update-agent": 15, "check-ports": 2, status: 3,
"frp-read": 2, "frp-write": 5, "probe-ports": 2,
};
/** Config sealed to the server's X25519 key (`sealConfig` in `@crosscode/contracts/signing`). */
@@ -213,6 +251,7 @@ function jobOf<T extends JobType>(type: T) {
export const agentJobSchema = z.discriminatedUnion("type", [
jobOf("install"), jobOf("add-product"), jobOf("deploy"), jobOf("adopt"), jobOf("adopt-undo"), jobOf("restart"), jobOf("seed-demo"),
jobOf("env-read"), jobOf("env-set"), jobOf("export"), jobOf("uninstall"), jobOf("purge"), jobOf("update-agent"), jobOf("check-ports"), jobOf("status"),
jobOf("frp-read"), jobOf("frp-write"), jobOf("probe-ports"),
]);
export type AgentJob = z.infer<typeof agentJobSchema>;
export type UnsignedAgentJob = Omit<AgentJob, "signature">;
@@ -280,9 +319,9 @@ export const processStatSchema = z.object({
});
export const centralStatSchema = z.object({
/** `proxy_bind_addr` in frps.ini, null when it isn't set (tunnels then open on every address). */
/** `proxy_bind_addr` (frps.ini) or `proxyBindAddr` (frps.toml), null when it isn't set (tunnels then open on every address). */
proxyBindAddr: z.string().max(100).nullable(),
/** `allow_ports` in frps.ini as written, e.g. `20000-29999`. */
/** `allow_ports` as written (`20000-29999`); frps.toml's `allowPorts` is written the same way. */
allowPorts: z.string().max(2000).nullable(),
frpsRunning: z.boolean().nullable(),
});
@@ -298,6 +337,8 @@ export const agentStatsSchema = z.object({
frpcRunning: z.boolean().nullable(),
processes: z.array(processStatSchema).max(200),
central: centralStatSchema.nullable().optional(),
/** Agent 1.4.0+: the frps (central) or frpc (church) config the agent uses, null when it found none. */
frpConfigPath: z.string().max(255).nullable().optional(),
});
export type AgentStats = z.infer<typeof agentStatsSchema>;
@@ -395,6 +436,42 @@ export const envReadResultSchema = z.object({
});
export type EnvReadResult = z.infer<typeof envReadResultSchema>;
// ---------------------------------------------------------------------------------------------
// frp config and free ports (contracts 1.15.0, agent 1.4.0)
// ---------------------------------------------------------------------------------------------
/** How the agent found the frp config: set from the Hub, the systemd unit's `-c`, or a usual place. */
export const FRP_CONFIG_SOURCES = ["hub", "systemd", "usual-place"] as const;
/** The `result` of an `frp-read` report (and of an `frp-write` that went through). */
export const frpReadResultSchema = z.object({
/** `frps` on the central server, `frpc` on a church server. */
service: z.enum(["frps", "frpc"]),
path: z.string().max(255).nullable(),
source: z.enum(FRP_CONFIG_SOURCES).nullable(),
found: z.boolean(),
format: z.enum(["ini", "toml"]).nullable(),
/** The file with each secret value replaced by {@link FRP_HIDDEN}. */
content: z.string().max(FRP_CONFIG_MAX).nullable(),
/** The names of the hidden values (`token`, `auth.token`, `webServer.password` …). */
hidden: z.array(z.string().max(100)).max(50),
/** frps only (null on a church server): what the Hub checks. */
proxyBindAddr: z.string().max(100).nullable(),
allowPorts: z.string().max(2000).nullable(),
serviceRunning: z.boolean().nullable(),
/** Where the agent looked, when it found nothing. */
looked: z.array(z.string().max(255)).max(20).optional(),
readAt: dateTimeSchema,
});
export type FrpReadResult = z.infer<typeof frpReadResultSchema>;
/** The `result` of a `probe-ports` report. */
export const probePortsResultSchema = z.object({
ports: z.array(z.object({ port: portSchema, free: z.boolean(), reason: z.string().max(200).nullable() })).max(50),
configPath: z.string().max(255).nullable(),
});
export type ProbePortsResult = z.infer<typeof probePortsResultSchema>;
/** The variables a layer must provide for a template, that it doesn't (the Hub's check before a job). */
export function missingRequired(template: EnvTemplate, layer: "server" | "defaults", values: Record<string, string | undefined>): string[] {
const missing: string[] = [];
+35
View File
@@ -240,3 +240,38 @@ describe("env templates", () => {
expect(agent.invalidValues({ TRUST_PROXY: "loopback" })).toEqual({});
});
});
describe("frp config and free ports (1.15.0)", () => {
const read = (a: Record<string, unknown>) => agent.jobArgsSchemas["frp-read"].safeParse(a).success;
const write = (a: Record<string, unknown>) => agent.jobArgsSchemas["frp-write"].safeParse({ path: "/etc/frp/frps.toml", content: "bindPort = 7000\n", restart: true, ...a }).success;
it("read the config the agent finds, or one at a path", () => {
expect(read({})).toBe(true);
expect(read({ path: "/etc/frp/frps.toml" })).toBe(true);
expect(read({ path: "/usr/local/frp/frpc.ini" })).toBe(true);
for (const path of ["/etc/shadow", "etc/frp/frps.ini", "/etc/frp/../shadow/frps.ini", "/etc/frp/frps.ini; rm -rf /", "/etc/frp/frps.service", "/etc/frp/server.toml"]) expect(read({ path })).toBe(false);
expect(read({ path: "/etc/frp/frps.ini", extra: 1 })).toBe(false);
});
it("write one, with content and whether to restart", () => {
expect(write({})).toBe(true);
expect(write({ content: "" })).toBe(false);
expect(write({ content: "x".repeat(agent.FRP_CONFIG_MAX + 1) })).toBe(false);
expect(write({ path: "/etc/passwd" })).toBe(false);
expect(write({ restart: "yes" })).toBe(false);
});
it("probe ports", () => {
expect(agent.jobArgsSchemas["probe-ports"].safeParse({ ports: [20000, 20001] }).success).toBe(true);
expect(agent.jobArgsSchemas["probe-ports"].safeParse({ ports: [] }).success).toBe(false);
expect(agent.jobArgsSchemas["probe-ports"].safeParse({ ports: [80] }).success).toBe(false);
});
it("the central agent runs all three", () => {
expect(agent.CENTRAL_JOB_TYPES).toEqual(expect.arrayContaining(["frp-read", "frp-write", "probe-ports"]));
expect(agent.JOB_TIME_LIMIT_MINUTES["frp-write"]).toBeGreaterThan(0);
});
it("results", () => {
expect(agent.frpReadResultSchema.safeParse({
service: "frps", path: "/etc/frp/frps.toml", source: "systemd", found: true, format: "toml", content: `auth.token = "${agent.FRP_HIDDEN}"\n`, hidden: ["auth.token"],
proxyBindAddr: "127.0.0.1", allowPorts: "20000-29999", serviceRunning: true, readAt: "2026-11-21T10:00:00.000Z",
}).success).toBe(true);
expect(agent.probePortsResultSchema.safeParse({ ports: [{ port: 20000, free: false, reason: "in use" }], configPath: null }).success).toBe(true);
});
});
+1 -1
View File
@@ -2,7 +2,7 @@
Shared UI for the products a church's members see: the branded shell, cards, buttons, form fields
and notices. First used by Accounts' sign-in and account pages (phase 3); the Church Website and
App build on it (phases 4 and 6).
App build on it (phases 5 and 6).
- Plain React + Tailwind, no runtime dependencies. Apps compile the source
(`transpilePackages: ["@crosscode/ui"]` in `next.config.ts`) and add
+18 -4
View File
@@ -355,10 +355,24 @@ node_major() { node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo
# Files changed or added by hand in a checkout (ignored files such as .env, uploads, backups and
# the install's ecosystem.config.js never count). The PM2 configs this script makes for each
# install never count either, also in checkouts of releases that don't ignore them yet (Accounts
# 1.0–1.1 has no .gitignore for its ecosystem.config.cjs).
# 1.0–1.1 has no .gitignore for its ecosystem.config.cjs). Nor do the files in the folders this
# script writes into (Accounts below 1.3.0 doesn't ignore the database dumps made before each
# deploy, so the dump would stop the very deploy that brings the .gitignore).
CROSSCODE_OWN_FILES=(apps/events/ecosystem.config.js apps/accounts/ecosystem.config.cjs)
CROSSCODE_OWN_DIRS=(apps/accounts/backend/backups/)
local_changes() {
git_in "$1" status --porcelain --untracked-files=all | awk -v own="${CROSSCODE_OWN_FILES[*]}" '
BEGIN { n = split(own, f, " "); for (i = 1; i <= n; i++) skip[f[i]] = 1 }
!(substr($0, 1, 2) == "??" && substr($0, 4) in skip)'
git_in "$1" status --porcelain --untracked-files=all |
awk -v own="${CROSSCODE_OWN_FILES[*]}" -v dirs="${CROSSCODE_OWN_DIRS[*]}" '
BEGIN {
n = split(own, f, " "); for (i = 1; i <= n; i++) skip[f[i]] = 1
m = split(dirs, d, " ")
}
{
if (substr($0, 1, 2) == "??") {
path = substr($0, 4)
if (path in skip) next
for (i = 1; i <= m; i++) if (index(path, d[i]) == 1) next
}
print
}'
}
+10 -7
View File
@@ -517,15 +517,18 @@ server {
server_name $domain;
client_max_body_size 25m;
# For the backend locations below ("location /" sets its own).
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
# The API, uploaded files, health and API docs go to the backend; everything else to the site.
# (From Events 2.2.0 everything is under /api; the other paths are for older releases.)
location ~ ^/(api|uploads|health|docs)(/|\$) {
proxy_pass http://127.0.0.1:$api;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
}
# ^~ so a regex location added later (e.g. caching *.png) can't send /api/…/logo.png to the site.
location ^~ /api/ { proxy_pass http://127.0.0.1:$api; }
location ^~ /uploads/ { proxy_pass http://127.0.0.1:$api; }
location ~ ^/(api|uploads|health|docs)(/|\$) { proxy_pass http://127.0.0.1:$api; }
location / {
proxy_pass http://127.0.0.1:$web;
proxy_http_version 1.1;
+14
View File
@@ -159,6 +159,20 @@ cc() { bash "$CROSSCODE_HOME/crosscode" "$@"; }
[[ "$output" == *"apps/accounts/notes.txt"* ]]
}
@test "the database dumps crosscode makes don't count as changes by hand" {
# Accounts below 1.3.0 has no .gitignore for backend/backups/.
mkdir -p "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups"
echo "dump" > "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups/accounts-20261119-221205.sql.gz"
run cc deploy hope events --version events@2.2.1 --check
[ "$status" -eq 0 ]
# A file merely named like the folder still counts.
echo "notes" > "$CROSSCODE_SITES/hope/events/apps/accounts/backend/backups.txt"
run cc deploy hope events --version events@2.2.1 --check
[ "$status" -eq 1 ]
[[ "$output" == *"apps/accounts/backend/backups.txt"* ]]
[[ "$output" != *"accounts-20261119-221205.sql.gz"* ]]
}
@test "--allow-local-changes deploys with a file added by hand" {
echo "notes" > "$CROSSCODE_SITES/hope/events/apps/events/notes.txt"
run cc deploy hope events --version events@2.2.1