@ghub/identity-chrome 0.0.0-stage → 0.2.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,158 @@
-# 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. Two custom elements with shadow DOM (`<gp-apps>`, `<gp-account>`) and React
+wrappers for them; the browser half under both (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).
+
+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.
+
+## The two controls
+
+```ts
+import { createChromeCore, defineChromeElements } from "@ghub/identity-chrome";
+
+defineChromeElements(); // <gp-apps> and <gp-account>, each once; a no-op on a server
+
+const apps = document.querySelector("gp-apps")!;
+apps.core = chrome; // the core above: one fetch and one cache behind both
+
+const account = document.querySelector("gp-account")!;
+account.core = chrome;
+account.product = "GAdvisory"; // your own name, from your catalogue entry
+account.person = { name: user.name, email: user.email, id: user.id, avatarUrl: user.picture };
+account.organisations = [{ id: "org_1", name: "Hafen Labs", role: "admin", active: true }];
+account.onSwitch = async (id) => switchOrganisation(id); // reject when it did not switch
+account.onSignOut = async () => {
+  await signOut(); // reject when it failed: the popup says they are still signed in
+  location.assign("/"); // you navigate; as this resolves the element forgets the kept list
+};
+```
+
+Everything is a property, because a core, a person and a callback are objects. Each can be
+set before the element is defined. Neither control renders anything while the core is off,
+and the account popup renders nothing without a person.
+
+**The account popup shows mostly what the product passes**: the name and address from your
+session, your organisations with their roles (Owner, Admin or Member) and your two actions.
+Identity adds the picture, the colour of the initial, the links to its own account and set up
+screens and the footer, so the popup still signs somebody out while Identity is down. The
+picture is Identity's if the person has one, else yours, else a coloured initial whose tint
+Identity picks from its own id; for somebody with no Identity, pass your own stable user id as
+`id` and the same hash (`avatarTint`) picks it. Set `viaIdentity` once you sign in through
+Identity, and Sign out says it ends both. Sign out leaves this product only.
+
+Every word can be replaced through `labels`; the rest stay English.
+
+### In React
+
+```tsx
+import { GpAccount, GpApps } from "@ghub/identity-chrome/react";
+
+<GpApps core={chrome} />
+<GpAccount core={chrome} product="GAdvisory" person={person} organisations={orgs} onSwitch={switchTo} onSignOut={signOut} />
+```
+
+The wrappers define the elements and set the properties after mounting, so they render on a
+server as the bare tags. React 19 or newer, as an optional peer.
+
+### The host contract
+
+Shadow DOM: nothing reaches in and nothing leaks out but the custom properties a page
+declares on its root, which inherit into the shadow. The controls read the published
+`@ghub/tokens` names, so a page on `@ghub/tokens` is styled with no setup, and Aurora's frosted
+menu where the page is on Aurora:
+
+| Reads                                                                                                                                                                                                | For                                            |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `--ga-menu`, else `--gm-overlay`; `--ga-frost-menu`; `--ga-shadow-menu`, else `--gm-shadow-overlay`                                                                                                  | the picker's surface, its frost and its shadow |
+| `--ga-menu`, else `--gm-sunken`                                                                                                                                                                      | the account popup's tinted ground              |
+| `--ga-track`, else `--gm-overlay`                                                                                                                                                                    | the account popup's panels                     |
+| `--gm-plate`, `--gm-ink`, `--gm-ink-2`, `--gm-ink-3`, `--gm-hairline`, `--gm-control`, `--gm-hover`, `--gm-active`, `--gm-selected`, `--gm-accent`, `--gm-accent-text`, `--gm-ring`, `--gm-crit-ink` | everything else                                |
+| `--font-sans`                                                                                                                                                                                        | the face                                       |
+
+A page that declares none of them gets modern light, or modern dark under
+`prefers-color-scheme: dark`. There is no second accent: the controls take the page's. Both
+follow reduced motion, reduced transparency and forced colours, and below 600 wide each is a
+modal bottom sheet. `part="trigger"` and `part="popup"` are there for placement only.
+
+## 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