@getfamiliar/shared 0.1.13 → 0.1.16

package/build/WebAuth.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Trusted-proxy contract of the core webserver.
+ *
+ * A reverse proxy in front of the webserver (a user-run Authelia /
+ * oauth2-proxy, or a plugin's own proxy such as the tailscale sidecar)
+ * proves that a request went through it by sending
+ * {@link PROXY_SECRET_HEADER} with a shared secret. Only then does the
+ * webserver read the proxy's user header; without a matching secret,
+ * identity headers are ignored. Shared because plugins register such
+ * proxies through `ctx.web.registerTrustedProxy`.
+ *
+ * Also the contract of a web UI plugin's root controller
+ * ({@link WebUiEnv}, see `PluginHostManifest.webUi`).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Hono } from "hono";
+import type { WebMenuEntry } from "./WebMenu.js";
+import type { WebPageEntry } from "./WebPlugin.js";
+/** Request header carrying a trusted proxy's shared secret (lowercase, as Hono / node normalize it). */
+export declare const PROXY_SECRET_HEADER = "x-familiar-proxy-secret";
+/** Minimum length of a trusted-proxy secret; shorter ones are rejected. */
+export declare const MIN_PROXY_SECRET_LENGTH = 32;
+/** A reverse proxy whose user header the webserver trusts once its secret matches. */
+export interface TrustedProxyRegistration {
+    /** Shared secret the proxy sends in {@link PROXY_SECRET_HEADER}; at least {@link MIN_PROXY_SECRET_LENGTH} characters. */
+    readonly secret: string;
+    /** Header holding the authenticated login (e.g. `Tailscale-User-Login`, `Remote-User`). Empty or absent means "no identity". */
+    readonly userHeader: string;
+    /** Optional header holding a display name (e.g. `Tailscale-User-Name`). */
+    readonly nameHeader?: string;
+    /**
+     * Optional: where browsers reach the webserver through this proxy right
+     * now (e.g. `https://familiar.<tailnet>.ts.net`), or null while it is
+     * not serving. Used to build login links that work from the user's
+     * other devices. Called on demand; must be cheap and must not throw.
+     */
+    readonly publicBaseUrl?: () => string | null;
+    /**
+     * Whether the proxy signs users in by itself: an allowed user who opens
+     * {@link publicBaseUrl} is already authenticated (Tailscale identity,
+     * an Authelia login page, …), so a login link is pointless there and is
+     * not offered under that URL; the URL is listed as "signs in
+     * automatically" instead. Default `false`: login links are built for
+     * the proxy's URL.
+     */
+    readonly hasBuiltInAuth?: boolean;
+}
+/** Webserver hooks exposed to plugins as `ctx.web`. */
+export interface WebApi {
+    /**
+     * Register this plugin as a trusted proxy of the webserver; its id is
+     * the plugin id. Call it from **`prepare()`**. The host drops the
+     * registration when the plugin restarts.
+     *
+     * @throws {Error} When the secret is shorter than
+     *   {@link MIN_PROXY_SECRET_LENGTH}, the user header is empty, or the
+     *   plugin already registered a proxy.
+     */
+    registerTrustedProxy(registration: TrustedProxyRegistration): void;
+    /**
+     * The web UI menu: every running plugin's `webMenu(ctx)` items, sorted
+     * by plugin weight (then plugin id), each plugin's items in its own
+     * order. Read it per request; it changes when plugins restart. For
+     * the web UI plugin; others contribute through their `webMenu` hook.
+     *
+     * @returns The flat, sorted item list (empty when nobody contributes).
+     */
+    listMenuItems(): readonly WebMenuEntry[];
+    /**
+     * The plugin pages (`webPlugin(ctx)` hooks with a `page`), one per
+     * plugin, sorted by plugin id. Read it per request. For the web UI
+     * plugin, which loads the page owning the current route.
+     *
+     * @returns The pages.
+     */
+    listPages(): readonly WebPageEntry[];
+}
+/** Who a request belongs to, as resolved by the core auth middleware. */
+export interface WebPrincipal {
+    /** Login as listed in `webserver.auth.users`. */
+    readonly login: string;
+    /** Display name from the proxy's name header, else the login. */
+    readonly displayName: string;
+    /** `session`, or the id of the trusted proxy that vouched for the login (`plugin:tailscale`, `config:authelia`). */
+    readonly via: string;
+}
+/**
+ * Node bindings the webserver passes on every request (`c.env`), the same
+ * shape as `HttpBindings` of `@hono/node-server`. A UI controller may
+ * hand them to node-style middleware (e.g. Vite's dev server) and answer
+ * with `RESPONSE_ALREADY_SENT`.
+ */
+export interface WebUiBindings {
+    readonly incoming: IncomingMessage;
+    readonly outgoing: ServerResponse;
+}
+/**
+ * Hono environment of a web UI plugin's root controller. Every request
+ * reaching the controller passed the core auth middleware, so
+ * `c.get("principal")` is always set.
+ */
+export interface WebUiEnv {
+    Bindings: WebUiBindings;
+    Variables: {
+        /** The signed-in, allowlisted user. */
+        principal: WebPrincipal;
+        /** Whether the browser talks HTTPS (directly, or to a trusted proxy that says so). */
+        isHttps: boolean;
+    };
+}
+/**
+ * One of the core login-flow pages, described as data. The core decides
+ * which page is shown, with which status code, and handles every form
+ * submission itself; a web UI only turns the view into markup
+ * ({@link WebUi.renderAuthPage}).
+ */
+export type WebAuthPageView = 
+/** `GET /login` with an allowed identity: who is signed in, link to the app. */
+{
+    readonly kind: "signedIn";
+    readonly principal: WebPrincipal;
+    /** Where "continue" leads (`/`). */
+    readonly continueUrl: string;
+    /** Form action of the sign-out button (`POST`, `/logout`). */
+    readonly logoutAction: string;
+}
+/** `GET /login` without identity: how to get a login link. */
+ | {
+    readonly kind: "signedOut";
+    /** CLI command that prints a login link (`familiar web login`). */
+    readonly loginCommand: string;
+}
+/** `GET /login/:token`: confirm before the one-time token is redeemed. */
+ | {
+    readonly kind: "confirmLoginLink";
+    /** Form action redeeming the token (`POST`, `/login/<token>`). */
+    readonly formAction: string;
+}
+/** `POST /login/:token` with an invalid, used or expired token. */
+ | {
+    readonly kind: "invalidLoginLink";
+    /** CLI command that prints a new login link. */
+    readonly loginCommand: string;
+};
+/**
+ * What a web UI plugin hands the core webserver from its `webUi(ctx)` hook.
+ */
+export interface WebUi {
+    /**
+     * Root controller mounted at `/`, behind the core auth middleware and
+     * after the core login routes.
+     */
+    readonly controller: Hono<WebUiEnv>;
+    /**
+     * Optional: render a login-flow page as a complete HTML document.
+     * The page is served under a strict Content-Security-Policy (no
+     * scripts, no external resources; inline styles and `data:` fonts /
+     * images only; forms may post to the same origin only), so it must
+     * be self-contained. Text content must be escaped by the renderer.
+     * When it is absent or throws, the core serves its plain page.
+     *
+     * @param view The page the core decided to show.
+     * @returns The HTML document.
+     */
+    readonly renderAuthPage?: (view: WebAuthPageView) => Promise<string>;
+}

