@ghub/identity-chrome 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,115 @@
+Copyright (c) 2026 Gelhaus Solutions (Enno Gelhaus). All rights reserved.
+
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+---
+
+## Additional restriction
+
+In addition to the limitations in the Elastic License 2.0 above, and as a
+condition of the licence granted by it:
+
+  You may not use the software for commercial purposes without a separate
+  business licence granted in writing by Gelhaus Solutions.
+
+Commercial purposes include use in, by or for a business or other commercial
+undertaking, whether or not the software is provided to anyone outside it, and
+whether or not a fee is charged. Non-commercial use is not restricted by this
+paragraph.
+
+This restriction is ours and is not part of the Elastic License 2.0. The
+Elastic License 2.0 by itself permits commercial internal use; this paragraph
+removes that permission. Where the two conflict, this paragraph applies.
+
+For a business licence, contact egelhaus@ennogelhaus.de.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @ghub/identity-chrome
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared header controls of the Gelhaus Solutions products: the apps picker and the
+account popup. This version is the part with no markup in it: the browser half (what the
+controls know, what they keep, what they do when Identity cannot be reached) and the server
+half (a product's own server asking GPlatform Identity). The Web Component and the React
+wrapper come with the design.
+
+Nothing here depends on a product signing in through Identity. A product that has not
+adopted it uses the same package the same way.
+
+## Off unless enabled
+
+```ts
+import { createChromeCore } from "@ghub/identity-chrome";
+
+const chrome = createChromeCore({
+  enabled: true, // anything but exactly true makes no request and reads no storage
+  endpoint: "/api/identity-chrome", // the product's own route, same origin
+  storage: window.localStorage, // optional: the last list, held for an outage
+});
+
+chrome.subscribe((state) => draw(state));
+await chrome.load();
+```
+
+A self-hosted or customer-run installation never sets `enabled`, so it never calls anybody.
+The last answer is drawn at once while a fresh one is fetched, is kept and marked `stale`
+when the refresh fails, and is thirty days old at most. Call `chrome.clear()` on sign-out, so
+a shared device never shows the next person the previous one's products.
+
+Every address in an answer is checked before it is drawn: a tile or an icon whose address is
+not `http` or `https` is dropped, never repaired, in a fresh answer and in the cached copy
+alike.
+
+## The product's own route
+
+```ts
+import { createChromeServer } from "@ghub/identity-chrome/server";
+
+const chrome = createChromeServer({
+  baseUrl: process.env.GPID_URL,
+  product: "advisory",
+  token: process.env.GPID_CHROME_TOKEN, // never sent to a browser
+});
+
+// Any framework that speaks the web Request and Response:
+export const GET = chrome.handler(async (request) => {
+  const user = await sessionOf(request);
+  return user === null ? null : { email: user.verifiedEmail };
+});
+```
+
+The route says only who is signed in, by an address the product has verified, and Identity
+answers with the products that person has and the public ones they do not, and the two
+footer links of the account popup (the terms and the privacy policy, the same in every
+product, so a moved address needs no new release here). An unverified
+address is a way to ask about somebody else. Answers are reused for a minute, and the token
+is never in anything this package throws or answers.
+
+A one-off push of a product's users (`chrome.seed(emails)`) is refused unless staff have
+opened a window for it on Identity's product screen, and `chrome.remove(emails)` says people
+no longer have access.
+
+## A product's own name and mark
+
+Identity's catalogue is where every product's name and mark live. Read your own from it for
+your top bar, your title and your favicon, and a rename or a new mark reaches you without a
+release:
+
+```ts
+import { catalogueMarkUrl, createCatalogue } from "@ghub/identity-chrome";
+
+const catalogue = createCatalogue({ baseUrl: process.env.GPID_URL });
+const me = await catalogue.entry("gadvisory"); // { displayName, homeUrl, iconUrl, monoIconUrl, ... }
+
+// Where you cannot ask first, an address that always leads to the current mark:
+// <link rel="icon" type="image/svg+xml" href={catalogueMarkUrl(process.env.GPID_URL, "gadvisory")} />
+```
+
+No token is needed. An entry is reused for a minute, and after a failed ask the last good one
+is returned, so an outage leaves the name and mark you last had. A self-hosted install asks
+nobody and ships the copy its release was built with.
+
+The shapes are kept in step by hand with `ChromeView` and `CatalogueEntry` in GPlatform
+Identity, which this public package cannot depend on.
+
+Part of [GHub-Packages](https://github.com/Gelhaus-Solutions/GHub-Packages), the packages
+the Gelhaus Solutions products share.

package/dist/catalogue.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A product's own name and marks, read from Identity's catalogue.
+ *
+ * The catalogue is where a product's name and mark live. A product reads its own
+ * here when it draws its top bar, its title and its favicon, so a rename or a new
+ * mark reaches every product without a release. Nothing here needs a token: a
+ * product's name and mark are on its own pages already.
+ *
+ * Two ways in. `catalogueMarkUrl` is an address that always leads to the current
+ * mark, for places that cannot ask first (a favicon link, an `<img>` in static
+ * markup). `createCatalogue` asks for the whole entry and keeps the last good
+ * answer, so an Identity outage leaves the name and mark a product last had
+ * rather than none.
+ *
+ * Off for a self-hosted install, as the controls are: such an install ships the
+ * copy its release was built with and asks nobody.
+ */
+import type { CatalogueEntry } from "./types.js";
+/** The address that always leads to a product's current mark. Redirects, briefly cached. */
+export declare function catalogueMarkUrl(baseUrl: string, slug: string, variant?: "colour" | "mono"): string;
+export interface CatalogueOptions {
+    /** Identity's public address, with or without a trailing slash. */
+    baseUrl: string;
+    fetch?: typeof fetch;
+    /** Milliseconds. A call that hangs must not hang a page render. */
+    timeoutMs?: number;
+    /** How long an entry is reused before asking again, in seconds. Identity caches it for a minute too. */
+    cacheSeconds?: number;
+    now?: () => number;
+}
+export interface Catalogue {
+    /**
+     * A product's entry. After a failed ask, the last good answer, however old;
+     * null only when there never was one or the product does not exist.
+     */
+    entry(slug: string): Promise<CatalogueEntry | null>;
+}
+export declare function createCatalogue(options: CatalogueOptions): Catalogue;
+//# sourceMappingURL=catalogue.d.ts.map

package/dist/catalogue.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * A product's own name and marks, read from Identity's catalogue.
+ *
+ * The catalogue is where a product's name and mark live. A product reads its own
+ * here when it draws its top bar, its title and its favicon, so a rename or a new
+ * mark reaches every product without a release. Nothing here needs a token: a
+ * product's name and mark are on its own pages already.
+ *
+ * Two ways in. `catalogueMarkUrl` is an address that always leads to the current
+ * mark, for places that cannot ask first (a favicon link, an `<img>` in static
+ * markup). `createCatalogue` asks for the whole entry and keeps the last good
+ * answer, so an Identity outage leaves the name and mark a product last had
+ * rather than none.
+ *
+ * Off for a self-hosted install, as the controls are: such an install ships the
+ * copy its release was built with and asks nobody.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catalogueMarkUrl = catalogueMarkUrl;
+exports.createCatalogue = createCatalogue;
+const validate_js_1 = require("./validate.js");
+/** The address that always leads to a product's current mark. Redirects, briefly cached. */
+function catalogueMarkUrl(baseUrl, slug, variant = "colour") {
+    const base = baseUrl.replace(/\/+$/u, "");
+    return `${base}/api/v1/catalogue/${encodeURIComponent(slug)}/icon${variant === "mono" ? "/mono" : ""}`;
+}
+const DEFAULT_TIMEOUT_MS = 3000;
+const DEFAULT_CACHE_SECONDS = 60;
+function createCatalogue(options) {
+    const base = options.baseUrl.replace(/\/+$/u, "");
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const ttlMs = (options.cacheSeconds ?? DEFAULT_CACHE_SECONDS) * 1000;
+    const held = new Map();
+    async function ask(slug) {
+        const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const response = await send(`${base}/api/v1/catalogue/${encodeURIComponent(slug)}`, {
+                method: "GET",
+                headers: { accept: "application/json" },
+                credentials: "omit",
+                signal: controller.signal,
+            });
+            if (response.status === 404)
+                return null;
+            if (!response.ok)
+                throw new Error(`Identity answered ${String(response.status)}`);
+            const entry = (0, validate_js_1.parseCatalogueEntry)(await response.json());
+            if (entry === null)
+                throw new Error("Identity's answer was not understood");
+            return entry;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        async entry(slug) {
+            const last = held.get(slug);
+            if (last !== undefined && now() - last.at < ttlMs)
+                return last.entry;
+            try {
+                const entry = await ask(slug);
+                held.set(slug, { entry, at: now() });
+                return entry;
+            }
+            catch {
+                // The name and mark it last had, rather than none.
+                return last?.entry ?? null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=catalogue.js.map

package/dist/core.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The browser half: what the header controls know, and what they keep.
+ *
+ * It owns no markup. The apps picker and the account popup draw from `state()`
+ * and ask it to `load()`, which is what keeps one fetch, one cache and one
+ * failure story behind both controls.
+ *
+ * **Off unless enabled, and off means silent.** Nothing is fetched, nothing is
+ * read from storage and nothing is written, so a self-hosted installation that
+ * never sets `enabled` makes no call to anybody.
+ *
+ * **A cached list paints at once.** The last answer is drawn while a fresh one is
+ * fetched, and kept if the fetch fails, marked `stale`. It is thirty days old at
+ * most and is checked as hard as a fresh answer, because storage is something
+ * anybody on the device can write.
+ *
+ * **The product's own route is the personal half.** The product's server holds the
+ * secret token and says who is signed in; this only ever calls that route, same
+ * origin, with the page's own cookie. The public key, if one is given, fetches
+ * the lower group straight from Identity so it can paint before the product has
+ * answered, and nothing more.
+ */
+import type { ChromeView } from "./types.js";
+export type ChromeStatus = "off" | "idle" | "loading" | "ready" | "stale" | "error";
+export interface ChromeState {
+    status: ChromeStatus;
+    view: ChromeView | null;
+    /** When `view` was last confirmed by Identity, in milliseconds since the epoch, or null. */
+    updatedAt: number | null;
+    /** Why the last refresh failed, short and for a quiet line rather than for a person. */
+    error: string | null;
+}
+/** The three calls a storage needs, which `localStorage` and `sessionStorage` both have. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export declare const CACHE_KEY = "gpid.chrome.v1";
+/** A list older than this is not drawn, however the fetch fares. */
+export declare const CACHE_MAX_AGE_MS: number;
+export declare const DEFAULT_TIMEOUT_MS = 5000;
+export interface ChromeCoreOptions {
+    /** Nothing happens unless this is exactly `true`. */
+    enabled?: boolean;
+    /** The product's own route for the personal half, same origin. */
+    endpoint?: string;
+    /** Identity's address and this product's public key, for the lower group alone. */
+    baseUrl?: string;
+    publicKey?: string;
+    /** Where the last answer is kept. None means it is not kept. */
+    storage?: StorageLike | null;
+    cacheKey?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+}
+export interface ChromeCore {
+    state(): ChromeState;
+    subscribe(listener: (state: ChromeState) => void): () => void;
+    /** Fetch, update the cache and the state, and resolve with the state. Concurrent calls share one fetch. */
+    load(): Promise<ChromeState>;
+    /** Forget the cached list. A product calls it on sign-out, so a shared device never shows the next person the last one's products. */
+    clear(): void;
+    /** Stop: abort what is in flight and ignore what arrives. */
+    dispose(): void;
+}
+export declare function createChromeCore(options?: ChromeCoreOptions): ChromeCore;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * The browser half: what the header controls know, and what they keep.
+ *
+ * It owns no markup. The apps picker and the account popup draw from `state()`
+ * and ask it to `load()`, which is what keeps one fetch, one cache and one
+ * failure story behind both controls.
+ *
+ * **Off unless enabled, and off means silent.** Nothing is fetched, nothing is
+ * read from storage and nothing is written, so a self-hosted installation that
+ * never sets `enabled` makes no call to anybody.
+ *
+ * **A cached list paints at once.** The last answer is drawn while a fresh one is
+ * fetched, and kept if the fetch fails, marked `stale`. It is thirty days old at
+ * most and is checked as hard as a fresh answer, because storage is something
+ * anybody on the device can write.
+ *
+ * **The product's own route is the personal half.** The product's server holds the
+ * secret token and says who is signed in; this only ever calls that route, same
+ * origin, with the page's own cookie. The public key, if one is given, fetches
+ * the lower group straight from Identity so it can paint before the product has
+ * answered, and nothing more.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUT_MS = exports.CACHE_MAX_AGE_MS = exports.CACHE_KEY = void 0;
+exports.createChromeCore = createChromeCore;
+const validate_js_1 = require("./validate.js");
+exports.CACHE_KEY = "gpid.chrome.v1";
+/** A list older than this is not drawn, however the fetch fares. */
+exports.CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+exports.DEFAULT_TIMEOUT_MS = 5000;
+const NO_PERSON = { hasIdentity: false, avatarUrl: null };
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createChromeCore(options = {}) {
+    const enabled = options.enabled === true;
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    const storage = options.storage ?? null;
+    const cacheKey = options.cacheKey ?? exports.CACHE_KEY;
+    let state = {
+        status: enabled ? "idle" : "off",
+        view: null,
+        updatedAt: null,
+        error: null,
+    };
+    const listeners = new Set();
+    let inFlight = null;
+    let controller = null;
+    let disposed = false;
+    function set(next) {
+        if (disposed)
+            return;
+        state = { ...state, ...next };
+        for (const listener of [...listeners]) {
+            try {
+                listener(state);
+            }
+            catch {
+                // One listener's fault is not another's.
+            }
+        }
+    }
+    function readCache() {
+        if (storage === null)
+            return null;
+        try {
+            const raw = storage.getItem(cacheKey);
+            if (raw === null)
+                return null;
+            const parsed = JSON.parse(raw);
+            if (!isRecord(parsed) || typeof parsed["savedAt"] !== "number")
+                return null;
+            const savedAt = parsed["savedAt"];
+            // Too old, or dated in the future, which only somebody editing it would do.
+            if (now() - savedAt > exports.CACHE_MAX_AGE_MS || savedAt > now() + 60_000)
+                return null;
+            const view = (0, validate_js_1.parseView)(parsed["view"]);
+            return view === null ? null : { view, savedAt };
+        }
+        catch {
+            return null;
+        }
+    }
+    function writeCache(view, savedAt) {
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(cacheKey, JSON.stringify({ v: 1, savedAt, view }));
+        }
+        catch {
+            // Full, blocked or private: the controls work without it.
+        }
+    }
+    async function getJson(url, init, signal) {
+        const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+        const response = await send(url, { ...init, signal });
+        if (!response.ok)
+            throw new Error(`status ${String(response.status)}`);
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new Error("invalid answer");
+        }
+    }
+    async function fetchPersonal(endpoint, signal) {
+        const body = await getJson(endpoint, { method: "GET", headers: { accept: "application/json" }, credentials: "same-origin" }, signal);
+        const view = (0, validate_js_1.parseView)(body);
+        if (view === null)
+            throw new Error("invalid answer");
+        return view;
+    }
+    async function fetchPublic(baseUrl, key, signal) {
+        const url = `${baseUrl.replace(/\/+$/u, "")}/api/v1/chrome/public`;
+        const body = await getJson(url, {
+            method: "GET",
+            headers: { accept: "application/json", "x-gpid-key": key },
+            credentials: "omit",
+        }, signal);
+        const view = (0, validate_js_1.parsePublicView)(body);
+        if (view === null)
+            throw new Error("invalid answer");
+        return view;
+    }
+    function reasonOf(error, timedOut) {
+        if (timedOut)
+            return "timeout";
+        if (error instanceof Error && /^(status \d+|invalid answer)$/u.test(error.message))
+            return error.message;
+        return "network";
+    }
+    async function run() {
+        const cached = readCache();
+        set({
+            status: "loading",
+            view: cached?.view ?? state.view,
+            updatedAt: cached?.savedAt ?? state.updatedAt,
+            error: null,
+        });
+        const own = new AbortController();
+        controller = own;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            own.abort();
+        }, timeoutMs);
+        try {
+            const personalCall = options.endpoint === undefined
+                ? Promise.resolve(null)
+                : fetchPersonal(options.endpoint, own.signal);
+            const publicCall = options.baseUrl === undefined || options.publicKey === undefined
+                ? Promise.resolve(null)
+                : fetchPublic(options.baseUrl, options.publicKey, own.signal);
+            // The lower group paints as soon as it is back, when nothing else is on screen yet.
+            void publicCall
+                .then((pub) => {
+                if (pub !== null && state.status === "loading" && state.view === null) {
+                    set({ view: { person: NO_PERSON, yours: [], more: pub.more, legal: pub.legal } });
+                }
+            })
+                .catch(() => undefined);
+            const [personal, pub] = await Promise.allSettled([personalCall, publicCall]);
+            const publicHalf = pub.status === "fulfilled" ? pub.value : null;
+            if (personal.status === "fulfilled" && personal.value !== null) {
+                const at = now();
+                writeCache(personal.value, at);
+                set({ status: "ready", view: personal.value, updatedAt: at, error: null });
+                return state;
+            }
+            if (personal.status === "fulfilled" && publicHalf !== null) {
+                // No personal route configured: the public group is the whole answer.
+                set({
+                    status: "ready",
+                    view: { person: NO_PERSON, yours: [], ...publicHalf },
+                    updatedAt: now(),
+                    error: null,
+                });
+                return state;
+            }
+            const error = personal.status === "rejected" ? reasonOf(personal.reason, timedOut) : "not configured";
+            if (cached !== null) {
+                set({ status: "stale", view: cached.view, updatedAt: cached.savedAt, error });
+            }
+            else if (publicHalf !== null) {
+                set({
+                    status: "error",
+                    view: { person: NO_PERSON, yours: [], ...publicHalf },
+                    updatedAt: null,
+                    error,
+                });
+            }
+            else {
+                set({ status: "error", view: null, updatedAt: null, error });
+            }
+            return state;
+        }
+        finally {
+            clearTimeout(timer);
+            if (controller === own)
+                controller = null;
+        }
+    }
+    return {
+        state: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        load() {
+            if (!enabled || disposed)
+                return Promise.resolve(state);
+            inFlight ??= run().finally(() => {
+                inFlight = null;
+            });
+            return inFlight;
+        },
+        clear() {
+            if (storage !== null) {
+                try {
+                    storage.removeItem(cacheKey);
+                }
+                catch {
+                    // Nothing to forget that could be read.
+                }
+            }
+            if (enabled)
+                set({ status: "idle", view: null, updatedAt: null, error: null });
+        },
+        dispose() {
+            disposed = true;
+            controller?.abort();
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @ghub/identity-chrome
+ *
+ * The shared header controls of the Gelhaus Solutions products. This entry is the
+ * browser half: state, cache and the last list held for an outage. The server
+ * half, with the token, is `@ghub/identity-chrome/server`.
+ */
+export { CACHE_KEY, CACHE_MAX_AGE_MS, DEFAULT_TIMEOUT_MS, createChromeCore, type ChromeCore, type ChromeCoreOptions, type ChromeState, type ChromeStatus, type StorageLike, } from "./core.js";
+export { catalogueMarkUrl, createCatalogue, type Catalogue, type CatalogueOptions, } from "./catalogue.js";
+export type { CatalogueEntry, ChromeLegal, ChromePerson, ChromePublicView, ChromeTile, ChromeView, } from "./types.js";
+export { safeUrl } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * @ghub/identity-chrome
+ *
+ * The shared header controls of the Gelhaus Solutions products. This entry is the
+ * browser half: state, cache and the last list held for an outage. The server
+ * half, with the token, is `@ghub/identity-chrome/server`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeUrl = exports.createCatalogue = exports.catalogueMarkUrl = exports.createChromeCore = exports.DEFAULT_TIMEOUT_MS = exports.CACHE_MAX_AGE_MS = exports.CACHE_KEY = void 0;
+var core_js_1 = require("./core.js");
+Object.defineProperty(exports, "CACHE_KEY", { enumerable: true, get: function () { return core_js_1.CACHE_KEY; } });
+Object.defineProperty(exports, "CACHE_MAX_AGE_MS", { enumerable: true, get: function () { return core_js_1.CACHE_MAX_AGE_MS; } });
+Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return core_js_1.DEFAULT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "createChromeCore", { enumerable: true, get: function () { return core_js_1.createChromeCore; } });
+var catalogue_js_1 = require("./catalogue.js");
+Object.defineProperty(exports, "catalogueMarkUrl", { enumerable: true, get: function () { return catalogue_js_1.catalogueMarkUrl; } });
+Object.defineProperty(exports, "createCatalogue", { enumerable: true, get: function () { return catalogue_js_1.createCatalogue; } });
+var validate_js_1 = require("./validate.js");
+Object.defineProperty(exports, "safeUrl", { enumerable: true, get: function () { return validate_js_1.safeUrl; } });
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The server half: a product's own server speaking to Identity for the header
+ * controls.
+ *
+ * The secret token lives here and nowhere near a browser. The page asks the
+ * product's own route; that route knows who is signed in, from the product's own
+ * session, and asks Identity about that one person by verified email. Identity
+ * answers with the products they have and the public ones they do not.
+ *
+ * **Say only who is signed in, and only what the product has verified.** The
+ * address goes to Identity as the thing the person's products are joined on, so
+ * an address the product has not verified is a way to ask about somebody else.
+ *
+ * **Never log the token, and never put it in an error.** Everything thrown here
+ * says what happened and nothing about what was sent.
+ */
+import type { ChromeView } from "./types.js";
+/** A refusal or a failure from Identity, with how long to wait when it said. */
+export declare class ChromeError extends Error {
+    readonly status: number;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(status: number, message: string, retryAfterSeconds?: number | undefined);
+}
+export interface ChromeServerOptions {
+    /** Identity's public address, with or without a trailing slash. */
+    baseUrl: string;
+    /** This product's slug in the catalogue. */
+    product: string;
+    /** The secret token staff issued for this product. Never sent to a browser. */
+    token: string;
+    fetch?: typeof fetch;
+    /** Milliseconds. A call that hangs must not hang a page render. */
+    timeoutMs?: number;
+    /** How long one person's answer is reused, in seconds. Zero asks every time. */
+    viewCacheSeconds?: number;
+    now?: () => number;
+}
+export interface ChromeServer {
+    /** The products of the person signed in, as Identity knows them. Counts as a visit to this product. */
+    view(email: string): Promise<ChromeView>;
+    /** The one-off push of this product's users, inside the window staff opened. Batched for you. */
+    seed(emails: readonly string[]): Promise<{
+        changed: number;
+    }>;
+    /** Say these people no longer have access to this product. */
+    remove(emails: readonly string[]): Promise<{
+        changed: number;
+    }>;
+    /** Drop what is held for one person, on sign-out. */
+    forget(email: string): void;
+    /**
+     * A route for any framework that speaks the web `Request` and `Response`
+     * (Next route handlers, Hono, Bun, Deno, Cloudflare). `who` says who is
+     * signed in, from the product's own session, or null for nobody.
+     */
+    handler(who: (request: Request) => Promise<{
+        email: string;
+    } | null> | {
+        email: string;
+    } | null): (request: Request) => Promise<Response>;
+}
+/** One request to Identity carries at most this many addresses. */
+export declare const BATCH = 1000;
+export declare function createChromeServer(options: ChromeServerOptions): ChromeServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * The server half: a product's own server speaking to Identity for the header
+ * controls.
+ *
+ * The secret token lives here and nowhere near a browser. The page asks the
+ * product's own route; that route knows who is signed in, from the product's own
+ * session, and asks Identity about that one person by verified email. Identity
+ * answers with the products they have and the public ones they do not.
+ *
+ * **Say only who is signed in, and only what the product has verified.** The
+ * address goes to Identity as the thing the person's products are joined on, so
+ * an address the product has not verified is a way to ask about somebody else.
+ *
+ * **Never log the token, and never put it in an error.** Everything thrown here
+ * says what happened and nothing about what was sent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BATCH = exports.ChromeError = void 0;
+exports.createChromeServer = createChromeServer;
+const validate_js_1 = require("./validate.js");
+/** A refusal or a failure from Identity, with how long to wait when it said. */
+class ChromeError extends Error {
+    status;
+    retryAfterSeconds;
+    constructor(status, message, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "ChromeError";
+    }
+}
+exports.ChromeError = ChromeError;
+/** One request to Identity carries at most this many addresses. */
+exports.BATCH = 1000;
+const MAX_HELD = 500;
+const DEFAULT_TIMEOUT_MS = 4000;
+const DEFAULT_CACHE_SECONDS = 60;
+function createChromeServer(options) {
+    const base = options.baseUrl.replace(/\/+$/u, "");
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const ttlMs = (options.viewCacheSeconds ?? DEFAULT_CACHE_SECONDS) * 1000;
+    const held = new Map();
+    const key = (email) => email.trim().normalize("NFC").toLowerCase();
+    async function call(method, path, body) {
+        const send = options.fetch ?? globalThis.fetch.bind(globalThis);
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        let response;
+        try {
+            response = await send(`${base}${path}`, {
+                method,
+                headers: {
+                    accept: "application/json",
+                    "content-type": "application/json",
+                    "x-gpid-product": options.product,
+                    authorization: `Bearer ${options.token}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch {
+            throw new ChromeError(0, "Identity could not be reached");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const retry = Number(response.headers.get("retry-after"));
+            throw new ChromeError(response.status, `Identity answered ${String(response.status)}`, Number.isFinite(retry) && retry > 0 ? retry : undefined);
+        }
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new ChromeError(502, "Identity's answer was not understood");
+        }
+    }
+    async function batched(method, emails) {
+        let changed = 0;
+        for (let start = 0; start < emails.length; start += exports.BATCH) {
+            const answer = await call(method, "/api/v1/chrome/access", {
+                emails: emails.slice(start, start + exports.BATCH),
+            });
+            const count = answer.changed;
+            changed += typeof count === "number" ? count : 0;
+        }
+        return { changed };
+    }
+    const server = {
+        async view(email) {
+            const id = key(email);
+            const reuse = held.get(id);
+            if (reuse !== undefined && now() - reuse.at < ttlMs)
+                return reuse.view;
+            const view = (0, validate_js_1.parseView)(await call("POST", "/api/v1/chrome/view", { email }));
+            if (view === null)
+                throw new ChromeError(502, "Identity's answer was not understood");
+            // Newest last, so the oldest is the one to go when the table is full.
+            held.delete(id);
+            held.set(id, { view, at: now() });
+            if (held.size > MAX_HELD) {
+                const oldest = held.keys().next().value;
+                if (oldest !== undefined)
+                    held.delete(oldest);
+            }
+            return view;
+        },
+        seed: (emails) => batched("PUT", emails),
+        remove: (emails) => batched("DELETE", emails),
+        forget(email) {
+            held.delete(key(email));
+        },
+        handler(who) {
+            return async (request) => {
+                const json = (status, body, headers = {}) => new Response(JSON.stringify(body), {
+                    status,
+                    headers: {
+                        "content-type": "application/json",
+                        "cache-control": "private, no-store",
+                        ...headers,
+                    },
+                });
+                if (request.method !== "GET")
+                    return json(405, { error: "method not allowed" }, { allow: "GET" });
+                const person = await who(request);
+                if (person === null)
+                    return json(401, { error: "not signed in" });
+                try {
+                    return json(200, await server.view(person.email));
+                }
+                catch (error) {
+                    // Whatever went wrong, the page keeps the list it held. Nothing about why leaves here.
+                    const wait = error instanceof ChromeError && error.status === 429
+                        ? (error.retryAfterSeconds ?? 60)
+                        : 30;
+                    return json(503, { error: "unavailable" }, { "retry-after": String(wait) });
+                }
+            };
+        },
+    };
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What the header controls are told. These are the shapes GPlatform Identity
+ * answers with, kept in step by hand with `ChromeView` there: this package is
+ * public and cannot depend on that one, so a change to either is a change to
+ * both.
+ */
+/** One tile in the apps picker. */
+export interface ChromeTile {
+    slug: string;
+    displayName: string;
+    /** Where the tile goes. Only ever an http or https address: anything else is dropped on arrival. */
+    homeUrl: string;
+    /** Identity's address for the icon, or null until one is uploaded. */
+    iconUrl: string | null;
+    /** Whether this is the product the person is in. */
+    current: boolean;
+}
+/** What the person's own Identity adds to the account popup. Never a name: the product shows its own. */
+export interface ChromePerson {
+    hasIdentity: boolean;
+    avatarUrl: string | null;
+}
+/**
+ * The account popup's two footer links, the same in every product. Identity sends
+ * them, so a moved address needs no new release of this package. Null when they
+ * were not sent or either is not a web address, and then the footer is not drawn.
+ */
+export interface ChromeLegal {
+    termsUrl: string;
+    privacyUrl: string;
+}
+/** The person, the products they have, the public ones they do not, and the footer. */
+export interface ChromeView {
+    person: ChromePerson;
+    yours: ChromeTile[];
+    more: ChromeTile[];
+    legal: ChromeLegal | null;
+}
+/** The public half alone, for painting the lower group before the personal one arrives. */
+export interface ChromePublicView {
+    more: ChromeTile[];
+    legal: ChromeLegal | null;
+}
+/**
+ * A product's name and marks as Identity keeps them: the one place they live, so
+ * a product reads its own here for its top bar, title and favicon, and a rename or
+ * a new mark reaches every product without a release.
+ */
+export interface CatalogueEntry {
+    slug: string;
+    displayName: string;
+    homeUrl: string;
+    /** The colour mark, at an address that never changes its file. Null until one is uploaded. */
+    iconUrl: string | null;
+    /** The one colour mark, the same way. */
+    monoIconUrl: string | null;
+    /** When the entry or a mark last changed, ISO. */
+    updatedAt: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * What the header controls are told. These are the shapes GPlatform Identity
+ * answers with, kept in step by hand with `ChromeView` there: this package is
+ * public and cannot depend on that one, so a change to either is a change to
+ * both.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/validate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What is believed about an answer before it is drawn.
+ *
+ * A tile's address becomes a link on every page of every product that mounts the
+ * controls, and an icon's address becomes an image source. Both come over the
+ * network, from a service that is trusted and not infallible, so the shape is
+ * checked and an address with any scheme but http or https is **dropped, not
+ * repaired**: a `javascript:` link is script on the host's page, and a tile that
+ * goes nowhere is a smaller fault than that.
+ *
+ * Applied to the cached copy as well as to a fresh answer, because the cache is
+ * storage anybody on the device can write.
+ */
+import type { CatalogueEntry, ChromePublicView, ChromeView } from "./types.js";
+/** An absolute http or https address, or null. */
+export declare function safeUrl(value: unknown): string | null;
+/** A view that can be drawn, or null where the answer is not one. */
+export declare function parseView(value: unknown): ChromeView | null;
+export declare function parsePublicView(value: unknown): ChromePublicView | null;
+/** A catalogue entry that can be drawn, or null where the answer is not one. */
+export declare function parseCatalogueEntry(value: unknown): CatalogueEntry | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * What is believed about an answer before it is drawn.
+ *
+ * A tile's address becomes a link on every page of every product that mounts the
+ * controls, and an icon's address becomes an image source. Both come over the
+ * network, from a service that is trusted and not infallible, so the shape is
+ * checked and an address with any scheme but http or https is **dropped, not
+ * repaired**: a `javascript:` link is script on the host's page, and a tile that
+ * goes nowhere is a smaller fault than that.
+ *
+ * Applied to the cached copy as well as to a fresh answer, because the cache is
+ * storage anybody on the device can write.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeUrl = safeUrl;
+exports.parseView = parseView;
+exports.parsePublicView = parsePublicView;
+exports.parseCatalogueEntry = parseCatalogueEntry;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** An absolute http or https address, or null. */
+function safeUrl(value) {
+    if (typeof value !== "string" || value.length > 2048)
+        return null;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:" ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tileOf(value) {
+    if (!isRecord(value))
+        return null;
+    const { slug, displayName, homeUrl, iconUrl, current } = value;
+    if (typeof slug !== "string" ||
+        slug === "" ||
+        typeof displayName !== "string" ||
+        displayName === "") {
+        return null;
+    }
+    const href = safeUrl(homeUrl);
+    if (href === null)
+        return null;
+    return {
+        slug,
+        displayName,
+        homeUrl: href,
+        iconUrl: iconUrl === null || iconUrl === undefined ? null : safeUrl(iconUrl),
+        current: current === true,
+    };
+}
+function tilesOf(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.map(tileOf).filter((tile) => tile !== null);
+}
+/**
+ * Both footer links, or null. Missing is not a broken answer: an older Identity or
+ * an older cached copy has none, and the popup draws no footer rather than nothing.
+ */
+function legalOf(value) {
+    if (!isRecord(value))
+        return null;
+    const termsUrl = safeUrl(value["termsUrl"]);
+    const privacyUrl = safeUrl(value["privacyUrl"]);
+    return termsUrl === null || privacyUrl === null ? null : { termsUrl, privacyUrl };
+}
+/** A view that can be drawn, or null where the answer is not one. */
+function parseView(value) {
+    if (!isRecord(value) || !isRecord(value["person"]))
+        return null;
+    const person = value["person"];
+    const yours = tilesOf(value["yours"]);
+    const more = tilesOf(value["more"]);
+    if (yours === null || more === null)
+        return null;
+    if (typeof person["hasIdentity"] !== "boolean")
+        return null;
+    const avatar = person["avatarUrl"];
+    return {
+        person: {
+            hasIdentity: person["hasIdentity"],
+            avatarUrl: avatar === null || avatar === undefined ? null : safeUrl(avatar),
+        },
+        yours,
+        more,
+        legal: legalOf(value["legal"]),
+    };
+}
+function parsePublicView(value) {
+    if (!isRecord(value))
+        return null;
+    const more = tilesOf(value["more"]);
+    return more === null ? null : { more, legal: legalOf(value["legal"]) };
+}
+/** A catalogue entry that can be drawn, or null where the answer is not one. */
+function parseCatalogueEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const { slug, displayName, homeUrl, iconUrl, monoIconUrl, updatedAt } = value;
+    if (typeof slug !== "string" ||
+        slug === "" ||
+        typeof displayName !== "string" ||
+        displayName === "") {
+        return null;
+    }
+    const home = safeUrl(homeUrl);
+    if (home === null || typeof updatedAt !== "string")
+        return null;
+    return {
+        slug,
+        displayName,
+        homeUrl: home,
+        iconUrl: iconUrl === null || iconUrl === undefined ? null : safeUrl(iconUrl),
+        monoIconUrl: monoIconUrl === null || monoIconUrl === undefined ? null : safeUrl(monoIconUrl),
+        updatedAt,
+    };
+}
+//# sourceMappingURL=validate.js.map

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@ghub/identity-chrome",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The shared header controls of the Gelhaus Solutions products: the apps picker and the account popup. The browser half (state, cache, the last list held for an outage) and the server half (the token calls and a route handler). No dependencies.",
+  "author": "Gelhaus Solutions (Enno Gelhaus) <egelhaus@ennogelhaus.de> (https://ennogelhaus.de)",
+  "homepage": "https://ennogelhaus.de",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gelhaus-Solutions/GHub-Packages.git",
+    "directory": "packages/identity-chrome"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.7",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "lint": "eslint \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }