@hwip/cli 0.0.1 → 0.1.0

package/dist/login-address.d.ts

@@ -0,0 +1,25 @@
+/** Hosts a callback may name without the user having said so. */
+export declare const BUILT_IN_HOSTS: readonly string[];
+/**
+ * Why `url` may not be saved as the `field` the console sent, or null. The reason names the host at most —
+ * never the userinfo, path or query — because it is printed.
+ */
+export declare const callbackAddressProblem: (field: "baseUrl" | "wsUrl", url: string, extraHosts?: readonly string[]) => string | null;
+/**
+ * The hosts `--allow-host a.example,b.example` names (C132), or why the value is no list of them. A bare host
+ * name: a scheme, port, path or `*` is refused rather than trimmed, and so is a name with one label — it would
+ * trust a whole top-level domain, and a callback host is trusted with its subdomains (a public suffix like `co.uk`
+ * passes the same way — the host is the user's to name). An IP address is trusted as itself only. The value
+ * not given is no hosts.
+ */
+export declare const parseAllowHosts: (raw: string | boolean | undefined) => {
+    hosts: string[];
+} | {
+    error: string;
+};
+/** The hosts besides `hwip.app` that a callback may name: the console's own, and those `config.json` already holds. */
+export declare const trustedCallbackHosts: (webUrl: string, config: {
+    baseUrl?: unknown;
+    wsUrl?: unknown;
+}) => string[];
+//# sourceMappingURL=login-address.d.ts.map

package/dist/login-address.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trustedCallbackHosts = exports.parseAllowHosts = exports.callbackAddressProblem = exports.BUILT_IN_HOSTS = void 0;
+/**
+ * The addresses a sign-in callback may hand to `config.json` (C131). The console sends the key together with
+ * the `baseUrl` and `wsUrl` it belongs to, and the config then sends the key wherever they point — so a callback
+ * that names an address the user never chose is refused, not saved.
+ *
+ * Allowed: https (wss) on a host under `hwip.app`, on the console's own host (a self-hosted console and its
+ * subdomains), on a host the config file already names, or on one the user named with `--allow-host` (C132); and this machine, over http or https, for local
+ * development. No userinfo, query or fragment, and a socket URL that can carry the key's query.
+ */
+const insecure_url_js_1 = require("./insecure-url.js");
+const ws_url_js_1 = require("./ws-url.js");
+/** Hosts a callback may name without the user having said so. */
+exports.BUILT_IN_HOSTS = ['hwip.app'];
+const MAX_ADDRESS_CHARS = 2048;
+const hostOf = (url) => {
+    if (typeof url !== 'string')
+        return null;
+    try {
+        return new URL(url).hostname.toLowerCase().replace(/\.$/, '');
+    }
+    catch {
+        return null;
+    }
+};
+/** `host` is `trusted` or one of its subdomains (an IP address has none). */
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/;
+const NUMERIC = /^[\d.]+$/;
+const under = (host, trusted) => host === trusted || (!NUMERIC.test(trusted) && host.endsWith(`.${trusted}`));
+/**
+ * Why `url` may not be saved as the `field` the console sent, or null. The reason names the host at most —
+ * never the userinfo, path or query — because it is printed.
+ */
+const callbackAddressProblem = (field, url, extraHosts = []) => {
+    if (url.length > MAX_ADDRESS_CHARS)
+        return `the ${field} is too long`;
+    if (field === 'wsUrl') {
+        const problem = (0, ws_url_js_1.wsUrlProblem)(url);
+        if (problem)
+            return problem;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `the ${field} is not a URL`;
+    }
+    const secure = field === 'baseUrl' ? 'https:' : 'wss:';
+    const plain = field === 'baseUrl' ? 'http:' : 'ws:';
+    const local = (0, insecure_url_js_1.isLoopbackHost)(parsed.hostname);
+    if (parsed.protocol !== secure && !(parsed.protocol === plain && local)) {
+        return `the ${field} is not ${field === 'baseUrl' ? 'https' : 'wss'} (${parsed.protocol.replace(':', '')}://${parsed.host})`;
+    }
+    if (parsed.username || parsed.password)
+        return `the ${field} has a user name or password in it`;
+    if (parsed.search || parsed.hash)
+        return `the ${field} has a query or fragment, which the key's address cannot carry`;
+    if (local)
+        return null;
+    const host = hostOf(url);
+    const trusted = [...exports.BUILT_IN_HOSTS, ...extraHosts].map((h) => h.toLowerCase());
+    if (!trusted.some((t) => under(host, t)))
+        return `the ${field} host ${host} is not one hwip knows (hwip.app, the console's host, one already in config.json, or one named with --allow-host)`;
+    return null;
+};
+exports.callbackAddressProblem = callbackAddressProblem;
+const HOST_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+/**
+ * The hosts `--allow-host a.example,b.example` names (C132), or why the value is no list of them. A bare host
+ * name: a scheme, port, path or `*` is refused rather than trimmed, and so is a name with one label — it would
+ * trust a whole top-level domain, and a callback host is trusted with its subdomains (a public suffix like `co.uk`
+ * passes the same way — the host is the user's to name). An IP address is trusted as itself only. The value
+ * not given is no hosts.
+ */
+const parseAllowHosts = (raw) => {
+    if (raw === undefined)
+        return { hosts: [] };
+    if (typeof raw !== 'string')
+        return { error: '--allow-host needs a host name (--allow-host api.example.com)' };
+    const hosts = [];
+    for (const entry of raw.split(',')) {
+        const host = entry.trim().toLowerCase().replace(/\.$/, '');
+        // A dotted name of digits only is an IPv4 address, whole or not at all: `0.5` is no host, and as a suffix it would match every `*.0.5`.
+        if (!HOST_NAME.test(host) || (NUMERIC.test(host) && !IPV4.test(host))) {
+            return { error: `--allow-host takes bare host names like api.example.com, comma-separated — not "${entry.trim()}"` };
+        }
+        hosts.push(host);
+    }
+    return { hosts };
+};
+exports.parseAllowHosts = parseAllowHosts;
+/** The hosts besides `hwip.app` that a callback may name: the console's own, and those `config.json` already holds. */
+const trustedCallbackHosts = (webUrl, config) => [hostOf(webUrl), hostOf(config.baseUrl), hostOf(config.wsUrl)].filter((h) => h !== null && h !== '');
+exports.trustedCallbackHosts = trustedCallbackHosts;

package/dist/login-page.d.ts

@@ -0,0 +1,29 @@
+/** design/tokens.json colours this page uses, as of hwip 011525e. `logo` is the lockup wordmark ink (kit `lockup-horizontal[-on-dark].svg`). */
+export declare const PAGE_PALETTE: {
+    readonly light: {
+        readonly grouped: "#F3EEE6";
+        readonly card: "#FFFDF9";
+        readonly raised: "#F1ECE3";
+        readonly ink: "#1E1D1B";
+        readonly muted: "#6B665E";
+        readonly danger: "#B3261E";
+        readonly separator: "#E6DFD3";
+        readonly logo: "#1E1D1B";
+    };
+    readonly dark: {
+        readonly grouped: "#100F0D";
+        readonly card: "#221F1C";
+        readonly raised: "#2C2925";
+        readonly ink: "#F2F1EE";
+        readonly muted: "#A9A39A";
+        readonly danger: "#F2A8A0";
+        readonly separator: "#36322D";
+        readonly logo: "#E9E4DA";
+    };
+};
+type PageVariant = 'ok' | 'error';
+export declare const renderPage: (variant: PageVariant, title: string, message: string, hint?: string) => string;
+export declare const okPage: () => string;
+export declare const errorPage: (reason: string) => string;
+export {};
+//# sourceMappingURL=login-page.d.ts.map

package/dist/login-page.js