package/build/WebAuth.js

@@ -0,0 +1,18 @@
+/**
+ * Trusted-proxy contract of the core webserver.
+ *
+ * A reverse proxy in front of the webserver (a user-run Authelia /
+ * oauth2-proxy, or a plugin's own proxy such as the tailscale sidecar)
+ * proves that a request went through it by sending
+ * {@link PROXY_SECRET_HEADER} with a shared secret. Only then does the
+ * webserver read the proxy's user header; without a matching secret,
+ * identity headers are ignored. Shared because plugins register such
+ * proxies through `ctx.web.registerTrustedProxy`.
+ *
+ * Also the contract of a web UI plugin's root controller
+ * ({@link WebUiEnv}, see `PluginHostManifest.webUi`).
+ */
+/** Request header carrying a trusted proxy's shared secret (lowercase, as Hono / node normalize it). */
+export const PROXY_SECRET_HEADER = "x-familiar-proxy-secret";
+/** Minimum length of a trusted-proxy secret; shorter ones are rejected. */
+export const MIN_PROXY_SECRET_LENGTH = 32;

package/build/WebMenu.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Navigation entries plugins contribute to the web UI's sidebar.
+ *
+ * A plugin returns one {@link WebMenuContribution} from its `webMenu(ctx)`
+ * hook; the core collects them, sorts them by weight and hands the flat
+ * list to the web UI plugin (`ctx.web.listMenuItems()`), which renders it.
+ */
+/** Lucide icon id, kebab-case (`mail`, `calendar-days`), see https://lucide.dev/icons. */
+export declare const WEB_MENU_ICON_PATTERN: RegExp;
+/** A sub-entry of a collapsible menu item. */
+export interface WebMenuSubItem {
+    /** Text shown in the menu. */
+    readonly label: string;
+    /** Path inside the web UI, starting with `/` (e.g. `/plugins/mail/inbox`). */
+    readonly route: string;
+}
+/**
+ * One top-level menu item: a direct link (`route` without `children`) or a
+ * collapsible group (`children`, optionally with its own `route`).
+ */
+export interface WebMenuItem {
+    /** Lucide icon id (see {@link WEB_MENU_ICON_PATTERN}). */
+    readonly icon: string;
+    /** Text shown in the menu. */
+    readonly label: string;
+    /** Path inside the web UI, starting with `/`. Required when there are no children. */
+    readonly route?: string;
+    /** Sub-entries; makes the item collapsible. */
+    readonly children?: readonly WebMenuSubItem[];
+}
+/** What one plugin contributes to the menu. */
+export interface WebMenuContribution {
+    /**
+     * Position of the plugin's items among all plugins: lower weights come
+     * first (default 0; ties are ordered by plugin id). The plugin's items
+     * keep their own order.
+     */
+    readonly weight?: number;
+    /** The plugin's items, in display order. */
+    readonly items: readonly WebMenuItem[];
+}
+/** A menu item as the core hands it to the web UI. */
+export interface WebMenuEntry extends WebMenuItem {
+    /** Plugin that contributed the item. */
+    readonly pluginId: string;
+}
+/**
+ * The first route of a menu: the first item's own route, else its first
+ * child's route. The web UI opens it instead of an empty start page.
+ *
+ * @param items Sorted menu items.
+ * @returns The route, or null for an empty menu.
+ */
+export declare function firstMenuRoute(items: readonly WebMenuItem[]): string | null;

