@serfab/cadre-core 1.14.0 → 1.15.0

package/dist/peer-record.js

@@ -11,7 +11,8 @@
  * SQL constraint from the row's own columns and the node-local `party_id()`:
  *
  *   digest('CadreControl.CadrePeer', 'publish', party_id(),
- *          new.PeerId, new.Multiaddr, cast(new.UpdatedAt as text))
+ *          new.PeerId, new.Multiaddr, cast(new.UpdatedAt as text),
+ *          coalesce(new.Profile, ''))
  *
  * Keep {@link peerRecordSignedPayload} and that constraint byte-for-byte in
  * sync. The `'publish'` action tag marks this as a peer's SELF-signed record
@@ -50,9 +51,10 @@ const SIGNALING_PREFIX = '/p2p-circuit';
  * @param peerId - base58btc libp2p peer id (the row key)
  * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
  * @param updatedAt - epoch-ms freshness stamp
+ * @param profile - the publisher's node profile; null signs as `''`, as the constraint coalesces it
  */
-export function peerRecordSignedPayload(partyId, peerId, multiaddr, updatedAt) {
-    const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', partyId, [peerId, multiaddr, String(updatedAt)]);
+export function peerRecordSignedPayload(partyId, peerId, multiaddr, updatedAt, profile) {
+    const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', partyId, [peerId, multiaddr, String(updatedAt), profile ?? '']);
     return digest(fields, 'sha256', 'base64url');
 }
 /**
@@ -65,9 +67,9 @@ export function peerRecordSignedPayload(partyId, peerId, multiaddr, updatedAt) {
  * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
  */
 export function signPeerRecord(partyId, fields, privateKeyB64) {
-    const payloadDigest = peerRecordSignedPayload(partyId, fields.peerId, fields.addrs.join(','), fields.updatedAt);
+    const payloadDigest = peerRecordSignedPayload(partyId, fields.peerId, fields.addrs.join(','), fields.updatedAt, fields.profile);
     const sig = sign(payloadDigest, privateKeyB64, 'ed25519', 'base64url', 'base64url', 'base64url');
-    return { peerId: fields.peerId, publicKey: fields.publicKey, addrs: [...fields.addrs], updatedAt: fields.updatedAt, sig };
+    return { peerId: fields.peerId, publicKey: fields.publicKey, addrs: [...fields.addrs], updatedAt: fields.updatedAt, profile: fields.profile, sig };
 }
 /**
  * Verify a record's self-signature against its own `publicKey`, for `partyId`.
@@ -78,7 +80,7 @@ export function verifyPeerRecordSignature(partyId, record) {
     if (!record.publicKey || !record.sig) {
         return false;
     }
-    const payloadDigest = peerRecordSignedPayload(partyId, record.peerId, record.addrs.join(','), record.updatedAt);
+    const payloadDigest = peerRecordSignedPayload(partyId, record.peerId, record.addrs.join(','), record.updatedAt, record.profile);
     return verify(payloadDigest, record.sig, record.publicKey, 'ed25519', 'base64url', 'base64url', 'base64url');
 }
 /**
@@ -96,50 +98,6 @@ export function isPeerRecordFresh(updatedAt, maxAgeMs, now) {
 export function isSignalingAddr(addr) {
     return addr.includes(SIGNALING_PREFIX);
 }
-/**
- * The peer id a multiaddr terminates in, or `null` when it names none.
- *
- * The LAST `/p2p/` component is the dial target: a circuit address
- * (`…/p2p/<relay>/p2p-circuit/p2p/<target>`) names the relay first and the peer
- * being reached last. Replaces the deprecated `Multiaddr.getPeerId()`, which
- * cannot express that distinction.
- */
-export function trailingPeerId(addr) {
-    const p2p = addr.getComponents().filter((c) => c.name === 'p2p');
-    return p2p.length > 0 ? (p2p[p2p.length - 1].value ?? null) : null;
-}
-/**
- * `addr` guaranteed to terminate in `/p2p/<peerId>` — the shape every dial path
- * needs — or `null` when it cannot, because the address already terminates in a
- * DIFFERENT peer id and therefore does not reach `peerId` at all.
- *
- * Three input shapes, matching what a `CadrePeer` record can legitimately carry:
- *
- * - no `/p2p/` component (`/ip4/1.2.3.4/tcp/4001`) — the suffix is appended;
- * - a relay hop with the destination missing (`…/p2p/<relay>/p2p-circuit`) — the
- *   last component is the circuit, not a peer id, so the suffix is appended and
- *   the address becomes the full `…/p2p/<relay>/p2p-circuit/p2p/<peerId>`;
- * - already terminating in `/p2p/<X>` — returned untouched when `X` is `peerId`,
- *   dropped otherwise.
- *
- * This is deliberately the same rule libp2p applies internally in
- * `calculateMultiaddrs` (append when the LAST component is not `p2p`) followed by
- * its wrong-peer-id filter, so a normalized list matches what libp2p would have
- * built anyway. Normalizing before the dial is what keeps a list from mixing
- * suffixed and unsuffixed entries, which `getPeerAddress` rejects outright
- * ("Multiaddrs must all have the same peer id or have no peer id") — taking the
- * whole peer down with it, not just the odd address.
- *
- * Never use before signature verification: verification runs against the
- * original on-record strings.
- */
-export function withTrailingPeerId(addr, peerId) {
-    const components = addr.getComponents();
-    if (components[components.length - 1]?.name !== 'p2p') {
-        return addr.encapsulate(`/p2p/${peerId}`);
-    }
-    return trailingPeerId(addr) === peerId ? addr : null;
-}
 /**
  * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
  * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate

package/dist/peer-record.js.map

@@ -1 +1 @@
-{"version":3,"file":"peer-record.js","sourceRoot":"","sources":["../src/peer-record.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"peer-record.js","sourceRoot":"","sources":["../src/peer-record.ts"],"names":[],"mappings":"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"}

package/dist/primary-lan-address.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The machine's primary IPv4 address, or undefined when there is no route (offline) or the
+ * probe fails. Callers then fall back to keeping every LAN address. `probe` is for tests.
+ */
+export declare function primaryLanAddress(probe?: {
+    host: string;
+    port: number;
+}): Promise<string | undefined>;

package/dist/primary-lan-address.js

@@ -0,0 +1,46 @@
+/**
+ * Node-only: the machine's main LAN address, for {@link selectNodeClaimAddresses}'s `lan`.
+ *
+ * The address the OS would send from to reach the internet, learned by "connecting" a UDP
+ * socket to a public address: a UDP connect only picks a route and sends nothing. On a
+ * server that also has Docker bridges, a VPN or other interfaces, that is the one a phone on
+ * the same network reaches. A subpath module (`@serfab/cadre-core/primary-lan-address`), like
+ * `key-store-file`, so `node:dgram` never reaches a React Native bundle.
+ */
+import dgram from 'node:dgram';
+import debug from 'debug';
+const log = debug('sereus:cadre:primary-lan-address');
+/** Any public IPv4 address works: nothing is sent to it. */
+const ROUTE_PROBE = { host: '1.1.1.1', port: 53 };
+/**
+ * The machine's primary IPv4 address, or undefined when there is no route (offline) or the
+ * probe fails. Callers then fall back to keeping every LAN address. `probe` is for tests.
+ */
+export async function primaryLanAddress(probe = ROUTE_PROBE) {
+    return new Promise((resolve) => {
+        const socket = dgram.createSocket('udp4');
+        let settled = false;
+        const finish = (address) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.close();
+            resolve(address);
+        };
+        socket.on('error', (err) => {
+            log('route probe failed: %s', err.message);
+            finish();
+        });
+        socket.connect(probe.port, probe.host, (err) => {
+            // A failed connect reports here, not as 'error', and leaves the socket bound to
+            // 0.0.0.0, so its address() must not be read.
+            if (err) {
+                log('no route to probe: %s', err.message);
+                finish();
+                return;
+            }
+            finish(socket.address().address);
+        });
+    });
+}
+//# sourceMappingURL=primary-lan-address.js.map

