Compare commits
20
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ce1c978f21 | ||
|
|
8542d19be0 | ||
|
|
4cc30c1445 | ||
|
|
d91d956e78 | ||
|
|
9f07ecf0dd | ||
|
|
74df4aa7b5 | ||
|
|
72a6283024 | ||
|
|
86711699cf | ||
|
|
d28029e96e | ||
|
|
e65e26202a | ||
|
|
ca55142f6f | ||
|
|
1b94814f67 | ||
|
|
0b70a87669 | ||
|
|
ead07ef932 | ||
|
|
d8312f4b33 | ||
|
|
a9239d429a | ||
|
|
405b5f1b92 | ||
|
|
c8c5db46bc | ||
|
|
031fb11e02 | ||
|
|
16d3ffe6ba |
@@ -2,6 +2,42 @@
|
||||
|
||||
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
|
||||
sign-in, as Cross Events' own sign-in did; Sign-in settings → `signin_notices` turns it off.
|
||||
|
||||
## events@3.6.0, accounts@1.5.0, contracts@1.14.0 - 2026-11-20
|
||||
|
||||
A nightly check that each site's copies of people match their church accounts, for changes that
|
||||
|
||||
@@ -1,5 +1,18 @@
|
||||
# Changelog — Accounts
|
||||
|
||||
## [1.6.0] - 2026-11-20
|
||||
|
||||
### Added
|
||||
|
||||
- **"New sign-in" notices**, as Cross Events' own sign-in sends (`src/accounts/signInNotice.ts`):
|
||||
after each completed sign-in (the interaction reaching done, so not the silent ones a second
|
||||
product gets from an existing session), an email with when, the site, rough location and device
|
||||
(`newSignInEmail` in `src/lib/emails.ts`), and a WhatsApp message when the person has a verified
|
||||
number and WhatsApp is set up. Location from ip-api.com in production only, never for private
|
||||
addresses. Fire-and-forget: never holds up or fails a sign-in. Admins can turn it off:
|
||||
`signin_notices` (Sign-in settings, on by default). In Accounts mode Cross Events no longer sends
|
||||
its own, so before this nobody was told.
|
||||
|
||||
## [1.5.0] - 2026-11-20
|
||||
|
||||
Needs contracts 1.14.0.
|
||||
|
||||
@@ -3,6 +3,13 @@
|
||||
What each version changes for the church, in plain language (read by the Hub like Cross Events'
|
||||
WHATS-NEW.md; a section shows once its version is tagged).
|
||||
|
||||
## 1.6.0
|
||||
|
||||
- **You're told about each sign-in.** After someone signs in, they get an email saying when, roughly
|
||||
where, on what device and to which site, with what to do if it wasn't them, as Cross Events
|
||||
does for its own sign-in. People with a confirmed WhatsApp number get it on WhatsApp too.
|
||||
Admins can turn this off under Sign-in settings.
|
||||
|
||||
## 1.5.0
|
||||
|
||||
- Your church's sites can now check every night that the details they keep for each person match
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@crosscode/accounts-backend",
|
||||
"version": "1.5.0",
|
||||
"version": "1.6.0",
|
||||
"description": "Cross Code Accounts: the church's sign-in (OpenID Connect provider), account pages API and admin API",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
/**
|
||||
* "New sign-in" notices (1.6.0), as Cross Events sends for its own sign-in: after each completed
|
||||
* sign-in, an email to the person, and a WhatsApp message too when they have a verified number and
|
||||
* WhatsApp is set up. Admins can turn them off (Sign-in settings, `signin_notices`). Never holds up
|
||||
* or fails the sign-in.
|
||||
*
|
||||
* The rough location comes from the IP (ip-api.com, as Cross Events), in production only, and never
|
||||
* for private addresses.
|
||||
*/
|
||||
import type { Ctx } from '../context.js';
|
||||
import { newSignInEmail } from '../lib/emails.js';
|
||||
import { productName } from '../oidc/clients.js';
|
||||
|
||||
const PRIVATE_IP = /^(::1$|127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|fc|fd|fe80|::ffff:(127|10|192\.168)\.)/i;
|
||||
|
||||
/** "Chrome on Windows" from a user agent; the raw string when it can't tell. */
|
||||
export function describeDevice(ua: string | null | undefined): string {
|
||||
const s = String(ua || '');
|
||||
if (!s) return 'Unknown device';
|
||||
const browser = /Edg\//.test(s) ? 'Edge' : /OPR\/|Opera/.test(s) ? 'Opera' : /Firefox\//.test(s) ? 'Firefox'
|
||||
: /SamsungBrowser\//.test(s) ? 'Samsung Internet' : /Chrome\//.test(s) ? 'Chrome' : /Safari\//.test(s) ? 'Safari' : null;
|
||||
const os = /iPhone|iPad|iPod/.test(s) ? 'iPhone or iPad' : /Android/.test(s) ? 'Android' : /Windows/.test(s) ? 'Windows'
|
||||
: /Mac OS X|Macintosh/.test(s) ? 'a Mac' : /CrOS/.test(s) ? 'a Chromebook' : /Linux/.test(s) ? 'Linux' : null;
|
||||
if (browser && os) return `${browser} on ${os}`;
|
||||
return browser || os || s.slice(0, 120);
|
||||
}
|
||||
|
||||
async function roughLocation(ctx: Ctx, ip: string | null): Promise<string> {
|
||||
if (!ip || PRIVATE_IP.test(ip) || !ctx.config.production) return 'Unknown';
|
||||
try {
|
||||
const res = await fetch(`http://ip-api.com/json/${encodeURIComponent(ip.replace(/^::ffff:/, ''))}?fields=status,city,regionName,country`, { signal: AbortSignal.timeout(3000) });
|
||||
const geo = (await res.json()) as { status?: string; city?: string; regionName?: string; country?: string };
|
||||
const parts = geo.status === 'success' ? [geo.city, geo.regionName, geo.country].filter(Boolean) : [];
|
||||
return parts.length ? parts.join(', ') : 'Unknown';
|
||||
} catch {
|
||||
return 'Unknown';
|
||||
}
|
||||
}
|
||||
|
||||
export async function sendSignInNotice(ctx: Ctx, o: { accountId: string; ip: string | null; userAgent: string | null; clientId: string | null }): Promise<'sent' | 'off' | 'failed'> {
|
||||
try {
|
||||
if (!(await ctx.settings.bool('signin_notices', true))) return 'off';
|
||||
const a = await ctx.db.account.findUnique({ where: { id: o.accountId } });
|
||||
if (!a || a.status !== 'active') return 'off';
|
||||
const link = o.clientId ? await ctx.db.productLink.findUnique({ where: { installId: o.clientId } }) : null;
|
||||
const site = link ? productName(link.product) : o.clientId === 'accounts-self' ? 'Your account page' : null;
|
||||
const when = ctx.now().toLocaleString('en-ZA', { timeZone: ctx.config.timezone, dateStyle: 'medium', timeStyle: 'short' });
|
||||
const msg = await newSignInEmail(ctx, { name: a.name, when, location: await roughLocation(ctx, o.ip), device: describeDevice(o.userAgent), site });
|
||||
await ctx.messenger.email({ to: a.email, subject: msg.subject, text: msg.text, html: msg.html });
|
||||
if (a.phone && a.phoneVerified && (await ctx.messenger.whatsappReady())) {
|
||||
await ctx.messenger.whatsapp({ to: a.phone, text: msg.whatsapp }).catch((e: Error) => console.warn('[sign-in notice] WhatsApp:', e.message));
|
||||
}
|
||||
return 'sent';
|
||||
} catch (e) {
|
||||
console.warn('[sign-in notice] not sent:', (e as Error).message);
|
||||
return 'failed';
|
||||
}
|
||||
}
|
||||
@@ -8,7 +8,8 @@ import type Provider from 'oidc-provider';
|
||||
import { decodeState, encodeState, safeReturnPath } from '@crosscode/contracts';
|
||||
import type { Ctx } from '../context.js';
|
||||
import { ApiError, handle, limit } from '../http.js';
|
||||
import { loginEvent } from '../lib/audit.js';
|
||||
import { clientIp, loginEvent } from '../lib/audit.js';
|
||||
import { sendSignInNotice } from '../accounts/signInNotice.js';
|
||||
import { resetPasswordEmail } from '../lib/emails.js';
|
||||
import { hashToken, randomToken } from '../lib/crypto.js';
|
||||
import { hashPassword, passwordProblem } from '../lib/passwords.js';
|
||||
@@ -44,6 +45,8 @@ export function interactionRouter(ctx: Ctx, provider: Provider) {
|
||||
const clientId = String(details.params.client_id ?? '') || null;
|
||||
await loginEvent(ctx, pending.accountId, 'sign_in', req, { clientId, detail: { amr: pending.amr } });
|
||||
await signedInThrough(ctx, clientId, pending.accountId);
|
||||
// 1.6.0: "New sign-in" email (and WhatsApp), as Cross Events; never waited for.
|
||||
if (pending.accountId) void sendSignInNotice(ctx, { accountId: pending.accountId, ip: clientIp(req), userAgent: req.get('user-agent') ?? null, clientId });
|
||||
await ctx.db.pendingSignIn.deleteMany({ where: { uid: pending.uid } });
|
||||
return { stage: 'done', redirectTo, ...extra };
|
||||
}
|
||||
|
||||
@@ -206,3 +206,20 @@ export async function testEmail(ctx: Ctx, o: { from?: string } = {}): Promise<Bu
|
||||
: 'Email from Accounts works.';
|
||||
return { subject: o.from ? `Test email from ${b.name}'s sign-in` : 'Test email from Accounts', text, html: layout(b, body, 'A test email: email works.') };
|
||||
}
|
||||
|
||||
/** A sign-in happened (1.6.0, as Cross Events' "New login detected"). `whatsapp`: the same in a few lines. */
|
||||
export async function newSignInEmail(ctx: Ctx, o: { name?: string | null; when: string; location: string; device: string; site: string | null }): Promise<Built & { whatsapp: string }> {
|
||||
const b = await brand(ctx);
|
||||
const row = (k: string, v: string) => `<tr><td style="padding:10px 14px;border-top:1px solid #f1f5f9;color:#64748b;font-size:13px;font-weight:600;width:34%">${esc(k)}</td><td style="padding:10px 14px;border-top:1px solid #f1f5f9;color:#1e293b;font-size:14px;word-break:break-word">${esc(v)}</td></tr>`;
|
||||
const body = title('New sign-in', `Someone signed in to your ${b.name} account`)
|
||||
+ hello(o.name)
|
||||
+ `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border:1px solid #e2e8f0;border-radius:8px;overflow:hidden;margin:0 0 8px 0">`
|
||||
+ row('When', o.when) + (o.site ? row('Signed in to', o.site) : '') + row('Where (roughly)', o.location) + row('Device', o.device)
|
||||
+ '</table>'
|
||||
+ callout(`<strong>Not you?</strong> Change your password straight away from your account page, and let the church office know${contactLine(b)}.`, 'warning')
|
||||
+ small('If this was you, there\'s nothing to do.');
|
||||
const lines = [`When: ${o.when}`, ...(o.site ? [`Signed in to: ${o.site}`] : []), `Where (roughly): ${o.location}`, `Device: ${o.device}`];
|
||||
const text = `Hello ${o.name || 'there'},\n\nSomeone signed in to your ${b.name} account.\n\n${lines.join('\n')}\n\nIf this wasn't you, change your password straight away and let the church office know${b.email ? ` (${b.email})` : ''}.\nIf it was you, there's nothing to do.`;
|
||||
const whatsapp = `🔐 *New sign-in*\n\nHello ${o.name || 'there'}, someone signed in to your *${b.name}* account.\n\n${lines.join('\n')}\n\nNot you? Change your password straight away and let the church office know.`;
|
||||
return { subject: `New sign-in to your ${b.name} account`, text, html: layout(b, body, `New sign-in: ${o.when}, ${o.device}.`), whatsapp };
|
||||
}
|
||||
|
||||
@@ -9,7 +9,7 @@ export const SECRET_SETTINGS = new Set(['smtp_pass', 'wawp_access_token', 'hub_i
|
||||
|
||||
/** The settings an admin may read and change through the generic settings API. */
|
||||
export const ADMIN_SETTINGS = new Set([
|
||||
'signup_enabled', 'two_factor_required_for_admins', 'session_days',
|
||||
'signup_enabled', 'two_factor_required_for_admins', 'session_days', 'signin_notices',
|
||||
'smtp_host', 'smtp_port', 'smtp_user', 'smtp_pass', 'smtp_from', 'smtp_secure',
|
||||
'wawp_access_token', 'wawp_instance_id',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
// 1.6.0: a "New sign-in" email (and WhatsApp) after each sign-in, as Cross Events sends.
|
||||
import assert from 'node:assert/strict';
|
||||
import { after, before, describe, test } from 'node:test';
|
||||
import { startHarness, type Harness } from './support/harness.js';
|
||||
import { describeDevice, sendSignInNotice } from '../src/accounts/signInNotice.js';
|
||||
import type { MemoryMessenger } from '../src/lib/messages.js';
|
||||
|
||||
let h: Harness;
|
||||
before(async () => { h = await startHarness(); });
|
||||
after(async () => { await h.close(); });
|
||||
|
||||
const CHROME_WIN = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0 Safari/537.36';
|
||||
|
||||
describe('sign-in notices', () => {
|
||||
test('an email with when, where, the device and the site; WhatsApp too for a verified number', async () => {
|
||||
const m = h.ctx.messenger as MemoryMessenger;
|
||||
const a = await h.makeAccount({ email: 'notice.person@hope.test' });
|
||||
assert.equal(await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: '127.0.0.1', userAgent: CHROME_WIN, clientId: 'accounts-self' }), 'sent');
|
||||
const mail = m.emails.filter((e) => e.to === 'notice.person@hope.test').at(-1)!;
|
||||
assert.match(mail.subject, /^New sign-in to your .+ account$/);
|
||||
assert.match(mail.text, /Device: Chrome on Windows/);
|
||||
assert.match(mail.text, /Signed in to: Your account page/);
|
||||
assert.match(mail.html ?? '', /Not you\?/);
|
||||
|
||||
await h.db.account.update({ where: { id: a.id as string }, data: { phone: '+27821234567', phoneVerified: true } });
|
||||
m.whatsappOn = true;
|
||||
const before = m.whatsapps.length;
|
||||
await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: null, userAgent: null, clientId: null });
|
||||
assert.equal(m.whatsapps.length, before + 1);
|
||||
assert.match(m.whatsapps.at(-1)!.text, /New sign-in/);
|
||||
m.whatsappOn = false;
|
||||
});
|
||||
|
||||
test('admins can switch them off; a failing email never throws', async () => {
|
||||
const m = h.ctx.messenger as MemoryMessenger;
|
||||
const a = await h.makeAccount({ email: 'notice.off@hope.test' });
|
||||
await h.ctx.settings.set('signin_notices', 'false');
|
||||
assert.equal(await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: null, userAgent: null, clientId: null }), 'off');
|
||||
await h.ctx.settings.set('signin_notices', null);
|
||||
m.emailOn = false;
|
||||
assert.equal(await sendSignInNotice(h.ctx, { accountId: a.id as string, ip: null, userAgent: null, clientId: null }), 'failed');
|
||||
m.emailOn = true;
|
||||
});
|
||||
|
||||
test('device names', () => {
|
||||
assert.equal(describeDevice(CHROME_WIN), 'Chrome on Windows');
|
||||
assert.equal(describeDevice('Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 Version/17.0 Mobile/15E148 Safari/604.1'), 'Safari on iPhone or iPad');
|
||||
assert.equal(describeDevice(null), 'Unknown device');
|
||||
});
|
||||
});
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@crosscode/accounts-frontend",
|
||||
"version": "1.5.0",
|
||||
"version": "1.6.0",
|
||||
"private": true,
|
||||
"description": "Cross Code Accounts: the church's sign-in pages, the account page and admin",
|
||||
"scripts": {
|
||||
|
||||
@@ -57,7 +57,7 @@ export function Admin({ section = "people" }: { section?: AdminSection }) {
|
||||
{section === "deletions" && <Deletions flash={flash} />}
|
||||
{section === "church" && <Church flash={flash} />}
|
||||
{section === "linked" && <Linked flash={flash} />}
|
||||
{section === "signin" && <Settings flash={flash} keys={["signup_enabled", "two_factor_required_for_admins", "session_days"]} />}
|
||||
{section === "signin" && <Settings flash={flash} keys={["signup_enabled", "two_factor_required_for_admins", "signin_notices", "session_days"]} />}
|
||||
{section === "messages" && <Settings flash={flash} keys={["smtp_host", "smtp_port", "smtp_user", "smtp_pass", "smtp_from", "smtp_secure", "wawp_access_token", "wawp_instance_id"]} />}
|
||||
{section === "notice" && <NoticeTab flash={flash} />}
|
||||
{section === "backups" && <Backups flash={flash} />}
|
||||
@@ -252,6 +252,7 @@ function Linked({ flash }: { flash: Flash }) {
|
||||
const SETTING_LABELS: Record<string, [string, "bool" | "text" | "secret" | "number"]> = {
|
||||
signup_enabled: ["Members can create their own account", "bool"],
|
||||
two_factor_required_for_admins: ["Admins must use two-step sign-in", "bool"],
|
||||
signin_notices: ["Tell people by email (and WhatsApp) each time they sign in", "bool"],
|
||||
session_days: ['Days "Keep me signed in" lasts', "number"],
|
||||
smtp_host: ["SMTP server", "text"], smtp_port: ["SMTP port", "number"], smtp_user: ["SMTP user name", "text"], smtp_pass: ["SMTP password", "secret"],
|
||||
smtp_from: ["Send from (email address)", "text"], smtp_secure: ["Use TLS from the start (port 465)", "bool"],
|
||||
@@ -266,7 +267,7 @@ function Settings({ flash, keys }: { flash: Flash; keys: string[] }) {
|
||||
return () => { alive = false; };
|
||||
}, []);
|
||||
if (!values) return <p className="text-gray-600">Loading…</p>;
|
||||
const defaults: Record<string, boolean> = { signup_enabled: true, two_factor_required_for_admins: true };
|
||||
const defaults: Record<string, boolean> = { signup_enabled: true, two_factor_required_for_admins: true, signin_notices: true };
|
||||
return (
|
||||
<Card>
|
||||
<form onSubmit={async (e) => {
|
||||
|
||||
@@ -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,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
@@ -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[]>> {
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
@@ -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 } : {} });
|
||||
})();
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -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"); },
|
||||
};
|
||||
|
||||
@@ -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(() => {
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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
@@ -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;
|
||||
|
||||
@@ -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,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": {
|
||||
|
||||
@@ -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)"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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,6 +1,6 @@
|
||||
{
|
||||
"name": "@crosscode/events-frontend",
|
||||
"version": "3.6.0",
|
||||
"version": "3.6.1",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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,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).
|
||||
|
||||
@@ -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)"
|
||||
}
|
||||
|
||||
@@ -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
@@ -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.
|
||||
```
|
||||
|
||||
+75
-20
@@ -1,6 +1,6 @@
|
||||
# Handover — Cross Code, all products
|
||||
|
||||
Last updated: 2026-11-19. **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,28 +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 |
|
||||
| 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, 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 |
|
||||
|
||||
## 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
|
||||
|
||||
1. **Roll out**, in the order in [ROLLOUT-1.0.md](./ROLLOUT-1.0.md) (with the latest patch
|
||||
releases: Hub 2.1.1, agent 1.0.1, Events 2.3.1): Hub 2.1 (make and back up
|
||||
the job-signing key first) → the central server's agent (check `proxy_bind_addr = 127.0.0.1`)
|
||||
→ each church server's agent → **adopt** the demo site, then each church (Link existing → Move
|
||||
onto the monorepo) → a throwaway New install to prove FASTPANEL, DNS and Let's Encrypt.
|
||||
2. **Deploy crosscode-site `v1.3.0`** (secure sign-in in the features and the brochure).
|
||||
3. **Archive `hope-events`** once every install reports 2.2.0 or later (EVENTS-2.2-PLAN §7).
|
||||
4. **Cross Events 2.4.0** (phase 2) is built on branches: run `npm run test:e2e` in `apps/events`
|
||||
(with the e2e Postgres) and the VM test in EVENTS-2.4-PLAN §8, then merge and release in its
|
||||
order (contracts 1.4.0 → Hub 2.2.0, deployed → Events 2.4.0 → crosscode-site 1.4.0).
|
||||
Everything up to and including the 2026-11-20 releases is deployed, rolled out and tested
|
||||
(VERSIONS.md, "Deployed / rolled out").
|
||||
|
||||
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)
|
||||
|
||||
@@ -95,6 +137,19 @@ rollout.
|
||||
- **AI for a church:** set the licence's monthly AI cap above R0 on the Hub; with no cap the
|
||||
buttons don't show (rules in Events' handover, "AI rules"). Churches see tokens; only the Hub
|
||||
shows rand (markup 15% by default).
|
||||
- **The agent's version is in two places:** `apps/agent/package.json` *and* `AGENT_VERSION` in
|
||||
`apps/agent/src/stats.ts` (what it reports to the Hub). Bump both; the agent's test checks they match,
|
||||
so run `npm run check` *after* the bump (1.3.0 shipped reporting 1.2.0).
|
||||
- **Background jobs:** each job's switch and schedule can be set in the site's admin (Events and
|
||||
Accounts, AppSetting `job_overrides`); that wins over the .env flag and `JOB_SCHEDULE_<NAME>`.
|
||||
`JOBS_ENABLED=false` still turns everything off. A new job gets a `label` and, if it may be turned
|
||||
off from the .env, an `env` flag.
|
||||
- **An install's .env from the Hub** (install page → Settings (.env), agent 1.3.0+): plain values
|
||||
only. Names matching `SECRET_ENV_NAME` (contracts) / `SECRET_NAME` (`scripts/lib/envedit.cjs`;
|
||||
keep them in step) and generated values can't be read or changed from the Hub. Changing an
|
||||
address there doesn't change the Hub's domain for the install or FastPanel.
|
||||
- **Demo data keeps the links** to the church's other products (`KEEP_TABLES` in
|
||||
`apps/events/backend/scripts/set-demo.js`). Anything that must survive a demo load goes there.
|
||||
- **Releasing:** branch → merge → tag (`<product>@<version>` here, `v<version>` in events-hub and
|
||||
crosscode-site) → push, with a CHANGELOG entry, and `npm run check` first. Pushes to c-git often
|
||||
fail authentication the first time; retry once. A push can also hang waiting on a login prompt
|
||||
|
||||
+40
-8
@@ -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.
|
||||
|
||||
+36
-13
@@ -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 |
|
||||
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.5.0** | `accounts@1.5.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 |
|
||||
| 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.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,28 @@ 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.
|
||||
|
||||
- **Events 3.6.0 + Accounts 1.5.0 + contracts 1.14.0:** a nightly people check (Events asks Accounts
|
||||
about everyone with an account, 500 at a time, `people.check`): out-of-date copies are fixed,
|
||||
deleted accounts handled as `user.deleted`, and it stops if most people are unknown. Update
|
||||
@@ -125,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 | |
|
||||
|
||||
@@ -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.
|
||||
Generated
+6
-6
@@ -46,7 +46,7 @@
|
||||
},
|
||||
"apps/accounts/backend": {
|
||||
"name": "@crosscode/accounts-backend",
|
||||
"version": "1.5.0",
|
||||
"version": "1.6.0",
|
||||
"hasInstallScript": true,
|
||||
"dependencies": {
|
||||
"@crosscode/contracts": "*",
|
||||
@@ -83,7 +83,7 @@
|
||||
},
|
||||
"apps/accounts/frontend": {
|
||||
"name": "@crosscode/accounts-frontend",
|
||||
"version": "1.5.0",
|
||||
"version": "1.6.0",
|
||||
"dependencies": {
|
||||
"@crosscode/contracts": "*",
|
||||
"@crosscode/ui": "*",
|
||||
@@ -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,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",
|
||||
|
||||
@@ -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": [
|
||||
|
||||
@@ -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[] = [];
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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
@@ -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
@@ -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;
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user