@runonflux/flux-cloud-mcp 0.1.0

package/dist/deploy.js

@@ -0,0 +1,216 @@
+/**
+ * Deploying an app is two halves that must agree:
+ *
+ *   1. A signed specification message, handed to one FluxOS node and gossiped
+ *      to the network. The node answers with a 64-character hash and keeps the
+ *      message in a temporary store for one hour.
+ *   2. An on-chain payment to the network deployment address carrying that
+ *      hash in an OP_RETURN. When nodes index the transaction they pair it with
+ *      the stored message, check the amount, and publish the app globally.
+ *
+ * If the payment never lands the message just expires and nothing is spent.
+ * The amount paid is the Flux Cloud USD quote converted to FLUX. Consensus
+ * would accept far less, but that minimum is checked here only as a guard:
+ * underpaying it burns the FLUX with no refund, since the message is dropped
+ * silently and the same hash cannot be paid twice.
+ */
+import { Explorer, buildPayment, selectSpendable, toFlux, SATOSHIS } from './chain.js';
+import { FluxClient, findHealthyNodes } from './fluxapi.js';
+import { currentSession, identityFromWif, signMessage } from './keys.js';
+import { encryptEnterprise } from './enterprise.js';
+import { consensusMinimumFlux, quoteFromNetwork, } from './pricing.js';
+import { REGISTER_TYPE, UPDATE_TYPE, durabilityWarnings, formatSpecification, signablePayload, validateSpecification, } from './spec.js';
+const TEMP_MESSAGE_TTL_MS = 3600 * 1000;
+const FEE_ALLOWANCE_SAT = 100000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function walletFromConfig(config) {
+    if (!config.ownerWif) {
+        throw new Error('FLUX_ID_PRIVATE_KEY is not configured. Run flux_generate_keys, or set it to the WIF of your Flux ID.');
+    }
+    if (!config.payerWif) {
+        throw new Error('FLUX_PAYMENT_PRIVATE_KEY is not configured. Run flux_generate_keys, or set it to the WIF of a funded Flux address.');
+    }
+    return { owner: identityFromWif(config.ownerWif), payer: identityFromWif(config.payerWif) };
+}
+export function api(config) {
+    return new FluxClient(config.apiUrl, config.requestTimeoutMs);
+}
+export function explorer(config) {
+    return new Explorer(config.explorerUrls);
+}
+export async function publishedSpec(client, name) {
+    try {
+        const raw = await client.raw('GET', `/apps/appspecifications/${name}`, { timeoutMs: 30000 });
+        const payload = raw;
+        return payload.status === 'success' && payload.data?.name === name ? payload.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function appLocations(client, name) {
+    const raw = (await client.raw('GET', `/apps/location/${name}`, { timeoutMs: 30000 }));
+    return raw.status === 'success' && Array.isArray(raw.data) ? raw.data : [];
+}
+/**
+ * Pick a node that can take the registration: enough peers, ArcaneOS when
+ * the spec is enterprise, and honouring a pinned FLUX_NODE_URL.
+ */
+export async function selectNode(config, { arcane = false, log = () => { } } = {}) {
+    if (config.nodeUrl)
+        return new FluxClient(config.nodeUrl, config.requestTimeoutMs);
+    const [node] = await findHealthyNodes(api(config), 1, { arcane, log });
+    return node.client;
+}
+/**
+ * Everything needed to decide whether a deployment can proceed, without
+ * signing, spending or broadcasting anything.
+ */
+export async function plan(config, input, options = {}) {
+    const { log = () => { } } = options;
+    const wallet = walletFromConfig(config);
+    const lb = api(config);
+    const spec = formatSpecification({ ...input, owner: wallet.owner.zelid });
+    const isEnterprise = Boolean(options.enterprise) || Boolean(spec.enterprise);
+    const errors = validateSpecification(options.enterprise ? { ...spec, compose: options.enterprise.compose } : spec);
+    if (errors.length)
+        throw new Error(`Specification is not valid:\n- ${errors.join('\n- ')}`);
+    const [previous, node] = await Promise.all([
+        publishedSpec(lb, spec.name),
+        selectNode(config, { arcane: isEnterprise, log }),
+    ]);
+    const action = previous ? 'update' : 'register';
+    if (previous && previous.owner !== wallet.owner.zelid) {
+        throw new Error(`${spec.name} is already registered on the network by ${previous.owner}. Pick another name.`);
+    }
+    let candidate = spec;
+    if (options.enterprise) {
+        const session = currentSession(wallet.owner.wif);
+        candidate = await encryptEnterprise(node, session, spec, options.enterprise);
+        log('enterprise components encrypted for the network');
+    }
+    const verifyPath = action === 'update'
+        ? '/apps/verifyappupdatespecifications'
+        : '/apps/verifyappregistrationspecifications';
+    const formatted = await node.post(verifyPath, candidate, { timeoutMs: 120000 });
+    log(`node validated the specification (${action})`);
+    const [quote, deployment, info, balance] = await Promise.all([
+        quoteFromNetwork(lb, candidate),
+        lb.get('/apps/deploymentinformation', { timeoutMs: 30000 }),
+        lb.get('/daemon/getinfo', { timeoutMs: 20000 }),
+        explorer(config).balance(wallet.payer.fluxAddress),
+    ]);
+    const height = info.blocks;
+    const minimum = consensusMinimumFlux(candidate, deployment.price, height);
+    const requiredSat = Math.round(quote.flux * SATOSHIS) + FEE_ALLOWANCE_SAT;
+    const warnings = durabilityWarnings(options.enterprise ? { ...spec, compose: options.enterprise.compose } : spec);
+    if (quote.flux < minimum) {
+        warnings.push(`The network quoted ${quote.flux} FLUX but consensus needs at least ${minimum} FLUX; the payment will be raised to ${minimum} FLUX.`);
+    }
+    return {
+        action,
+        spec: candidate,
+        formatted,
+        previous,
+        quote,
+        consensusMinimumFlux: minimum,
+        deployment,
+        height,
+        payer: wallet.payer.fluxAddress,
+        balanceFlux: toFlux(balance.spendable),
+        requiredFlux: toFlux(requiredSat),
+        funded: balance.spendable >= requiredSat,
+        warnings,
+        node,
+    };
+}
+/** Sign, broadcast the message, then pay for it. Spends FLUX. */
+export async function execute(config, prepared, log = () => { }) {
+    const wallet = walletFromConfig(config);
+    if (!prepared.funded) {
+        throw new Error(`Payer ${prepared.payer} holds ${prepared.balanceFlux} FLUX spendable but needs about ${prepared.requiredFlux} FLUX. Fund the address and try again.`);
+    }
+    const type = prepared.action === 'update' ? UPDATE_TYPE : REGISTER_TYPE;
+    const timestamp = Date.now();
+    const signature = signMessage(signablePayload(prepared.formatted, timestamp, type), wallet.owner.wif);
+    const session = currentSession(wallet.owner.wif);
+    const message = { type, version: 1, appSpecification: prepared.formatted, timestamp, signature };
+    const hash = await prepared.node.post(prepared.action === 'update' ? '/apps/appupdate' : '/apps/appregister', message, { session, timeoutMs: 180000 });
+    if (typeof hash !== 'string' || hash.length !== 64) {
+        throw new Error(`Node returned an unexpected message hash: ${JSON.stringify(hash)}`);
+    }
+    log(`message broadcast, hash ${hash}`);
+    // Re-check against a fresh price table and height right before spending:
+    // consensus enforces the interval in force where the payment CONFIRMS.
+    const lb = api(config);
+    const [freshDeployment, info] = await Promise.all([
+        lb.get('/apps/deploymentinformation', { timeoutMs: 30000 }),
+        lb.get('/daemon/getinfo', { timeoutMs: 20000 }),
+    ]);
+    if (freshDeployment.address !== prepared.deployment.address) {
+        throw new Error('Deployment address changed between quote and payment; nothing was paid.');
+    }
+    const minimum = consensusMinimumFlux(prepared.spec, freshDeployment.price, info.blocks + 5);
+    const payFlux = Math.max(prepared.quote.flux, minimum);
+    const amountSat = Math.round(payFlux * SATOSHIS);
+    const chain = explorer(config);
+    const utxos = selectSpendable(await chain.utxos(wallet.payer.fluxAddress));
+    const payment = buildPayment({
+        wif: wallet.payer.wif,
+        to: freshDeployment.address,
+        amountSat,
+        message: hash,
+        utxos,
+        height: info.blocks,
+    });
+    const txid = await chain.broadcast(payment.hex);
+    log(`paid ${payFlux} FLUX, txid ${txid}`);
+    return {
+        action: prepared.action,
+        name: prepared.formatted.name,
+        messageHash: hash,
+        messageExpiresAt: new Date(timestamp + TEMP_MESSAGE_TTL_MS).toISOString(),
+        txid,
+        paidFlux: payFlux,
+        paidUsd: prepared.quote.usd,
+        feeFlux: toFlux(payment.fee),
+        deploymentAddress: freshDeployment.address,
+    };
+}
+/**
+ * Poll until the message is accepted and instances run, within `timeoutMs`.
+ * Returns partial progress on timeout so a caller can simply call again.
+ */
+export async function waitForApp(config, name, options = {}) {
+    const { txid, previousHash, timeoutMs = 5 * 60 * 1000, pollMs = 20000 } = options;
+    const lb = api(config);
+    const chain = explorer(config);
+    const deadline = Date.now() + timeoutMs;
+    let confirmations = 0;
+    let accepted = null;
+    let instances = [];
+    for (;;) {
+        if (txid && confirmations < 1) {
+            confirmations = Number((await chain.transaction(txid).catch(() => ({ confirmations: 0 }))).confirmations ?? 0);
+        }
+        const current = await publishedSpec(lb, name);
+        if (current && (!previousHash || current.hash !== previousHash))
+            accepted = current;
+        if (accepted)
+            instances = await appLocations(lb, name);
+        const wanted = accepted?.instances ?? 0;
+        const done = Boolean(accepted) && instances.length >= wanted;
+        if (done || Date.now() >= deadline) {
+            return {
+                accepted,
+                paymentConfirmations: confirmations,
+                instances,
+                wantedInstances: wanted,
+                done,
+                timedOut: !done,
+            };
+        }
+        await sleep(pollMs);
+    }
+}
+//# sourceMappingURL=deploy.js.map

package/dist/deploy.js.map

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

package/dist/docs.d.ts

@@ -0,0 +1,5 @@
+/** Guide texts served as MCP resources so a host can load them into context. */
+export declare const OVERVIEW = "# Flux Cloud, for agents\n\nFlux Cloud is a decentralized cloud: thousands of independently operated\nnodes run Docker containers for a monthly price paid in FLUX. There is no\naccount to create. Two secp256k1 keys are all the identity there is:\n\n- **Flux ID** (a \"1...\" address, also called ZelID): owns apps. It signs the\n  app specification and API sessions. It never holds funds.\n- **Payment address** (a \"t1...\" address): holds FLUX and pays deployment\n  fees on-chain. It can be rotated without changing app ownership.\n\nBoth come from `FLUX_ID_PRIVATE_KEY` and `FLUX_PAYMENT_PRIVATE_KEY` in this\nserver's environment. `flux_generate_keys` creates a fresh pair.\n\n## How a deployment works\n\n1. Describe the app: name, Docker image(s), ports, cpu/ram/hdd per component,\n   instance count, term. `flux_build_spec` turns that into a v8 spec.\n2. `flux_quote_app` returns the price in USD and the FLUX to pay.\n3. `flux_deploy_app` with `confirm: true` validates the spec on a node, signs it\n   with the Flux ID, broadcasts it, and pays the quoted FLUX from the payment\n   address. The transaction carries the message hash in an OP_RETURN.\n4. `flux_wait_for_app` (or `flux_get_app`) reports acceptance and the IPs\n   where instances run. Acceptance takes a few minutes; images then pull.\n\nAn existing app of the same owner is **updated** by the same call: the new\nspec replaces the old, and the network credits the unused part of the old term.\nTo stop an app early, update it with a very short term (`flux_cancel_app`).\n\n## Reaching an app\n\nEach instance is reachable at `http://<node-ip>:<port>` for every public port\nin the spec. The network also serves `https://<appname>.app.runonflux.io`\n(an alias for the first public port) and `<appname>_<port>.app.runonflux.io`\nfor every public port, load balanced across instances. Custom domains go in the component's\n`domains` list, one per port, and need a CNAME to `<appname>.app.runonflux.io`.\n\n## Rules of thumb\n\n- Names: 1-63 chars, letters/digits/inner hyphens, must not start with \"flux\"\n  or \"zel\", unique network-wide.\n- Public ports: pick from 31000-39999 unless you need a specific one; ports\n  0-1023, 8080, 8081, 8443 and 6667 are \"enterprise ports\" billed extra.\n- Persisted paths must be prefixed `r:` (replicated) to survive instance moves.\n- Images need an explicit tag and must be public unless `repoauth` is set.\n- One network month is 88000 blocks (about 30.5 days). Terms run 1 block to\n  12 months; 3+ months earn 3 to 12 percent off.\n- Flux sets only the container's Cmd, never Entrypoint.\n";
+export declare const SPEC_FORMAT = "# Flux v8 application specification\n\n```json\n{\n  \"version\": 8,\n  \"name\": \"myapp\",\n  \"description\": \"What it is\",\n  \"owner\": \"1YourFluxIdAddress\",\n  \"compose\": [\n    {\n      \"name\": \"web\",\n      \"description\": \"Web front end\",\n      \"repotag\": \"nginx:1.27-alpine\",\n      \"ports\": [31080],\n      \"domains\": [\"\"],\n      \"environmentParameters\": [\"KEY=value\"],\n      \"commands\": [],\n      \"containerPorts\": [80],\n      \"containerData\": \"r:/usr/share/nginx/html\",\n      \"cpu\": 0.5,\n      \"ram\": 500,\n      \"hdd\": 5,\n      \"repoauth\": \"\"\n    }\n  ],\n  \"instances\": 3,\n  \"contacts\": [],\n  \"geolocation\": [],\n  \"expire\": 88000,\n  \"nodes\": [],\n  \"staticip\": false,\n  \"enterprise\": \"\"\n}\n```\n\nField notes:\n\n- `compose`: 1-10 components. Each is one container. Components of one app\n  share a network and reach each other by component name.\n- `ports` / `containerPorts` / `domains`: parallel arrays, one entry per\n  exposed port. `domains` entries are \"\" or a custom domain.\n- `environmentParameters`: up to 20 \"KEY=value\" strings.\n- `commands`: up to 20 strings, passed as the container Cmd.\n- `containerData`: the path inside the container that persists. Prefixes:\n  `r:` replicate across instances (Syncthing), `g:` primary/standby\n  replication, `s:` sync only. Multiple paths: \"r:/data|/config\".\n- `cpu`: 0.1 to 15 in 0.1 steps. `ram`: 100 to 59000 MB in 100 MB steps.\n  `hdd`: 1 to 820 GB whole numbers.\n- `instances`: 1-100 copies, each on a different node.\n- `expire`: term in blocks. 88000 = 1 month. Max 1056000 (12 months).\n- `geolocation`: rules like \"acEU\" (allow continent EU), \"acNA_US\" (allow a\n  country), \"a!cAS\" (deny a continent), \"acALL\". Empty means anywhere.\n- `nodes`: pin to specific node IPs (adds the scope surcharge).\n- `staticip`: only nodes with a static IP (surcharge).\n- `enterprise`: \"\" for a normal app. For a private app the components are\n  encrypted into this field and `compose` is published empty; only the node\n  running it can decrypt. Use `enterprise` in `flux_deploy_app`.\n";
+export declare const PRICING = "# Flux Cloud pricing\n\nPrices are set in US dollars and paid in FLUX. This server always quotes the\nFlux Cloud USD price, converted at the live FLUX market rate.\n\nPer month, per instance-third of the app's resource total (an app's resources\nare priced as a single node's share; the per-instance figure is total / 3):\n\n| Resource | USD / month |\n|---|---|\n| 0.1 CPU core | $0.15 |\n| 100 MB RAM | $0.05 |\n| 1 GB SSD | $0.02 |\n| enterprise port (0-1023, 8080, 8081, 8443, 6667) | $2.00 each |\n| node pinning or private (enterprise) app | $4.00 |\n| static IP nodes | $2.00 |\n\nThen: multiplied by the instance count; minimum $0.99 per app per month;\nsmall apps (under 3 cores, 6 GB RAM, 150 GB and fewer than 4 instances) get\n20 percent off, medium apps 10 percent off; primary/standby (\"g:\") storage 20\npercent off; terms of 3, 6 and 9+ months get 3, 6 and 12 percent off.\n\nPaying in FLUX earns a 5 percent discount, so\n`FLUX to pay = USD / market rate x 0.95`.\n\n`flux_quote_app` returns the authoritative figure from the network; the same\nendpoint prices updates, crediting the unused part of the previous term.\n\nWorked example: one component with 0.5 CPU, 500 MB, 5 GB, 3 instances, 1 month\n= (0.75 + 0.25 + 0.10) / 3 = $0.37 per instance, x3 = $1.11, small-app\ndiscount = $0.89, floored to $0.99 per month.\n";
+export declare const GOTCHAS = "# Things that are easy to get wrong on Flux\n\n- **Underpaying burns FLUX.** Nodes drop an underpaid message silently and the\n  payment is not refunded. This server pays the quoted amount and re-checks\n  the network's minimum immediately before broadcasting.\n- **The message lives one hour.** Payment has to be broadcast within an hour of\n  registration; this server does both in one step.\n- **Acceptance is not instant.** The payment needs a confirmation (about 30\n  seconds per block), then nodes pair it with the message. Expect 2-10\n  minutes, then image pull time.\n- **Node-local data disappears.** Instances move when nodes churn. Persist\n  with `r:` and run 3+ instances if the data matters.\n- **Entrypoint images.** Flux only sets Cmd, so an image whose ENTRYPOINT is a\n  binary cannot be given a shell command through `commands`.\n- **Ports must be unique per node.** Two apps using the same public port\n  cannot share a node; pick unusual ports in 31000-39999.\n- **Non-streamed HTTP through the shared domain times out at 25 s.** Long\n  requests must stream or use the direct `ip:port`.\n- **Updates cost the difference.** The network credits the unused part of the\n  previous term; a mid-term update with the same resources is nearly free.\n- **Enterprise apps need ArcaneOS nodes.** Only they can decrypt and validate\n  a private spec; this server selects one automatically.\n";

package/dist/docs.js

@@ -0,0 +1,164 @@
+/** Guide texts served as MCP resources so a host can load them into context. */
+export const OVERVIEW = `# Flux Cloud, for agents
+
+Flux Cloud is a decentralized cloud: thousands of independently operated
+nodes run Docker containers for a monthly price paid in FLUX. There is no
+account to create. Two secp256k1 keys are all the identity there is:
+
+- **Flux ID** (a "1..." address, also called ZelID): owns apps. It signs the
+  app specification and API sessions. It never holds funds.
+- **Payment address** (a "t1..." address): holds FLUX and pays deployment
+  fees on-chain. It can be rotated without changing app ownership.
+
+Both come from \`FLUX_ID_PRIVATE_KEY\` and \`FLUX_PAYMENT_PRIVATE_KEY\` in this
+server's environment. \`flux_generate_keys\` creates a fresh pair.
+
+## How a deployment works
+
+1. Describe the app: name, Docker image(s), ports, cpu/ram/hdd per component,
+   instance count, term. \`flux_build_spec\` turns that into a v8 spec.
+2. \`flux_quote_app\` returns the price in USD and the FLUX to pay.
+3. \`flux_deploy_app\` with \`confirm: true\` validates the spec on a node, signs it
+   with the Flux ID, broadcasts it, and pays the quoted FLUX from the payment
+   address. The transaction carries the message hash in an OP_RETURN.
+4. \`flux_wait_for_app\` (or \`flux_get_app\`) reports acceptance and the IPs
+   where instances run. Acceptance takes a few minutes; images then pull.
+
+An existing app of the same owner is **updated** by the same call: the new
+spec replaces the old, and the network credits the unused part of the old term.
+To stop an app early, update it with a very short term (\`flux_cancel_app\`).
+
+## Reaching an app
+
+Each instance is reachable at \`http://<node-ip>:<port>\` for every public port
+in the spec. The network also serves \`https://<appname>.app.runonflux.io\`
+(an alias for the first public port) and \`<appname>_<port>.app.runonflux.io\`
+for every public port, load balanced across instances. Custom domains go in the component's
+\`domains\` list, one per port, and need a CNAME to \`<appname>.app.runonflux.io\`.
+
+## Rules of thumb
+
+- Names: 1-63 chars, letters/digits/inner hyphens, must not start with "flux"
+  or "zel", unique network-wide.
+- Public ports: pick from 31000-39999 unless you need a specific one; ports
+  0-1023, 8080, 8081, 8443 and 6667 are "enterprise ports" billed extra.
+- Persisted paths must be prefixed \`r:\` (replicated) to survive instance moves.
+- Images need an explicit tag and must be public unless \`repoauth\` is set.
+- One network month is 88000 blocks (about 30.5 days). Terms run 1 block to
+  12 months; 3+ months earn 3 to 12 percent off.
+- Flux sets only the container's Cmd, never Entrypoint.
+`;
+export const SPEC_FORMAT = `# Flux v8 application specification
+
+\`\`\`json
+{
+  "version": 8,
+  "name": "myapp",
+  "description": "What it is",
+  "owner": "1YourFluxIdAddress",
+  "compose": [
+    {
+      "name": "web",
+      "description": "Web front end",
+      "repotag": "nginx:1.27-alpine",
+      "ports": [31080],
+      "domains": [""],
+      "environmentParameters": ["KEY=value"],
+      "commands": [],
+      "containerPorts": [80],
+      "containerData": "r:/usr/share/nginx/html",
+      "cpu": 0.5,
+      "ram": 500,
+      "hdd": 5,
+      "repoauth": ""
+    }
+  ],
+  "instances": 3,
+  "contacts": [],
+  "geolocation": [],
+  "expire": 88000,
+  "nodes": [],
+  "staticip": false,
+  "enterprise": ""
+}
+\`\`\`
+
+Field notes:
+
+- \`compose\`: 1-10 components. Each is one container. Components of one app
+  share a network and reach each other by component name.
+- \`ports\` / \`containerPorts\` / \`domains\`: parallel arrays, one entry per
+  exposed port. \`domains\` entries are "" or a custom domain.
+- \`environmentParameters\`: up to 20 "KEY=value" strings.
+- \`commands\`: up to 20 strings, passed as the container Cmd.
+- \`containerData\`: the path inside the container that persists. Prefixes:
+  \`r:\` replicate across instances (Syncthing), \`g:\` primary/standby
+  replication, \`s:\` sync only. Multiple paths: "r:/data|/config".
+- \`cpu\`: 0.1 to 15 in 0.1 steps. \`ram\`: 100 to 59000 MB in 100 MB steps.
+  \`hdd\`: 1 to 820 GB whole numbers.
+- \`instances\`: 1-100 copies, each on a different node.
+- \`expire\`: term in blocks. 88000 = 1 month. Max 1056000 (12 months).
+- \`geolocation\`: rules like "acEU" (allow continent EU), "acNA_US" (allow a
+  country), "a!cAS" (deny a continent), "acALL". Empty means anywhere.
+- \`nodes\`: pin to specific node IPs (adds the scope surcharge).
+- \`staticip\`: only nodes with a static IP (surcharge).
+- \`enterprise\`: "" for a normal app. For a private app the components are
+  encrypted into this field and \`compose\` is published empty; only the node
+  running it can decrypt. Use \`enterprise\` in \`flux_deploy_app\`.
+`;
+export const PRICING = `# Flux Cloud pricing
+
+Prices are set in US dollars and paid in FLUX. This server always quotes the
+Flux Cloud USD price, converted at the live FLUX market rate.
+
+Per month, per instance-third of the app's resource total (an app's resources
+are priced as a single node's share; the per-instance figure is total / 3):
+
+| Resource | USD / month |
+|---|---|
+| 0.1 CPU core | $0.15 |
+| 100 MB RAM | $0.05 |
+| 1 GB SSD | $0.02 |
+| enterprise port (0-1023, 8080, 8081, 8443, 6667) | $2.00 each |
+| node pinning or private (enterprise) app | $4.00 |
+| static IP nodes | $2.00 |
+
+Then: multiplied by the instance count; minimum $0.99 per app per month;
+small apps (under 3 cores, 6 GB RAM, 150 GB and fewer than 4 instances) get
+20 percent off, medium apps 10 percent off; primary/standby ("g:") storage 20
+percent off; terms of 3, 6 and 9+ months get 3, 6 and 12 percent off.
+
+Paying in FLUX earns a 5 percent discount, so
+\`FLUX to pay = USD / market rate x 0.95\`.
+
+\`flux_quote_app\` returns the authoritative figure from the network; the same
+endpoint prices updates, crediting the unused part of the previous term.
+
+Worked example: one component with 0.5 CPU, 500 MB, 5 GB, 3 instances, 1 month
+= (0.75 + 0.25 + 0.10) / 3 = $0.37 per instance, x3 = $1.11, small-app
+discount = $0.89, floored to $0.99 per month.
+`;
+export const GOTCHAS = `# Things that are easy to get wrong on Flux
+
+- **Underpaying burns FLUX.** Nodes drop an underpaid message silently and the
+  payment is not refunded. This server pays the quoted amount and re-checks
+  the network's minimum immediately before broadcasting.
+- **The message lives one hour.** Payment has to be broadcast within an hour of
+  registration; this server does both in one step.
+- **Acceptance is not instant.** The payment needs a confirmation (about 30
+  seconds per block), then nodes pair it with the message. Expect 2-10
+  minutes, then image pull time.
+- **Node-local data disappears.** Instances move when nodes churn. Persist
+  with \`r:\` and run 3+ instances if the data matters.
+- **Entrypoint images.** Flux only sets Cmd, so an image whose ENTRYPOINT is a
+  binary cannot be given a shell command through \`commands\`.
+- **Ports must be unique per node.** Two apps using the same public port
+  cannot share a node; pick unusual ports in 31000-39999.
+- **Non-streamed HTTP through the shared domain times out at 25 s.** Long
+  requests must stream or use the direct \`ip:port\`.
+- **Updates cost the difference.** The network credits the unused part of the
+  previous term; a mid-term update with the same resources is nearly free.
+- **Enterprise apps need ArcaneOS nodes.** Only they can decrypt and validate
+  a private spec; this server selects one automatically.
+`;
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDvB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyD1B,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BtB,CAAC;AAEF,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBtB,CAAC"}

package/dist/enterprise.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Enterprise (private) specifications.
+ *
+ * A v8 enterprise app publishes an empty `compose` and carries the real
+ * components and contacts encrypted in the `enterprise` field. Layout, from
+ * enterpriseHelper.js decryptEnterpriseFromSession:
+ *
+ *   base64( RSA-OAEP-SHA256(256 bytes)( base64 text of AES-256 key )
+ *           || nonce(12) || AES-256-GCM ciphertext || tag(16) )
+ *
+ * The RSA block wraps the BASE64 TEXT of the AES key, not the raw bytes; raw
+ * bytes decrypt fine and then fail one step later as "Invalid key length".
+ *
+ * Only ArcaneOS nodes hold the private half, so only they can validate or
+ * accept an enterprise registration.
+ */
+import type { KeyObject } from 'node:crypto';
+import type { FluxClient } from './fluxapi.js';
+import type { Session } from './keys.js';
+import type { AppComponent, AppSpec } from './spec.js';
+export declare function buildEnterpriseBlob(publicKey: KeyObject, plaintextJson: string): string;
+/**
+ * Encrypt `compose` and `contacts` into the envelope. The node's app public
+ * key is fetched through an owner session (a 'user' privileged endpoint).
+ */
+export declare function encryptEnterprise(node: FluxClient, session: Session, spec: AppSpec, plaintext: {
+    compose: AppComponent[];
+    contacts: string[];
+}): Promise<AppSpec>;

package/dist/enterprise.js

@@ -0,0 +1,45 @@
+/**
+ * Enterprise (private) specifications.
+ *
+ * A v8 enterprise app publishes an empty `compose` and carries the real
+ * components and contacts encrypted in the `enterprise` field. Layout, from
+ * enterpriseHelper.js decryptEnterpriseFromSession:
+ *
+ *   base64( RSA-OAEP-SHA256(256 bytes)( base64 text of AES-256 key )
+ *           || nonce(12) || AES-256-GCM ciphertext || tag(16) )
+ *
+ * The RSA block wraps the BASE64 TEXT of the AES key, not the raw bytes; raw
+ * bytes decrypt fine and then fail one step later as "Invalid key length".
+ *
+ * Only ArcaneOS nodes hold the private half, so only they can validate or
+ * accept an enterprise registration.
+ */
+import { constants, createCipheriv, createPublicKey, publicEncrypt, randomBytes, } from 'node:crypto';
+function toPublicKey(raw) {
+    const s = raw.trim();
+    if (s.includes('-----BEGIN'))
+        return createPublicKey(s);
+    return createPublicKey({ key: Buffer.from(s, 'base64'), format: 'der', type: 'spki' });
+}
+export function buildEnterpriseBlob(publicKey, plaintextJson) {
+    const aesKey = randomBytes(32);
+    const encryptedKey = publicEncrypt({ key: publicKey, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, Buffer.from(aesKey.toString('base64')));
+    if (encryptedKey.length !== 256) {
+        throw new Error(`Expected a 256-byte RSA block (RSA-2048), got ${encryptedKey.length}`);
+    }
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', aesKey, nonce);
+    const body = Buffer.concat([cipher.update(plaintextJson, 'utf8'), cipher.final()]);
+    return Buffer.concat([encryptedKey, nonce, body, cipher.getAuthTag()]).toString('base64');
+}
+/**
+ * Encrypt `compose` and `contacts` into the envelope. The node's app public
+ * key is fetched through an owner session (a 'user' privileged endpoint).
+ */
+export async function encryptEnterprise(node, session, spec, plaintext) {
+    const raw = await node.post('/apps/getpublickey', { owner: spec.owner, name: spec.name }, { session, timeoutMs: 60000 });
+    const publicKey = toPublicKey(raw);
+    const blob = buildEnterpriseBlob(publicKey, JSON.stringify({ contacts: plaintext.contacts, compose: plaintext.compose }));
+    return { ...spec, contacts: [], compose: [], enterprise: blob };
+}
+//# sourceMappingURL=enterprise.js.map

package/dist/enterprise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enterprise.js","sourceRoot":"","sources":["../src/enterprise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AAMrB,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACrB,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAoB,EAAE,aAAqB;IAC7E,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC/B,MAAM,YAAY,GAAG,aAAa,CAChC,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,sBAAsB,EAAE,QAAQ,EAAE,QAAQ,EAAE,EACjF,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CACvC,CAAC;IACF,IAAI,YAAY,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,iDAAiD,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnF,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC5F,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAgB,EAChB,OAAgB,EAChB,IAAa,EACb,SAA0D;IAE1D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CACzB,oBAAoB,EACpB,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EACtC,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAC9B,CAAC;IACF,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,mBAAmB,CAC9B,SAAS,EACT,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC,CAC7E,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAClE,CAAC"}

package/dist/fluxapi.d.ts

@@ -0,0 +1,71 @@
+/**
+ * FluxOS HTTP client.
+ *
+ * Every FluxOS response is `{ status: 'success' | 'error', data }`; `unwrap`
+ * turns the error shape into a thrown Error with the node's message.
+ *
+ * POST bodies are sent as text/plain, never application/json. FluxOS installs
+ * `express.json()` globally, but the handlers this server needs
+ * (/apps/appregister, /apps/appupdate, /apps/calculatefiatandfluxprice,
+ * /apps/verifyapp*specifications, /apps/getpublickey) read the raw request
+ * stream themselves. With a JSON content type the middleware has already
+ * consumed the stream, the handler's 'end' listener never fires and the
+ * request hangs until a gateway 504. The payload is still JSON text.
+ */
+import type { Session } from './keys.js';
+export interface FluxResponse<T> {
+    status: 'success' | 'error';
+    data: T;
+}
+export declare class FluxApiError extends Error {
+    readonly endpoint: string;
+    constructor(message: string, endpoint: string);
+}
+export declare function unwrap<T>(payload: unknown, endpoint: string): T;
+export declare function sessionHeader(session: Session): string;
+export interface RequestOptions {
+    body?: unknown;
+    session?: Session | undefined;
+    timeoutMs?: number;
+}
+export declare class FluxClient {
+    readonly baseUrl: string;
+    private readonly defaultTimeoutMs;
+    constructor(baseUrl: string, defaultTimeoutMs?: number);
+    raw(method: 'GET' | 'POST', pathname: string, options?: RequestOptions): Promise<unknown>;
+    get<T>(pathname: string, options?: RequestOptions): Promise<T>;
+    post<T>(pathname: string, body: unknown, options?: RequestOptions): Promise<T>;
+}
+export interface NodeCandidate {
+    endpoint: string;
+    ip: string;
+    tier: string;
+}
+export interface NodeHealth {
+    outgoing: number;
+    incoming: number;
+    ok: boolean;
+    arcaneVersion: string | undefined;
+}
+/** FluxOS refuses registrations on nodes with fewer peers than this. */
+export declare const MIN_OUTGOING_PEERS = 8;
+export declare const MIN_INCOMING_PEERS = 4;
+export declare function listNodeEndpoints(api: FluxClient): Promise<NodeCandidate[]>;
+export declare function nodeHealth(node: FluxClient): Promise<NodeHealth>;
+export interface HealthyNode extends NodeCandidate {
+    client: FluxClient;
+    health: NodeHealth;
+}
+/**
+ * Probe random nodes until `count` of them meet the peer thresholds. With
+ * `arcane` only ArcaneOS nodes qualify: they alone hold the key that
+ * decrypts enterprise specifications, so only they can validate or accept one.
+ */
+export declare function findHealthyNodes(api: FluxClient, count: number, options?: {
+    arcane?: boolean;
+    batchSize?: number;
+    maxProbes?: number;
+    log?: (m: string) => void;
+}): Promise<HealthyNode[]>;
+/** `http://ip:port` for an app instance reported by /apps/location. */
+export declare function instanceEndpoint(ip: string): string;