package/dist/primary-lan-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primary-lan-address.js","sourceRoot":"","sources":["../src/primary-lan-address.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,GAAG,GAAG,KAAK,CAAC,kCAAkC,CAAC,CAAC;AAEtD,4DAA4D;AAC5D,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAW,CAAC;AAE3D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAwC,WAAW;IAC1F,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,CAAC,OAAgB,EAAQ,EAAE;YACzC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,OAAO,CAAC,CAAC;QAClB,CAAC,CAAC;QACF,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YAC1B,GAAG,CAAC,wBAAwB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;YAC3C,MAAM,EAAE,CAAC;QACV,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE;YACtD,gFAAgF;YAChF,8CAA8C;YAC9C,IAAI,GAAG,EAAE,CAAC;gBACT,GAAG,CAAC,uBAAuB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC1C,MAAM,EAAE,CAAC;gBACT,OAAO;YACR,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/dist/provider/client.d.ts

@@ -0,0 +1,131 @@
+/**
+ * A typed client for a hosting provider's container API (`docs/architecture.md` → "Provider
+ * Integration"; the wire shapes are cadre-provider's, `packages/cadre-provider/README.md`).
+ * The interface is what `rentNode` and the apps depend on; a hand-written object implementing
+ * it is how tests avoid HTTP.
+ *
+ * One request helper does the HTTP: the bearer from the token source, JSON in and out, a 401
+ * answered once by `tokens.invalidate()` and a retry, every other non-2xx a
+ * {@link ProviderApiError} from the provider's `{ ok: false, error }` envelope. Dates arrive
+ * as ISO strings and are parsed into epoch milliseconds here, so nothing above the client
+ * handles date strings. Global `fetch` only: loads on React Native and in the browser.
+ */
+import type { TokenSource } from './oauth.js';
+/** How a container was asked to join its cadre (`POST /containers` `join`). */
+export type ContainerJoinRequest = {
+    kind: 'claim';
+} | {
+    kind: 'invitation';
+    invitation: string;
+};
+/** The join as the node last reported it, folded onto the record by the provider's `/status` reads. */
+export type ContainerJoinState = {
+    kind: 'claim';
+    state: 'awaiting';
+} | {
+    kind: 'claim';
+    state: 'claimed';
+    ownerKey: string;
+    partyId: string;
+} | {
+    kind: 'invitation';
+    state: 'pending';
+} | {
+    kind: 'invitation';
+    state: 'accepted';
+    memberPeerId?: string;
+} | {
+    kind: 'invitation';
+    state: 'failed';
+    error: string;
+    retryable: boolean;
+};
+export type RentedContainerStatus = 'pending' | 'creating' | 'enrolling' | 'running' | 'stopping' | 'stopped' | 'error';
+/** Why a container was stopped: its customer asked, or the customer's subscription lapsed. */
+export type ContainerStopReason = 'customer' | 'non-payment';
+/** A container as the API returns it to its customer (the provider's `RedactedContainer`), dates in epoch ms. */
+export interface RentedContainer {
+    id: string;
+    /** The cadre the container serves; a claim container's is the placeholder `unclaimed` until the claim is folded. */
+    partyId: string;
+    profile: 'storage' | 'transaction';
+    status: RentedContainerStatus;
+    createdAt: number;
+    updatedAt: number;
+    /** The failure, when `status` is `error`. */
+    error?: string;
+    /** The node's peer id once it first came up. */
+    peerId?: string;
+    /** How the container joins; the credential itself never leaves the provider this way. */
+    join?: {
+        kind: ContainerJoinRequest['kind'];
+    };
+    joinState?: ContainerJoinState;
+    /** The owner key a claim named, once folded. */
+    ownerKey?: string;
+    stopReason?: ContainerStopReason;
+    tags: Record<string, string>;
+}
+/** The node's live `/status`, as far as an app reads it. */
+export interface RentedContainerHealth {
+    status: 'healthy' | 'unhealthy' | 'starting';
+    peerId?: string;
+    multiaddrs?: string[];
+}
+/** `GET /containers/:id`: the record after a live read, the read itself, and the join state lifted out of the record. */
+export interface RentedContainerStatusReport {
+    container: RentedContainer;
+    health?: RentedContainerHealth;
+    join?: ContainerJoinState;
+}
+export interface CreateContainerBody {
+    join: ContainerJoinRequest;
+    /** Default `storage`. */
+    profile?: 'storage' | 'transaction';
+    tags?: Record<string, string>;
+}
+export type SubscriptionStatus = 'active' | 'past-due' | 'lapsed';
+/** `GET /billing/status`, dates in epoch ms. */
+export interface BillingStatus {
+    planId: string;
+    subscription: {
+        status: SubscriptionStatus;
+        /** When the current period renews; null once lapsed. */
+        renewsAt: number | null;
+        /** `past-due` only: when the grace period ends and the containers are stopped. */
+        lapsesAt: number | null;
+    };
+}
+/** `GET /containers/:id/code`: the code the owner claims the container with, or not yet. */
+export type NodeCodeAnswer = {
+    code: string;
+    peerId: string;
+    multiaddrs: string[];
+}
+/** The node has not reported its peer id and an announced address yet (503); poll. */
+ | {
+    notReady: true;
+};
+/** A non-2xx answer the provider explained: its `error.code` (`NOT_FOUND`, `ALREADY_CLAIMED`, `QUOTA_EXCEEDED`, ...) and message. */
+export declare class ProviderApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface ProviderClient {
+    createContainer(body: CreateContainerBody): Promise<RentedContainer>;
+    getContainer(id: string): Promise<RentedContainerStatusReport>;
+    listContainers(): Promise<RentedContainer[]>;
+    deleteContainer(id: string): Promise<void>;
+    /** Undefined when the customer has no billing record yet. */
+    getBillingStatus(): Promise<BillingStatus | undefined>;
+    /** `notReady` on 503; a `ProviderApiError` for the 409s (`NOT_CLAIMABLE`, `ALREADY_CLAIMED`, `CONTAINER_GONE`). */
+    getNodeCode(id: string): Promise<NodeCodeAnswer>;
+}
+export interface ProviderClientOptions {
+    /** The descriptor's `apiBaseUrl`; the bearer is sent here and nowhere else. */
+    apiBaseUrl: string;
+    tokens: TokenSource;
+    fetch?: typeof fetch;
+}
+export declare function createProviderClient(options: ProviderClientOptions): ProviderClient;