@@ -0,0 +1,93 @@
+"use strict";
+// The page the browser lands on after `hwip login`, served from the loopback
+// callback server (login.ts). The user arrives from the web console's connect
+// screen, so it speaks the console's language — warm paper background, one
+// card, the logo lockup, Pretendard when installed — with the colours copied
+// from hwip `design/tokens.json` (color.grouped · card · raised · ink · muted ·
+// danger · separator, light and dark). The server has no network, so this is
+// one self-contained document: inline styles, inline SVG, no script, no font
+// or image fetch (the console loads Pretendard from a CDN; here the same
+// stack falls back to the system face). It is on screen for a few seconds
+// before the user returns to the terminal, so its job is to confirm state and
+// point back.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorPage = exports.okPage = exports.renderPage = exports.PAGE_PALETTE = void 0;
+/** design/tokens.json colours this page uses, as of hwip 011525e. `logo` is the lockup wordmark ink (kit `lockup-horizontal[-on-dark].svg`). */
+exports.PAGE_PALETTE = {
+    light: {
+        grouped: '#F3EEE6', card: '#FFFDF9', raised: '#F1ECE3', ink: '#1E1D1B', muted: '#6B665E',
+        danger: '#B3261E', separator: '#E6DFD3', logo: '#1E1D1B',
+    },
+    dark: {
+        grouped: '#100F0D', card: '#221F1C', raised: '#2C2925', ink: '#F2F1EE', muted: '#A9A39A',
+        danger: '#F2A8A0', separator: '#36322D', logo: '#E9E4DA',
+    },
+};
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+const schemeVars = (p) => `--grouped:${p.grouped};--card:${p.card};--raised:${p.raised};--ink:${p.ink};--muted:${p.muted};` +
+    `--danger:${p.danger};--separator:${p.separator};--logo:${p.logo}`;
+const PAGE_STYLE = `*,*::before,*::after{box-sizing:border-box}
+:root{color-scheme:light dark;${schemeVars(exports.PAGE_PALETTE.light)};--shadow:0 3px 14px rgb(30 29 27/.05);--edge:transparent;
+--font:Pretendard Variable,Pretendard,-apple-system,system-ui,"Apple SD Gothic Neo",sans-serif}
+@media (prefers-color-scheme:dark){:root{${schemeVars(exports.PAGE_PALETTE.dark)};--shadow:none;--edge:var(--separator)}}
+body{margin:0;background:var(--grouped);color:var(--ink);font:400 15px/1.5 var(--font)}
+.center{min-height:100vh;min-height:100dvh;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:16px;padding:24px 16px}
+.lockup{width:120px;height:auto;color:var(--logo)}
+.card{width:100%;max-width:360px;display:flex;flex-direction:column;gap:12px;padding:24px;background:var(--card);
+border:1px solid var(--edge);border-radius:24px;box-shadow:var(--shadow)}
+.status{width:40px;height:40px;border-radius:999px;background:var(--raised);color:var(--ink);display:grid;place-items:center}
+.status.error{color:var(--danger)}
+.status svg{width:40px;height:40px;fill:none;stroke:currentColor;stroke-width:3;stroke-linecap:round;stroke-linejoin:round}
+h1{margin:0;font-size:20px;font-weight:600;line-height:1.3;overflow-wrap:anywhere}
+p{margin:0;color:var(--muted);font-size:14px;overflow-wrap:anywhere}
+.chip{align-self:flex-start;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px;color:var(--ink);
+background:var(--raised);border-radius:12px;padding:6px 10px}`;
+// Drawn in a 48×48 box inside the 40px disc: a check, or an exclamation
+// (the `h.01` path renders as a dot through the round line cap).
+const GLYPH = {
+    ok: '<path d="M14 25l7 7 13-14"/>',
+    error: '<path d="M24 14v13"/><path d="M24 34h.01"/>',
+};
+// The kit's horizontal lockup (`design/logo/kit/svg/lockup-horizontal.svg`)
+// with the ink as `currentColor`, so one drawing serves light and dark; the
+// persimmon dot is the kit's in both.
+const LOCKUP = '<svg class="lockup" viewBox="0 0 506 256" aria-hidden="true"><g transform="translate(0 8) scale(0.94)">' +
+    '<g transform="translate(5.1 42.4) scale(0.917)"><g transform="translate(0 -12)">' +
+    '<path fill="currentColor" fill-rule="evenodd" d="M14 122 C22 104 56 94 96 92 C130 90 152 90 166 86 C170 80 178 80 184 86 C196 82 206 72 212 60 C210 44 214 26 222 12 C230 26 232 42 228 56 C238 46 248 40 254 38 C250 54 238 68 222 78 C204 100 184 120 156 134 C126 148 84 158 50 152 C32 148 16 138 14 122 Z M30 136 C50 146 74 152 100 154 C74 150 50 144 30 134 Z M38 146 C56 152 74 156 94 158 C74 154 56 150 38 144 Z"/>' +
+    '<path fill="currentColor" transform="matrix(0.6587 -0.1926 -0.1926 0.8913 58.93 33.26)" d="M82 144 C112 150 150 170 180 192 C194 202 204 212 214 222 C202 216 188 210 172 202 C140 188 110 172 94 160 C88 156 84 150 82 144 Z"/>' +
+    '<circle fill="#D9623B" cx="100" cy="56" r="17"/></g></g></g>' +
+    '<g transform="translate(262 60) scale(0.62)">' +
+    '<path d="M0 190 V30 M0 190 V136 A36 36 0 0 1 72 136 V190 M102 96 L128 190 L154 104 L180 190 L206 96 M232 96 V190 M262 96 V238 M262 143 A47 47 0 1 1 356 143 A47 47 0 1 1 262 143" fill="none" stroke="currentColor" stroke-width="13" stroke-linecap="round" stroke-linejoin="round"/>' +
+    '<circle cx="232" cy="56" r="9.8" fill="currentColor"/></g></svg>';
+const renderPage = (variant, title, message, hint) => `<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<title>Hwip · ${esc(title)}</title><style>${PAGE_STYLE}</style></head>` +
+    `<body><div class="center">${LOCKUP}<main class="card">` +
+    `<span class="status ${variant}" aria-hidden="true"><svg viewBox="0 0 48 48">${GLYPH[variant]}</svg></span>` +
+    `<h1>${esc(title)}</h1><p>${esc(message)}</p>` +
+    (hint ? `<code class="chip">${esc(hint)}</code>` : '') +
+    `</main></div></body></html>`;
+exports.renderPage = renderPage;
+const okPage = () => (0, exports.renderPage)('ok', "You're connected", 'Close this tab and head back to your terminal.', 'hwip is ready');
+exports.okPage = okPage;
+// Turn an internal callback failure reason into end-user guidance: name what
+// happened and how to recover, in the interface's voice — never an apology.
+const errorPage = (reason) => {
+    const copy = {
+        'state mismatch': [
+            "Sign-in didn't match",
+            "This link didn't match the request that started it. Return to your terminal and run login again.",
+        ],
+        'missing key': [
+            'No key came back',
+            'The sign-in finished without a key. Return to your terminal and run login again.',
+        ],
+        'not found': [
+            'Nothing to see here',
+            'This page only handles the Hwip login callback.',
+        ],
+    };
+    const [title, message] = copy[reason] ?? ['Something went wrong', reason];
+    return (0, exports.renderPage)('error', title, message);
+};
+exports.errorPage = errorPage;