package/build/WebMenu.js

@@ -0,0 +1,23 @@
+/**
+ * Navigation entries plugins contribute to the web UI's sidebar.
+ *
+ * A plugin returns one {@link WebMenuContribution} from its `webMenu(ctx)`
+ * hook; the core collects them, sorts them by weight and hands the flat
+ * list to the web UI plugin (`ctx.web.listMenuItems()`), which renders it.
+ */
+/** Lucide icon id, kebab-case (`mail`, `calendar-days`), see https://lucide.dev/icons. */
+export const WEB_MENU_ICON_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * The first route of a menu: the first item's own route, else its first
+ * child's route. The web UI opens it instead of an empty start page.
+ *
+ * @param items Sorted menu items.
+ * @returns The route, or null for an empty menu.
+ */
+export function firstMenuRoute(items) {
+    const first = items[0];
+    if (first === undefined) {
+        return null;
+    }
+    return first.route ?? first.children?.[0]?.route ?? null;
+}

package/build/WebPlugin.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Plugin pages and controllers of the web UI.
+ *
+ * A plugin's `webPlugin(ctx)` hook returns a {@link WebPluginUi}: a Hono
+ * controller the core webserver mounts at `/plugins/<plugin-id>/`
+ * (behind its authentication) and, optionally, a page module the web UI
+ * plugin loads into its content area for every browser route under
+ * `/plugins/<plugin-id>`.
+ */
+import type { Hono } from "hono";
+import type { WebPrincipal, WebUiEnv } from "./WebAuth.js";
+/** Where a plugin page's ES module comes from. */
+export interface WebPageModule {
+    /**
+     * Path of the built module relative to the plugin's controller mount,
+     * e.g. `page/page.js` → served as `/plugins/<id>/page/page.js` by the
+     * plugin's own controller.
+     */
+    readonly module: string;
+    /**
+     * Dev mode only: absolute path of the page's source entry (`.tsx`).
+     * A web UI with a dev server may load it from source instead (hot
+     * reload, one React); omit it in production.
+     */
+    readonly sourceFile?: string;
+}
+/** What a plugin hands the core from its `webPlugin(ctx)` hook. */
+export interface WebPluginUi {
+    /**
+     * Controller mounted at `/plugins/<plugin-id>/`, behind the core auth
+     * middleware (`c.get("principal")` is set). Register concrete routes
+     * only (e.g. `/api/*`, `/page/*`) and **no catch-all**: every path the
+     * controller does not match falls through to the web UI, which is how
+     * the browser routes of the plugin's page (`/plugins/<id>`, …) reach it.
+     */
+    readonly controller: Hono<WebUiEnv>;
+    /** Optional page shown by the web UI for routes under `/plugins/<plugin-id>`. */
+    readonly page?: WebPageModule;
+    /**
+     * Optional WebSocket endpoints, served at `/plugins/<plugin-id><path>`.
+     * The core authenticates every handshake like an ordinary request
+     * (proxy login or session, allowlist) and additionally requires a
+     * same-origin `Origin` header; only then is `onConnection` called.
+     * All sockets of a plugin are closed when it restarts.
+     */
+    readonly sockets?: readonly WebPluginSocket[];
+}
+/** A WebSocket endpoint of a plugin (see {@link WebPluginUi.sockets}). */
+export interface WebPluginSocket {
+    /**
+     * Path below the plugin's mount, starting with `/` (e.g. `/socket`
+     * → `/plugins/<plugin-id>/socket`). Matched exactly, query ignored.
+     */
+    readonly path: string;
+    /**
+     * Called once per authenticated connection. Must not throw; errors
+     * of the connection's own work belong on the peer (`close`).
+     *
+     * @param peer The open socket.
+     * @param info Who connected and how.
+     */
+    onConnection(peer: WebSocketPeer, info: WebSocketConnectionInfo): void;
+}
+/** Who opened a plugin WebSocket. */
+export interface WebSocketConnectionInfo {
+    /** The signed-in, allowlisted user. */
+    readonly principal: WebPrincipal;
+    /** Whether the browser reached the server over HTTPS (directly or via a trusted proxy). */
+    readonly isHttps: boolean;
+}
+/**
+ * Minimal, library-independent view of an open WebSocket, so plugins do
+ * not depend on the server's WebSocket implementation.
+ */
+export interface WebSocketPeer {
+    /**
+     * Send a text (string) or binary (bytes) frame. Silently dropped once
+     * the socket is closing.
+     *
+     * @param data Frame payload.
+     */
+    send(data: string | Uint8Array): void;
+    /**
+     * Close the socket.
+     *
+     * @param code WebSocket close code (default 1000; 4000–4999 are free for the application).
+     * @param reason Short human-readable reason (≤ 123 bytes).
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Register the frame handler (one per peer; a second call replaces it).
+     *
+     * @param handler Receives text frames as string, binary frames as bytes.
+     */
+    onMessage(handler: (data: string | Uint8Array) => void): void;
+    /**
+     * Register the close handler (one per peer; a second call replaces
+     * it). Called exactly once, also when the server closed the socket.
+     *
+     * @param handler Receives the close code and reason.
+     */
+    onClose(handler: (code: number, reason: string) => void): void;
+    /** Bytes queued but not yet sent (for backpressure). */
+    readonly bufferedAmount: number;
+    /** Whether the socket is open (not connecting, closing or closed). */
+    readonly isOpen: boolean;
+}
+/** A plugin page as the core lists it for the web UI (`ctx.web.listPages()`). */
+export interface WebPageEntry {
+    /** Plugin providing the page. */
+    readonly pluginId: string;
+    /** Browser route prefix the page owns: `/plugins/<plugin-id>`. */
+    readonly basePath: string;
+    /** URL of the built module (`/plugins/<plugin-id>/<module>`). */
+    readonly moduleUrl: string;
+    /** Dev mode: absolute source entry (see {@link WebPageModule.sourceFile}). */
+    readonly sourceFile?: string;
+}
+/** What the web UI passes to a page module's `mount`. */
+export interface WebPageContext {
+    /** Route prefix of the page (`/plugins/<plugin-id>`). */
+    readonly basePath: string;
+    /** Current browser path (at or below `basePath`). */
+    readonly pathname: string;
+    /** The signed-in user. */
+    readonly user: WebPrincipal;
+    /** Navigate the web UI to another route. */
+    navigate(to: string): void;
+}
+/**
+ * Default export of a page module: render the page into `container`
+ * (the web UI's content area) and return a function that unmounts it.
+ * Framework-agnostic; a React page creates its own root.
+ */
+export type MountWebPage = (container: HTMLElement, context: WebPageContext) => () => void;
+/** Route prefix of a plugin's controller and page. */
+export declare function webPluginBasePath(pluginId: string): string;