package/dist/provider/client.js

@@ -0,0 +1,226 @@
+/**
+ * A typed client for a hosting provider's container API (`docs/architecture.md` → "Provider
+ * Integration"; the wire shapes are cadre-provider's, `packages/cadre-provider/README.md`).
+ * The interface is what `rentNode` and the apps depend on; a hand-written object implementing
+ * it is how tests avoid HTTP.
+ *
+ * One request helper does the HTTP: the bearer from the token source, JSON in and out, a 401
+ * answered once by `tokens.invalidate()` and a retry, every other non-2xx a
+ * {@link ProviderApiError} from the provider's `{ ok: false, error }` envelope. Dates arrive
+ * as ISO strings and are parsed into epoch milliseconds here, so nothing above the client
+ * handles date strings. Global `fetch` only: loads on React Native and in the browser.
+ */
+import debug from 'debug';
+import { requireFetch } from '../fetch-impl.js';
+const log = debug('sereus:cadre:provider-client');
+/** A non-2xx answer the provider explained: its `error.code` (`NOT_FOUND`, `ALREADY_CLAIMED`, `QUOTA_EXCEEDED`, ...) and message. */
+export class ProviderApiError extends Error {
+    constructor(status, code, message) {
+        super(`Provider answered ${status} ${code}: ${message}`);
+        this.status = status;
+        this.code = code;
+        this.name = 'ProviderApiError';
+    }
+}
+export function createProviderClient(options) {
+    const doFetch = requireFetch(options.fetch);
+    const base = options.apiBaseUrl.replace(/\/+$/, '');
+    const tokens = options.tokens;
+    /** One authenticated JSON request; see the module doc for the 401 retry and the error envelope. */
+    async function request(method, path, body, allow = []) {
+        const headers = { accept: 'application/json' };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        const encoded = body === undefined ? undefined : JSON.stringify(body);
+        const send = async (bearer) => doFetch(`${base}/${path}`, {
+            method,
+            headers: { ...headers, authorization: `Bearer ${bearer}` },
+            body: encoded,
+        });
+        const first = await tokens.accessToken();
+        let response = await send(first);
+        if (response.status === 401) {
+            log('%s %s answered 401; refreshing the token and retrying once', method, path);
+            response = await send(await tokens.invalidate(first));
+        }
+        const parsed = await readEnvelope(response);
+        if (allow.includes(response.status))
+            return { status: response.status, data: parsed.data };
+        if (!response.ok || parsed.ok === false) {
+            throw new ProviderApiError(response.status, parsed.code ?? `HTTP_${response.status}`, parsed.message ?? `${method} ${path} failed`);
+        }
+        return { status: response.status, data: parsed.data };
+    }
+    return {
+        async createContainer(body) {
+            const { data } = await request('POST', 'containers', body);
+            return parseContainer(requireObject(data, 'POST containers').container);
+        },
+        async getContainer(id) {
+            const { data } = await request('GET', `containers/${encodeURIComponent(id)}`);
+            const report = requireObject(data, 'GET containers/:id');
+            const container = parseContainer(report.container);
+            const health = parseHealth(report.health);
+            return { container, ...(health ? { health } : {}), ...(container.joinState ? { join: container.joinState } : {}) };
+        },
+        async listContainers() {
+            const { data } = await request('GET', 'containers');
+            const list = requireObject(data, 'GET containers').containers;
+            if (!Array.isArray(list))
+                throw new Error('The provider\'s container list is not a list');
+            return list.map(parseContainer);
+        },
+        async deleteContainer(id) {
+            await request('DELETE', `containers/${encodeURIComponent(id)}`);
+        },
+        async getBillingStatus() {
+            const { data } = await request('GET', 'billing/status');
+            const billing = requireObject(data, 'GET billing/status').billing;
+            return billing === null || billing === undefined ? undefined : parseBilling(billing);
+        },
+        async getNodeCode(id) {
+            const { status, data } = await request('GET', `containers/${encodeURIComponent(id)}/code`, undefined, [503]);
+            if (status === 503)
+                return { notReady: true };
+            const code = requireObject(data, 'GET containers/:id/code');
+            return {
+                code: requireString(code.code, 'code'),
+                peerId: requireString(code.peerId, 'peerId'),
+                multiaddrs: requireStrings(code.multiaddrs, 'multiaddrs'),
+            };
+        },
+    };
+}
+/** The provider's `{ ok, data }` / `{ ok: false, error: { code, message } }` envelope, tolerating a body that is not one (a proxy's error page). */
+async function readEnvelope(response) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        log('answer %d carried a body that is not JSON: %o', response.status, error);
+        return {};
+    }
+    if (typeof body !== 'object' || body === null)
+        return {};
+    const envelope = body;
+    const error = typeof envelope.error === 'object' && envelope.error !== null ? envelope.error : undefined;
+    return {
+        ok: typeof envelope.ok === 'boolean' ? envelope.ok : undefined,
+        data: envelope.data,
+        code: typeof error?.code === 'string' ? error.code : undefined,
+        // `DELETE` reports a failed termination as `{ ok: false, message }` with no `error`.
+        message: typeof error?.message === 'string' ? error.message : typeof envelope.message === 'string' ? envelope.message : undefined,
+    };
+}
+function parseContainer(value) {
+    const record = requireObject(value, 'a container record');
+    const container = {
+        id: requireString(record.id, 'id'),
+        partyId: requireString(record.partyId, 'partyId'),
+        profile: record.profile === 'transaction' ? 'transaction' : 'storage',
+        status: requireStatus(record.status),
+        createdAt: parseIsoMs(record.createdAt, 'createdAt'),
+        updatedAt: parseIsoMs(record.updatedAt, 'updatedAt'),
+        tags: typeof record.tags === 'object' && record.tags !== null ? record.tags : {},
+    };
+    if (typeof record.error === 'string')
+        container.error = record.error;
+    if (typeof record.peerId === 'string')
+        container.peerId = record.peerId;
+    if (typeof record.ownerKey === 'string')
+        container.ownerKey = record.ownerKey;
+    if (record.stopReason === 'customer' || record.stopReason === 'non-payment')
+        container.stopReason = record.stopReason;
+    const join = record.join;
+    if (typeof join === 'object' && join !== null) {
+        const kind = join.kind;
+        if (kind === 'claim' || kind === 'invitation')
+            container.join = { kind };
+    }
+    if (record.joinState !== undefined)
+        container.joinState = parseJoinState(record.joinState);
+    return container;
+}
+function parseJoinState(value) {
+    const state = requireObject(value, 'a join state');
+    const key = `${String(state.kind)}/${String(state.state)}`;
+    switch (key) {
+        case 'claim/awaiting':
+            return { kind: 'claim', state: 'awaiting' };
+        case 'claim/claimed':
+            return { kind: 'claim', state: 'claimed', ownerKey: requireString(state.ownerKey, 'joinState.ownerKey'), partyId: requireString(state.partyId, 'joinState.partyId') };
+        case 'invitation/pending':
+            return { kind: 'invitation', state: 'pending' };
+        case 'invitation/accepted':
+            return { kind: 'invitation', state: 'accepted', ...(typeof state.memberPeerId === 'string' ? { memberPeerId: state.memberPeerId } : {}) };
+        case 'invitation/failed':
+            return { kind: 'invitation', state: 'failed', error: requireString(state.error, 'joinState.error'), retryable: state.retryable === true };
+        default:
+            throw new Error(`The provider reported a join state this client does not know (${key})`);
+    }
+}
+function parseHealth(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const health = value;
+    const status = health.status === 'healthy' || health.status === 'unhealthy' || health.status === 'starting' ? health.status : undefined;
+    if (!status)
+        return undefined;
+    return {
+        status,
+        ...(typeof health.peerId === 'string' ? { peerId: health.peerId } : {}),
+        ...(Array.isArray(health.multiaddrs) ? { multiaddrs: health.multiaddrs.filter((addr) => typeof addr === 'string') } : {}),
+    };
+}
+function parseBilling(value) {
+    const billing = requireObject(value, 'a billing record');
+    const subscription = requireObject(billing.subscription, 'a billing record\'s subscription');
+    const status = subscription.status;
+    if (status !== 'active' && status !== 'past-due' && status !== 'lapsed') {
+        throw new Error(`The provider reported a subscription status this client does not know (${String(status)})`);
+    }
+    return {
+        planId: requireString(billing.planId, 'planId'),
+        subscription: {
+            status,
+            renewsAt: parseNullableIsoMs(subscription.renewsAt, 'subscription.renewsAt'),
+            lapsesAt: parseNullableIsoMs(subscription.lapsesAt, 'subscription.lapsesAt'),
+        },
+    };
+}
+const CONTAINER_STATUSES = ['pending', 'creating', 'enrolling', 'running', 'stopping', 'stopped', 'error'];
+function requireStatus(value) {
+    if (!CONTAINER_STATUSES.includes(value)) {
+        throw new Error(`The provider reported a container status this client does not know (${String(value)})`);
+    }
+    return value;
+}
+function requireObject(value, what) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`The provider's answer to ${what} is not the JSON object the API documents`);
+    }
+    return value;
+}
+function requireString(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`The provider's answer lacks the string field ${field}`);
+    return value;
+}
+function requireStrings(value, field) {
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+        throw new Error(`The provider's answer lacks the string list ${field}`);
+    }
+    return value;
+}
+/** An ISO 8601 date string as epoch ms; the client's boundary, so nothing above it handles date strings. */
+function parseIsoMs(value, field) {
+    const ms = typeof value === 'string' ? Date.parse(value) : Number.NaN;
+    if (Number.isNaN(ms))
+        throw new Error(`The provider's answer carries no ISO date in ${field}`);
+    return ms;
+}
+function parseNullableIsoMs(value, field) {
+    return value === null || value === undefined ? null : parseIsoMs(value, field);
+}
+//# sourceMappingURL=client.js.map

