@serfab/cadre-core 1.13.0 → 1.15.0

package/dist/provider/descriptor.js

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+import { requireFetch } from '../fetch-impl.js';
+/**
+ * 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 function parseProviderDescriptor(json) {
+    const doc = requireObject(json, 'A provider descriptor');
+    if (doc.v !== 1)
+        throw new Error(`A provider descriptor must carry v: 1 (this one carries ${JSON.stringify(doc.v)})`);
+    const id = requireText(doc.id, 'id');
+    const name = requireText(doc.name, 'name');
+    const apiBaseUrl = requireApiUrl(doc.apiBaseUrl, 'apiBaseUrl');
+    const plansUrl = requireApiUrl(doc.plansUrl, 'plansUrl');
+    const oauth = requireObject(doc.oauth, 'A provider descriptor\'s oauth block');
+    const parsed = {
+        v: 1,
+        id,
+        name,
+        apiBaseUrl,
+        oauth: {
+            authorizeUrl: requireApiUrl(oauth.authorizeUrl, 'oauth.authorizeUrl'),
+            tokenUrl: requireApiUrl(oauth.tokenUrl, 'oauth.tokenUrl'),
+            scopes: requireStrings(oauth.scopes, 'oauth.scopes'),
+        },
+        plansUrl,
+    };
+    if (doc.termsUrl !== undefined)
+        parsed.termsUrl = requireWebUrl(doc.termsUrl, 'termsUrl');
+    if (doc.icon !== undefined)
+        parsed.icon = requireWebUrl(doc.icon, 'icon');
+    if (doc.regions !== undefined)
+        parsed.regions = requireStrings(doc.regions, 'regions');
+    return parsed;
+}
+/** `GET url`, parsed with {@link parseProviderDescriptor}, for an app that holds a URL rather than the document. */
+export async function fetchProviderDescriptor(url, fetchImpl) {
+    const doFetch = requireFetch(fetchImpl);
+    const response = await doFetch(url, { headers: { accept: 'application/json' } });
+    if (!response.ok) {
+        throw new Error(`The provider descriptor at ${url} answered ${response.status}`);
+    }
+    return parseProviderDescriptor(await response.json());
+}
+/** Hosts at which an API URL may be plain `http`: a dev run on this machine. */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+function requireObject(value, what) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`${what} must be a JSON object`);
+    }
+    return value;
+}
+function requireText(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`A provider descriptor's ${field} must be a non-blank string`);
+    }
+    return value;
+}
+function requireStrings(value, field) {
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+        throw new Error(`A provider descriptor's ${field} must be a list of strings`);
+    }
+    return [...value];
+}
+/** An absolute `http(s)` URL, as a link a store screen opens. */
+function requireWebUrl(value, field) {
+    const text = requireText(value, field);
+    const url = parseUrl(text, field);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`A provider descriptor's ${field} must be an http or https URL (${text} is not)`);
+    }
+    return text;
+}
+/** {@link requireWebUrl}, and `https` unless the host is loopback: tokens and the node code travel over it. */
+function requireApiUrl(value, field) {
+    const text = requireWebUrl(value, field);
+    const url = new URL(text);
+    if (url.protocol === 'http:' && !LOOPBACK_HOSTS.has(url.hostname)) {
+        throw new Error(`A provider descriptor's ${field} must be https unless its host is loopback (${text} is plain http at ${url.hostname})`);
+    }
+    return text;
+}
+function parseUrl(text, field) {
+    try {
+        return new URL(text);
+    }
+    catch (error) {
+        throw new Error(`A provider descriptor's ${field} must be an absolute URL (${text} is not)`, { cause: error });
+    }
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/provider/descriptor.js.map

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

package/dist/provider/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Everything an app needs to rent a node from a hosting provider: the provider's descriptor,
+ * the sign-in handshake, the typed API client, and `rentNode` / `finishRental`. Every module
+ * here loads on React Native and in the browser as well as Node.
+ */
+export { parseProviderDescriptor, fetchProviderDescriptor, type ProviderDescriptor } from './descriptor.js';
+export { ProviderAuthError, pkceChallenge, createPkce, createAuthorizationState, authorizationUrl, readAuthorizationRedirect, exchangeAuthorizationCode, refreshTokens, createTokenSource, TOKEN_REFRESH_MARGIN_MS, type Pkce, type ProviderTokens, type AuthorizationUrlOptions, type AuthorizationRedirect, type ExchangeAuthorizationCodeOptions, type RefreshTokensOptions, type TokenSource, type TokenSourceOptions, } from './oauth.js';
+export { createProviderClient, ProviderApiError, type ProviderClient, type ProviderClientOptions, type ContainerJoinRequest, type ContainerJoinState, type ContainerStopReason, type RentedContainer, type RentedContainerStatus, type RentedContainerHealth, type RentedContainerStatusReport, type CreateContainerBody, type SubscriptionStatus, type BillingStatus, type NodeCodeAnswer, } from './client.js';
+export { rentNode, finishRental, RentNodeError, DEFAULT_NODE_CODE_DEADLINE_MS, NODE_CODE_POLL_MS, RENTAL_INVITATION_TTL_MS, type RentNodeJoin, type RentNodeStep, type RentNodeOptions, type RentNodeResult, type RentalFailed, type RentNodeErrorCode, type RentingNode, } from './rent-node.js';

package/dist/provider/index.js

@@ -0,0 +1,10 @@
+/**
+ * Everything an app needs to rent a node from a hosting provider: the provider's descriptor,
+ * the sign-in handshake, the typed API client, and `rentNode` / `finishRental`. Every module
+ * here loads on React Native and in the browser as well as Node.
+ */
+export { parseProviderDescriptor, fetchProviderDescriptor } from './descriptor.js';
+export { ProviderAuthError, pkceChallenge, createPkce, createAuthorizationState, authorizationUrl, readAuthorizationRedirect, exchangeAuthorizationCode, refreshTokens, createTokenSource, TOKEN_REFRESH_MARGIN_MS, } from './oauth.js';
+export { createProviderClient, ProviderApiError, } from './client.js';
+export { rentNode, finishRental, RentNodeError, DEFAULT_NODE_CODE_DEADLINE_MS, NODE_CODE_POLL_MS, RENTAL_INVITATION_TTL_MS, } from './rent-node.js';
+//# sourceMappingURL=index.js.map

package/dist/provider/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/provider/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAA2B,MAAM,iBAAiB,CAAC;AAC5G,OAAO,EACN,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,wBAAwB,EACxB,gBAAgB,EAChB,yBAAyB,EACzB,yBAAyB,EACzB,aAAa,EACb,iBAAiB,EACjB,uBAAuB,GASvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,oBAAoB,EACpB,gBAAgB,GAchB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,6BAA6B,EAC7B,iBAAiB,EACjB,wBAAwB,GAQxB,MAAM,gBAAgB,CAAC"}

package/dist/provider/oauth.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 type { ProviderDescriptor } from './descriptor.js';
+/**
+ * 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 declare class ProviderAuthError extends Error {
+    readonly code: string;
+    constructor(code: string, description?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 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 declare function pkceChallenge(verifier: string): string;
+/** A fresh pair: 32 random bytes as a 43-character base64url verifier, and its challenge. */
+export declare function createPkce(): Pkce;
+/** A random `state` for one authorization, which {@link readAuthorizationRedirect} checks the redirect against. */
+export declare function createAuthorizationState(): string;
+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 declare function authorizationUrl(descriptor: ProviderDescriptor, options: AuthorizationUrlOptions): string;
+/** 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 declare function readAuthorizationRedirect(url: string, options: {
+    expectedState: string;
+}): AuthorizationRedirect;
+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 declare function exchangeAuthorizationCode(descriptor: ProviderDescriptor, options: ExchangeAuthorizationCodeOptions): Promise<ProviderTokens>;
+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 declare function refreshTokens(descriptor: ProviderDescriptor, options: RefreshTokensOptions): Promise<ProviderTokens>;
+/** 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 declare const TOKEN_REFRESH_MARGIN_MS = 60000;
+/**
+ * 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 declare function createTokenSource(options: TokenSourceOptions): TokenSource;

package/dist/provider/oauth.js

@@ -0,0 +1,199 @@
+/**
+ * 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';
+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(code, description, options) {
+        super(description ? `${code}: ${description}` : code, options);
+        this.code = code;
+        this.name = 'ProviderAuthError';
+    }
+}
+/** The S256 challenge for `verifier`: base64url(SHA-256(ascii(verifier))), unpadded. */
+export function pkceChallenge(verifier) {
+    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() {
+    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() {
+    return uint8ArrayToString(randomBytes(16), 'base64url');
+}
+/** 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, options) {
+    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();
+}
+/**
+ * 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, options) {
+    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 };
+}
+/** `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, options) {
+    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);
+}
+/** `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, options) {
+    return await requestTokens(descriptor, {
+        grant_type: 'refresh_token',
+        refresh_token: options.refreshToken,
+        client_id: options.clientId,
+    }, options.fetch);
+}
+/** 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 = 60000;
+/**
+ * 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) {
+    const now = options.now ?? Date.now;
+    let current = options.tokens;
+    let inFlight = null;
+    const refresh = () => {
+        if (!inFlight) {
+            inFlight = rotate().finally(() => { inFlight = null; });
+        }
+        return inFlight;
+    };
+    async function rotate() {
+        let next;
+        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() {
+            const fresh = now() < current.expiresAt - TOKEN_REFRESH_MARGIN_MS ? current : await refresh();
+            return fresh.accessToken;
+        },
+        async invalidate(stale) {
+            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, form, fetchImpl) {
+    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) {
+    try {
+        const parsed = await response.json();
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : 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, requestedAt) {
+    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 !== '') : [],
+    };
+}
+//# sourceMappingURL=oauth.js.map

package/dist/provider/oauth.js.map

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

package/dist/provider/rent-node.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 type { CadreNode } from '../cadre-node.js';
+import { type ProviderClient } from './client.js';
+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 declare class RentNodeError extends Error {
+    readonly code: RentNodeErrorCode;
+    readonly containerId?: string | undefined;
+    constructor(code: RentNodeErrorCode, containerId?: string | undefined);
+}
+/** 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.
+ */
+export declare const DEFAULT_NODE_CODE_DEADLINE_MS = 120000;
+export declare const NODE_CODE_POLL_MS = 2000;
+/** Lifetime of the invitation a rental mints: long enough for the container to start and redeem, short enough to limit a leaked bundle. */
+export declare const RENTAL_INVITATION_TTL_MS: number;
+/**
+ * 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 declare function rentNode(node: RentingNode, client: ProviderClient, options?: RentNodeOptions): Promise<RentNodeResult>;
+/**
+ * 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 declare function finishRental(node: RentingNode, client: ProviderClient, containerId: string, options?: RentNodeOptions): Promise<RentNodeResult | RentalFailed>;