package/dist/login.d.ts

@@ -0,0 +1,98 @@
+/** Credentials returned by a completed login. apiKey is guaranteed present
+ *  (parseCallback rejects a missing key with 400). Shared by handleLogin and
+ *  handleInstall via runLoginFlow. */
+export type LoginFlowResult = {
+    apiKey: string;
+    hookId?: string;
+    baseUrl?: string;
+    wsUrl?: string;
+};
+type CallbackResult = {
+    ok: true;
+    config: LoginFlowResult;
+}
+/** `endsLogin`: what the terminal says when this refusal ends the login. */
+ | {
+    ok: false;
+    status: number;
+    reason: string;
+    endsLogin?: string;
+};
+export declare const stripUndefined: <T extends Record<string, unknown>>(obj: T) => Partial<T>;
+/**
+ * `post=1` tells the console this listener takes the callback as a form POST:
+ * the key then travels in the request body and never in a URL (browser history,
+ * autofill and session restore keep URLs). `/cb` takes no key any other way.
+ */
+export declare const buildBridgeUrl: (webUrl: string, port: number, state: string, host: string) => string;
+export declare const persistConfig: (next: LoginFlowResult) => void;
+/**
+ * The callback's fields, from a form body (the only place the key may be). The `baseUrl` and `wsUrl` it names are
+ * where `config.json` will send the key, so one that is not https/wss on a host hwip knows (`login-address.ts`) is
+ * refused whole — nothing is saved — and ends the login saying which address and why (C131).
+ * `extraHosts`: hosts besides `hwip.app` the callback may name (the console's, those already in the config).
+ */
+export declare const parseCallbackParams: (params: URLSearchParams, expectedState: string, extraHosts?: readonly string[]) => CallbackResult;
+/** Requests with a wrong state one login answers 403 and waits through, before it gives up. */
+export declare const MAX_STATE_MISMATCHES = 5;
+/**
+ * A GET callback. It carries no key: the console's "cancel" is one (`?error=denied&state=…`) and answers "missing
+ * key". A key in the query is refused unread (C102) and ends the login with `KEY_IN_URL`; its value is not in the
+ * result, the page or the log.
+ */
+export declare const parseCallback: (reqUrl: string, expectedState: string) => CallbackResult;
+/** A form with five short fields is well under this; the cap is for whatever else can reach a loopback port. */
+export declare const MAX_CALLBACK_BODY_BYTES: number;
+/**
+ * Where the sign-in browser can run. `open`: here. `ssh`: on the user's own
+ * machine, with the callback port forwarded — a browser opened here would
+ * land on the remote box. `none`: nowhere this login can reach.
+ */
+export type BrowserPlan = {
+    kind: 'open';
+} | {
+    kind: 'ssh';
+} | {
+    kind: 'none';
+    reason: string;
+};
+export declare const browserPlan: (env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform) => BrowserPlan;
+/**
+ * Opens `url`; resolves to why it could not, or undefined once the opener
+ * started. An opener that exits non-zero inside the grace window failed —
+ * `xdg-open` with no handler exits 3 — and one still running after it, or
+ * done with 0, handed the URL on.
+ */
+export declare const openBrowser: (url: string, graceMs?: number) => Promise<string | undefined>;
+/** A key typed while the login waited (inside install), instead of the browser's answer. */
+export type PastedKey = {
+    pastedKey: string;
+};
+export declare const resolveWebUrl: (raw: string | boolean | undefined) => string;
+/** The hosts `--allow-host` adds to the callback's trusted ones. A bad value stops the command — it is not read as "none". */
+export declare const resolveAllowHosts: (raw: string | boolean | undefined) => string[];
+export declare const resolveTimeoutSec: (raw: string | boolean | undefined) => number;
+/**
+ * Core login flow shared by `handleLogin` (CLI command) and `handleInstall`
+ * (auto-trigger on missing credentials). Returns the issued credentials, or
+ * null when the browser can't open (headless) or the callback never arrives.
+ * `deps.open` is injectable for tests; defaults to the real browser launcher.
+ */
+export declare const runLoginFlow: (
+/** `pasteNext`: the caller (`hwip install`) prompts for the key when this returns null. */
+opts: {
+    webUrl: string;
+    timeoutSec: number;
+    pasteNext?: boolean;
+    allowHosts?: readonly string[];
+}, deps?: {
+    open?: (url: string) => Promise<string | undefined>;
+    plan?: BrowserPlan;
+    skip?: () => {
+        pressed: Promise<string>;
+        close: () => void;
+    } | null;
+}) => Promise<LoginFlowResult | PastedKey | null>;
+export declare const handleLogin: (args: Record<string, string | boolean>, deps?: Parameters<typeof runLoginFlow>[1]) => Promise<number>;
+export {};
+//# sourceMappingURL=login.d.ts.map