authflow-cli 0.1.0

package/dist/commands/signup.js

@@ -0,0 +1,53 @@
+import { requireIssuer } from "../config.js";
+import { signupTenant } from "../rail.js";
+import { writeAdminApiKey } from "../secrets.js";
+export function signupCommand(program) {
+    program
+        .command("signup")
+        .description("Mint a per-tenant admin API key (shown once)")
+        .requiredOption("--email <address>", "Email that owns the tenant")
+        .option("--issuer <url>", "Authflow issuer (default: AUTHFLOW_ISSUER)")
+        .option("--write-secrets", "Write the key to an env file (default: .env.local)", true)
+        .option("--no-write-secrets", "Print the key only; do not write it to disk")
+        .option("--secret-destination <path>", "Env-file path for --write-secrets")
+        .addHelpText("after", [
+        "",
+        "The key is scoped to slugs you register with it. Paste it into Cursor as",
+        "AUTHFLOW_ADMIN_API_KEY, then run `authflow mcp` or `authflow init`.",
+    ].join("\n"))
+        .action(async (opts) => {
+        const issuer = requireIssuer(opts.issuer);
+        const receipt = await signupTenant(issuer, opts.email);
+        let storedAt;
+        if (opts.writeSecrets !== false) {
+            storedAt = await writeAdminApiKey({
+                value: receipt.admin_api_key,
+                destination: opts.secretDestination,
+            });
+        }
+        const mcpConfig = {
+            mcpServers: {
+                authflow: {
+                    command: "npx",
+                    args: ["-y", "authflow-cli", "mcp"],
+                    env: {
+                        AUTHFLOW_ISSUER: receipt.issuer,
+                        AUTHFLOW_ADMIN_API_KEY: storedAt ? `<from ${storedAt}>` : receipt.admin_api_key,
+                    },
+                },
+            },
+        };
+        process.stdout.write(JSON.stringify({
+            ...receipt,
+            admin_api_key: storedAt ? `<stored in ${storedAt}>` : receipt.admin_api_key,
+            mcp_config: mcpConfig,
+            next_steps: [
+                storedAt
+                    ? `Load ${storedAt} (or copy the key into Cursor's MCP env) and run: npx -y authflow-cli init --slug <your-slug>`
+                    : "Store the admin_api_key, then: npx -y authflow-cli init --slug <your-slug>",
+                "Or paste mcp_config into Cursor and let the agent finish onboarding.",
+            ],
+        }, null, 2) + "\n");
+    });
+}
+//# sourceMappingURL=signup.js.map

