Compare commits

...
Author SHA1 Message Date
joshuaandClaude Opus 5.5 9e315f199c Merge branch 'fix/trust-proxy-checks'
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:23:49 +02:00
joshuaandClaude Opus 5.5 fd8f6c28b0 Refuse a TRUST_PROXY the apps can't start with; Accounts reads loopback
A server configuration with TRUST_PROXY=TRUE made an Events install build for
minutes, then fail: Express threw "invalid IP address: TRUE" at startup.

- scripts/lib/envtpl.cjs: VALUE_RULES checked before any .env is written
  (exit 4, naming the value and the fix), for every release.
- Contracts 1.6.0: agent.checkEnvValue / agent.invalidValues, the same rules
  for the Hub.
- Accounts 1.0.1: TRUST_PROXY read as Events reads it; loopback used to
  turn proxy trust off.
- Docs: CHANGELOGs, WHATS-NEW, HANDOVER, AGENT-1.0-PLAN, ROLLOUT-1.0, READMEs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:23:49 +02:00
joshuaandClaude Opus 5.5 db2e544ed6 docs: VERSIONS.md, the latest version of everything and what's deployed
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 09:23:36 +02:00
joshua ccd1cfff46 Merge branch 'fix/install-keeps-backend-logs' 2026-11-19 09:03:50 +02:00
joshuaandClaude Opus 5.5 7fd699a2fd Release the crosscode script fix: failed installs show their PM2 logs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 09:03:48 +02:00
joshuaandClaude Opus 5.5 6988b5ce7c Scripts: a failed install shows its PM2 apps' last log lines
Before removing what a failed install made, print each PM2 app's last
30 log lines, so the Hub's job log says why the backend didn't start
instead of only "/health didn't report 2.3.1 within 90s".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 08:44:38 +02:00
joshua 06222fd94a Merge branch 'fix/agent-stats-during-jobs' 2026-11-18 19:03:20 +02:00
joshuaandClaude Opus 5.5 43189c599a Release agent@1.1.1: stats during jobs, its real version
Stats go every minute on their own timer, also while a job runs (before,
a 30-minute install made the Hub alert that the server was down). The
version constant said 1.0.1 in 1.1.0; a test keeps it equal to
package.json now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 19:03:19 +02:00
27 changed files with 397 additions and 28 deletions
+32
View File
@@ -2,6 +2,38 @@
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
## accounts@1.0.1, contracts@1.6.0, crosscode script - 2026-11-19
A server configuration with `TRUST_PROXY=TRUE` made an Events install build for minutes, then
fail: the backend crashed at startup (`invalid IP address: TRUE`) and the install was removed.
- **Scripts: a value the app can't start with stops the install before the build.**
`lib/envtpl.cjs` checks values against `VALUE_RULES` (so far `TRUST_PROXY`: `loopback`, a hop
count, lowercase `true`/`false`, or proxy IPs/CIDRs) and exits 4 naming the value and the fix,
before any `.env` is written. The rules are in the script, so they apply to every release,
including ones from before them. On deploy, values already in a `.env` aren't checked.
- **Contracts 1.6.0:** `agent.checkEnvValue(name, value)` and `agent.invalidValues(values)`, the
same rules for the Hub (Hub 2.3.3 refuses a bad value when the configuration is saved and before
a job).
- **Accounts 1.0.1:** `TRUST_PROXY=loopback` turned proxy trust off; it's now read as Events reads
it. Details in `apps/accounts/CHANGELOG.md`.
## crosscode script - 2026-11-19 (no tag: servers run `main`)
- **Scripts: a failed install says why its apps didn't start.** Before removing what a failed
install made, `crosscode install` / `crosscode add` print each PM2 app's last 30 log lines. The
logs used to go with the apps, so the Hub only showed "/health didn't report 2.3.1 within 90s
(last answer: none)" and the reason was lost.
## agent@1.1.1 - 2026-11-18
- **Stats keep going while a job runs.** The agent sent stats and polled in one loop, so during
a job (an install or update can take 30 minutes) the Hub heard nothing and alerted, by email,
that the server was down. Stats now go every minute on their own timer, job or not (Hub 2.3.1
also treats a server running a job as busy, for agents not updated yet).
- The agent reports its real version: 1.1.0 still said 1.0.1 (a test now keeps it equal to
package.json).
## accounts@1.0.0, contracts@1.5.0, agent@1.1.0 - 2026-11-18
Phase 3 (docs/ACCOUNTS-1.0-PLAN.md). Released before the VM test and a run on real Postgres (both still to do).
+11
View File
@@ -1,5 +1,16 @@
# Changelog — Accounts
## [1.0.1] - 2026-11-19
### Fixed
- **`TRUST_PROXY=loopback` turned proxy trust off.** Accounts read `TRUST_PROXY` as true/false, so
anything but `true`, including the `loopback` the Hub suggests behind frp, meant off: rate
limiting and the audit log saw every visitor as `127.0.0.1`, and oidc-provider ignored
`X-Forwarded-Proto`. It's now read as Events reads it: `loopback`, a hop count, proxy IP
addresses/CIDRs separated by commas, or `true`/`false` in any case (`true` is one hop, as
before). Unset is still one hop in production.
## [1.0.0] - 2026-11-18
The first release (docs/ACCOUNTS-1.0-PLAN.md), with Hub 2.3.0 and agent 1.1.0. Released before the
+5
View File
@@ -3,6 +3,11 @@
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.0.1
- **Fix:** sign-in limits and the activity log now see each visitor's own address on servers
behind the Cross Code proxy, instead of the proxy's.
## 1.0.0
- **One sign-in for all your church's sites and apps.** People sign in once with their own account
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/accounts-backend",
"version": "1.0.0",
"version": "1.0.1",
"description": "Cross Code Accounts: the church's sign-in (OpenID Connect provider), account pages API and admin API",
"private": true,
"type": "module",
+1 -1
View File
@@ -24,7 +24,7 @@ import { appVersion } from './lib/version.js';
export function createApp(ctx: Ctx, provider: Provider) {
const app = express();
app.disable('x-powered-by');
if (ctx.config.trustProxy) app.set('trust proxy', 1);
if (ctx.config.trustProxySetting !== false) app.set('trust proxy', ctx.config.trustProxySetting);
app.use((_req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff');
+24 -2
View File
@@ -9,8 +9,10 @@ export type Config = {
/** Encrypts secrets at rest and signs cookies. Generated on the server, never sent anywhere. */
secret: string;
production: boolean;
/** Behind nginx/frp: trust X-Forwarded-* (as Events' TRUST_PROXY). */
/** Behind nginx/frp: trust X-Forwarded-* (oidc-provider's `proxy`). */
trustProxy: boolean;
/** Express's "trust proxy" (TRUST_PROXY, read as Events reads it), or false when off. */
trustProxySetting: TrustProxy;
hubUrl: string;
hubLicenceKey: string | null;
hubPublicKey: string | null;
@@ -25,17 +27,37 @@ export type Config = {
const bool = (v: string | undefined, def: boolean) => (v === undefined || v === '' ? def : String(v).toLowerCase() === 'true');
export type TrustProxy = false | number | string | string[];
/**
* TRUST_PROXY as Express's "trust proxy": `loopback` (behind frp, the default the Hub suggests),
* a hop count, IP addresses/CIDRs separated by commas, `true` (one hop: never "trust everyone") or
* `false`. Unset: one hop in production, off otherwise. Before 1.0.1 anything but `true` meant
* off, so `loopback` turned it off.
*/
export function trustProxyFrom(v: string | undefined, production: boolean): TrustProxy {
const raw = (v ?? '').trim();
if (raw === '') return production ? 1 : false;
const lower = raw.toLowerCase();
if (lower === 'true') return 1;
if (lower === 'false') return false;
if (/^\d+$/.test(raw)) return Number(raw) || false;
return raw.includes(',') ? raw.split(',').map((s) => s.trim()).filter(Boolean) : raw;
}
export function loadConfig(env: Record<string, string | undefined> = process.env): Config {
const publicUrl = String(env.ACCOUNTS_URL || env.PUBLIC_URL || 'http://localhost:3200').replace(/\/+$/, '');
const production = env.NODE_ENV === 'production';
const secret = env.ACCOUNTS_SECRET || '';
const trustProxySetting = trustProxyFrom(env.TRUST_PROXY, production);
if (production && secret.length < 32) throw new Error('ACCOUNTS_SECRET must be set (at least 32 characters) in production.');
return {
publicUrl,
port: Number(env.PORT || 5200),
secret: secret || 'development-only-secret-change-me-0123456789',
production,
trustProxy: bool(env.TRUST_PROXY, production),
trustProxy: trustProxySetting !== false,
trustProxySetting,
hubUrl: String(env.HUB_URL || 'https://hub.crosscode.co.za').replace(/\/+$/, ''),
hubLicenceKey: env.HUB_LICENCE_KEY?.trim() || null,
hubPublicKey: env.HUB_PUBLIC_KEY?.trim() || null,
+23
View File
@@ -10,6 +10,29 @@ import { Secrets } from '../src/lib/crypto.js';
import { stateFor, type LicenceClaims } from '../src/hub/licence.js';
import { normalisePhone } from '../src/accounts/service.js';
import { waNumber } from '../src/lib/messages.js';
import { loadConfig, trustProxyFrom } from '../src/lib/config.js';
describe('TRUST_PROXY', () => {
test('read as Events reads it: loopback behind frp is on, not off', () => {
assert.equal(trustProxyFrom('loopback', true), 'loopback');
assert.deepEqual(trustProxyFrom('loopback, 203.0.113.10', true), ['loopback', '203.0.113.10']);
assert.equal(trustProxyFrom('2', true), 2);
assert.equal(trustProxyFrom('TRUE', true), 1);
assert.equal(trustProxyFrom('true', false), 1);
assert.equal(trustProxyFrom('false', true), false);
assert.equal(trustProxyFrom('0', true), false);
assert.equal(trustProxyFrom(undefined, true), 1);
assert.equal(trustProxyFrom('', false), false);
});
test('oidc-provider trusts the proxy whenever Express does', () => {
const on = loadConfig({ NODE_ENV: 'test', TRUST_PROXY: 'loopback' });
assert.equal(on.trustProxy, true);
assert.equal(on.trustProxySetting, 'loopback');
const off = loadConfig({ NODE_ENV: 'test', TRUST_PROXY: 'false' });
assert.equal(off.trustProxy, false);
});
});
describe('passwords', () => {
test('Argon2id hashes verify, wrong passwords don\'t', async () => {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/accounts-frontend",
"version": "1.0.0",
"version": "1.0.1",
"private": true,
"description": "Cross Code Accounts: the church's sign-in pages, the account page and admin",
"scripts": {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/agent",
"version": "1.1.0",
"version": "1.1.1",
"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",
+23 -7
View File
@@ -214,17 +214,33 @@ export class Agent {
}
}
/** Runs until stopped: polls and stats on their own timers, never at the same time as a job. */
/**
* Runs until stopped. Stats go on their own timer, every `statsSeconds`, also while a job runs:
* an install or update can take 30 minutes, and before 1.1.1 the agent went quiet for all of it,
* so the Hub reported it as down (and emailed) though it was busy. Polls wait for the job.
*/
async start(): Promise<void> {
log(`[agent] ${AGENT_VERSION} (${this.deps.config.mode}) for ${this.deps.config.serverId}, Hub ${this.deps.config.hubUrl}`);
let nextStats = 0;
while (!this.stopped) {
if (Date.now() >= nextStats) {
let sending = false;
const statsTick = async () => {
if (sending || this.stopped) return;
sending = true;
try {
await this.statsOnce();
nextStats = Date.now() + this.deps.config.statsSeconds * 1000;
} finally {
sending = false;
}
const delay = await this.pollOnce();
await new Promise((r) => setTimeout(r, Math.max(5, Math.min(delay, this.deps.config.statsSeconds)) * 1000));
};
void statsTick();
const timer = setInterval(() => void statsTick(), this.deps.config.statsSeconds * 1000);
try {
while (!this.stopped) {
const delay = await this.pollOnce();
if (this.stopped) break;
await new Promise((r) => setTimeout(r, Math.max(5, delay) * 1000));
}
} finally {
clearInterval(timer);
}
}
+1 -1
View File
@@ -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.0.1";
export const AGENT_VERSION = "1.1.1";
function run(cmd: string, args: string[], timeoutMs = 10_000): Promise<string | null> {
return new Promise((resolve) => {
+9
View File
@@ -49,3 +49,12 @@ describe("crosscode arguments for each job", () => {
expect(crosscodeArgs(parsed({ type: "update-agent", args: { version: "agent@1.0.1" } }))).toBeNull();
});
});
describe("the agent's version", () => {
it("is the one in package.json (it's what the Hub shows and compares)", () => {
// eslint-disable-next-line @typescript-eslint/no-require-imports
const pkg = require("../package.json") as { version: string };
// eslint-disable-next-line @typescript-eslint/no-require-imports
expect((require("../src/stats") as { AGENT_VERSION: string }).AGENT_VERSION).toBe(pkg.version);
});
});
+26
View File
@@ -42,6 +42,32 @@ function make(jobs: unknown[], run: jest.Mock<ReturnType<Run>, Parameters<Run>>
const reports = (posts: { path: string; body: unknown }[]) => posts.filter((p) => p.path === "/api/agent/v1/report").map((p) => p.body as agent.AgentReport);
describe("the agent loop", () => {
it("keeps sending stats while a long job runs, so the Hub doesn't think it's down", async () => {
jest.useFakeTimers();
try {
let finish!: () => void;
const longRun = jest.fn<ReturnType<Run>, Parameters<Run>>(() => new Promise<RunResult>((resolve) => { finish = () => resolve(ok()); }));
const h = fakeHub([job()]);
const a = new Agent({ config, keys: { ed25519Pem: serverKeys.ed25519.privateKeyPem, x25519Pem: serverKeys.x25519.privateKeyPem }, hub: h.hub, seen: new SeenJobs(path.join(state, `seen-${Math.random()}.json`)), run: longRun, now: () => NOW, stats: async () => ({}) as agent.AgentStats });
const running = a.start();
await jest.advanceTimersByTimeAsync(10);
expect(longRun).toHaveBeenCalledTimes(1);
// 20 minutes of a job: a stats post every minute all the way through.
await jest.advanceTimersByTimeAsync(20 * 60 * 1000);
const stats = h.posts.filter((p) => p.path === "/api/agent/v1/stats").length;
expect(stats).toBeGreaterThanOrEqual(20);
expect(reports(h.posts)).toHaveLength(0);
finish();
await jest.advanceTimersByTimeAsync(10);
expect(reports(h.posts)).toHaveLength(1);
a.stop();
await jest.advanceTimersByTimeAsync(60 * 1000);
await running;
} finally {
jest.useRealTimers();
}
});
it("runs a valid job once and reports it", async () => {
const j = job();
const { a, run, posts } = make([j, j]);
+1 -1
View File
@@ -84,7 +84,7 @@ Create `backend/.env` from `.env.example`. The only variables you must set are:
| `APP_BASE_URL` | — | Public frontend URL — used in email links (fallback if not set via admin panel) |
| `BACKEND_URL` | — | Public backend URL — used to serve ticket PDFs over WhatsApp |
| `PORT` | — | Port to listen on (default `3000`) |
| `TRUST_PROXY` | — | Set when running behind a reverse proxy (e.g. nginx on a separate server), so `req.ip`/`X-Forwarded-For` are read correctly by rate limiting. Accepts a hop count (`1`), `true`/`false`, or comma-separated trusted proxy IP(s)/CIDR(s). |
| `TRUST_PROXY` | — | Set when running behind a reverse proxy (e.g. nginx on a separate server), so `req.ip`/`X-Forwarded-For` are read correctly by rate limiting. Accepts a hop count (`1`), `true`/`false` (lowercase), `loopback` (behind frp), or comma-separated trusted proxy IP(s)/CIDR(s). Anything else (e.g. `TRUE`) stops the backend starting; the Hub and the crosscode script refuse it. |
| `NODE_ENV` | — | `production` or `development` |
| `WAWP_ACCESS_TOKEN` | — | WAWP fallback token (preferred: set via Admin → Site Settings) |
| `WAWP_INSTANCE_ID` | — | WAWP fallback instance ID (preferred: set via Admin → Site Settings) |
+4 -1
View File
@@ -188,7 +188,10 @@ monorepo, listing every variable with its layer, whether it's required, and a de
**For Joshua to set per server before the first install:** the database settings and
`TRUST_PROXY`. Behind frp the app sees every connection from frpc on `127.0.0.1`, and the
visitor's address arrives in `X-Forwarded-For` from FastPanel's nginx, so the expected value is
`loopback` (the Hub suggests it).
`loopback` (the Hub suggests it). A value the apps can't start with (e.g. `TRUE`, which crashed
the Events backend after a whole install's build) is refused when the configuration is saved (Hub
2.3.3), before a job is made, and again by the crosscode script before it writes a `.env`
(`checkEnvValue` in `@crosscode/contracts` 1.6.0, `VALUE_RULES` in `scripts/lib/envtpl.cjs`).
## 6. frp and the central server
+7 -2
View File
@@ -8,7 +8,9 @@ are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and th
The docs for every product are here in `docs/`: the roadmap, the Hub protocol
([hub-protocol.md](./hub-protocol.md), with a copy in `events-hub`), this handover, the plans
for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)). The latest
version of everything, and what's deployed, is in [VERSIONS.md](./VERSIONS.md) (update it with
every release).
## Repos
@@ -78,7 +80,10 @@ rollout.
- **The agent pins the Hub's job key** when it joins. Back up `events-hub/backend/keys/` (licence
and job keys); replacing the job key means every server joins again.
- **A new `.env` variable** goes in three env templates: `apps/<product>/env.template.json`,
`scripts/products/<product>.env.template.json` and the Hub's `envTemplates/<product>.json`.
`scripts/products/<product>.env.template.json` and the Hub's `envTemplates/<product>.json`. If
the app refuses some values at startup (as Events does a `TRUST_PROXY` it can't parse), add a
rule to both `checkEnvValue` in `packages/contracts/src/agent.ts` (the Hub) and `VALUE_RULES` in
`scripts/lib/envtpl.cjs` (the server), so a bad value stops before an install's build.
- **A new Events install never takes over an existing database**: moving an existing site is
`adopt`, not a New install pointed at the old database.
- **Prisma in the monorepo:** each app other than Events sets its own generator `output`, so
+2 -1
View File
@@ -43,7 +43,8 @@ Follow `events-hub/deployment.md` → "Upgrading to 2.1":
- [ ] Hub → Servers → Add server → **Church**; run the command as root. It installs Node tools,
the agent (`/opt/crosscode/agent`) and the crosscode script (`/opt/crosscode/tools`, from
main), and starts `crosscode-agent`. The agent listens on nothing.
- [ ] On the server's page: its configuration. `TRUST_PROXY=loopback` behind frp; the database:
- [ ] On the server's page: its configuration. `TRUST_PROXY=loopback` behind frp (lowercase;
`TRUE` stops the Events backend starting, and the Hub refuses it from 2.3.3); the database:
`DB_HOST`/`DB_PORT`/`DB_ADMIN_URL` for a separate PostgreSQL, or nothing for the local one.
- [ ] `systemctl status crosscode-agent` is active; the server's stats show on the Hub.
- [ ] The first time the agent changes `frpc.ini` it adds the admin lines and **restarts frpc once**
+65
View File
@@ -0,0 +1,65 @@
# Versions — the latest release of everything
Last updated: 2026-11-19. 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
separately below; the two often differ.
## Released
| What | Repo | Latest | Tag | Released |
|------|------|--------|-----|----------|
| Cross Events | `crosscode-platform` (`apps/events`) | **2.4.0** | `events@2.4.0` | 2026-11-18 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.0.0** | `accounts@1.0.0` | 2026-11-18 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.1.1** | `agent@1.1.1` | 2026-11-18 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.5.0** | `contracts@1.5.0` | 2026-11-18 |
| Cross Code Hub | `events-hub` | **2.3.2** | `v2.3.2` | 2026-11-19 |
| crosscode.co.za | `crosscode-site` | **1.5.0** | `v1.5.0` | 2026-11-18 |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-19 (last change) |
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
[CHANGELOG.md](../CHANGELOG.md) under "crosscode script".
### Not tagged yet
| What | Where | Version in package.json |
|------|-------|-------------------------|
| `@crosscode/auth-client` | `packages/auth-client` | 1.0.0 (released with Accounts 1.0.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 4) |
| 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
need their own tags until something outside this repo depends on them.
## What each latest release was for
- **Events 2.4.0:** protocol v2, Linked products, the event feed, `packages/seo`
([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). 2.3.1 is the version for churches until 2.4.0's
e2e run on Postgres and VM test are done.
- **Accounts 1.0.0:** the church's sign-in (OpenID Connect provider)
([ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)). Needs the VM test and a run on real Postgres
before a church gets it.
- **Agent 1.1.1:** stats keep going while a job runs; reports its real version.
- **Contracts 1.5.0:** the Accounts contracts (OIDC client paths, scopes, church events).
- **Hub 2.3.2:** installs no longer get stuck "Uninstalling" when the export fails; a failed
install's record can be removed (and uninstall is refused for it).
- **crosscode.co.za 1.5.0:** lists Accounts.
- **`crosscode` script (2026-11-19):** a failed install prints each PM2 app's last log lines before
removing it, so the Hub's job log shows why the backend didn't start.
## Deployed / rolled out
What actually runs isn't in git, so this table is kept by hand. Fill in a version and date when
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.3.2 not deployed yet** |
| 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 |
+4 -4
View File
@@ -46,7 +46,7 @@
},
"apps/accounts/backend": {
"name": "@crosscode/accounts-backend",
"version": "1.0.0",
"version": "1.0.1",
"hasInstallScript": true,
"dependencies": {
"@crosscode/contracts": "*",
@@ -82,7 +82,7 @@
},
"apps/accounts/frontend": {
"name": "@crosscode/accounts-frontend",
"version": "1.0.0",
"version": "1.0.1",
"dependencies": {
"@crosscode/contracts": "*",
"@crosscode/ui": "*",
@@ -108,7 +108,7 @@
},
"apps/agent": {
"name": "@crosscode/agent",
"version": "1.1.0",
"version": "1.1.1",
"license": "UNLICENSED",
"dependencies": {
"@crosscode/contracts": "*",
@@ -21274,7 +21274,7 @@
},
"packages/contracts": {
"name": "@crosscode/contracts",
"version": "1.5.0",
"version": "1.6.0",
"license": "UNLICENSED",
"dependencies": {
"zod": "^4.6.7"
+1
View File
@@ -13,6 +13,7 @@ Events and the Hub, uses it, so the key fields are the same in every product's J
| Sign-in return | — | The return-path check and OIDC `state` every product uses (ROADMAP-v3 §3) | `src/return-to.ts` |
| Product link | `crosscode.link/1` | **Connect** under Settings → Linked products: the signed handshake that sets up a link's secret (`link.connect`, `link.connected`, `link.disconnect`) | `src/link.ts` |
| Hub protocol v2 | `protocolVersion: 2` | Register, heartbeat (stats per product), linked products, update requests, AI, licence token | `src/hub.ts` (exported as `hub`) |
| Env template | `crosscode.env-template/1` | Each product's `.env` variables by layer; `missingRequired` and, from 1.6.0, `checkEnvValue` / `invalidValues` (values an app can't start with, e.g. `TRUST_PROXY=TRUE`), which the Hub checks before a job | `src/agent.ts` (exported as `agent`) |
| Signing | — | HMAC request signing for the Hub and for product links (Node only) | `src/signing.ts` (`@crosscode/contracts/signing`) |
## Using it
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.5.0",
"version": "1.6.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",
+38
View File
@@ -318,3 +318,41 @@ export function missingRequired(template: EnvTemplate, layer: "server" | "defaul
}
return [...new Set(missing)];
}
// Values the apps check at startup, so a bad one is refused when it's entered instead of
// crashing the app after an install's build. Keep in step with VALUE_RULES in
// scripts/lib/envtpl.cjs (which checks again on the server, for any release).
const PROXY_NAME = /^(loopback|linklocal|uniquelocal)$/;
const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
const isIp = (s: string) => IPV4.test(s) || (s.includes(":") && /^[0-9A-Fa-f:.]+$/.test(s));
function proxyEntry(s: string): boolean {
if (PROXY_NAME.test(s)) return true;
const [ip, bits, extra] = s.split("/");
if (extra !== undefined || ip === undefined || !isIp(ip)) return false;
return bits === undefined || /^\d{1,3}$/.test(bits) || IPV4.test(bits);
}
const ENV_VALUE_RULES: Record<string, { ok: (v: string) => boolean; hint: string }> = {
// Events hands this to Express's "trust proxy" (apps/events/backend/src/app.js).
TRUST_PROXY: {
ok: (v) => v === "true" || v === "false" || /^\d+$/.test(v) || v.split(",").every((s) => proxyEntry(s.trim())),
hint: "Use loopback behind frp, a hop count such as 1, true or false (lowercase), or proxy IP addresses/CIDRs separated by commas.",
},
};
/** Why an app can't start with this value (a sentence for the person who entered it), or null when it can. */
export function checkEnvValue(name: string, value: string): string | null {
const rule = ENV_VALUE_RULES[name];
if (!rule || rule.ok(String(value).trim())) return null;
return `${name} can't be "${value}". ${rule.hint}`;
}
/** The problems with a layer's values ({ NAME: message }), empty when there are none (the Hub's check on save and before a job). */
export function invalidValues(values: Record<string, string | undefined>): Record<string, string> {
const out: Record<string, string> = {};
for (const [name, value] of Object.entries(values)) {
if (value === undefined || value === null || String(value) === "") continue;
const problem = checkEnvValue(name, String(value));
if (problem) out[name] = problem;
}
return out;
}
+14
View File
@@ -171,4 +171,18 @@ describe("env templates", () => {
expect(agent.missingRequired(template, "server", { TRUST_PROXY: "loopback" })).toEqual(["DB_HOST"]);
expect(agent.missingRequired(template, "defaults", {})).toEqual(["HUB_URL"]);
});
it("refuses a TRUST_PROXY the Events backend can't start with", () => {
for (const ok of ["loopback", "1", "true", "false", "loopback, 203.0.113.10", "10.0.0.0/8", "::1", "fd00::/8", "192.168.1.0/255.255.255.0"]) {
expect(agent.checkEnvValue("TRUST_PROXY", ok)).toBeNull();
}
for (const bad of ["TRUE", "True", "yes", "on", "300.1.1.1", "10.0.0.0/8/1", "loopback,"]) {
expect(agent.checkEnvValue("TRUST_PROXY", bad)).toMatch(/^TRUST_PROXY can't be/);
}
expect(agent.checkEnvValue("DB_HOST", "anything")).toBeNull();
expect(agent.invalidValues({ TRUST_PROXY: "TRUE", DB_HOST: "10.0.0.5", DB_PORT: undefined })).toEqual({
TRUST_PROXY: expect.stringContaining("loopback"),
});
expect(agent.invalidValues({ TRUST_PROXY: "loopback" })).toEqual({});
});
});
+43 -3
View File
@@ -12,7 +12,9 @@
// appear in arguments or files other than the .env); server / defaults → the config's layers;
// install → the config's install[product], else the variable's `from` filled with --var values.
// Then --fallback, then the template's `default`. A required variable with no value stops
// everything before any file is written (exit 3, the names on stderr).
// everything before any file is written (exit 3, the names on stderr). So does a value the app
// can't start with (VALUE_RULES, exit 4), e.g. TRUST_PROXY=TRUE, which crashes the Events backend
// only after the long build.
// --check: only says what would be added. Prints names only, never values.
'use strict';
@@ -54,6 +56,33 @@ function keysIn(text) {
return keys;
}
// Values the apps check at startup. The rules live here rather than in the templates so they also
// apply to releases whose templates predate them. Keep in step with checkEnvValue in
// packages/contracts/src/agent.ts. Only for values that aren't secret: the message shows the value.
const PROXY_NAME = /^(loopback|linklocal|uniquelocal)$/;
const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
const isIp = s => IPV4.test(s) || (s.includes(':') && /^[0-9A-Fa-f:.]+$/.test(s));
function proxyEntry(s) {
if (PROXY_NAME.test(s)) return true;
const [ip, bits, extra] = s.split('/');
if (extra !== undefined || !isIp(ip)) return false;
return bits === undefined || /^\d{1,3}$/.test(bits) || IPV4.test(bits);
}
const VALUE_RULES = {
// Events hands this to Express's "trust proxy" (apps/events/backend/src/app.js).
TRUST_PROXY: {
ok: v => v === 'true' || v === 'false' || /^\d+$/.test(v) || v.split(',').every(s => proxyEntry(s.trim())),
hint: 'use loopback behind frp, a hop count such as 1, true or false (lowercase), or proxy IP addresses/CIDRs separated by commas',
},
};
/** Why the app can't use this value, or undefined when it can (or there's no rule for it). */
function checkValue(name, value) {
const rule = VALUE_RULES[name];
if (!rule || rule.ok(String(value).trim())) return undefined;
return `${name}=${JSON.stringify(String(value))} won't work: ${rule.hint}`;
}
function fill(from, vars) {
let missing = false;
const value = from.replace(/\{([A-Za-z]+)\}/g, (_, k) => {
@@ -94,6 +123,7 @@ function plan(opts) {
const ctx = { config, vars: opts.vars, fallback: opts.fallback, product: opts.product || template.product };
const files = [];
const missing = [];
const invalid = [];
for (const [rel, variables] of Object.entries(template.files)) {
if (rel.includes('..') || path.isAbsolute(rel)) throw new Error(`Bad file name in the template: ${rel}`);
const file = path.join(opts.dir, rel);
@@ -107,11 +137,17 @@ function plan(opts) {
if (v.required) missing.push(`${v.name} (${v.layer}, ${rel})`);
continue;
}
const problem = checkValue(v.name, value);
if (problem) {
const where = v.layer === 'server' ? "server, from the server's configuration on the Hub" : v.layer;
invalid.push(`${problem} (${where}, ${rel})`);
continue;
}
add.push({ name: v.name, value });
}
files.push({ rel, file, exists, add });
}
return { files, missing };
return { files, missing, invalid: [...new Set(invalid)] };
}
function write({ files }, release) {
@@ -151,6 +187,10 @@ function main() {
console.error(`Required settings with no value: ${result.missing.join(', ')}`);
process.exit(3);
}
if (result.invalid.length) {
console.error(`Settings the app can't start with:\n ${result.invalid.join('\n ')}`);
process.exit(4);
}
for (const f of result.files) {
if (!f.add.length) continue;
const names = f.add.map(a => a.name).join(', ');
@@ -161,4 +201,4 @@ function main() {
if (require.main === module) main();
module.exports = { parseArgs, keysIn, fill, line, plan, write };
module.exports = { parseArgs, keysIn, fill, line, plan, write, checkValue };
+15 -1
View File
@@ -58,12 +58,26 @@ random_secret() { openssl rand -base64 64 | tr -d '/+=\n' | head -c "${1:-48}";
INSTALL_UNDO=""
undo_add() { [ -z "$INSTALL_UNDO" ] || printf '%s\n' "$*" >> "$INSTALL_UNDO"; }
# pm2_last_logs <user> <name…>: each PM2 app's last 30 log lines (output and errors), indented.
pm2_last_logs() {
local user="$1" name
shift
for name in "$@"; do
info "PM2: last log lines of $name"
run_as "$user" / pm2 logs "$name" --lines 30 --nostream --raw </dev/null 2>&1 | tail -n 60 | sed 's/^/ /' || true
done
}
install_undo() {
local kind a b
step "Removing what this install made"
tac "$INSTALL_UNDO" | while read -r kind a b; do
case "$kind" in
pm2) # shellcheck disable=SC2086 # b is a space-separated list of PM2 names
pm2)
# Their logs go with them, so show why they didn't start first (the Hub gets the log).
# shellcheck disable=SC2086 # b is a space-separated list of PM2 names
pm2_last_logs "$a" $b
# shellcheck disable=SC2086
run_as "$a" / pm2 delete $b >/dev/null 2>&1 || true
run_as "$a" / pm2 save --force >/dev/null 2>&1 || true
info "PM2: $b removed" ;;
+17
View File
@@ -259,3 +259,20 @@ EOF
[ "$(host_from_url "$(env_value "$TMP/.env" FRONTEND_URL)")" = events.hopefamily.co.za ]
[ "$(host_from_url http://localhost:3000/x)" = localhost ]
}
# ── install undo ────────────────────────────────────────────────────────────────────────────
@test "a failed install shows each PM2 app's last log lines before removing it" {
# shellcheck source=../lib/install.sh
source "$BATS_TEST_DIRNAME/../lib/install.sh"
run_as() { shift 2; case "$2" in logs) printf 'Error: %s crashed\n' "$3" ;; esac; echo "$*" >> "$TMP/pm2"; }
INSTALL_UNDO="$TMP/undo"
undo_add pm2 cc-hope "hope-events-backend hope-events-frontend"
run install_undo
[ "$status" -eq 0 ]
[[ "$output" == *"last log lines of hope-events-backend"* ]]
[[ "$output" == *" Error: hope-events-backend crashed"* ]]
[[ "$output" == *" Error: hope-events-frontend crashed"* ]]
# The logs are read before the apps are deleted.
[ "$(grep -n 'logs hope-events-backend' "$TMP/pm2" | cut -d: -f1)" -lt "$(grep -n '^pm2 delete' "$TMP/pm2" | cut -d: -f1)" ]
}
+27
View File
@@ -54,6 +54,33 @@ envtpl() { node "$TPL_JS" --template "$TMP/template.json" --dir "$APP" --product
[ ! -e "$APP/frontend/.env.production" ]
}
@test "a value the app can't start with: nothing is written, the value and the fix are named" {
printf '{ "server": { "TRUST_PROXY": "TRUE" } }\n' > "$TMP/bad.json"
run envtpl --config "$TMP/bad.json" --release events@2.4.0
[ "$status" -eq 4 ]
[[ "$output" == *'TRUST_PROXY="TRUE" won'"'"'t work'* ]]
[[ "$output" == *"loopback behind frp"* ]]
[[ "$output" == *"server's configuration on the Hub"* ]]
[ ! -e "$APP/backend/.env" ]
[ ! -e "$APP/frontend/.env.production" ]
}
@test "TRUST_PROXY: the values Events understands are accepted" {
for v in loopback 1 true false 'loopback, 203.0.113.10' 10.0.0.0/8 '::1'; do
rm -rf "$APP/backend/.env" "$APP/frontend/.env.production"
printf '{ "server": { "TRUST_PROXY": "%s" } }\n' "$v" > "$TMP/ok.json"
run envtpl --config "$TMP/ok.json"
[ "$status" -eq 0 ] || { echo "$v: $output"; false; }
done
}
@test "deploy: a bad value already in a .env is left alone (only new variables are checked)" {
printf 'DATABASE_URL=x\nPORT=1\nFRONTEND_URL=y\nTRUST_PROXY=TRUE\n' > "$APP/backend/.env"
printf '{ "server": { "TRUST_PROXY": "TRUE" } }\n' > "$TMP/bad.json"
run envtpl --config "$TMP/bad.json"
[ "$status" -eq 0 ]
}
@test "--fallback fills a value no layer gives" {
run envtpl --fallback TRUST_PROXY=1
[ "$status" -eq 0 ]