@statewalker/httpeers-join 0.1.3

package/dist/invite-panel.js

@@ -0,0 +1,357 @@
+/**
+ * The Invite panel: an admin makes an invitation -- member or admin, one
+ * hour, one day or seven days -- and hands it over as a link, a QR code, the
+ * phone's share sheet or the clipboard. Pending invitations are listed with
+ * their role and how long they have left.
+ *
+ * SHOWN ONLY TO AN ADMIN, AND THE HUB SAYS WHO THAT IS. The panel stays
+ * hidden until the page is live, the mesh view lists this member as `admin`
+ * (`adminHint`: the hint that decides whether to ask), and
+ * `GET /hub/api/roles` succeeded for it (`./invite.ts`). A 403 (a member), a 404 (a hub with no admin API)
+ * or a 401 hides it for the life of that link; a network error or a 5xx is
+ * tried again a few times, because the first call can race the link coming
+ * up. It is a convenience, never a gate: the hub decides every call.
+ *
+ * WHAT IS ON SCREEN IS A SECRET. The link, and the QR code of it, redeem
+ * once for whoever holds them. They are never logged, the pending list shows
+ * no invitation ids (a bare id redeems too), and all of it is cleared when the
+ * link to the hub goes away.
+ */
+import { ADMIN_INVITATION_WARNING, adminHint, createHubAdminClient, DEFAULT_INVITE_EXPIRY, DEFAULT_INVITE_ROLE, describeExpiry, expiryMs, hubAdminBase, INVITE_EXPIRIES, INVITE_ROLES, isFinalRefusal, offeredRoles, } from "./invite.js";
+const pageFetch = (input, init) => globalThis.fetch(input, init);
+async function defaultQrSvg(text) {
+    const { qrSvg } = await import("@statewalker/httpeers-qr");
+    return qrSvg(text);
+}
+function defaultShare(doc) {
+    const nav = doc.defaultView?.navigator;
+    if (nav == null || typeof nav.share !== "function")
+        return null;
+    return (data) => nav.share(data);
+}
+/**
+ * Build the panel (hidden) with `make`, the widget's element helper. `n` is
+ * the widget instance number, for unique ids.
+ */
+export function createInvitePanel(doc, make, n, options = {}) {
+    const fetchImpl = options.fetch ?? pageFetch;
+    const share = options.share === undefined ? defaultShare(doc) : options.share;
+    const toQrSvg = options.qrSvg ?? defaultQrSvg;
+    const now = options.now ?? Date.now;
+    const retryDelayMs = options.retryDelayMs ?? 2_000;
+    const roleAttempts = Math.max(1, options.roleAttempts ?? 3);
+    const button = (className, label) => {
+        const b = make("button", `hp-join-button ${className}`, label);
+        b.type = "button";
+        return b;
+    };
+    // --- structure ----------------------------------------------------------
+    const root = make("details", "hp-invite");
+    root.hidden = true;
+    const summary = make("summary", "hp-invite-toggle", "Invite someone");
+    const body = make("div", "hp-invite-body");
+    const roleGroup = make("fieldset", "hp-invite-roles");
+    const roleLegend = make("legend", "hp-invite-legend", "Invite as");
+    roleGroup.append(roleLegend);
+    const roleInputs = new Map();
+    for (const role of INVITE_ROLES) {
+        const label = make("label", `hp-invite-role hp-invite-role-${role}`);
+        const input = make("input", "hp-invite-role-input");
+        input.type = "radio";
+        input.name = `hp-invite-role-${n}`;
+        input.value = role;
+        input.checked = role === DEFAULT_INVITE_ROLE;
+        label.append(input, ` ${role === "admin" ? "Admin" : "Member"}`);
+        roleGroup.append(label);
+        roleInputs.set(role, { input, label });
+    }
+    const warning = make("p", "hp-invite-warning", ADMIN_INVITATION_WARNING);
+    warning.setAttribute("role", "note");
+    const expiry = make("select", "hp-invite-expiry");
+    expiry.id = `hp-invite-expiry-${n}`;
+    for (const e of INVITE_EXPIRIES) {
+        const option = make("option", "", `Expires in ${e.label}`);
+        option.value = e.id;
+        option.selected = e.id === DEFAULT_INVITE_EXPIRY;
+        expiry.append(option);
+    }
+    const expiryLabel = make("label", "hp-join-visually-hidden", "Expiry");
+    expiryLabel.htmlFor = expiry.id;
+    const create = button("hp-join-primary hp-invite-create", "Create invitation");
+    const createRow = make("div", "hp-join-actions");
+    createRow.append(expiryLabel, expiry, create);
+    const error = make("p", "hp-join-error hp-invite-error");
+    error.setAttribute("role", "alert");
+    error.hidden = true;
+    const result = make("div", "hp-invite-result");
+    result.hidden = true;
+    const resultNote = make("p", "hp-invite-note");
+    const qr = make("div", "hp-invite-qr");
+    const link = make("input", "hp-join-input hp-invite-link");
+    link.id = `hp-invite-link-${n}`;
+    link.type = "text";
+    link.readOnly = true;
+    link.autocomplete = "off";
+    link.spellcheck = false;
+    const linkLabel = make("label", "hp-join-visually-hidden", "Invitation link");
+    linkLabel.htmlFor = link.id;
+    const shareButton = button("hp-join-primary hp-invite-share", "Share");
+    const copyButton = button("hp-invite-copy", "Copy link");
+    const copied = make("span", "hp-invite-copied");
+    copied.setAttribute("role", "status");
+    const resultActions = make("div", "hp-join-actions");
+    resultActions.append(shareButton, copyButton, copied);
+    result.append(resultNote, qr, linkLabel, link, resultActions);
+    const pendingBox = make("div", "hp-invite-pending");
+    const pendingHead = make("div", "hp-invite-pending-head");
+    const pendingTitle = make("p", "hp-invite-pending-title", "Pending invitations");
+    const refresh = button("hp-invite-refresh", "Refresh");
+    pendingHead.append(pendingTitle, refresh);
+    const pendingList = make("ul", "hp-invite-pending-list");
+    const pendingEmpty = make("p", "hp-invite-pending-empty", "None.");
+    pendingBox.append(pendingHead, pendingList, pendingEmpty);
+    body.append(roleGroup, warning, createRow, error, result, pendingBox);
+    root.append(summary, body);
+    // --- behaviour ----------------------------------------------------------
+    let apiBase = null;
+    let client = null;
+    /** Bumped on every target change and on destroy: an answer for an older link writes nothing. */
+    let generation = 0;
+    let destroyed = false;
+    let creating = false;
+    let loadingPending = false;
+    let copiedTimer;
+    let current = null;
+    const showError = (text) => {
+        error.textContent = text ?? "";
+        error.hidden = text == null;
+    };
+    const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+    const selectedRole = () => {
+        for (const [role, { input }] of roleInputs)
+            if (input.checked)
+                return role;
+        return DEFAULT_INVITE_ROLE;
+    };
+    const renderRole = () => {
+        const role = selectedRole();
+        warning.hidden = role !== "admin";
+        root.dataset.role = role;
+        create.textContent = role === "admin" ? "Create admin invitation" : "Create invitation";
+        create.classList.toggle("hp-invite-create-admin", role === "admin");
+    };
+    const clearResult = () => {
+        current = null;
+        result.hidden = true;
+        link.value = "";
+        qr.replaceChildren();
+        copied.textContent = "";
+        resultNote.textContent = "";
+    };
+    const renderPending = (items) => {
+        const t = now();
+        const live = items.filter((i) => i.expiresAt > t).sort((a, b) => a.expiresAt - b.expiresAt);
+        pendingList.replaceChildren(...live.map((item) => {
+            const li = make("li", "hp-invite-pending-item");
+            const role = item.roles.join(", ") || "(no role)";
+            const roleTag = make("span", `hp-invite-tag${item.roles.includes("admin") ? " hp-invite-tag-admin" : ""}`, role);
+            const when = make("span", "hp-invite-when", `expires ${describeExpiry(item.expiresAt, t)}`);
+            when.title = new Date(item.expiresAt).toLocaleString();
+            li.append(roleTag, " ", when);
+            return li;
+        }));
+        pendingTitle.textContent = `Pending invitations (${live.length})`;
+        pendingEmpty.hidden = live.length > 0;
+    };
+    const loadPending = async () => {
+        const c = client;
+        const gen = generation;
+        if (c == null || loadingPending)
+            return;
+        loadingPending = true;
+        refresh.disabled = true;
+        try {
+            const items = await c.pending();
+            if (gen === generation && !destroyed)
+                renderPending(items);
+        }
+        catch (err) {
+            if (gen === generation && !destroyed)
+                showError(messageOf(err));
+        }
+        finally {
+            loadingPending = false;
+            refresh.disabled = false;
+        }
+    };
+    const showCreated = async (created, role) => {
+        current = created;
+        link.value = created.link;
+        resultNote.textContent =
+            `Anyone with this link joins as ${role === "admin" ? "an ADMIN" : "a member"}, once, ` +
+                `until ${new Date(created.expiresAt).toLocaleString()}. Send it only to the person you mean.`;
+        shareButton.hidden = share == null;
+        copied.textContent = "";
+        result.hidden = false;
+        qr.replaceChildren();
+        const gen = generation;
+        try {
+            const svg = await toQrSvg(created.link);
+            if (gen !== generation || destroyed || current !== created)
+                return;
+            // Our own encoder's markup, from a string it built: no page content goes in.
+            qr.innerHTML = svg;
+        }
+        catch {
+            // No QR is not fatal: the link, Share and Copy still work.
+        }
+    };
+    const hide = () => {
+        root.hidden = true;
+        root.open = false;
+        clearResult();
+        showError(null);
+        pendingList.replaceChildren();
+        pendingEmpty.hidden = false;
+        pendingTitle.textContent = "Pending invitations";
+    };
+    const detect = async (gen, c) => {
+        for (let attempt = 1; attempt <= roleAttempts; attempt++) {
+            try {
+                const roles = await c.roles();
+                if (gen !== generation || destroyed)
+                    return;
+                const offered = offeredRoles(roles);
+                if (offered.length === 0)
+                    return; // an admin, but of a hub with neither role: nothing to offer
+                for (const [role, { input, label }] of roleInputs) {
+                    label.hidden = !offered.includes(role);
+                    input.disabled = !offered.includes(role);
+                }
+                if (!offered.includes(selectedRole())) {
+                    const first = roleInputs.get(offered[0]);
+                    if (first != null)
+                        first.input.checked = true;
+                }
+                renderRole();
+                root.hidden = false;
+                return;
+            }
+            catch (err) {
+                if (gen !== generation || destroyed || isFinalRefusal(err))
+                    return;
+                if (attempt < roleAttempts) {
+                    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+                    if (gen !== generation || destroyed)
+                        return;
+                }
+            }
+        }
+    };
+    const setTarget = (target) => {
+        if (destroyed)
+            return;
+        let base = hubAdminBase(target);
+        const hint = base == null ? false : adminHint(target);
+        // No view yet: keep whatever was decided for this same hub, else wait for one.
+        if (hint === undefined && base === apiBase)
+            return;
+        if (hint !== true)
+            base = null;
+        if (base === apiBase)
+            return;
+        apiBase = base;
+        generation++;
+        client = base == null ? null : createHubAdminClient(fetchImpl, base);
+        hide();
+        if (client != null)
+            void detect(generation, client);
+    };
+    for (const { input } of roleInputs.values())
+        input.addEventListener("change", renderRole);
+    root.addEventListener("toggle", () => {
+        if (root.open)
+            void loadPending();
+    });
+    refresh.addEventListener("click", () => {
+        showError(null);
+        void loadPending();
+    });
+    create.addEventListener("click", () => {
+        const c = client;
+        if (c == null || creating)
+            return;
+        const gen = generation;
+        const role = selectedRole();
+        creating = true;
+        create.disabled = true;
+        showError(null);
+        clearResult();
+        c.create(role, expiryMs(expiry.value)).then(async (created) => {
+            creating = false;
+            create.disabled = false;
+            if (gen !== generation || destroyed)
+                return;
+            await showCreated(created, role);
+            void loadPending();
+        }, (err) => {
+            creating = false;
+            create.disabled = false;
+            if (gen === generation && !destroyed)
+                showError(messageOf(err));
+        });
+    });
+    link.addEventListener("focus", () => link.select());
+    const flashCopied = (text) => {
+        copied.textContent = text;
+        clearTimeout(copiedTimer);
+        copiedTimer = setTimeout(() => {
+            copied.textContent = "";
+        }, 2_500);
+    };
+    copyButton.addEventListener("click", () => {
+        const value = current?.link;
+        if (value == null)
+            return;
+        const viaSelection = () => {
+            link.focus();
+            link.select();
+            const ok = doc.execCommand?.("copy") ?? false;
+            flashCopied(ok ? "Copied" : "Select the link and copy it");
+        };
+        const copy = options.copy ??
+            (doc.defaultView?.navigator.clipboard?.writeText != null
+                ? (text) => doc.defaultView.navigator.clipboard.writeText(text)
+                : null);
+        if (copy == null) {
+            viaSelection();
+            return;
+        }
+        copy(value).then(() => flashCopied("Copied"), () => viaSelection());
+    });
+    shareButton.addEventListener("click", () => {
+        const value = current?.link;
+        if (value == null || share == null)
+            return;
+        share({ title: "Join the mesh", text: "An invitation to join the mesh:", url: value }).catch((err) => {
+            // Closing the share sheet is not an error.
+            if (err?.name === "AbortError")
+                return;
+            showError(`Could not share (${messageOf(err)}). Copy the link instead.`);
+        });
+    });
+    renderRole();
+    return {
+        element: root,
+        setTarget,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            generation++;
+            clearTimeout(copiedTimer);
+            clearResult();
+            root.remove();
+        },
+    };
+}