package/build/WebPlugin.js

@@ -0,0 +1,13 @@
+/**
+ * Plugin pages and controllers of the web UI.
+ *
+ * A plugin's `webPlugin(ctx)` hook returns a {@link WebPluginUi}: a Hono
+ * controller the core webserver mounts at `/plugins/<plugin-id>/`
+ * (behind its authentication) and, optionally, a page module the web UI
+ * plugin loads into its content area for every browser route under
+ * `/plugins/<plugin-id>`.
+ */
+/** Route prefix of a plugin's controller and page. */
+export function webPluginBasePath(pluginId) {
+    return `/plugins/${pluginId}`;
+}

package/build/WebServerDefaults.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Defaults of the core `webserver.*` config keys. Shared because both
+ * the host's `WebServer` and plugins that front it (tailscale) must
+ * resolve the same effective port and bind address.
+ */
+/** Port the webserver listens on when `webserver.port` is unset. */
+export declare const DEFAULT_WEBSERVER_PORT = 8080;
+/** Address the webserver binds on when `webserver.host` is unset. */
+export declare const DEFAULT_WEBSERVER_HOST = "0.0.0.0";

package/build/WebServerDefaults.js

@@ -0,0 +1,9 @@
+/**
+ * Defaults of the core `webserver.*` config keys. Shared because both
+ * the host's `WebServer` and plugins that front it (tailscale) must
+ * resolve the same effective port and bind address.
+ */
+/** Port the webserver listens on when `webserver.port` is unset. */
+export const DEFAULT_WEBSERVER_PORT = 8080;
+/** Address the webserver binds on when `webserver.host` is unset. */
+export const DEFAULT_WEBSERVER_HOST = "0.0.0.0";