package/dist/provider/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/provider/client.ts"],"names":[],"mappings":"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"}

package/dist/provider/descriptor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The provider descriptor: what a hosting provider says about itself (`GET /descriptor`,
+ * `docs/architecture.md` → "Provider descriptor and sign-in"), as an app's store screen
+ * renders it and as the sign-in and the provider client read it. The parser refuses, with a
+ * plain message, a document the rest of this directory could not work with.
+ *
+ * Imports only the package's `fetch` helper: it loads on React Native and in the browser as
+ * well as Node.
+ */
+/** Version 1 of the descriptor, the only one an app reads. */
+export interface ProviderDescriptor {
+    v: 1;
+    /** Stable identifier an app keys its rental records by. */
+    id: string;
+    name: string;
+    /** The root every API route hangs off (`https://nodes.acme.example/api/v1`); the bearer goes here and nowhere else. */
+    apiBaseUrl: string;
+    /** The sign-in endpoints, and the union of the scopes any registered app may be granted. */
+    oauth: {
+        authorizeUrl: string;
+        tokenUrl: string;
+        scopes: string[];
+    };
+    /** The public plan list, readable before sign-in. */
+    plansUrl: string;
+    termsUrl?: string;
+    /** Regions in the provider's own words. */
+    regions?: string[];
+    icon?: string;
+}
+/**
+ * Read a descriptor document. Refuses: any version but 1; a missing or blank `id` or `name`;
+ * an `apiBaseUrl`, `oauth.authorizeUrl`, `oauth.tokenUrl` or `plansUrl` that is not an
+ * absolute URL, or is `http` at a host other than loopback, since the node code and the tokens
+ * travel over them; a `termsUrl` or `icon` that is not an absolute web URL; `regions` or
+ * `oauth.scopes` that are not string lists. A descriptor without `oauth` is refused too:
+ * no app could sign in to that provider.
+ */
+export declare function parseProviderDescriptor(json: unknown): ProviderDescriptor;
+/** `GET url`, parsed with {@link parseProviderDescriptor}, for an app that holds a URL rather than the document. */
+export declare function fetchProviderDescriptor(url: string, fetchImpl?: typeof fetch): Promise<ProviderDescriptor>;