@ghub/gopencsr-client 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/dist/canonical.d.ts

@@ -0,0 +1,9 @@
+/**
+ * RFC 8785 canonical JSON (JCS), as @gopencsr/contracts writes it: one value always has one
+ * serialisation, so a registry computes the same change hash GOpenCSR's signing step shows and
+ * signs. Object keys are sorted by UTF-16 code units, which is how JavaScript compares strings;
+ * strings and numbers are written as ECMAScript's JSON.stringify writes them, which is what RFC
+ * 8785 specifies.
+ */
+export declare function canonicalJson(value: unknown): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = canonicalJson;
+/**
+ * RFC 8785 canonical JSON (JCS), as @gopencsr/contracts writes it: one value always has one
+ * serialisation, so a registry computes the same change hash GOpenCSR's signing step shows and
+ * signs. Object keys are sorted by UTF-16 code units, which is how JavaScript compares strings;
+ * strings and numbers are written as ECMAScript's JSON.stringify writes them, which is what RFC
+ * 8785 specifies.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("canonical JSON has no form for a non-finite number");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object") {
+        // A plain object only. A Date, a Buffer or a Decimal would be written through its own
+        // members here, while JSON.stringify and a jsonb column go through its toJSON: the log and
+        // the database would then hold two different bodies.
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            const kind = value.constructor?.name;
+            throw new Error(`canonical JSON has no form for a ${kind ?? "non-plain object"}`);
+        }
+        const members = Object.entries(value)
+            .filter(([, member]) => member !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${members.map(([key, member]) => `${JSON.stringify(key)}:${canonicalJson(member)}`).join(",")}}`;
+    }
+    throw new Error(`canonical JSON has no form for a ${typeof value}`);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/client.d.ts

@@ -0,0 +1,218 @@
+/** GOpenCSR could not be asked: unreachable, too slow, or failing on its side. */
+export declare class CsrUnavailable extends Error {
+    readonly name = "CsrUnavailable";
+}
+/** GOpenCSR answered, and refused: what it said, for the log and the audit record. */
+export declare class CsrRefused extends Error {
+    readonly status: number;
+    readonly reason: string;
+    readonly name = "CsrRefused";
+    constructor(status: number, reason: string);
+}
+/** What GOpenCSR's tokens say when the sign-in was a passkey (GOPENCSR-15). */
+export declare const ACR_PASSKEY = "urn:gopencsr:acr:passkey";
+/** What a registry asks GOpenCSR to tell it: who, their address and name, and their passkeys. */
+export declare const SCOPE = "openid email profile roles";
+/** The registries GOpenCSR signs changes for; every change hash names its own. */
+export type Product = "cdr" | "cnr" | "csr";
+/** The person as GOpenCSR's ID token describes them, checked. */
+export interface Identity {
+    /** GOpenCSR's subject, the person's account id in every registry. */
+    sub: string;
+    acr: string;
+    /** When the person last signed in at GOpenCSR, by `acr`. */
+    authTime: Date;
+    /** GOpenCSR's grant. */
+    sid: string | null;
+    email: string | null;
+    emailVerified: boolean;
+    name: string | null;
+    /** How many passkeys the account holds at GOpenCSR, or null when the token did not say. */
+    passkeys: number | null;
+    /**
+     * The person's standing with the registry's documents, which GOpenCSR states in every token for
+     * the registry to enforce (consent per product): agreed; asked, with the date the version they
+     * have not accepted takes effect; restricted, allowed to sign in, read, export and use their
+     * data-protection rights and nothing else; null when the token said nothing.
+     */
+    terms: {
+        state: string;
+        inForceFrom: Date | null;
+    } | null;
+}
+/** A token response, its ID token checked. */
+export interface CsrTokens {
+    refreshToken: string;
+    accessExpiresAt: Date;
+    identity: Identity;
+}
+/** A change as GOpenCSR's signing step shows it (GOPENCSR-17). */
+export interface ChangeDocument {
+    type: string;
+    object: string;
+    description: string;
+    changes: {
+        label: string;
+        before: string | null;
+        after: string | null;
+    }[];
+    detail?: Record<string, unknown>;
+}
+/** A signing request as GOpenCSR reads it back to the client that made it. */
+export interface SigningState {
+    id: string;
+    status: "open" | "signed" | "declined" | "moved" | "expired";
+    account: string;
+    hash: string;
+    signaturesRequired: number;
+    signatures: {
+        passkey: string;
+        signedAt: string;
+        receipt: string;
+    }[];
+}
+/**
+ * An entry of the one log as a registry delivers it (GOPENCSR-44): the registry's own id and time
+ * for it, a kind with the registry's prefix (cnr.change.signed), and the public body, ids and
+ * hashes only.
+ */
+export interface TlogEntry {
+    id: string;
+    kind: string;
+    /** As toISOString() writes it. */
+    time: string;
+    body: Record<string, unknown>;
+}
+/** An entry as the one log holds it: its leaf byte for byte and, once appended, its index. */
+export interface TlogEntryState {
+    id: string;
+    kind: string;
+    time: string;
+    leaf: string;
+    index: number | null;
+    appendedAt: string | null;
+}
+/** One passkey's signature, as GOpenCSR's receipt states it, checked. */
+export interface Receipt {
+    passkey: string;
+    hash: string;
+}
+/**
+ * The SHA-256 GOpenCSR's signing step commits to, in hex: the change's canonical form with the
+ * registry's product added, as GOpenCSR computes it.
+ */
+export declare function changeHash(product: Product, change: ChangeDocument): string;
+/** How a registry is GOpenCSR's client. */
+export interface CsrClientOptions {
+    /** GOpenCSR's issuer, the origin people sign in at, such as https://csr.gplatform.org. */
+    issuer: string;
+    /**
+     * Where the registry's own calls to GOpenCSR go, when not the issuer: a direct link between
+     * the hosts. The browser always goes to the issuer.
+     */
+    endpoints?: string | undefined;
+    clientId: string;
+    /** Where GOpenCSR sends the browser back, one of the client's registered redirect URIs. */
+    redirectUri: string;
+    /** The registry this client is, which every change hash names. */
+    product: Product;
+    /**
+     * The client secret, asked for at each authenticated call: the registry keeps it where its
+     * secrets are (Vault KV) and reads it again as often as it likes, so a new one takes without a
+     * restart.
+     */
+    clientSecret: () => Promise<string>;
+    /** The scope asked for; SCOPE when left out. */
+    scope?: string;
+    /** The tests' own fetch and clock. */
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * A registry as GOpenCSR's client (GOPENCDR-333, extracted from GOpenCDR's api for every
+ * registry): the authorisation code flow with PKCE for sign-in and step-up, refresh and revocation
+ * of the tokens a session holds, the signing step that a change asks one or two passkeys through,
+ * and the delivery of the registry's entries to the one log. Every token is checked against GOpenCSR's published keys (EdDSA), which are read again
+ * for a key id not seen yet. Sessions, accounts and what a person may do stay the registry's own.
+ */
+export declare class CsrClient {
+    private readonly options;
+    private keys;
+    private readonly fetch;
+    private readonly now;
+    constructor(options: CsrClientOptions);
+    /** GOpenCSR's issuer, the origin people sign in at. */
+    get issuer(): string;
+    /** The authorisation request a browser takes to GOpenCSR. */
+    authorizeUrl(request: {
+        state: string;
+        nonce: string;
+        challenge: string;
+        /** For a step-up: a sign-in older than this many seconds is asked for again. */
+        maxAge?: number;
+    }): string;
+    /** The code GOpenCSR sent back, for tokens. The ID token must carry the nonce sent. */
+    exchange(code: string, verifier: string, nonce: string): Promise<CsrTokens>;
+    /**
+     * New tokens for a refresh token, which GOpenCSR replaces at each use; null when it refuses,
+     * because the person signed out there or the grant was revoked.
+     */
+    refresh(refreshToken: string): Promise<CsrTokens | null>;
+    /** Revokes a refresh token, and with it GOpenCSR's grant (RFC 7009). */
+    revoke(refreshToken: string): Promise<void>;
+    /**
+     * Asks GOpenCSR for the person's signature over a change (GOPENCSR-17), and checks that the
+     * hash it will show and sign is the one the registry computed.
+     */
+    requestSignature(request: {
+        account: string;
+        change: ChangeDocument;
+        returnUri: string;
+        signatures: 1 | 2;
+    }): Promise<{
+        id: string;
+        url: string;
+        hash: string;
+        expiresAt: string;
+    }>;
+    /** A signing request this client made, as GOpenCSR reads it back; null if it knows none. */
+    signingRequest(id: string): Promise<SigningState | null>;
+    /** Withdraws an open signing request whose change moved on: nothing can sign it any more. */
+    withdrawSignature(id: string): Promise<void>;
+    /**
+     * A signature's receipt, checked: GOpenCSR's key, its type, made for this client and account,
+     * over this request; null for any receipt that is not all of those.
+     */
+    receipt(token: string, expect: {
+        account: string;
+        request: string;
+    }): Promise<Receipt | null>;
+    private tokensOf;
+    /** The ID token's claims, checked (OpenID Connect Core 3.1.3.7), or null. */
+    private identityOf;
+    /**
+     * The claims of a compact JWS GOpenCSR signed, typed `typ`, or null for any that is not one.
+     * Times and audience are the caller's to check.
+     */
+    private verifyJws;
+    private publicKeys;
+    /**
+     * Delivers entries to the one log (GOPENCSR-44), at least once: an id delivered again with the
+     * same leaf is the same entry, and with another it is refused. Each comes back as the log holds
+     * it, its leaf checked to be the one this registry wrote (the canonical JSON of id, kind, time
+     * and body), with its index once the appender added it, which is soon but not at once.
+     */
+    deliverEntries(entries: TlogEntry[]): Promise<TlogEntryState[]>;
+    /** An entry of the one log as GOpenCSR holds it, by its id; null if it holds none. */
+    tlogEntry(id: string): Promise<TlogEntryState | null>;
+    private tokenCall;
+    /** client_secret_basic (RFC 6749 2.3.1): the id and the secret, each form-encoded. */
+    private authorization;
+    /**
+     * One call to GOpenCSR's api, authenticated as the registry's client unless `anonymous`. A
+     * refusal (4xx) throws CsrRefused; anything that kept an answer from coming (the network, a
+     * timeout, a 5xx) throws CsrUnavailable, which the caller does not take as a refusal.
+     */
+    private call;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsrClient = exports.SCOPE = exports.ACR_PASSKEY = exports.CsrRefused = exports.CsrUnavailable = void 0;
+exports.changeHash = changeHash;
+const node_crypto_1 = require("node:crypto");
+const canonical_1 = require("./canonical");
+/** GOpenCSR could not be asked: unreachable, too slow, or failing on its side. */
+class CsrUnavailable extends Error {
+    name = "CsrUnavailable";
+}
+exports.CsrUnavailable = CsrUnavailable;
+/** GOpenCSR answered, and refused: what it said, for the log and the audit record. */
+class CsrRefused extends Error {
+    status;
+    reason;
+    name = "CsrRefused";
+    constructor(status, reason) {
+        super(`gopencsr refused: HTTP ${status} ${reason}`);
+        this.status = status;
+        this.reason = reason;
+    }
+}
+exports.CsrRefused = CsrRefused;
+/** What GOpenCSR's tokens say when the sign-in was a passkey (GOPENCSR-15). */
+exports.ACR_PASSKEY = "urn:gopencsr:acr:passkey";
+/** What a registry asks GOpenCSR to tell it: who, their address and name, and their passkeys. */
+exports.SCOPE = "openid email profile roles";
+/** The JOSE type of a signing receipt, which nothing else of GOpenCSR's carries. */
+const RECEIPT_TYPE = "gopencsr-signature+jwt";
+/** Every call to GOpenCSR must answer within this. */
+const TIMEOUT_MS = 10_000;
+/** How long GOpenCSR's public keys are trusted before they are read again. */
+const KEYS_FOR_MS = 5 * 60_000;
+/** How far apart the two clocks may be. */
+const LEEWAY_S = 60;
+/**
+ * The SHA-256 GOpenCSR's signing step commits to, in hex: the change's canonical form with the
+ * registry's product added, as GOpenCSR computes it.
+ */
+function changeHash(product, change) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update((0, canonical_1.canonicalJson)({ ...change, product }))
+        .digest("hex");
+}
+const isString = (value) => typeof value === "string";
+/** The terms claim, as GOpenCSR writes it: { state, in_force_from? }, or null for anything else. */
+function termsOf(claim) {
+    if (typeof claim !== "object" || claim === null)
+        return null;
+    const { state, in_force_from: inForceFrom } = claim;
+    if (!isString(state))
+        return null;
+    return {
+        state,
+        inForceFrom: typeof inForceFrom === "number" ? new Date(inForceFrom * 1000) : null,
+    };
+}
+/**
+ * A registry as GOpenCSR's client (GOPENCDR-333, extracted from GOpenCDR's api for every
+ * registry): the authorisation code flow with PKCE for sign-in and step-up, refresh and revocation
+ * of the tokens a session holds, the signing step that a change asks one or two passkeys through,
+ * and the delivery of the registry's entries to the one log. Every token is checked against GOpenCSR's published keys (EdDSA), which are read again
+ * for a key id not seen yet. Sessions, accounts and what a person may do stay the registry's own.
+ */
+class CsrClient {
+    options;
+    keys = null;
+    fetch;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.fetch = options.fetch ?? fetch;
+        this.now = options.now ?? Date.now;
+    }
+    /** GOpenCSR's issuer, the origin people sign in at. */
+    get issuer() {
+        return new URL(this.options.issuer).origin;
+    }
+    /** The authorisation request a browser takes to GOpenCSR. */
+    authorizeUrl(request) {
+        const url = new URL("/api/v1/oidc/authorize", this.issuer);
+        url.search = new URLSearchParams({
+            response_type: "code",
+            client_id: this.options.clientId,
+            redirect_uri: this.options.redirectUri,
+            scope: this.options.scope ?? exports.SCOPE,
+            state: request.state,
+            nonce: request.nonce,
+            code_challenge: request.challenge,
+            code_challenge_method: "S256",
+            acr_values: exports.ACR_PASSKEY,
+            ...(request.maxAge === undefined ? {} : { max_age: String(request.maxAge) }),
+        }).toString();
+        return url.toString();
+    }
+    /** The code GOpenCSR sent back, for tokens. The ID token must carry the nonce sent. */
+    async exchange(code, verifier, nonce) {
+        const body = await this.tokenCall({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: this.options.redirectUri,
+            code_verifier: verifier,
+        });
+        return this.tokensOf(body, nonce);
+    }
+    /**
+     * New tokens for a refresh token, which GOpenCSR replaces at each use; null when it refuses,
+     * because the person signed out there or the grant was revoked.
+     */
+    async refresh(refreshToken) {
+        try {
+            return await this.tokensOf(await this.tokenCall({ grant_type: "refresh_token", refresh_token: refreshToken }), null);
+        }
+        catch (error) {
+            if (error instanceof CsrRefused && error.status === 400)
+                return null;
+            throw error;
+        }
+    }
+    /** Revokes a refresh token, and with it GOpenCSR's grant (RFC 7009). */
+    async revoke(refreshToken) {
+        await this.call("POST", "oidc/revoke", {
+            form: { token: refreshToken, token_type_hint: "refresh_token" },
+        });
+    }
+    /**
+     * Asks GOpenCSR for the person's signature over a change (GOPENCSR-17), and checks that the
+     * hash it will show and sign is the one the registry computed.
+     */
+    async requestSignature(request) {
+        const created = (await this.call("POST", "signing-requests", { json: request }));
+        const hash = changeHash(this.options.product, request.change);
+        if (!isString(created.id) ||
+            !isString(created.url) ||
+            !isString(created.expiresAt) ||
+            created.hash !== hash) {
+            throw new Error("gopencsr: the signing request it made is not the change sent");
+        }
+        if (new URL(created.url).origin !== this.issuer) {
+            throw new Error("gopencsr: the signing page is not on its own origin");
+        }
+        return { id: created.id, url: created.url, hash, expiresAt: created.expiresAt };
+    }
+    /** A signing request this client made, as GOpenCSR reads it back; null if it knows none. */
+    async signingRequest(id) {
+        try {
+            return (await this.call("GET", `signing-requests/${encodeURIComponent(id)}`, {}));
+        }
+        catch (error) {
+            if (error instanceof CsrRefused && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+    /** Withdraws an open signing request whose change moved on: nothing can sign it any more. */
+    async withdrawSignature(id) {
+        await this.call("POST", `signing-requests/${encodeURIComponent(id)}/withdrawal`, {
+            json: { reason: "moved" },
+        });
+    }
+    /**
+     * A signature's receipt, checked: GOpenCSR's key, its type, made for this client and account,
+     * over this request; null for any receipt that is not all of those.
+     */
+    async receipt(token, expect) {
+        const claims = await this.verifyJws(token, RECEIPT_TYPE);
+        if (claims === null ||
+            claims.iss !== this.issuer ||
+            claims.aud !== this.options.clientId ||
+            claims.sub !== expect.account ||
+            claims.req !== expect.request ||
+            !isString(claims.hash) ||
+            !isString(claims.passkey)) {
+            return null;
+        }
+        return { passkey: claims.passkey, hash: claims.hash };
+    }
+    async tokensOf(body, nonce) {
+        const { refresh_token: refreshToken, id_token: idToken, expires_in: expiresIn } = body;
+        if (!isString(refreshToken) || !isString(idToken) || typeof expiresIn !== "number") {
+            throw new Error("gopencsr: the token response lacks a refresh token or an ID token");
+        }
+        const identity = await this.identityOf(idToken, nonce);
+        if (identity === null)
+            throw new Error("gopencsr: an ID token that does not verify");
+        return { refreshToken, accessExpiresAt: new Date(this.now() + expiresIn * 1000), identity };
+    }
+    /** The ID token's claims, checked (OpenID Connect Core 3.1.3.7), or null. */
+    async identityOf(idToken, nonce) {
+        const claims = await this.verifyJws(idToken, "JWT");
+        const now = Math.floor(this.now() / 1000);
+        if (claims === null ||
+            claims.iss !== this.issuer ||
+            claims.aud !== this.options.clientId ||
+            !isString(claims.sub) ||
+            !isString(claims.acr) ||
+            typeof claims.exp !== "number" ||
+            claims.exp + LEEWAY_S <= now ||
+            typeof claims.iat !== "number" ||
+            claims.iat - LEEWAY_S > now ||
+            typeof claims.auth_time !== "number" ||
+            (nonce !== null && claims.nonce !== nonce)) {
+            return null;
+        }
+        return {
+            sub: claims.sub,
+            acr: claims.acr,
+            authTime: new Date(claims.auth_time * 1000),
+            sid: isString(claims.sid) ? claims.sid : null,
+            email: isString(claims.email) ? claims.email : null,
+            emailVerified: claims.email_verified === true,
+            name: isString(claims.name) ? claims.name : null,
+            passkeys: typeof claims.passkeys === "number" && Number.isInteger(claims.passkeys)
+                ? claims.passkeys
+                : null,
+            terms: termsOf(claims.terms),
+        };
+    }
+    /**
+     * The claims of a compact JWS GOpenCSR signed, typed `typ`, or null for any that is not one.
+     * Times and audience are the caller's to check.
+     */
+    async verifyJws(token, typ) {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        const [head, body, signature] = parts;
+        let header;
+        let claims;
+        try {
+            header = JSON.parse(Buffer.from(head, "base64url").toString("utf8"));
+            claims = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+        }
+        catch {
+            return null;
+        }
+        if (header.alg !== "EdDSA" || header.typ !== typ || !isString(header.kid))
+            return null;
+        if (typeof claims !== "object" || claims === null || Array.isArray(claims))
+            return null;
+        let key = (await this.publicKeys()).get(header.kid);
+        // A key id not seen yet may be a rotation since the last read: ask once more.
+        if (key === undefined) {
+            this.keys = null;
+            key = (await this.publicKeys()).get(header.kid);
+        }
+        if (key === undefined)
+            return null;
+        const ok = (0, node_crypto_1.verify)(null, Buffer.from(`${head}.${body}`, "ascii"), key, Buffer.from(signature, "base64url"));
+        return ok ? claims : null;
+    }
+    async publicKeys() {
+        if (this.keys !== null && this.now() - this.keys.at < KEYS_FOR_MS)
+            return this.keys.byKid;
+        const jwks = (await this.call("GET", "oidc/jwks", { anonymous: true }));
+        const byKid = new Map();
+        for (const jwk of jwks.keys ?? []) {
+            if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !isString(jwk.x) || !isString(jwk.kid)) {
+                continue;
+            }
+            byKid.set(jwk.kid, (0, node_crypto_1.createPublicKey)({ key: { kty: "OKP", crv: "Ed25519", x: jwk.x }, format: "jwk" }));
+        }
+        this.keys = { at: this.now(), byKid };
+        return byKid;
+    }
+    /**
+     * Delivers entries to the one log (GOPENCSR-44), at least once: an id delivered again with the
+     * same leaf is the same entry, and with another it is refused. Each comes back as the log holds
+     * it, its leaf checked to be the one this registry wrote (the canonical JSON of id, kind, time
+     * and body), with its index once the appender added it, which is soon but not at once.
+     */
+    async deliverEntries(entries) {
+        const prefix = `${this.options.product}.`;
+        for (const entry of entries) {
+            if (!entry.kind.startsWith(prefix)) {
+                throw new Error(`gopencsr: ${entry.kind} is not a ${this.options.product} kind`);
+            }
+        }
+        const answer = (await this.call("POST", "tlog/entries", { json: { entries } }));
+        const held = Array.isArray(answer?.entries) ? answer.entries : [];
+        if (held.length !== entries.length) {
+            throw new Error("gopencsr: the log answered for other entries than those delivered");
+        }
+        entries.forEach((entry, at) => {
+            const leaf = (0, canonical_1.canonicalJson)({
+                id: entry.id,
+                kind: entry.kind,
+                time: entry.time,
+                body: entry.body,
+            });
+            if (held[at]?.id !== entry.id || held[at]?.leaf !== leaf) {
+                throw new Error(`gopencsr: the log holds entry ${entry.id} with another leaf`);
+            }
+        });
+        return held;
+    }
+    /** An entry of the one log as GOpenCSR holds it, by its id; null if it holds none. */
+    async tlogEntry(id) {
+        try {
+            return (await this.call("GET", `tlog/entries/${encodeURIComponent(id)}`, {
+                anonymous: true,
+            }));
+        }
+        catch (error) {
+            if (error instanceof CsrRefused && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+    async tokenCall(form) {
+        return (await this.call("POST", "oidc/token", { form }));
+    }
+    /** client_secret_basic (RFC 6749 2.3.1): the id and the secret, each form-encoded. */
+    async authorization() {
+        const form = (value) => encodeURIComponent(value).replace(/%20/g, "+");
+        const secret = await this.options.clientSecret();
+        const pair = `${form(this.options.clientId)}:${form(secret)}`;
+        return `Basic ${Buffer.from(pair, "utf8").toString("base64")}`;
+    }
+    /**
+     * One call to GOpenCSR's api, authenticated as the registry's client unless `anonymous`. A
+     * refusal (4xx) throws CsrRefused; anything that kept an answer from coming (the network, a
+     * timeout, a 5xx) throws CsrUnavailable, which the caller does not take as a refusal.
+     */
+    async call(method, path, request) {
+        const base = this.options.endpoints ?? this.issuer;
+        const url = new URL(`/api/v1/${path}`, base);
+        const headers = { accept: "application/json" };
+        if (request.anonymous !== true)
+            headers.authorization = await this.authorization();
+        let body;
+        if (request.form !== undefined) {
+            headers["content-type"] = "application/x-www-form-urlencoded";
+            body = new URLSearchParams(request.form).toString();
+        }
+        else if (request.json !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(request.json);
+        }
+        let res;
+        try {
+            res = await this.fetch(url, {
+                method,
+                headers,
+                ...(body === undefined ? {} : { body }),
+                redirect: "error",
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            throw new CsrUnavailable(`gopencsr: ${method} ${url.pathname} failed`, { cause: error });
+        }
+        const text = await res.text();
+        if (res.status >= 500) {
+            throw new CsrUnavailable(`gopencsr: ${method} ${url.pathname} answered ${res.status}`);
+        }
+        let parsed = undefined;
+        try {
+            parsed = text === "" ? undefined : JSON.parse(text);
+        }
+        catch {
+            // Not JSON, perhaps a proxy's page: the status says enough.
+        }
+        if (!res.ok) {
+            const reason = parsed?.error ??
+                parsed?.code;
+            throw new CsrRefused(res.status, isString(reason) ? reason : "unknown");
+        }
+        return parsed;
+    }
+}
+exports.CsrClient = CsrClient;
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @ghub/gopencsr-client: what a registry needs to be GOpenCSR's client. GOpenCSR signs people in
+ * for GOpenCDR and GOpenCNR, and its signing step signs their changes; the code that talks to it
+ * is built and released here once, for every registry (GOpenCSR's shared-code rule).
+ */
+export { canonicalJson } from "./canonical";
+export * from "./client";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJson = void 0;
+/**
+ * @ghub/gopencsr-client: what a registry needs to be GOpenCSR's client. GOpenCSR signs people in
+ * for GOpenCDR and GOpenCNR, and its signing step signs their changes; the code that talks to it
+ * is built and released here once, for every registry (GOpenCSR's shared-code rule).
+ */
+var canonical_1 = require("./canonical");
+Object.defineProperty(exports, "canonicalJson", { enumerable: true, get: function () { return canonical_1.canonicalJson; } });
+__exportStar(require("./client"), exports);
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@ghub/gopencsr-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "GOpenCSR's identity client for the registries it signs people in for: the OpenID Connect code flow with PKCE, refresh and revocation, ID tokens and signing receipts checked against GOpenCSR's EdDSA keys, and the signing step's requests and change hash. No framework, no dependencies.",
+  "author": "Gelhaus Solutions (Enno Gelhaus) <egelhaus@ennogelhaus.de> (https://ennogelhaus.de)",
+  "homepage": "https://ennogelhaus.de",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.11",
+    "@gopencsr/config-tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.