@serfab/cadre-core 1.14.0 → 1.16.0

package/src/provider/oauth.ts

@@ -0,0 +1,285 @@
+/**
+ * The app's side of signing in to a hosting provider: OAuth 2 authorization code with PKCE
+ * (RFC 6749 §4.1, RFC 7636), the flow for a public client that holds no secret, against the
+ * endpoints a provider descriptor names (`docs/architecture.md` → "Provider descriptor and
+ * sign-in"). Opening the browser is the app's or its kit's; this module builds the URL it
+ * opens, reads the redirect it comes back with, exchanges and refreshes tokens, and keeps a
+ * token fresh for the provider client ({@link createTokenSource}).
+ *
+ * Imports `@noble/hashes` for SHA-256 and the CSPRNG (`crypto.getRandomValues`, which the
+ * React Native kit polyfills) and `uint8arrays` for base64url, so it loads on React Native
+ * and in the browser as well as Node. Codes and tokens are credentials: none is ever logged.
+ */
+
+import debug from 'debug';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { requireFetch } from '../fetch-impl.js';
+import type { ProviderDescriptor } from './descriptor.js';
+
+const log = debug('sereus:cadre:provider-oauth');
+
+/**
+ * A sign-in fault, with a machine-readable `code`: the provider's own OAuth error code
+ * (`invalid_grant`, `access_denied`, ... per RFC 6749 §5.2) when it answered one;
+ * `state-mismatch` or `missing-code` when the redirect could not be read; `invalid_response`
+ * when the token endpoint answered something that is not a token response; `reauthorize`
+ * when a refresh was refused, the app's cue to run the authorization again.
+ */
+export class ProviderAuthError extends Error {
+	constructor(readonly code: string, description?: string, options?: { cause?: unknown }) {
+		super(description ? `${code}: ${description}` : code, options);
+		this.name = 'ProviderAuthError';
+	}
+}
+
+/** What a token exchange or refresh yields, with `expiresAt` already in epoch milliseconds. */
+export interface ProviderTokens {
+	accessToken: string;
+	refreshToken: string;
+	/** Epoch ms when `accessToken` stops working. */
+	expiresAt: number;
+	scopes: string[];
+}
+
+/** A PKCE pair (RFC 7636): the verifier the app keeps, and the S256 challenge it sends first. */
+export interface Pkce {
+	verifier: string;
+	challenge: string;
+}
+
+/** The S256 challenge for `verifier`: base64url(SHA-256(ascii(verifier))), unpadded. */
+export function pkceChallenge(verifier: string): string {
+	return uint8ArrayToString(sha256(new TextEncoder().encode(verifier)), 'base64url');
+}
+
+/** A fresh pair: 32 random bytes as a 43-character base64url verifier, and its challenge. */
+export function createPkce(): Pkce {
+	const verifier = uint8ArrayToString(randomBytes(32), 'base64url');
+	return { verifier, challenge: pkceChallenge(verifier) };
+}
+
+/** A random `state` for one authorization, which {@link readAuthorizationRedirect} checks the redirect against. */
+export function createAuthorizationState(): string {
+	return uint8ArrayToString(randomBytes(16), 'base64url');
+}
+
+export interface AuthorizationUrlOptions {
+	/** The client id the app registered with the provider. */
+	clientId: string;
+	/** One of that client's registered redirect URIs, exactly as registered. */
+	redirectUri: string;
+	state: string;
+	/** The S256 challenge of the verifier the app keeps ({@link createPkce}). */
+	challenge: string;
+	/** Scopes to ask for; defaults to every scope the descriptor lists. */
+	scopes?: readonly string[];
+}
+
+/** The authorize URL to open in the system browser: `response_type=code`, the client, the redirect URI, the scopes space-joined, the state and the S256 challenge. */
+export function authorizationUrl(descriptor: ProviderDescriptor, options: AuthorizationUrlOptions): string {
+	const url = new URL(descriptor.oauth.authorizeUrl);
+	url.searchParams.set('response_type', 'code');
+	url.searchParams.set('client_id', options.clientId);
+	url.searchParams.set('redirect_uri', options.redirectUri);
+	url.searchParams.set('scope', (options.scopes ?? descriptor.oauth.scopes).join(' '));
+	url.searchParams.set('state', options.state);
+	url.searchParams.set('code_challenge', options.challenge);
+	url.searchParams.set('code_challenge_method', 'S256');
+	return url.toString();
+}
+
+/** What the browser came back with: a code to exchange, or the provider's refusal (RFC 6749 §4.1.2.1). */
+export type AuthorizationRedirect =
+	| { code: string }
+	| { error: string; description?: string };
+
+/**
+ * Read the redirect URL the browser returned to the app. Throws `ProviderAuthError`
+ * (`state-mismatch`) when its `state` is not `expectedState`, whichever outcome it carries,
+ * and (`missing-code`) when it carries neither a code nor an error. The code is a credential
+ * and never appears in a message or a log line.
+ */
+export function readAuthorizationRedirect(url: string, options: { expectedState: string }): AuthorizationRedirect {
+	const params = new URL(url).searchParams;
+	if (params.get('state') !== options.expectedState) {
+		throw new ProviderAuthError('state-mismatch', 'the redirect\'s state is not the one this authorization sent');
+	}
+	const error = params.get('error');
+	if (error !== null) {
+		const description = params.get('error_description');
+		return description === null ? { error } : { error, description };
+	}
+	const code = params.get('code');
+	if (code === null || code === '') {
+		throw new ProviderAuthError('missing-code', 'the redirect carries neither a code nor an error');
+	}
+	return { code };
+}
+
+export interface ExchangeAuthorizationCodeOptions {
+	clientId: string;
+	/** The redirect URI the authorization was sent with, exactly. */
+	redirectUri: string;
+	code: string;
+	/** The verifier of the challenge the authorization was sent with. */
+	verifier: string;
+	fetch?: typeof fetch;
+}
+
+/** `grant_type=authorization_code` at the descriptor's token endpoint, form-encoded; a refusal is a `ProviderAuthError` with the provider's error code. */
+export async function exchangeAuthorizationCode(descriptor: ProviderDescriptor, options: ExchangeAuthorizationCodeOptions): Promise<ProviderTokens> {
+	return await requestTokens(descriptor, {
+		grant_type: 'authorization_code',
+		code: options.code,
+		code_verifier: options.verifier,
+		client_id: options.clientId,
+		redirect_uri: options.redirectUri,
+	}, options.fetch);
+}
+
+export interface RefreshTokensOptions {
+	clientId: string;
+	refreshToken: string;
+	fetch?: typeof fetch;
+}
+
+/** `grant_type=refresh_token`: rotates the pair (the presented one stops working); a refusal is a `ProviderAuthError` with the provider's error code. */
+export async function refreshTokens(descriptor: ProviderDescriptor, options: RefreshTokensOptions): Promise<ProviderTokens> {
+	return await requestTokens(descriptor, {
+		grant_type: 'refresh_token',
+		refresh_token: options.refreshToken,
+		client_id: options.clientId,
+	}, options.fetch);
+}
+
+/** Hands the provider client a working bearer; see {@link createTokenSource}. */
+export interface TokenSource {
+	/** The current access token, refreshed first when it is within a minute of expiry. */
+	accessToken(): Promise<string>;
+	/**
+	 * The provider answered 401 to `stale`: refresh and return the new token. A refresh that
+	 * already replaced `stale` is not repeated, so two requests refused at once cost one
+	 * rotation.
+	 */
+	invalidate(stale?: string): Promise<string>;
+}
+
+export interface TokenSourceOptions {
+	descriptor: ProviderDescriptor;
+	clientId: string;
+	/** The tokens the app holds, from the exchange or from its store. */
+	tokens: ProviderTokens;
+	/** Called with the new pair after every refresh; the old pair has stopped working by then. */
+	persist: (tokens: ProviderTokens) => void | Promise<void>;
+	fetch?: typeof fetch;
+	/** The clock, for tests. */
+	now?: () => number;
+}
+
+/** A token is refreshed this long before it expires, so a request does not leave with one about to lapse. */
+export const TOKEN_REFRESH_MARGIN_MS = 60_000;
+
+/**
+ * A {@link TokenSource} over one token pair: refreshes within {@link TOKEN_REFRESH_MARGIN_MS}
+ * of expiry and on `invalidate`, calls `persist` after every refresh, and shares one refresh
+ * among concurrent callers (a rotation spends the presented refresh token, so two at once
+ * would leave one caller with a refused pair). A refused refresh throws
+ * `ProviderAuthError('reauthorize')`: the pair is gone and the app signs in again; a network
+ * failure is rethrown as is, since the pair may still be good.
+ */
+export function createTokenSource(options: TokenSourceOptions): TokenSource {
+	const now = options.now ?? Date.now;
+	let current = options.tokens;
+	let inFlight: Promise<ProviderTokens> | null = null;
+
+	const refresh = (): Promise<ProviderTokens> => {
+		if (!inFlight) {
+			inFlight = rotate().finally(() => { inFlight = null; });
+		}
+		return inFlight;
+	};
+
+	async function rotate(): Promise<ProviderTokens> {
+		let next: ProviderTokens;
+		try {
+			next = await refreshTokens(options.descriptor, { clientId: options.clientId, refreshToken: current.refreshToken, fetch: options.fetch });
+		} catch (error) {
+			if (error instanceof ProviderAuthError) {
+				log('token refresh refused (%s); the app must authorize again', error.code);
+				throw new ProviderAuthError('reauthorize', `the provider refused to refresh the token (${error.code})`, { cause: error });
+			}
+			throw error;
+		}
+		current = next;
+		await options.persist(next);
+		log('token refreshed; expires in %ds', Math.round((next.expiresAt - now()) / 1000));
+		return next;
+	}
+
+	return {
+		async accessToken(): Promise<string> {
+			const fresh = now() < current.expiresAt - TOKEN_REFRESH_MARGIN_MS ? current : await refresh();
+			return fresh.accessToken;
+		},
+		async invalidate(stale?: string): Promise<string> {
+			if (stale !== undefined && stale !== current.accessToken) return current.accessToken;
+			return (await refresh()).accessToken;
+		},
+	};
+}
+
+/** One token-endpoint request (RFC 6749 §4.1.3, §6): form-encoded in, a token response or a `{ error, error_description }` refusal out. */
+async function requestTokens(descriptor: ProviderDescriptor, form: Record<string, string>, fetchImpl?: typeof fetch): Promise<ProviderTokens> {
+	const doFetch = requireFetch(fetchImpl);
+	const requestedAt = Date.now();
+	const response = await doFetch(descriptor.oauth.tokenUrl, {
+		method: 'POST',
+		headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+		body: new URLSearchParams(form).toString(),
+	});
+	const body = await readJson(response);
+	if (!response.ok) {
+		const error = body && typeof body.error === 'string' ? body.error : 'invalid_response';
+		const description = body && typeof body.error_description === 'string'
+			? body.error_description
+			: `the token endpoint answered ${response.status}`;
+		throw new ProviderAuthError(error, description);
+	}
+	return tokensFrom(body, requestedAt);
+}
+
+/** The response's JSON object, or null when the body is not one. */
+async function readJson(response: Response): Promise<Record<string, unknown> | null> {
+	try {
+		const parsed: unknown = await response.json();
+		return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
+	} catch (error) {
+		log('token endpoint answered %d with a body that is not JSON: %o', response.status, error);
+		return null;
+	}
+}
+
+/** `{ access_token, expires_in, refresh_token, scope }` as {@link ProviderTokens}; `expires_in` counts from when the request left. */
+function tokensFrom(body: Record<string, unknown> | null, requestedAt: number): ProviderTokens {
+	const accessToken = body?.access_token;
+	const refreshToken = body?.refresh_token;
+	const expiresIn = body?.expires_in;
+	if (typeof accessToken !== 'string' || accessToken === '') {
+		throw new ProviderAuthError('invalid_response', 'the token response carries no access_token');
+	}
+	if (typeof refreshToken !== 'string' || refreshToken === '') {
+		throw new ProviderAuthError('invalid_response', 'the token response carries no refresh_token, which a token source needs to outlive the access token');
+	}
+	if (typeof expiresIn !== 'number' || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+		throw new ProviderAuthError('invalid_response', 'the token response carries no positive expires_in');
+	}
+	const scope = body?.scope;
+	return {
+		accessToken,
+		refreshToken,
+		expiresAt: requestedAt + expiresIn * 1000,
+		scopes: typeof scope === 'string' ? scope.split(' ').filter((entry) => entry !== '') : [],
+	};
+}