package/dist/commands/signup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signup.js","sourceRoot":"","sources":["../../src/commands/signup.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AASjD,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,8CAA8C,CAAC;SAC3D,cAAc,CAAC,mBAAmB,EAAE,4BAA4B,CAAC;SACjE,MAAM,CAAC,gBAAgB,EAAE,4CAA4C,CAAC;SACtE,MAAM,CAAC,iBAAiB,EAAE,oDAAoD,EAAE,IAAI,CAAC;SACrF,MAAM,CAAC,oBAAoB,EAAE,6CAA6C,CAAC;SAC3E,MAAM,CAAC,6BAA6B,EAAE,mCAAmC,CAAC;SAC1E,WAAW,CACV,OAAO,EACP;QACE,EAAE;QACF,0EAA0E;QAC1E,qEAAqE;KACtE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;SACA,MAAM,CAAC,KAAK,EAAE,IAAmB,EAAE,EAAE;QACpC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAEvD,IAAI,QAA4B,CAAC;QACjC,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC;YAChC,QAAQ,GAAG,MAAM,gBAAgB,CAAC;gBAChC,KAAK,EAAE,OAAO,CAAC,aAAa;gBAC5B,WAAW,EAAE,IAAI,CAAC,iBAAiB;aACpC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,SAAS,GAAG;YAChB,UAAU,EAAE;gBACV,QAAQ,EAAE;oBACR,OAAO,EAAE,KAAK;oBACd,IAAI,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC;oBACnC,GAAG,EAAE;wBACH,eAAe,EAAE,OAAO,CAAC,MAAM;wBAC/B,sBAAsB,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa;qBAChF;iBACF;aACF;SACF,CAAC;QAEF,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CACZ;YACE,GAAG,OAAO;YACV,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,cAAc,QAAQ,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa;YAC3E,UAAU,EAAE,SAAS;YACrB,UAAU,EAAE;gBACV,QAAQ;oBACN,CAAC,CAAC,QAAQ,QAAQ,+FAA+F;oBACjH,CAAC,CAAC,4EAA4E;gBAChF,sEAAsE;aACvE;SACF,EACD,IAAI,EACJ,CAAC,CACF,GAAG,IAAI,CACT,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+export type CliConfig = {
+    issuer: string;
+    adminApiKey?: string;
+    originApiKey?: string;
+    resource?: string;
+    gatewayUrl?: string;
+};
+export declare function requireIssuer(flag?: string): string;
+export declare function requireAdminKey(flag?: string): string;
+export declare function requireOriginKey(flag?: string): string;
+/** Registration receipt fields (snake_case) from RegistryAdminEndpoints. */
+export type RegistrationReceipt = {
+    slug?: string;
+    display_name?: string;
+    resource?: string;
+    gateway_url?: string;
+    prm_url?: string;
+    issuer?: string;
+    keys_url?: string;
+    usage_url?: string;
+    origin_base_uri?: string;
+    connected_account_id?: string;
+    currency?: string;
+    price_amount_minor?: number;
+    credits_per_period?: number;
+    price_version?: number;
+    application_fee_percent?: number;
+    origin_api_key?: string;
+    gateway_egress_cidrs?: string[];
+    status?: string;
+    metering_mode?: string;
+    /** What still blocks go-live: origin_base_uri, connected_account_id, stripe_onboarding_complete. */
+    pending_requirements?: string[];
+};
+export declare function readReceipt(path: string): Promise<RegistrationReceipt>;
+export declare function resolveGatewayUrl(opts: {
+    gatewayUrl?: string;
+    receipt?: RegistrationReceipt;
+}): string | undefined;
+export declare function apiJson<T>(url: string, init?: RequestInit & {
+    expectedStatuses?: number[];
+}): Promise<{
+    status: number;
+    body: T;
+    raw: string;
+}>;
+export declare function bearer(token: string): Record<string, string>;