package/dist/invite.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Inviting from the widget: the hub's admin REST API, called over the mesh.
+ *
+ * NO DOM HERE, so every decision the Invite panel makes -- who counts as an
+ * admin, which roles are offered, what a request body carries, how long an
+ * invitation lives -- is a plain function a test calls with a fake `fetch`.
+ * `./invite-panel.ts` is the DOM on top.
+ *
+ * THE SAME PATH A PAGE ALREADY USES TO REACH THE HUB. A page's ServiceWorker
+ * edge routes `<baseUrl><hubPeerId>/...` over the mesh with this member's
+ * token attached (llm-chat's `mesh.html` requests an LLM key exactly this
+ * way), and the hub serves its admin API at `/hub/api/*` behind
+ * `std:mesh.admin` (`apps/hub/src/rules.ts`, `CORE_POLICIES`). So:
+ *
+ *   - `GET  /hub/api/roles`       -> role names; a 403 means "not an admin".
+ *   - `POST /hub/api/invitations` -> `{ id, expiresAt, blob, link }`.
+ *   - `GET  /hub/api/invitations` -> the pending ones, `{ id, roles, expiresAt }[]`.
+ *
+ * THE ROLES CALL IS THE ADMIN CHECK. The mesh view's own roles are a hint
+ * only (`adminHint`: it decides whether to ask, so a member's console is not
+ * sprayed with 403s); the hub's policy is the answer, and asking the hub costs
+ * one request per link. A hub that is a browser tab (the demos) has no `/hub/api` at all
+ * and answers 404, which hides the panel the same way.
+ *
+ * AN INVITATION IS A BEARER SECRET. Nothing here logs one, and no error
+ * message quotes a response body that could carry one: the only body read on
+ * failure is the hub's `{ error }`, which never includes an invitation.
+ */
+/** The roles the panel offers, in order. Anything else a hub knows (`hidden`, a module's own) is not offered. */
+export declare const INVITE_ROLES: readonly ["member", "admin"];
+export type InviteRole = (typeof INVITE_ROLES)[number];
+export declare const DEFAULT_INVITE_ROLE: InviteRole;
+/** The lifetimes offered. The hub's own default is one day, and so is the panel's. */
+export declare const INVITE_EXPIRIES: readonly [{
+    readonly id: "1h";
+    readonly label: "1 hour";
+    readonly ttlMs: number;
+}, {
+    readonly id: "1d";
+    readonly label: "1 day";
+    readonly ttlMs: number;
+}, {
+    readonly id: "7d";
+    readonly label: "7 days";
+    readonly ttlMs: number;
+}];
+export type InviteExpiryId = (typeof INVITE_EXPIRIES)[number]["id"];
+export declare const DEFAULT_INVITE_EXPIRY: InviteExpiryId;
+/** What an admin invitation hands over, said before one is made. */
+export declare const ADMIN_INVITATION_WARNING: string;
+/** A lifetime id to milliseconds. An unknown id is the default, never `undefined`: the request always says how long. */
+export declare function expiryMs(id: string): number;
+/** The body of `POST /hub/api/invitations`: one role, and the lifetime. */
+export declare function invitationRequestBody(role: InviteRole, ttlMs: number): {
+    roles: string[];
+    ttlMs: number;
+};
+/** The roles to offer, given what the hub says it knows: ours, in our order, and only those it knows. */
+export declare function offeredRoles(hubRoles: readonly string[]): InviteRole[];
+/** The part of a mesh view the admin hint reads, by shape. */
+export interface MeshViewHint {
+    self: string;
+    members: ReadonlyArray<{
+        peerId: string;
+        roles: readonly string[];
+    }>;
+}
+/**
+ * The part of a member handle the panel needs. `baseUrl` is absent where no
+ * edge is mounted (Node). `meshView`, when present, is the hint that decides
+ * whether the hub is asked at all -- see `adminHint`.
+ */
+export interface HubTarget {
+    hubPeerId: string;
+    baseUrl?: string;
+    meshView?: () => MeshViewHint | null;
+}
+/**
+ * Whether to ask the hub if this member is an admin: `true` when the mesh
+ * view lists this member with the `admin` role, `false` when it lists it
+ * without, `undefined` while there is no view yet (it arrives on the first
+ * heartbeat). A target with no `meshView` at all is always asked.
+ *
+ * WHY ASK ONLY A LIKELY ADMIN. The hub's 403 is the answer, but a browser
+ * reports every refused request in the console as an error, so asking every
+ * member would put a red line in every member's console on every link. The
+ * view says who holds `admin`, and the hub still decides: a view that says
+ * `admin` to a peer the hub refuses leaves the panel hidden.
+ */
+export declare function adminHint(target: HubTarget | null | undefined): boolean | undefined;
+/** `<baseUrl><hubPeerId>/hub/api/`, or `null` when there is no edge to call through. */
+export declare function hubAdminBase(target: HubTarget | null | undefined): string | null;
+export interface CreatedInvitation {
+    id: string;
+    expiresAt: number;
+    blob: string;
+    link: string;
+}
+export interface PendingInvitation {
+    id: string;
+    roles: string[];
+    expiresAt: number;
+}
+/** A failed admin call. `status` is 0 when the request never got an answer. */
+export declare class HubAdminError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Whether a failed roles call means "this member is not an admin here" (or
+ * "this hub has no admin API"), as opposed to a hiccup worth another try.
+ */
+export declare function isFinalRefusal(error: unknown): boolean;
+export interface HubAdminClient {
+    /** The hub's role names. Rejects with a `HubAdminError`; a 403 is the usual "not an admin". */
+    roles(): Promise<string[]>;
+    create(role: InviteRole, ttlMs: number): Promise<CreatedInvitation>;
+    pending(): Promise<PendingInvitation[]>;
+}
+/** The admin API at `apiBase` (`hubAdminBase`'s value), through `fetchImpl`. */
+export declare function createHubAdminClient(fetchImpl: typeof fetch, apiBase: string): HubAdminClient;
+/** "in 59 min", "in 23 h", "in 6 d", or "expired": how long an invitation has left, at a glance. */
+export declare function describeExpiry(expiresAt: number, now: number): string;
+//# sourceMappingURL=invite.d.ts.map