package/src/provider/rent-node.ts

@@ -0,0 +1,275 @@
+/**
+ * Rent a node from a hosting provider and add it to this node's cadre, by whichever of the two
+ * join paths fits (`docs/architecture.md` → "Renting a node from an app"):
+ *
+ * - **invitation**, when the cadre has a member the container can reach from the provider's
+ *   network (`CadreNode.invitationReach()` reads `anywhere`): mint a single-use, non-owner
+ *   invitation and create the container with it; the container joins by itself and the app
+ *   watches `getContainer(id).join`.
+ * - **claim**, otherwise (a phone that is the cadre's only member, or members reachable only on
+ *   their LAN, which the provider's container is never on): create the container, poll for its
+ *   node code, and claim it from this node.
+ *
+ * Nothing here persists anything: which container belongs to which cadre is the app's record,
+ * and {@link finishRental} is how an app resumes a rental it was killed in the middle of. The
+ * node code carries the claim secret, so neither the code nor the decoded payload is ever
+ * logged, only the container id and the peer id.
+ */
+
+import debug from 'debug';
+import type { CadreNode } from '../cadre-node.js';
+import { decodeNodeClaimPayload } from '../node-claim-payload.js';
+import { ProviderApiError, type ProviderClient, type RentedContainerStatusReport } from './client.js';
+
+const log = debug('sereus:cadre:provider-rent');
+
+export type RentNodeJoin = 'claim' | 'invitation';
+
+/** Progress, as `RentNodeOptions.onProgress` reports it; `claiming` can last a while, see {@link rentNode}. */
+export type RentNodeStep = 'creating' | 'waiting-for-code' | 'claiming' | 'inviting' | 'done';
+
+export interface RentNodeOptions {
+	/** Default `storage`. */
+	profile?: 'storage' | 'transaction';
+	/** Called at each step; an exception it throws is logged and ignored. */
+	onProgress?: (step: RentNodeStep) => void;
+	/**
+	 * How long to wait for the node code before giving up with `node-not-ready`; default
+	 * {@link DEFAULT_NODE_CODE_DEADLINE_MS}. The container exists by then and
+	 * {@link finishRental} resumes it.
+	 */
+	nodeCodeDeadlineMs?: number;
+	/** How often the node code is asked for while it is not ready; default {@link NODE_CODE_POLL_MS}. */
+	nodeCodePollMs?: number;
+}
+
+export interface RentNodeResult {
+	containerId: string;
+	join: RentNodeJoin;
+	/** The node's peer id, known at once on the claim path and once the container reported it on the invitation path. */
+	peerId?: string;
+}
+
+/** {@link finishRental} on an invitation container whose node could not redeem: delete the container and rent again. */
+export interface RentalFailed {
+	containerId: string;
+	outcome: 'failed';
+	error: string;
+	retryable: boolean;
+}
+
+export type RentNodeErrorCode =
+	/** This node cannot act as an owner of its cadre, so it can neither invite nor claim. */
+	| 'not-an-owner'
+	/** The node code was not ready by the deadline; the container exists, `finishRental` resumes it. */
+	| 'node-not-ready'
+	/** The container is `stopped` or `error`, or the provider reported it so while the code was awaited. */
+	| 'container-gone'
+	/** A claim container that another cadre's owner claimed. */
+	| 'claimed-by-another'
+	/** A container `rentNode` did not create: it carries no join. */
+	| 'not-a-rental';
+
+export class RentNodeError extends Error {
+	constructor(readonly code: RentNodeErrorCode, readonly containerId?: string) {
+		super(`rentNode: ${code}${containerId ? ` (container ${containerId})` : ''}`);
+		this.name = 'RentNodeError';
+	}
+}
+
+/** The `CadreNode` surface renting needs; a hand-written object implementing it is how tests avoid a node. */
+export type RentingNode = Pick<CadreNode, 'partyId' | 'isOwner' | 'invitationReach' | 'createCadreInvitation' | 'withdrawCadreInvitation' | 'claimNode'>;
+
+/**
+ * The provider's enrolment window is 60 s and an image pull can precede it. Bounds the
+ * container's start, not an exchange over the link, so it is not derived from the link budget.
+ */
+// eslint-disable-next-line no-restricted-syntax -- link-independent: bounds the container's start (an image pull plus the provider's 60 s enrolment window), not an exchange over the link
+export const DEFAULT_NODE_CODE_DEADLINE_MS = 120_000;
+export const NODE_CODE_POLL_MS = 2_000;
+/** Lifetime of the invitation a rental mints: long enough for the container to start and redeem, short enough to limit a leaked bundle. */
+export const RENTAL_INVITATION_TTL_MS = 15 * 60_000;
+
+/**
+ * Rent a node and add it to `node`'s cadre; see the module doc for the path choice.
+ *
+ * The claim path's `claimNode` can take up to the per-peer dial limit plus the seed request
+ * when no address answers (its doc: 114.5 s at the default link); no timeout is added on top
+ * of it, and `onProgress('claiming')` is the app's cue to show a slow hint. Two calls at once
+ * on one node both mint or both create; serializing them is the app's.
+ *
+ * @throws {RentNodeError} `not-an-owner`, or `node-not-ready` once the container exists.
+ * @throws {ProviderApiError} when the provider refused a request (a lapsed subscription is `403 QUOTA_EXCEEDED`).
+ * @throws {ClaimRefusedError} or {PeerUnreachableError} from `claimNode`, as it throws them.
+ */
+export async function rentNode(node: RentingNode, client: ProviderClient, options: RentNodeOptions = {}): Promise<RentNodeResult> {
+	await requireOwner(node);
+	const reach = await node.invitationReach();
+	log('renting a node for party %s; invitation reach %s → %s path', node.partyId, reach, reach === 'anywhere' ? 'invitation' : 'claim');
+	return reach === 'anywhere'
+		? await rentByInvitation(node, client, options)
+		: await rentByClaim(node, client, options);
+}
+
+/**
+ * Resume a rental: for an app that was killed mid-flow or hit the node-code deadline.
+ *
+ * - a `stopped` or `error` container → `RentNodeError('container-gone')`;
+ * - a claim container not yet claimed → the code, then `claimNode`, as {@link rentNode} would;
+ * - a claim container claimed into this cadre → done. The provider withholds the code once a
+ *   claim is folded, so the claim is not re-run; one claimed by another cadre's owner →
+ *   `RentNodeError('claimed-by-another')`;
+ * - an invitation container → done while `pending` or `accepted` (the app watches `join`), or
+ *   the failed outcome, after which the app deletes the container and rents again (the claim
+ *   path is chosen then if the member that answered is gone).
+ */
+export async function finishRental(node: RentingNode, client: ProviderClient, containerId: string, options: RentNodeOptions = {}): Promise<RentNodeResult | RentalFailed> {
+	await requireOwner(node);
+	const report = await client.getContainer(containerId);
+	const kind = joinKindOf(report, containerId);
+	if (kind === 'claim') {
+		return await finishClaim(node, client, report, options);
+	}
+	const join = report.join;
+	if (join?.kind === 'invitation' && join.state === 'failed') {
+		return { containerId, outcome: 'failed', error: join.error, retryable: join.retryable };
+	}
+	return invitationResult(report.container);
+}
+
+async function requireOwner(node: RentingNode): Promise<void> {
+	if (!await node.isOwner()) throw new RentNodeError('not-an-owner');
+}
+
+async function rentByInvitation(node: RentingNode, client: ProviderClient, options: RentNodeOptions): Promise<RentNodeResult> {
+	report(options, 'inviting');
+	const { invitation, encoded } = await node.createCadreInvitation({ grantsOwner: false, uses: 1, expiresInMs: RENTAL_INVITATION_TTL_MS });
+	report(options, 'creating');
+	let container;
+	try {
+		container = await client.createContainer({ join: { kind: 'invitation', invitation: encoded }, profile: options.profile ?? 'storage' });
+	} catch (error) {
+		await withdrawQuietly(node, invitation.invite.key);
+		throw error;
+	}
+	log('container %s created with an invitation; it joins by itself', container.id);
+	report(options, 'done');
+	return invitationResult(container);
+}
+
+/** A create that failed leaves no live invitation behind; a withdrawal that fails too is logged, and the create's error is what the caller sees. */
+async function withdrawQuietly(node: RentingNode, key: string): Promise<void> {
+	try {
+		await node.withdrawCadreInvitation(key);
+	} catch (error) {
+		log('withdrawing invitation %s after a failed create failed too: %o', key, error);
+	}
+}
+
+async function rentByClaim(node: RentingNode, client: ProviderClient, options: RentNodeOptions): Promise<RentNodeResult> {
+	report(options, 'creating');
+	const container = await client.createContainer({ join: { kind: 'claim' }, profile: options.profile ?? 'storage' });
+	log('container %s created for a claim', container.id);
+	return await claimContainer(node, client, container.id, options);
+}
+
+/** Poll for the node code, then claim; the second half of the claim path, shared with {@link finishRental}. */
+async function claimContainer(node: RentingNode, client: ProviderClient, containerId: string, options: RentNodeOptions): Promise<RentNodeResult> {
+	report(options, 'waiting-for-code');
+	const { code, peerId } = await awaitNodeCode(client, containerId, options);
+	report(options, 'claiming');
+	// The claim is the owner's signature; the app asked the user before calling.
+	await node.claimNode(decodeNodeClaimPayload(code));
+	log('container %s claimed; its node is %s', containerId, peerId);
+	report(options, 'done');
+	return { containerId, join: 'claim', peerId };
+}
+
+/**
+ * `getNodeCode` every poll interval until it answers or the deadline passes. A container that
+ * dies meanwhile (`409 CONTAINER_GONE`) is `container-gone`, the same code `finishRental` gives
+ * one found dead, so an app handles both at one site.
+ */
+async function awaitNodeCode(client: ProviderClient, containerId: string, options: RentNodeOptions): Promise<{ code: string; peerId: string }> {
+	const deadline = Date.now() + (options.nodeCodeDeadlineMs ?? DEFAULT_NODE_CODE_DEADLINE_MS);
+	const poll = options.nodeCodePollMs ?? NODE_CODE_POLL_MS;
+	for (;;) {
+		const answer = await requestNodeCode(client, containerId);
+		if (!('notReady' in answer)) return answer;
+		if (Date.now() >= deadline) {
+			log('container %s has no node code by the deadline', containerId);
+			throw new RentNodeError('node-not-ready', containerId);
+		}
+		await sleep(poll);
+	}
+}
+
+async function requestNodeCode(client: ProviderClient, containerId: string): ReturnType<ProviderClient['getNodeCode']> {
+	try {
+		return await client.getNodeCode(containerId);
+	} catch (error) {
+		if (error instanceof ProviderApiError && error.code === 'CONTAINER_GONE') throw new RentNodeError('container-gone', containerId);
+		throw error;
+	}
+}
+
+async function finishClaim(node: RentingNode, client: ProviderClient, report: RentedContainerStatusReport, options: RentNodeOptions): Promise<RentNodeResult> {
+	const { container, join } = report;
+	if (join?.kind === 'claim' && join.state === 'claimed') return judgeClaimed(node, report);
+	try {
+		return await claimContainer(node, client, container.id, options);
+	} catch (error) {
+		// The node was claimed between the read and the code request; judge the fresh record.
+		if (error instanceof ProviderApiError && error.code === 'ALREADY_CLAIMED') {
+			return judgeClaimed(node, await client.getContainer(container.id));
+		}
+		throw error;
+	}
+}
+
+/**
+ * A claimed container is this cadre's when the claim named this party.
+ *
+ * NOTE: the row `claimNode` writes after the node accepts is not re-run here, because the
+ * provider withholds the code once the claim is folded. An app killed between the node
+ * accepting and that one local insert has a node that belongs to this owner with no row for it
+ * on this machine, the window the React Native app's accepted tradeoff for cadre-host claims
+ * names; the remedy is to delete the container and rent again. Revisit if a device run sees it.
+ */
+function judgeClaimed(node: RentingNode, report: RentedContainerStatusReport): RentNodeResult {
+	const { container, join } = report;
+	if (join?.kind !== 'claim' || join.state !== 'claimed') throw new RentNodeError('container-gone', container.id);
+	if (join.partyId !== node.partyId) {
+		log('container %s was claimed into another party', container.id);
+		throw new RentNodeError('claimed-by-another', container.id);
+	}
+	return { containerId: container.id, join: 'claim', ...(container.peerId ? { peerId: container.peerId } : {}) };
+}
+
+/** Which path a container is on; refuses one that is gone or was never a rental. */
+function joinKindOf(report: RentedContainerStatusReport, containerId: string): RentNodeJoin {
+	const { container, join } = report;
+	if (container.status === 'stopped' || container.status === 'error') throw new RentNodeError('container-gone', containerId);
+	// The join state is folded from the node's first `/status` read, so a container still
+	// starting carries only the kind it was created with.
+	const kind = join?.kind ?? container.join?.kind;
+	if (kind === undefined) throw new RentNodeError('not-a-rental', containerId);
+	return kind;
+}
+
+function invitationResult(container: { id: string; peerId?: string }): RentNodeResult {
+	return { containerId: container.id, join: 'invitation', ...(container.peerId ? { peerId: container.peerId } : {}) };
+}
+
+function report(options: RentNodeOptions, step: RentNodeStep): void {
+	try {
+		options.onProgress?.(step);
+	} catch (error) {
+		log('onProgress(%s) threw; ignored: %o', step, error);
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	// A plain timer, not an unref'd one: a Node process renting from a script must stay up for it.
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/relay-addrs.ts

@@ -50,7 +50,10 @@
  * only once the relay-hop protocol id is in that peer's peer-store protocol list,
  * and that list is written exclusively by IDENTIFY — which `@optimystic/db-p2p`
  * namespaces per network, so a cadre node and a stock relay never identify each
- * other. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
+ * other. A node with configured relays is built with that discovery switched off
+ * altogether when it has a transport list to wrap (`node-transports.ts`), because it
+ * CAN reach a relay-capable peer in its own namespace and take the configured relay's
+ * slot. See `relay-reservation.ts`'s module doc and `docs/architecture.md`.
  */
 
 import { multiaddr, type Component } from '@multiformats/multiaddr';
@@ -191,9 +194,11 @@ const WS_TRANSPORT_SWITCH_PORT = 0;
  *
  * - **WebSocket is DERIVED.** It is the one non-TCP transport the shipped configs need
  *   (the React Native reference app's companion drone; `cadre start --ws-port`), and
- *   `@optimystic/db-p2p` already knows how to add it. `cadre-core` grows no dependency
- *   and decides no transport policy — it flips db-p2p's own switch
- *   ({@link WS_TRANSPORT_SWITCH_PORT}).
+ *   `@optimystic/db-p2p` already knows how to add it, so `cadre-core` flips db-p2p's own
+ *   switch ({@link WS_TRANSPORT_SWITCH_PORT}). A node with configured relays is the one
+ *   case where cadre passes the transport list itself (`node-transports.ts`, to switch
+ *   relay discovery off); when the embedder gave none, that list comes from
+ *   `network.defaultTransports`, which reads the same switch.
  * - **Everything else is REFUSED.** Deriving `/quic-v1`, `/webrtc` or `/webtransport`
  *   would mean importing transport packages into every `cadre-core` consumer including
  *   the React Native and browser bundles (against the cross-platform rule in