aegis-desktop 1.0.13 → 1.0.15

package/vendor/topup.js

@@ -1,299 +1,3 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
-// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
-// Conveying a modified copy, or running one as a network service, owes the
-// corresponding source under this licence (§5/§13) — see LICENSING.md.
-'use strict';
-
-/**
- * topup.js — the shared token-bank top-up: what to ask for, how to read the
- * answer, and how to know the money arrived.
- *
- * WHY THIS IS SHARED AND NOT HOST CODE. A top-up ends server-side: Stripe's
- * webhook credits the bank (aegis1 `services/billing_service.py`,
- * `add_funds()`), and the browser landing page is pure UI on top of that. But
- * that page (`/topup`) is `@login_required` against a browser SESSION, and
- * `POST /api/v1/auth/register-device` mints the account this product
- * auto-provisions with a password that is never returned and an email at
- * `@device.aegiscloud`. So the very account auto-provision creates cannot sign
- * in to the page it was just sent to: following that link lands on a login
- * wall, and the user concludes the payment failed while the money and the
- * credit are both real.
- *
- * The key that STARTED the checkout is enough to READ the result —
- * `login_required` accepts `X-API-Key`/Bearer, and the same credential
- * authenticates `GET /api/token-bank/balance` — so each host confirms the
- * credit itself. Three hosts need that: the desktop (`desktop/main.js`), the
- * terminal (`aegiscode topup` / `/topup`), and whatever comes next.
- *
- * What must never differ between them, and therefore lives here:
- *
- *   1. the AMOUNT rule — aegis1 rejects anything outside 2..1000 EUR with 400,
- *      and a client that accepts 1 EUR is a round trip the user pays for with
- *      a rejection message;
- *   2. the PAYLOAD reading (`bankAmount`) — aegis1 has shipped
- *      `balance_micros`, `balance_eur`, `balance` and a bare number, and two
- *      hosts guessing differently is how one screen shows a credit the other
- *      misses;
- *   3. the UNKNOWN-vs-ZERO rule — an unreadable bank stays unknown. Reading it
- *      as zero would make the `{}` case look like a real baseline, so the FIRST
- *      credit would be silently swallowed as "no change", and elsewhere a zero
- *      manufactures a paywall out of a timeout;
- *   4. the RISING-READ rule — announce on the first read strictly above the
- *      baseline, once, then stop.
- *
- * What is deliberately NOT here: the timer. The desktop's watch must live in
- * the main process (test/auto.test.mjs asserts "neither renderer starts a timer
- * of its own"), unref'd, because the window stays open and a payment may never
- * complete. The terminal's must block, because the process exits and a
- * detached timer would be killed before the credit lands. Those are two
- * schedulers over one state machine — and the state machine (`createCreditWatch`)
- * is the part that must not drift, so that is what this file owns.
- *
- * No I/O of its own and no host imports: it takes the client it is handed.
- */
-
-/** aegis1's own bounds (`app.py` token_bank_topup): outside these is a 400. */
-const TOPUP_MIN_EUR = 2;
-const TOPUP_MAX_EUR = 1000;
-/** The server's default when the body omits the amount. */
-const TOPUP_DEFAULT_EUR = 10;
-
-/** Poll period and window for the credit watch: ~2 minutes, then stop asking. */
-const TOPUP_POLL_MS = 4000;
-const TOPUP_POLL_TRIES = 30;
-
-/**
- * Read a euro amount out of an aegis1 token-bank payload, across the shapes the
- * server has used (`balance_micros`, `balance_eur`, `balance`, or a bare
- * number). Returns null when nothing numeric is present — an unreadable bank
- * must stay UNKNOWN rather than read as a zero.
- */
-function bankAmount(res) {
-  if (res == null) return null;
-  if (typeof res === 'number') return isFinite(res) ? res : null;
-  if (typeof res === 'string') {
-    const n = Number(res.trim());
-    return res.trim() !== '' && isFinite(n) ? n : null;
-  }
-  if (typeof res !== 'object') return null;
-  if (res.balance_micros != null) {
-    const n = Number(res.balance_micros);
-    return isFinite(n) ? n / 1e6 : null;
-  }
-  for (const key of ['balance_eur', 'balance', 'bank', 'balance_eur_cents']) {
-    if (!(key in res)) continue;
-    const n = Number(res[key]);
-    if (!isFinite(n)) continue;
-    return key === 'balance_eur_cents' ? n / 100 : n;
-  }
-  if (res.data) return bankAmount(res.data);
-  return null;
-}
-
-/**
- * Parse a user-typed amount against the server's own bounds.
- *
- * Rejecting here rather than letting aegis1 answer 400 is not cosmetic: the
- * whole point of `/topup 1` failing locally is that it says WHY in the same
- * breath, instead of printing the server's "Amount must be between 2 and 1000
- * EUR" after a round trip on a slow connection.
- *
- * @param {string|number} raw the typed argument ('' or undefined ⇒ the default)
- * @param {number} [fallback] default when nothing was typed
- * @returns {{ok:boolean, amount:number|null, message:string|null}}
- */
-function parseTopupAmount(raw, fallback) {
-  const str = String(raw == null ? '' : raw).trim();
-  if (!str) {
-    const d = fallback == null ? TOPUP_DEFAULT_EUR : Number(fallback);
-    return { ok: true, amount: d, message: null };
-  }
-  // A euro figure with the separators a person actually types: `$20`, `20 EUR`,
-  // `20eur`. No `\b` before the word — `25eur` has its boundary between the 5
-  // and the e, so a boundary-anchored pattern strips nothing and the figure is
-  // refused as "not an amount".
-  const cleaned = str.replace(/[€$]|eur(o|os)?\b/gi, '').trim();
-  const n = Number(cleaned);
-  if (!isFinite(n) || cleaned === '') {
-    return { ok: false, amount: null, message: `"${str}" is not an amount — give a number of euro, e.g. /topup 20` };
-  }
-  if (!Number.isInteger(n)) {
-    return { ok: false, amount: null, message: `${n} EUR is not whole — Stripe charges whole euro here (e.g. /topup 20)` };
-  }
-  if (n < TOPUP_MIN_EUR || n > TOPUP_MAX_EUR) {
-    return {
-      ok: false,
-      amount: null,
-      message: `${n} EUR is outside the accepted range — top-ups are ${TOPUP_MIN_EUR}..${TOPUP_MAX_EUR} EUR`,
-    };
-  }
-  return { ok: true, amount: n, message: null };
-}
-
-/**
- * Classify a failed checkout the way a user needs to hear it. The shared client
- * attaches `err.status` / `err.data` while the failure is still in the host, so
- * the status is read here rather than string-matched out of a message later.
- *
- * `setupRequired` is aegis1's 503 `setup_required` — Stripe is not configured
- * on the deployment, which is NOT the user's problem to fix and must not be
- * reported as one.
- *
- * @returns {{status:number, message:string, hint:string|null, setupRequired:boolean}}
- */
-function classifyTopupError(err) {
-  const status = (err && (err.status || (err.response && err.response.status))) || 0;
-  const data = (err && err.data) || {};
-  const message = err && err.message ? err.message : String(err);
-  const setupRequired = Boolean(data.setup_required) || status === 503;
-  if (setupRequired) {
-    return {
-      status: status || 503,
-      message,
-      hint: 'this deployment has no payment provider configured — top-ups are unavailable here, not on your side',
-      setupRequired: true,
-    };
-  }
-  if (status === 400) {
-    return { status, message, hint: `pick an amount between ${TOPUP_MIN_EUR} and ${TOPUP_MAX_EUR} EUR`, setupRequired: false };
-  }
-  if (status === 401 || status === 403) {
-    return {
-      status,
-      message,
-      hint: 'the account key was refused — save a fresh one (aegiscode login) and try again',
-      setupRequired: false,
-    };
-  }
-  if (status === 402) {
-    return { status, message, hint: 'the server refused the checkout for this account — see /billing for the account state', setupRequired: false };
-  }
-  if (!status) {
-    return { status: 0, message, hint: 'the server could not be reached — check the connection and retry', setupRequired: false };
-  }
-  return { status, message, hint: null, setupRequired: false };
-}
-
-/**
- * Create a token-bank checkout and hand back the Stripe-hosted URL.
- *
- * Never throws: a host that has to tell 401 from 400 from 503 must receive the
- * fields, and an exception crossing an IPC boundary loses `status` and `data`.
- *
- * @param {object} aegis the client whose key pays
- * @param {number} amount EUR, already validated by parseTopupAmount
- * @returns {Promise<{ok:boolean, url:string|null, status:number, message:string|null,
- *   hint:string|null, setupRequired:boolean, amount:number}>}
- */
-async function startTopup(aegis, amount) {
-  const eur = amount == null ? TOPUP_DEFAULT_EUR : Number(amount);
-  if (!aegis || typeof aegis.tokenBankTopup !== 'function') {
-    return {
-      ok: false, url: null, status: 0, amount: eur, setupRequired: false,
-      message: 'this host has no billing client', hint: null,
-    };
-  }
-  try {
-    const data = await aegis.tokenBankTopup(eur);
-    const url = data && data.url ? String(data.url) : null;
-    if (!url) {
-      // A 2xx with no URL is a success shape we cannot act on. Saying so beats
-      // opening "undefined" in a browser and calling it a payment.
-      return {
-        ok: false, url: null, status: 0, amount: eur, setupRequired: false,
-        message: 'the server accepted the request but returned no checkout URL',
-        hint: 'check the account in the browser at /billing, then retry',
-      };
-    }
-    return { ok: true, url, status: 0, message: null, hint: null, setupRequired: false, amount: eur };
-  } catch (err) {
-    const info = classifyTopupError(err);
-    return { ok: false, url: null, amount: eur, ...info };
-  }
-}
-
-/**
- * The credit watch, as a state machine a host drives.
- *
- * `tick()` reads the bank once and returns the next state; the HOST decides
- * when to call it again (an unref'd interval in the desktop's main process, an
- * awaited sleep loop in the terminal). One read per call, so a slow or failing
- * balance call can never overlap itself and double-announce.
- *
- * States:
- *   `pending`  — nothing conclusive yet; call again
- *   `credited` — the bank read strictly above the baseline: announce, then stop
- *   `expired`  — the window ran out with no rising read
- *
- * A failed or unreadable read is `pending`, never a zero: offline is unknown,
- * and unknown must not become a baseline (see the header).
- *
- * @param {object} aegis the client whose key read the balance
- * @param {object} [opts]
- * @param {number} [opts.maxTries] reads before giving up (default TOPUP_POLL_TRIES)
- * @returns {{tick:function():Promise<{state:string,amount:number|null,baseline:number|null}>,
- *   stop:function():void, baseline:number|null, credited:number|null, tries:number}}
- */
-function createCreditWatch(aegis, opts) {
-  const options = opts || {};
-  const maxTries = options.maxTries || TOPUP_POLL_TRIES;
-  const state = { baseline: null, credited: null, tries: 0, stopped: false };
-  return {
-    get baseline() {
-      return state.baseline;
-    },
-    get credited() {
-      return state.credited;
-    },
-    get tries() {
-      return state.tries;
-    },
-    stop() {
-      state.stopped = true;
-    },
-    async tick() {
-      const answer = (s, amount) => ({ state: s, amount: amount == null ? null : amount, baseline: state.baseline });
-      if (state.stopped) return answer(state.credited != null ? 'credited' : 'stopped', state.credited);
-      state.tries += 1;
-      if (state.tries > maxTries) {
-        state.stopped = true;
-        return answer('expired', null);
-      }
-      let now = null;
-      try {
-        now = bankAmount(await aegis.tokenBankBalance());
-      } catch {
-        return answer('pending', null); // offline or restarting: the next read retries
-      }
-      if (now === null) return answer('pending', null);
-      if (state.baseline === null) {
-        // The first successful read is the pre-payment figure. Stripe checkout
-        // takes longer than one poll, so this is normally still the old balance
-        // — but if it is already higher we still announce on the NEXT read,
-        // because the baseline is what "higher" is measured against.
-        state.baseline = now;
-        return answer('pending', null);
-      }
-      if (now > state.baseline) {
-        state.stopped = true;
-        state.credited = now;
-        return answer('credited', now);
-      }
-      return answer('pending', null);
-    },
-  };
-}
-
-module.exports = {
-  TOPUP_MIN_EUR,
-  TOPUP_MAX_EUR,
-  TOPUP_DEFAULT_EUR,
-  TOPUP_POLL_MS,
-  TOPUP_POLL_TRIES,
-  bankAmount,
-  parseTopupAmount,
-  classifyTopupError,
-  startTopup,
-  createCreditWatch,
-};
+"use strict";const TOPUP_MIN_EUR=2,TOPUP_MAX_EUR=1e3,TOPUP_DEFAULT_EUR=10,TOPUP_POLL_MS=4e3,TOPUP_POLL_TRIES=30;function bankAmount(e){if(null==e)return null;if("number"==typeof e)return isFinite(e)?e:null;if("string"==typeof e){const t=Number(e.trim());return""!==e.trim()&&isFinite(t)?t:null}if("object"!=typeof e)return null;if(null!=e.balance_micros){const t=Number(e.balance_micros);return isFinite(t)?t/1e6:null}for(const t of["balance_eur","balance","bank","balance_eur_cents"]){if(!(t in e))continue;const n=Number(e[t]);if(isFinite(n))return"balance_eur_cents"===t?n/100:n}return e.data?bankAmount(e.data):null}function parseTopupAmount(e,t){const n=String(null==e?"":e).trim();if(!n)return{ok:!0,amount:null==t?10:Number(t),message:null};const u=n.replace(/[€$]|eur(o|os)?\b/gi,"").trim(),r=Number(u);return isFinite(r)&&""!==u?Number.isInteger(r)?r<TOPUP_MIN_EUR||r>TOPUP_MAX_EUR?{ok:!1,amount:null,message:`${r} EUR is outside the accepted range — top-ups are ${TOPUP_MIN_EUR}..${TOPUP_MAX_EUR} EUR`}:{ok:!0,amount:r,message:null}:{ok:!1,amount:null,message:`${r} EUR is not whole — Stripe charges whole euro here (e.g. /topup 20)`}:{ok:!1,amount:null,message:`"${n}" is not an amount — give a number of euro, e.g. /topup 20`}}function classifyTopupError(e){const t=e&&(e.status||e.response&&e.response.status)||0,n=e&&e.data||{},u=e&&e.message?e.message:String(e);return Boolean(n.setup_required)||503===t?{status:t||503,message:u,hint:"this deployment has no payment provider configured — top-ups are unavailable here, not on your side",setupRequired:!0}:400===t?{status:t,message:u,hint:`pick an amount between ${TOPUP_MIN_EUR} and ${TOPUP_MAX_EUR} EUR`,setupRequired:!1}:401===t||403===t?{status:t,message:u,hint:"the account key was refused — save a fresh one (aegiscode login) and try again",setupRequired:!1}:402===t?{status:t,message:u,hint:"the server refused the checkout for this account — see /billing for the account state",setupRequired:!1}:t?{status:t,message:u,hint:null,setupRequired:!1}:{status:0,message:u,hint:"the server could not be reached — check the connection and retry",setupRequired:!1}}async function startTopup(e,t){const n=null==t?10:Number(t);if(!e||"function"!=typeof e.tokenBankTopup)return{ok:!1,url:null,status:0,amount:n,setupRequired:!1,message:"this host has no billing client",hint:null};try{const t=await e.tokenBankTopup(n),u=t&&t.url?String(t.url):null;return u?{ok:!0,url:u,status:0,message:null,hint:null,setupRequired:!1,amount:n}:{ok:!1,url:null,status:0,amount:n,setupRequired:!1,message:"the server accepted the request but returned no checkout URL",hint:"check the account in the browser at /billing, then retry"}}catch(e){return{ok:!1,url:null,amount:n,...classifyTopupError(e)}}}function createCreditWatch(e,t){const n=(t||{}).maxTries||30,u={baseline:null,credited:null,tries:0,stopped:!1};return{get baseline(){return u.baseline},get credited(){return u.credited},get tries(){return u.tries},stop(){u.stopped=!0},async tick(){const t=(e,t)=>({state:e,amount:null==t?null:t,baseline:u.baseline});if(u.stopped)return t(null!=u.credited?"credited":"stopped",u.credited);if(u.tries+=1,u.tries>n)return u.stopped=!0,t("expired",null);let r=null;try{r=bankAmount(await e.tokenBankBalance())}catch{return t("pending",null)}return null===r?t("pending",null):null===u.baseline?(u.baseline=r,t("pending",null)):r>u.baseline?(u.stopped=!0,u.credited=r,t("credited",r)):t("pending",null)}}}module.exports={TOPUP_MIN_EUR:TOPUP_MIN_EUR,TOPUP_MAX_EUR:TOPUP_MAX_EUR,TOPUP_DEFAULT_EUR:10,TOPUP_POLL_MS:4e3,TOPUP_POLL_TRIES:30,bankAmount:bankAmount,parseTopupAmount:parseTopupAmount,classifyTopupError:classifyTopupError,startTopup:startTopup,createCreditWatch:createCreditWatch};