package/build/WebStaticAssets.d.ts

@@ -0,0 +1,72 @@
+import type { Context } from "hono";
+/**
+ * Content type for a file name, by extension.
+ *
+ * @param fileName File name or path.
+ * @returns The media type, `application/octet-stream` when unknown.
+ */
+export declare function contentTypeForFile(fileName: string): string;
+/** Options of {@link WebStaticAssets}. */
+export interface WebStaticAssetsOptions {
+    /**
+     * URL prefix the directory is served under (e.g. `/plugins/web-chat/page`);
+     * stripped from the request path before mapping it onto a file.
+     * Default: the site root.
+     */
+    readonly urlPrefix?: string;
+    /**
+     * Answer unknown GET paths without a file extension with `index.html`,
+     * so client-side routes of a single-page app survive a reload.
+     */
+    readonly spaFallback: boolean;
+    /** Hint added to the 500 answer when the directory was never built (e.g. "run `npm run build` in plugins/web-chat"). */
+    readonly missingBuildHint?: string;
+}
+/**
+ * Serve a directory of built web assets (a Vite build output) from a
+ * Hono route, for web UI plugins and plugin pages.
+ *
+ * A request path maps onto a file below the directory; paths escaping it
+ * are refused. Files under `assets/` (content-hashed) are cached forever,
+ * everything else is revalidated (`no-cache`).
+ */
+export declare class WebStaticAssets {
+    private readonly rootDir;
+    private readonly options;
+    /**
+     * @param rootDir Absolute path of the build output.
+     * @param options URL prefix, SPA fallback, build hint.
+     */
+    constructor(rootDir: string, options: WebStaticAssetsOptions);
+    /**
+     * Answer one request.
+     *
+     * @param c Request context.
+     * @returns The file, the SPA fallback, 404, or a 500 page when the
+     *   directory was never built.
+     */
+    handle(c: Context): Promise<Response>;
+    /**
+     * The 500 answer for a directory that was never built.
+     *
+     * @param c Request context.
+     * @returns The response.
+     */
+    private missingBuild;
+    /**
+     * Map a URL path onto a file path below {@link rootDir}.
+     *
+     * @param urlPath Request path.
+     * @returns The absolute file path, or null when it lies outside the
+     *   prefix, escapes the directory or is not decodable.
+     */
+    private resolveRequestPath;
+    /**
+     * Send one file with content type and cache headers.
+     *
+     * @param c Request context.
+     * @param file Absolute file path below the root.
+     * @returns The response.
+     */
+    private sendFile;
+}