package/dist/invite.d.ts.map

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

package/dist/invite.js

@@ -0,0 +1,192 @@
+/**
+ * Inviting from the widget: the hub's admin REST API, called over the mesh.
+ *
+ * NO DOM HERE, so every decision the Invite panel makes -- who counts as an
+ * admin, which roles are offered, what a request body carries, how long an
+ * invitation lives -- is a plain function a test calls with a fake `fetch`.
+ * `./invite-panel.ts` is the DOM on top.
+ *
+ * THE SAME PATH A PAGE ALREADY USES TO REACH THE HUB. A page's ServiceWorker
+ * edge routes `<baseUrl><hubPeerId>/...` over the mesh with this member's
+ * token attached (llm-chat's `mesh.html` requests an LLM key exactly this
+ * way), and the hub serves its admin API at `/hub/api/*` behind
+ * `std:mesh.admin` (`apps/hub/src/rules.ts`, `CORE_POLICIES`). So:
+ *
+ *   - `GET  /hub/api/roles`       -> role names; a 403 means "not an admin".
+ *   - `POST /hub/api/invitations` -> `{ id, expiresAt, blob, link }`.
+ *   - `GET  /hub/api/invitations` -> the pending ones, `{ id, roles, expiresAt }[]`.
+ *
+ * THE ROLES CALL IS THE ADMIN CHECK. The mesh view's own roles are a hint
+ * only (`adminHint`: it decides whether to ask, so a member's console is not
+ * sprayed with 403s); the hub's policy is the answer, and asking the hub costs
+ * one request per link. A hub that is a browser tab (the demos) has no `/hub/api` at all
+ * and answers 404, which hides the panel the same way.
+ *
+ * AN INVITATION IS A BEARER SECRET. Nothing here logs one, and no error
+ * message quotes a response body that could carry one: the only body read on
+ * failure is the hub's `{ error }`, which never includes an invitation.
+ */
+/** The roles the panel offers, in order. Anything else a hub knows (`hidden`, a module's own) is not offered. */
+export const INVITE_ROLES = ["member", "admin"];
+export const DEFAULT_INVITE_ROLE = "member";
+const HOUR = 60 * 60 * 1000;
+/** The lifetimes offered. The hub's own default is one day, and so is the panel's. */
+export const INVITE_EXPIRIES = [
+    { id: "1h", label: "1 hour", ttlMs: HOUR },
+    { id: "1d", label: "1 day", ttlMs: 24 * HOUR },
+    { id: "7d", label: "7 days", ttlMs: 7 * 24 * HOUR },
+];
+export const DEFAULT_INVITE_EXPIRY = "1d";
+/** What an admin invitation hands over, said before one is made. */
+export const ADMIN_INVITATION_WARNING = "An admin invitation grants full control of this mesh: whoever redeems it can invite " +
+    "others (admins too), revoke members, and use every admin service the hub offers. " +
+    "Send it only to someone you would trust with this device.";
+/** A lifetime id to milliseconds. An unknown id is the default, never `undefined`: the request always says how long. */
+export function expiryMs(id) {
+    const found = INVITE_EXPIRIES.find((e) => e.id === id) ??
+        INVITE_EXPIRIES.find((e) => e.id === DEFAULT_INVITE_EXPIRY);
+    return found.ttlMs;
+}
+/** The body of `POST /hub/api/invitations`: one role, and the lifetime. */
+export function invitationRequestBody(role, ttlMs) {
+    return { roles: [role], ttlMs };
+}
+/** The roles to offer, given what the hub says it knows: ours, in our order, and only those it knows. */
+export function offeredRoles(hubRoles) {
+    return INVITE_ROLES.filter((role) => hubRoles.includes(role));
+}
+/**
+ * Whether to ask the hub if this member is an admin: `true` when the mesh
+ * view lists this member with the `admin` role, `false` when it lists it
+ * without, `undefined` while there is no view yet (it arrives on the first
+ * heartbeat). A target with no `meshView` at all is always asked.
+ *
+ * WHY ASK ONLY A LIKELY ADMIN. The hub's 403 is the answer, but a browser
+ * reports every refused request in the console as an error, so asking every
+ * member would put a red line in every member's console on every link. The
+ * view says who holds `admin`, and the hub still decides: a view that says
+ * `admin` to a peer the hub refuses leaves the panel hidden.
+ */
+export function adminHint(target) {
+    if (target == null)
+        return false;
+    if (typeof target.meshView !== "function")
+        return true;
+    const view = target.meshView();
+    if (view == null)
+        return undefined;
+    return view.members.find((m) => m.peerId === view.self)?.roles.includes("admin") ?? false;
+}
+/** `<baseUrl><hubPeerId>/hub/api/`, or `null` when there is no edge to call through. */
+export function hubAdminBase(target) {
+    if (target?.baseUrl == null || target.baseUrl === "")
+        return null;
+    if (!/^[A-Za-z0-9]+$/.test(target.hubPeerId))
+        return null;
+    const base = target.baseUrl.endsWith("/") ? target.baseUrl : `${target.baseUrl}/`;
+    return `${base}${target.hubPeerId}/hub/api/`;
+}
+/** A failed admin call. `status` is 0 when the request never got an answer. */
+export class HubAdminError extends Error {
+    status;
+    constructor(status, message, options) {
+        super(message, options);
+        this.status = status;
+        this.name = "HubAdminError";
+    }
+}
+/**
+ * Whether a failed roles call means "this member is not an admin here" (or
+ * "this hub has no admin API"), as opposed to a hiccup worth another try.
+ */
+export function isFinalRefusal(error) {
+    return (error instanceof HubAdminError &&
+        (error.status === 401 || error.status === 403 || error.status === 404));
+}
+async function failure(response, what) {
+    let reason = "";
+    try {
+        const body = (await response.json());
+        if (typeof body.error === "string")
+            reason = body.error.slice(0, 200);
+    }
+    catch {
+        // Not JSON: say the status only. A body we do not understand is not quoted.
+    }
+    const status = response.status;
+    const text = status === 403
+        ? `The hub refused to ${what} (403): only a mesh admin can.`
+        : `Could not ${what}: HTTP ${status}${reason === "" ? "" : ` (${reason})`}.`;
+    return new HubAdminError(status, text);
+}
+/** The admin API at `apiBase` (`hubAdminBase`'s value), through `fetchImpl`. */
+export function createHubAdminClient(fetchImpl, apiBase) {
+    const call = async (path, what, init) => {
+        let response;
+        try {
+            response = await fetchImpl(new URL(path, apiBase).href, {
+                ...init,
+                headers: { accept: "application/json", ...(init?.headers ?? {}) },
+            });
+        }
+        catch (cause) {
+            throw new HubAdminError(0, `Could not reach the hub to ${what}.`, { cause });
+        }
+        if (!response.ok)
+            throw await failure(response, what);
+        try {
+            return await response.json();
+        }
+        catch (cause) {
+            throw new HubAdminError(response.status, `The hub's answer to ${what} was not JSON.`, {
+                cause,
+            });
+        }
+    };
+    return {
+        async roles() {
+            const value = await call("roles", "list its roles");
+            if (!Array.isArray(value) || !value.every((r) => typeof r === "string")) {
+                throw new HubAdminError(200, "The hub's role list is not a list of names.");
+            }
+            return value;
+        },
+        async create(role, ttlMs) {
+            const value = (await call("invitations", "create an invitation", {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(invitationRequestBody(role, ttlMs)),
+            }));
+            if (value == null ||
+                typeof value.link !== "string" ||
+                value.link === "" ||
+                typeof value.expiresAt !== "number") {
+                throw new HubAdminError(200, "The hub answered without an invitation link.");
+            }
+            return value;
+        },
+        async pending() {
+            const value = await call("invitations", "list pending invitations");
+            if (!Array.isArray(value)) {
+                throw new HubAdminError(200, "The hub's pending invitations are not a list.");
+            }
+            return value.filter((v) => v != null &&
+                typeof v === "object" &&
+                Array.isArray(v.roles) &&
+                typeof v.expiresAt === "number");
+        },
+    };
+}
+/** "in 59 min", "in 23 h", "in 6 d", or "expired": how long an invitation has left, at a glance. */
+export function describeExpiry(expiresAt, now) {
+    const left = expiresAt - now;
+    if (left <= 0)
+        return "expired";
+    const minutes = Math.ceil(left / 60_000);
+    if (minutes < 60)
+        return `in ${minutes} min`;
+    const hours = Math.round(left / HOUR);
+    if (hours < 48)
+        return `in ${hours} h`;
+    return `in ${Math.round(left / (24 * HOUR))} d`;
+}