package/dist/config.js

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+export function requireIssuer(flag) {
+    const issuer = (flag ?? process.env.AUTHFLOW_ISSUER ?? "").trim().replace(/\/+$/, "");
+    if (!issuer) {
+        throw new Error("Set AUTHFLOW_ISSUER or pass --issuer.");
+    }
+    return issuer;
+}
+export function requireAdminKey(flag) {
+    const key = (flag ?? process.env.AUTHFLOW_ADMIN_API_KEY ?? "").trim();
+    if (!key) {
+        throw new Error("Set AUTHFLOW_ADMIN_API_KEY or pass --admin-key.");
+    }
+    return key;
+}
+export function requireOriginKey(flag) {
+    const key = (flag ?? process.env.AUTHFLOW_ORIGIN_API_KEY ?? "").trim();
+    if (!key) {
+        throw new Error("Set AUTHFLOW_ORIGIN_API_KEY or pass --origin-key.");
+    }
+    return key;
+}
+export async function readReceipt(path) {
+    const raw = (await readFile(path, "utf8")).replace(/^\uFEFF/, "");
+    return JSON.parse(raw);
+}
+export function resolveGatewayUrl(opts) {
+    return (opts.gatewayUrl?.trim() ||
+        process.env.AUTHFLOW_GATEWAY_URL?.trim() ||
+        process.env.AUTHFLOW_RESOURCE?.trim() ||
+        opts.receipt?.gateway_url?.trim() ||
+        opts.receipt?.resource?.trim() ||
+        undefined);
+}
+export async function apiJson(url, init = {}) {
+    const { expectedStatuses, ...fetchInit } = init;
+    const response = await fetch(url, fetchInit);
+    const raw = await response.text();
+    let body;
+    try {
+        body = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        throw new Error(`Non-JSON response from ${url} (${response.status}): ${raw.slice(0, 200)}`);
+    }
+    if (expectedStatuses && !expectedStatuses.includes(response.status)) {
+        const err = body;
+        const detail = err.error_description ?? err.error ?? raw.slice(0, 300);
+        throw new Error(`${url} returned ${response.status}: ${detail}`);
+    }
+    return { status: response.status, body, raw };
+}
+export function bearer(token) {
+    return { Authorization: `Bearer ${token}` };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Origin Protocol wire constants, mirrored from `Rail.Kernel.OriginProtocol.OriginProtocolConstants`.
+ * These are published contract: version, never mutate.
+ */
+export declare const OriginProtocol: {
+    readonly version1: "v1";
+    readonly identityHeaderName: "X-Authflow-Identity";
+    readonly verificationKeysPath: "/.well-known/authflow-origin-keys";
+    readonly usagePath: "/origin/v1/usage";
+    readonly conformancePath: "/origin/v1/conformance";
+    readonly devMintHeaderPath: "/origin/v1/dev/mint-header";
+};

package/dist/constants.js

@@ -0,0 +1,13 @@
+/**
+ * Origin Protocol wire constants, mirrored from `Rail.Kernel.OriginProtocol.OriginProtocolConstants`.
+ * These are published contract: version, never mutate.
+ */
+export const OriginProtocol = {
+    version1: "v1",
+    identityHeaderName: "X-Authflow-Identity",
+    verificationKeysPath: "/.well-known/authflow-origin-keys",
+    usagePath: "/origin/v1/usage",
+    conformancePath: "/origin/v1/conformance",
+    devMintHeaderPath: "/origin/v1/dev/mint-header",
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,QAAQ,EAAE,IAAI;IACd,kBAAkB,EAAE,qBAAqB;IACzC,oBAAoB,EAAE,mCAAmC;IACzD,SAAS,EAAE,kBAAkB;IAC7B,eAAe,EAAE,wBAAwB;IACzC,iBAAiB,EAAE,4BAA4B;CACvC,CAAC"}

package/dist/doctor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Preflight against a rail deployment, from a tenant's point of view.
+ *
+ * This exists because of a real onboarding failure: tenant #1 was given a staging hostname whose
+ * DNS resolved but which was never bound to the App Service, so Azure answered `404 Site Not Found`
+ * on every path. They read the 404 on the keys document as "the rail's keys endpoint is broken" and
+ * filed it, while the rail was healthy the whole time on a different hostname. Nothing in the
+ * onboarding path told either side which of the two it was. These checks do.
+ */
+export type DoctorCheck = {
+    name: string;
+    pass: boolean;
+    detail: string;
+    /** What to do about it. Empty when the check passed. */
+    remedy?: string;
+};
+export type DoctorReport = {
+    issuer: string;
+    slug?: string;
+    pass: boolean;
+    checks: DoctorCheck[];
+};
+export declare function runDoctor(issuer: string, slug?: string): Promise<DoctorReport>;
+export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/doctor.js

@@ -0,0 +1,230 @@
+import { OriginProtocol } from "./constants.js";
+const timeoutMs = 15_000;
+export async function runDoctor(issuer, slug) {
+    const base = issuer.trim().replace(/\/+$/, "");
+    const checks = [];
+    const reachable = await checkHostBound(base);
+    checks.push(reachable);
+    // Every later check reads a document from this host. If the host is not the rail, they would all
+    // fail with misleading messages that each look like a separate rail bug — which is exactly the
+    // pile of bugs this whole function exists to prevent.
+    if (!reachable.pass) {
+        return { issuer: base, slug, pass: false, checks };
+    }
+    checks.push(...(await checkOriginKeys(base)));
+    if (slug) {
+        checks.push(await checkProtectedResourceMetadata(base, slug));
+        checks.push(await checkGatewayChallenge(base, slug));
+    }
+    return { issuer: base, slug, pass: checks.every((c) => c.pass), checks };
+}
+/**
+ * An unbound Azure custom domain answers `404 Site Not Found` on every path, `/healthz` included.
+ * That is the signature that separates "wrong hostname" from "endpoint is broken", so it is worth
+ * one dedicated check with an unambiguous remedy.
+ */
+async function checkHostBound(base) {
+    const url = `${base}/healthz`;
+    const response = await fetchOrNull(url);
+    if (!response.ok && response.error) {
+        return {
+            name: "issuer reachable",
+            pass: false,
+            detail: `${url} could not be reached: ${response.error}`,
+            remedy: "Check the hostname and DNS. A TLS name mismatch usually means the hostname is not bound " +
+                "to the deployment that answers on its IP.",
+        };
+    }
+    const status = response.status ?? 0;
+    if (status === 404) {
+        return {
+            name: "issuer reachable",
+            pass: false,
+            detail: `${url} returned 404. /healthz exists on every rail deployment, so this host is not serving the rail.`,
+            remedy: "The hostname is almost certainly not bound to the rail. Use the issuer from your " +
+                "registration receipt rather than a hostname copied from prose, and confirm with " +
+                "GET {issuer}/healthz before anything else.",
+        };
+    }
+    if (status !== 200) {
+        return {
+            name: "issuer reachable",
+            pass: false,
+            detail: `${url} returned ${status}, expected 200.`,
+            remedy: "The host is serving something, but not a healthy rail. Check the deployment.",
+        };
+    }
+    return { name: "issuer reachable", pass: true, detail: `${url} returned 200.` };
+}
+async function checkOriginKeys(base) {
+    const url = `${base}${OriginProtocol.verificationKeysPath}`;
+    const response = await fetchOrNull(url);
+    const checks = [];
+    if (!response.ok || response.status !== 200) {
+        checks.push({
+            name: "origin keys document",
+            pass: false,
+            detail: `${url} returned ${response.status ?? response.error}, expected 200.`,
+            remedy: "The host is a healthy rail but is not serving Origin Protocol keys. That is a rail-side " +
+                "bug — file it. Origins cannot verify identity headers until it is fixed.",
+        });
+        return checks;
+    }
+    let document;
+    try {
+        document = JSON.parse(response.body ?? "");
+    }
+    catch {
+        checks.push({
+            name: "origin keys document",
+            pass: false,
+            detail: `${url} did not return JSON.`,
+            remedy: "File this against the rail.",
+        });
+        return checks;
+    }
+    checks.push({ name: "origin keys document", pass: true, detail: `${url} returned 200.` });
+    // Byte-compare, per spec §5. A mismatch here is the tell-tale of configuring the origin from a
+    // hostname that redirects, or of pointing at the wrong environment entirely.
+    const documentIssuer = (document.issuer ?? "").trim();
+    checks.push(documentIssuer === base
+        ? {
+            name: "issuer matches",
+            pass: true,
+            detail: `Document issuer is ${documentIssuer}.`,
+        }
+        : {
+            name: "issuer matches",
+            pass: false,
+            detail: `Document issuer is '${documentIssuer}', but you configured '${base}'.`,
+            remedy: `Set AUTHFLOW_ISSUER to '${documentIssuer}' — origins MUST reject a keys document whose ` +
+                "issuer does not match their configured issuer, so this mismatch fails every request.",
+        });
+    const version = document.protocol_version ?? "";
+    checks.push(version === OriginProtocol.version1
+        ? { name: "protocol version", pass: true, detail: `Document advertises ${version}.` }
+        : {
+            name: "protocol version",
+            pass: false,
+            detail: `Document advertises '${version}', expected '${OriginProtocol.version1}'.`,
+            remedy: "This CLI implements v1. Upgrade the CLI, or file a rail bug.",
+        });
+    const keys = document.keys ?? [];
+    const signing = keys.filter((k) => k.kty === "OKP" && k.crv === "Ed25519" && k.x);
+    checks.push(signing.length > 0
+        ? {
+            name: "ed25519 verification key",
+            pass: true,
+            detail: `${signing.length} key(s): ${signing.map((k) => k.kid ?? "?").join(", ")}.`,
+        }
+        : {
+            name: "ed25519 verification key",
+            pass: false,
+            detail: "No usable Ed25519 JWK in the document.",
+            remedy: "File this against the rail. Identity headers cannot be verified without one.",
+        });
+    // A private key in a public document would be a total compromise of the identity header, so it
+    // is worth failing loudly rather than trusting that it never happens.
+    const leaked = keys.filter((k) => k.d !== undefined);
+    if (leaked.length > 0) {
+        checks.push({
+            name: "no private key material",
+            pass: false,
+            detail: `${leaked.length} key(s) contain a 'd' member.`,
+            remedy: "Stop. The rail is publishing private key material. Report this immediately and treat the " +
+                "signing key as compromised.",
+        });
+    }
+    return checks;
+}
+async function checkProtectedResourceMetadata(base, slug) {
+    const url = `${base}/.well-known/oauth-protected-resource/${encodeURIComponent(slug)}/mcp`;
+    const response = await fetchOrNull(url);
+    if (response.status === 200) {
+        return { name: "protected resource metadata", pass: true, detail: `${url} returned 200.` };
+    }
+    if (response.status === 404) {
+        return {
+            name: "protected resource metadata",
+            pass: false,
+            detail: `${url} returned 404.`,
+            remedy: `No live resource is registered at slug '${slug}'. A draft resource 404s here by design — ` +
+                "check its pending_requirements.",
+        };
+    }
+    return {
+        name: "protected resource metadata",
+        pass: false,
+        detail: `${url} returned ${response.status ?? response.error}, expected 200.`,
+        remedy: "MCP clients discover the authorization server from this document. File a rail bug.",
+    };
+}
+/**
+ * The paywall is a transport-level 401 carrying `resource_metadata`. If this is not exactly right,
+ * MCP clients never prompt for auth, which presents as "the server just does not work in Claude".
+ */
+async function checkGatewayChallenge(base, slug) {
+    const url = `${base}/${encodeURIComponent(slug)}/mcp`;
+    const response = await fetchOrNull(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }),
+    });
+    if (response.status !== 401) {
+        return {
+            name: "gateway 401 challenge",
+            pass: false,
+            detail: `Unauthenticated POST ${url} returned ${response.status ?? response.error}, expected 401.`,
+            remedy: response.status === 404
+                ? `No live resource at slug '${slug}'. Check pending_requirements on the receipt.`
+                : "An unauthenticated connect that does not 401 means clients will never start OAuth.",
+        };
+    }
+    const challenge = response.headers?.get("www-authenticate") ?? "";
+    if (!/resource_metadata=/i.test(challenge)) {
+        return {
+            name: "gateway 401 challenge",
+            pass: false,
+            detail: `401 returned, but WWW-Authenticate has no resource_metadata parameter: '${challenge}'.`,
+            remedy: "MCP clients cannot discover the authorization server. File a rail bug.",
+        };
+    }
+    return {
+        name: "gateway 401 challenge",
+        pass: true,
+        detail: "401 with a resource_metadata challenge.",
+    };
+}
+/** Network failures are a diagnosis here, not an exception — every one of them is a real finding. */
+async function fetchOrNull(url, init = {}) {
+    try {
+        const response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        return {
+            ok: true,
+            status: response.status,
+            body: await response.text(),
+            headers: response.headers,
+        };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function formatDoctorReport(report) {
+    const lines = [`issuer: ${report.issuer}`];
+    if (report.slug) {
+        lines.push(`slug:   ${report.slug}`);
+    }
+    lines.push("");
+    for (const check of report.checks) {
+        lines.push(`${check.pass ? "PASS" : "FAIL"}  ${check.name}`);
+        lines.push(`      ${check.detail}`);
+        if (!check.pass && check.remedy) {
+            lines.push(`      -> ${check.remedy}`);
+        }
+    }
+    lines.push("");
+    lines.push(report.pass ? "Overall: PASS" : "Overall: FAIL");
+    return lines.join("\n");
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/integration.d.ts

@@ -0,0 +1,44 @@
+import type { RegistrationReceipt } from "./config.js";
+/**
+ * Framework-specific integration instructions, emitted as structured data rather than prose.
+ *
+ * The consumer is usually not a human: it is the creator's own coding agent, which already has the
+ * codebase open. The rail cannot see their files and should not try to — it supplies the plan, the
+ * agent applies it. That split is also what keeps this honest as a public contract: everything here
+ * is derived from the receipt and the published spec, never from rail internals.
+ */
+export declare const integrationFrameworks: readonly ["dotnet", "typescript", "python", "proxy"];
+export type IntegrationFramework = (typeof integrationFrameworks)[number];
+export type IntegrationStep = {
+    title: string;
+    /** What the agent should do. Imperative, one action. */
+    action: string;
+    /** Shell command to run, when the step is a command. */
+    command?: string;
+    /** File content or snippet to apply, when the step is an edit. */
+    snippet?: string;
+    /** Where the snippet goes. */
+    file?: string;
+};
+export type IntegrationPlan = {
+    framework: IntegrationFramework;
+    summary: string;
+    configuration: Record<string, string>;
+    secrets: {
+        key: string;
+        envVar: string;
+        note: string;
+    };
+    steps: IntegrationStep[];
+    verification: string[];
+    invariants: string[];
+    metering: string;
+};
+export declare function isIntegrationFramework(value: string): value is IntegrationFramework;
+export declare function buildIntegrationPlan(framework: IntegrationFramework, receipt: RegistrationReceipt): IntegrationPlan;
+/**
+ * Origins that bill exactly one unit per tool call can skip debit/compensate entirely by declaring
+ * per-tool costs at registration. It is the largest and subtlest part of the integration, so the
+ * plan should say so rather than leaving it to be discovered in §9 of the quickstart.
+ */
+export declare function meteringAdvice(gatewayMetered: boolean): string;