Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/DEVICE-UNIQUENESS-BACKEND.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,8 @@ And the secrets, in `scripts/dub/service.sh` rather than the TOML (see
`docs/PROFILES.md`): `CHAIN_WRITER_SIGNER_SURI`, `INVITER_SIGNER_SURI`,
`JWT_ED25519_SECRET` with `JWT_ED25519_PUBLIC_KEY` derived from it, and `TURN_SECRET` with
`ICE_SERVERS`, which `ppn service dub-turn-env` resolves together with the eturnal config
(see [TURN.md](TURN.md)).
(see [TURN.md](TURN.md)). It also reads `TURN_PROOF_GENESIS` from People when the network
lists TURN proof products.

The rest stay dormant under the dev defaults: `PAYMENT_MASTER_ACCOUNT` /
`PAYMENT_AMOUNT_PLANCK` are only read when `PAYMENT_LANE_ENABLED=true` (default false,
Expand Down
15 changes: 15 additions & 0 deletions docs/TURN.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,21 @@ whose `turn-api` mints the short-lived credentials the relay accepts.
`{ servers, username, password, ttl }`.
3. Pass `servers` as the ICE server URLs, with `username` and `password` as the credential.

A product without a DUB sign-in, such as Jollity, sends a personhood proof instead:
`POST /dub/api/v1/turn/issue-with-proof` with a ring-VRF proof made under its own product name.
turn-api serves this route only for the products the network lists in `turnProofProducts`, such
as `["dim2.testnet"]` on previewnet, and answers 404 when it lists none. Each product must be a
dotNS name under the network's TLD, since that is the name a host proves under. A deployment
replaces the list in its `PPN_NETWORK_OVERLAY` file, where `[]` turns the route off:

```json
{ "previewnet": { "turnProofProducts": ["dim2.testnet", "vox.testnet"] } }
```

The proofs are checked against the network's own People chain, whose genesis hash
`ppn service dub-turn-env` reads when `dub-api` starts. `dub-api` waits for People to answer
before it starts.

Clients never configure a password themselves. The dashboard lists the same servers under
**TURN / STUN**, and so does `/api/network` under `ice`.

Expand Down
3 changes: 2 additions & 1 deletion networks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,9 @@ or `PPN_NETWORK=<name>` in the environment of the scripts.
| *(para ids)* | `parachains[].paraId` is the single source: the genesis TOML, the fork TOML, `ppn generate` and `assign-cores.sh` all read it from here. `config/ports.env` deliberately holds no para ids — those belong to the network, not the machine. |
| `relay.extraArgs`, `parachains[].extraArgs` | Extra node flags for that chain. A flag the shared per-key table also sets takes this value (`--rpc-max-connections=5000` replaces the table's 500), and a `-l` arg replaces the default log targets whole; the rest are appended. |
| `parachains[].rpcNodes`, `parachains[].rpcNodeArgs` | Non-authoring full nodes (0..9) that serve the chain's public path instead of the collator, on the chain's port + 1, + 2, …, with nginx balancing across them. They run the collator's flags without the authoring ones, with `rpcNodeArgs` over them. |
| *(network overlay)* | `PPN_NETWORK_OVERLAY=<file>` changes `extraArgs`, `rpcNodes` and `rpcNodeArgs` for one deployment without a release: `{ "previewnet": { "relay": { "extraArgs": [...] }, "parachains": { "people": { "rpcNodes": 2, "rpcNodeArgs": [...] } } } }`. Every command applies it, so the zombienet config, nginx routes and dashboard agree. An unknown network, chain or field is an error. |
| *(network overlay)* | `PPN_NETWORK_OVERLAY=<file>` changes `extraArgs`, `rpcNodes`, `rpcNodeArgs` and `turnProofProducts` for one deployment without a release: `{ "previewnet": { "relay": { "extraArgs": [...] }, "parachains": { "people": { "rpcNodes": 2, "rpcNodeArgs": [...] } } } }`. Every command applies it, so the zombienet config, nginx routes and dashboard agree. An unknown network, chain or field is an error. |
| `services` | Per-service switches and binaries: `false` disables a service; `{ "binary": { … } }` says what it runs. `eth-rpc` must match the revive pallet in the network's Asset Hub runtime, which is exactly why it is pinned per network rather than shared. |
| `turnProofProducts` | The dotNS products, under the network's TLD, whose personhood proofs buy TURN credentials at DUB's `/api/v1/turn/issue-with-proof`, such as `["dim2.testnet"]`. Absent leaves the route off. A deployment replaces it in `PPN_NETWORK_OVERLAY` (see `docs/TURN.md`). |
| `tools` | Local tools this network needs that are neither a chain nor a service — previewnet's `chain-spec-builder`, for instance, which only a genesis network uses. |
| `bite.doppelganger` | `{repo, tag}` of the bite tool. Per network, because the build has to be able to execute the runtimes of the network being bitten. |
| *(bin layout)* | Only node binaries are network-versioned: previewnet's live in `bin/`, every other network's in `bin/<name>/` (plus `dg/` for bites). Shared tooling with no per-network dimension — zombie-cli, ipfs, postgres, identity, design families — lives in plain `bin/` and is pinned in `config/versions.env`. Collators run through `scripts/omni-node.sh` regardless of binary; it carries the libp2p fix and picks binary/dir from `PPN_COLLATOR_BINARY`/`PPN_BIN_DIR`. |
Expand Down
2 changes: 2 additions & 0 deletions networks/previewnet.json
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,8 @@
}
}
],
"turnProofProducts": ["dim2.testnet"],
"_turnProofProducts": "Jollity's product account, which proves as dim2.<tld> for TURN credentials (paritytech/individuality-apps packages/jollity-protocol/src/config.ts).",
"services": {
"eth-rpc": {
"binary": {
Expand Down
3 changes: 2 additions & 1 deletion packages/cli/src/commands/trinity-stack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import {
chainKey,
dashboardModel,
dotnsFromContracts,
networkTld,
trinityStackModel,
trinityStackUrl,
type ChainKey,
Expand Down Expand Up @@ -262,7 +263,7 @@ export async function trinityStack(ctx: ServiceContext): Promise<void> {
console.log('trinity-stack: an ephemeral run has no data directory to publish from');
return;
}
if (!ctx.net.stack?.tld && !ctx.net.genesisConfig?.networkSuffix) {
if (!networkTld(ctx.net)) {
console.log(`trinity-stack: networks/${ctx.net.name}.json names no TLD, so there is no descriptor to write`);
return;
}
Expand Down
28 changes: 24 additions & 4 deletions packages/cli/src/commands/turn.ts
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
// `ppn service turn`: the TURN/STUN relay (eturnal) whose credentials DUB's turn-api mints.
// `ppn service dub-turn-env`: the matching secret and ICE servers, as shell exports for
// scripts/dub/service.sh. Both resolve from the same inputs, so they cannot disagree.
// `ppn service dub-turn-env`: the matching secret and ICE servers, plus the People genesis the
// proof route is bound to, as shell exports for scripts/dub/service.sh. Both resolve from the
// same inputs, so they cannot disagree.
// See docs/TURN.md.

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { spawn, type ChildProcess } from 'node:child_process';
import { LOCAL_TURN_SECRET, eturnalConfig, iceServers, runsTurnRelay, turnSecret } from '@parity/ppn-network-config';
import { LOCAL_TURN_SECRET, asHttp, eturnalConfig, iceServers, runsTurnRelay, turnSecret } from '@parity/ppn-network-config';
import type { ServiceContext } from './service-context.js';
import { secretsFile } from '../lib/secrets.js';
import { rpc } from '../fork/rpc.js';
import { sleep, type Sleep } from '../fork/sleep.js';
import { ETURNAL_BREW_INSTALL, eturnalCtl, eturnalDist } from '../lib/eturnal.js';

/** The host clients reach the network under; only its hostname and scheme matter here. */
Expand All @@ -35,8 +38,25 @@ export function dubTurnEnv(ctx: ServiceContext): Record<string, string> {
};
}

/** The chain's genesis hash, once its RPC answers; it waits as long as that takes. */
export async function waitForGenesisHash(rpcUrl: string, wait: Sleep = sleep): Promise<string> {
for (let attempt = 1; ; attempt++) {
try {
return await rpc<string>(asHttp(rpcUrl), 'chain_getBlockHash', [0]);
} catch (error) {
if (attempt % 15 === 1) console.error(`dub-turn-env: waiting for ${rpcUrl}: ${(error as Error).message}`);
await wait(2000);
}
}
}

export async function printDubTurnEnv(ctx: ServiceContext): Promise<void> {
for (const [k, v] of Object.entries(dubTurnEnv(ctx))) {
const env = dubTurnEnv(ctx);
// turn-api exits at start when the proof route is on and no genesis is set.
if (process.env.TURN_PROOF_ENABLED === 'true' && process.env.TURN_PROOF_RPC_URL) {
env.TURN_PROOF_GENESIS = await waitForGenesisHash(process.env.TURN_PROOF_RPC_URL);
}
for (const [k, v] of Object.entries(env)) {
console.log(`export ${k}='${v.replace(/'/g, `'\\''`)}'`);
}
}
Expand Down
39 changes: 39 additions & 0 deletions packages/cli/tests/turn-proof.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import http from 'node:http';
import type { AddressInfo } from 'node:net';

import { waitForGenesisHash } from '../src/commands/turn.js';

const GENESIS = `0x${'ab'.repeat(32)}`;

/** A People RPC that fails `failures` requests before answering chain_getBlockHash(0). */
async function startPeopleRpc(failures: number): Promise<{ url: string; close: () => void }> {
let seen = 0;
const server = http.createServer((req, res) => {
let body = '';
req.on('data', (chunk) => (body += chunk));
req.on('end', () => {
if (seen++ < failures) return res.destroy();
const { method, params } = JSON.parse(body);
assert.deepEqual([method, params], ['chain_getBlockHash', [0]]);
res.setHeader('content-type', 'application/json');
res.end(JSON.stringify({ jsonrpc: '2.0', id: 1, result: GENESIS }));
});
});
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
return { url: `ws://127.0.0.1:${(server.address() as AddressInfo).port}`, close: () => server.close() };
}

describe('waitForGenesisHash', () => {
// dub-api starts beside the chains, so People may not answer yet; turn-api exits at start
// when the proof route is on and no genesis is set, and nothing restarts dub-api if it exits.
it('waits for People to answer', async () => {
const rpc = await startPeopleRpc(3);
try {
assert.equal(await waitForGenesisHash(rpc.url, async () => {}), GENESIS);
} finally {
rpc.close();
}
});
});
14 changes: 11 additions & 3 deletions packages/network-config/src/dub.ts
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,8 @@ export function peopleRpcUrl(peoplePort: number): string {
export function dubServices(
ports: DubPorts,
attesterAccount: string = ALICE_SS58,
inviterAccount: string = BOB_SS58
inviterAccount: string = BOB_SS58,
turnProofProducts: string[] = []
): DubService[] {
const rpc = peopleRpcUrl(ports.people);
const db = (name: (typeof DUB_DATABASES)[number]) => dubDatabaseUrl(name, ports.postgres);
Expand Down Expand Up @@ -180,6 +181,12 @@ export function dubServices(
// and ICE_SERVERS depend on the host, so service.sh supplies them.
TURN_PROVIDER: 'coturn',
TURN_REALM,
// /api/v1/turn/issue-with-proof. service.sh adds TURN_PROOF_GENESIS, read from People.
...(turnProofProducts.length && {
TURN_PROOF_ENABLED: 'true',
TURN_PROOF_RPC_URL: rpc,
TURN_PROOF_PRODUCTS: turnProofProducts.join(','),
}),
},
},
{
Expand Down Expand Up @@ -229,13 +236,14 @@ export function dubCustomProcesses(
// fork mode writes a standalone TOML with absolute paths already resolved.
scriptsDir: string = '{{SCRIPTS}}',
// The TURN/STUN relay whose credentials turn-api mints (docs/TURN.md).
turn: boolean = true
turn: boolean = true,
turnProofProducts: string[] = []
): string {
const wait = `127.0.0.1:${ports.postgres}`;

// zombienet validates custom_process args as CLI arguments — each must parse
// as a flag or --key=value, so bare positionals are rejected outright.
const blocks = dubServices(ports, attesterAccount).map(
const blocks = dubServices(ports, attesterAccount, undefined, turnProofProducts).map(
(svc) => `
[[custom_processes]]
name = "${svc.name}"
Expand Down
3 changes: 2 additions & 1 deletion packages/network-config/src/fork-toml.ts
Original file line number Diff line number Diff line change
Expand Up @@ -389,7 +389,8 @@ export function generateForkToml(options: GenerateForkTomlOptions): string {
},
undefined,
scriptsDir,
net.services['turn'] !== false
net.services['turn'] !== false,
net.turnProofProducts
)
: '';

Expand Down
36 changes: 36 additions & 0 deletions packages/network-config/src/networks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,11 @@ export interface NetworkDef {
parachains: NetworkParachain[];
/** Per-service switches and binaries for the custom processes. */
services: Record<string, ServiceConfig>;
/**
* The dotNS products whose personhood proofs buy TURN credentials at DUB's
* `/api/v1/turn/issue-with-proof`, such as `dim2.testnet`. Empty leaves the route off.
*/
turnProofProducts: string[];
/** Local tools this network needs that are neither a chain nor a service. */
tools: Record<string, BinaryRef>;
/**
Expand Down Expand Up @@ -474,13 +479,44 @@ export function loadDescriptor(name: string): NetworkDef {
rpcNodeArgs: parseArgs(`parachains.${p.key}.rpcNodeArgs`, p.rpcNodeArgs, bad),
})),
services,
turnProofProducts: parseTurnProofProducts(
'turnProofProducts',
raw.turnProofProducts,
networkTld({ stack, genesisConfig: raw.genesisConfig }),
bad
),
tools,
dotns: raw.dotns,
stack,
todos,
};
}

/** The dotNS TLD: `stack.tld`, else a genesis network's `genesisConfig.networkSuffix`. */
export function networkTld(net: Pick<NetworkDef, 'stack' | 'genesisConfig'>): string | undefined {
return net.stack?.tld ?? net.genesisConfig?.networkSuffix;
}

/**
* `products` as TURN proof products, or `bad` unless each is a dotNS name under the network's
* `tld`: a host proves under the product's name on this network, so any other name never matches.
* Absent or empty is none, which leaves the route off.
*/
export function parseTurnProofProducts(
at: string,
products: unknown,
tld: string | undefined,
bad: (why: string) => never
): string[] {
if (products === undefined || (Array.isArray(products) && !products.length)) return [];
if (!tld) bad(`${at}: the network has no dotNS TLD (stack.tld or genesisConfig.networkSuffix)`);
const name = new RegExp(`^[a-z0-9-]+\\.${tld}$`);
if (!Array.isArray(products) || products.some((product) => typeof product !== 'string' || !name.test(product))) {
bad(`${at} must be an array of dotNS names under .${tld}, such as "dim2.${tld}"`);
}
return products as string[];
}

/** `args` as node flags, or `bad` when it is not a list of "--flag" strings. Absent is none. */
export function parseArgs(at: string, args: unknown, bad: (why: string) => never): string[] {
if (args === undefined) return [];
Expand Down
16 changes: 11 additions & 5 deletions packages/network-config/src/overlay.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
// A deployment's own shape for a network, without a release of the engine: RPC nodes in front of
// a chain, or different flags on its nodes. Keyed by network, so loading another network (as
// `ppn networks` does) is unaffected by a section written for this one.
// a chain, different flags on its nodes, or the products its TURN proof route accepts. Keyed by
// network, so loading another network (as `ppn networks` does) is unaffected by a section written
// for this one.
//
// PPN_NETWORK_OVERLAY=/etc/ppn/network-overlay.json
// { "previewnet": {
Expand All @@ -9,14 +10,15 @@

import fs from 'node:fs';
import { overrideArgs } from './args.js';
import { listNetworks, parseArgs, parseRpcNodes, type NetworkDef } from './networks.js';
import { listNetworks, networkTld, parseArgs, parseRpcNodes, parseTurnProofProducts, type NetworkDef } from './networks.js';

const RELAY_FIELDS = ['extraArgs'];
const PARACHAIN_FIELDS = ['extraArgs', 'rpcNodes', 'rpcNodeArgs'];

/**
* `net` with the overlay file's section for it applied: its extraArgs and rpcNodeArgs override
* the descriptor's flag by flag, and rpcNodes replaces the count. Throws on an unreadable file,
* the descriptor's flag by flag, and rpcNodes and turnProofProducts replace the descriptor's.
* Throws on an unreadable file,
* an unknown network, chain or field, or a value the descriptor itself would reject.
*/
export function applyOverlay(net: NetworkDef, file: string): NetworkDef {
Expand All @@ -42,7 +44,7 @@ export function applyOverlay(net: NetworkDef, file: string): NetworkDef {
if (strangers.length) bad(`unknown networks ${strangers.join(', ')} (known: ${networks.join(', ')})`);
if (raw[net.name] === undefined) return net;

const section = object(net.name, raw[net.name], ['relay', 'parachains']);
const section = object(net.name, raw[net.name], ['relay', 'parachains', 'turnProofProducts']);
const relay = object(`${net.name}.relay`, section.relay ?? {}, RELAY_FIELDS);
const parachains = object(`${net.name}.parachains`, section.parachains ?? {});
const parachainKeys: string[] = net.parachains.map((parachain) => parachain.key);
Expand All @@ -53,6 +55,10 @@ export function applyOverlay(net: NetworkDef, file: string): NetworkDef {

return {
...net,
turnProofProducts:
section.turnProofProducts === undefined
? net.turnProofProducts
: parseTurnProofProducts(`${net.name}.turnProofProducts`, section.turnProofProducts, networkTld(net), bad),
relay: {
...net.relay,
extraArgs: overrideArgs(net.relay.extraArgs, parseArgs(`${net.name}.relay.extraArgs`, relay.extraArgs, bad)),
Expand Down
2 changes: 1 addition & 1 deletion packages/network-config/src/toml-generator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -584,7 +584,7 @@ command = "{{SCRIPTS}}/grant-invites.sh"
people: PORTS.people,
assetHub: PORTS['asset-hub'],
gateway: requiredPort('DUB_PORT'),
}, undefined, undefined, serviceEnabled('turn'))
}, undefined, undefined, serviceEnabled('turn'), genesisNet().turnProofProducts)
)}
${section(serviceEnabled('patch-bootnodes'), `
[[custom_processes]]
Expand Down
4 changes: 2 additions & 2 deletions packages/network-config/src/trinity-stack.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

import type { Block, Chain, Model, Service, SpecFile } from '@parity/trinity-stack';
import type { DashboardModel } from './dashboard-model.js';
import type { ChainKey, NetworkDef } from './networks.js';
import { networkTld, type ChainKey, type NetworkDef } from './networks.js';
import { CHAIN_ARGS } from './toml-generator.js';

/** RFC 0026 roles, plus Web3Storage, which serves tools. */
Expand Down Expand Up @@ -94,7 +94,7 @@ export function trinityStackUrl(baseUrl: string): string {
* source publishes its own descriptor: `fork.of` is that pointer.
*/
export function trinityStackModel(net: NetworkDef, model: DashboardModel, facts: StackFacts): Model {
const tld = net.stack?.tld ?? net.genesisConfig?.networkSuffix;
const tld = networkTld(net);
if (!tld) throw new Error(`networks/${net.name}.json has no stack.tld`);
// `fork` requires `forkedAt` on every chain, so it is all or nothing.
const everyForkedAt = Object.values(facts.chains).every((c) => c?.forkedAt);
Expand Down
16 changes: 16 additions & 0 deletions packages/network-config/tests/dub.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,22 @@ describe('dubServices', () => {
});
});

describe('TURN proof issuance', () => {
// turn-api mounts /api/v1/turn/issue-with-proof only with these set, and rejects a product
// missing from the list. Jollity fetches its relay credentials there.
it('enables the proof route on dub-api for the listed products, against local People', () => {
const [api, ...workers] = dubServices(PORTS, undefined, undefined, ['dim2.testnet', 'vox.testnet']);
assert.equal(api.env.TURN_PROOF_ENABLED, 'true');
assert.equal(api.env.TURN_PROOF_RPC_URL, api.env.PEOPLE_RPC_URL);
assert.equal(api.env.TURN_PROOF_PRODUCTS, 'dim2.testnet,vox.testnet');
for (const svc of workers) assert.ok(!('TURN_PROOF_ENABLED' in svc.env));
});

it('leaves the route off without products', () => {
for (const svc of dubServices(PORTS)) assert.ok(!Object.keys(svc.env).some((k) => k.startsWith('TURN_PROOF_')));
});
});

describe('dubCustomProcesses', () => {
const toml = dubCustomProcesses(PORTS);

Expand Down
Loading
Loading