ankka-console 0.10.0

package/README.md

@@ -0,0 +1,32 @@
+# ankka-console
+
+The ankka console as a package: a typed client for the control plane's API, sign-in through the
+installation's realm with sessions a browser script cannot read, and the pages — organizations,
+projects, services, members, deploy tokens — as routes a [React Router](https://reactrouter.com)
+host mounts under a prefix of its choosing, inside its own layout.
+
+The installation's own console is one host of this package. A product built on ankka can be another,
+adding panels and actions to the pages and hiding operations it handles itself.
+
+```ts
+// app/routes.ts
+import { layout, prefix, type RouteConfig } from "@react-router/dev/routes";
+import { consoleRoutes } from "ankka-console/server";
+
+export default [layout("./layout.tsx", [...prefix("console", consoleRoutes())])] satisfies RouteConfig;
+```
+
+```ts
+// app/root.tsx
+import { consoleMiddleware, consoleOptionsFromEnv } from "ankka-console/server";
+export const middleware = [consoleMiddleware(() => consoleOptionsFromEnv(process.env))];
+```
+
+`ankka-console` is the browser-safe entry point (the provider, hooks and types a layout uses);
+`ankka-console/server` is everything that runs only on the server; `ankka-console/client` is the
+control plane client; `ankka-console/testing` holds a fake control plane and a fake identity provider
+for a host's own tests.
+
+The package's version is the platform's: pin the one your installation runs. See
+[the package reference](https://docs.ankka.cloud/reference/console-package/) for what a host supplies
+and every extension point.

package/dist/auth/oidc.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Signing in through the installation's realm: the authorization code flow with PKCE, as a
+ * confidential client, over two addresses.
+ *
+ * The browser is sent to the realm's external address; the console's own calls — discovery, keys,
+ * token, revocation, logout — go to an address the installation names (in a cluster, Keycloak's own
+ * service, verified against the service authority), because the external name may not resolve
+ * inside the cluster at all. Keycloak answers discovery with its external URLs whichever address
+ * asked, so the document is fetched here and its backchannel endpoints re-pointed, rather than handed
+ * to `discovery()`, which rightly refuses a document whose issuer is not the address it asked.
+ */
+import * as client from "openid-client";
+import type { FetchLike } from "../server/transport.ts";
+export interface IssuerOptions {
+    /** The realm's issuer exactly as tokens name it: the control plane's `GET /auth` says what it is. */
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    /** Where server-side calls go instead of the issuer's origin, e.g. `https://ankka-keycloak-service.ankka-auth.svc:8443`. */
+    backchannelUrl?: string;
+    /** How server-side calls are made: trusts the installation's authority in a cluster. */
+    fetch?: FetchLike;
+    /** Permits a plain-HTTP issuer: the development Keycloak. */
+    allowInsecure?: boolean;
+}
+export declare class IdentityProviderUnavailable extends Error {
+    constructor(cause: unknown);
+}
+/** The identity provider refused a session: sign in again. */
+export declare class SessionEnded extends Error {
+    constructor(message?: string);
+}
+export interface Tokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}
+export interface BeganSignIn {
+    url: URL;
+    state: string;
+    nonce: string;
+    verifier: string;
+}
+export declare class Issuer {
+    #private;
+    constructor(options: IssuerOptions);
+    /** The configuration, discovered on first use and kept; a failed discovery is tried again next time. */
+    configuration(): Promise<client.Configuration>;
+    /** Where to send the browser, and what the callback must check. */
+    beginSignIn(redirectUri: string): Promise<BeganSignIn>;
+    /** Exchanges the callback's code, having checked state, nonce, PKCE and the identity token. */
+    finishSignIn(callbackUrl: URL, checks: {
+        state: string;
+        nonce: string;
+        verifier: string;
+    }): Promise<Tokens>;
+    refresh(refreshToken: string): Promise<Tokens>;
+    /**
+     * Ends the person's session at the identity provider, server to server: Keycloak's logout
+     * endpoint accepts a confidential client's refresh token and ends the user session it belongs to,
+     * so no identity token has to be kept for sign-out and no confirmation page is shown.
+     */
+    endSession(refreshToken: string): Promise<void>;
+}

package/dist/auth/oidc.js

@@ -0,0 +1,199 @@
+/**
+ * Signing in through the installation's realm: the authorization code flow with PKCE, as a
+ * confidential client, over two addresses.
+ *
+ * The browser is sent to the realm's external address; the console's own calls — discovery, keys,
+ * token, revocation, logout — go to an address the installation names (in a cluster, Keycloak's own
+ * service, verified against the service authority), because the external name may not resolve
+ * inside the cluster at all. Keycloak answers discovery with its external URLs whichever address
+ * asked, so the document is fetched here and its backchannel endpoints re-pointed, rather than handed
+ * to `discovery()`, which rightly refuses a document whose issuer is not the address it asked.
+ */
+import * as client from "openid-client";
+export class IdentityProviderUnavailable extends Error {
+    constructor(cause) {
+        super(`the identity provider cannot be reached: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = "IdentityProviderUnavailable";
+    }
+}
+/** The identity provider refused a session: sign in again. */
+export class SessionEnded extends Error {
+    constructor(message = "the identity provider no longer honours this session") {
+        super(message);
+        this.name = "SessionEnded";
+    }
+}
+function repoint(endpoint, backchannel) {
+    if (!endpoint || !backchannel)
+        return endpoint;
+    const url = new URL(endpoint);
+    url.protocol = backchannel.protocol;
+    url.host = backchannel.host;
+    return url.toString();
+}
+const isNetworkFailure = (e) => e instanceof TypeError ||
+    (e instanceof Error && /ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|socket hang up|fetch failed|other side closed/i.test(e.message + String(e.cause ?? "")));
+function isInvalidGrant(e) {
+    if (!(e instanceof Error))
+        return false;
+    const err = e;
+    return err.error === "invalid_grant" || /invalid_grant/.test(err.message);
+}
+export class Issuer {
+    #options;
+    #config;
+    constructor(options) {
+        this.#options = options;
+    }
+    /**
+     * Server-side calls, carrying the public address as forwarded headers when they go to the
+     * backchannel. Keycloak keeps only a host name and takes the scheme and port of its issuer from
+     * each request, trusting the forwarded headers the gateway adds; asked directly on its in-cluster
+     * TLS port, it would name itself `https://auth.<base>:8443` — a different issuer from the one every
+     * browser-obtained token carries, so discovery would be refused and every token it issued here
+     * would be refused by the control plane. The headers make the backchannel look, to Keycloak, like
+     * the front door.
+     */
+    #fetch() {
+        const base = this.#options.fetch ?? ((url, init) => fetch(url, init));
+        if (!this.#options.backchannelUrl)
+            return base;
+        const issuer = new URL(this.#options.issuer);
+        const proto = issuer.protocol.replace(":", "");
+        const port = issuer.port || (proto === "https" ? "443" : "80");
+        return (url, init = {}) => {
+            const headers = new Headers(init.headers);
+            headers.set("x-forwarded-proto", proto);
+            headers.set("x-forwarded-host", issuer.host);
+            headers.set("x-forwarded-port", port);
+            return base(url, { ...init, headers });
+        };
+    }
+    /** The configuration, discovered on first use and kept; a failed discovery is tried again next time. */
+    configuration() {
+        if (!this.#config) {
+            this.#config = this.#discover().catch((e) => {
+                this.#config = undefined;
+                throw e;
+            });
+        }
+        return this.#config;
+    }
+    async #discover() {
+        const { issuer, backchannelUrl, clientId, clientSecret, allowInsecure } = this.#options;
+        const backchannel = backchannelUrl ? new URL(backchannelUrl) : undefined;
+        const discoveryUrl = repoint(`${issuer.replace(/\/+$/, "")}/.well-known/openid-configuration`, backchannel);
+        let response;
+        try {
+            response = await this.#fetch()(discoveryUrl, { headers: { accept: "application/json" } });
+        }
+        catch (e) {
+            throw new IdentityProviderUnavailable(e);
+        }
+        if (!response.ok)
+            throw new IdentityProviderUnavailable(new Error(`discovery answered ${response.status} at ${discoveryUrl}`));
+        const document = (await response.json());
+        if (document.issuer !== issuer) {
+            throw new Error(`the identity provider names its issuer '${document.issuer}' but the control plane expects '${issuer}'; ` +
+                "they must be the same string, port included");
+        }
+        const metadata = {
+            ...document,
+            token_endpoint: repoint(document.token_endpoint, backchannel),
+            jwks_uri: repoint(document.jwks_uri, backchannel),
+            revocation_endpoint: repoint(document.revocation_endpoint, backchannel),
+            end_session_endpoint: repoint(document.end_session_endpoint, backchannel),
+        };
+        const config = new client.Configuration(metadata, clientId, clientSecret, client.ClientSecretBasic(clientSecret));
+        const outbound = this.#fetch();
+        config[client.customFetch] = (url, options) => outbound(url, options);
+        if (allowInsecure)
+            client.allowInsecureRequests(config);
+        return config;
+    }
+    /** Where to send the browser, and what the callback must check. */
+    async beginSignIn(redirectUri) {
+        const config = await this.#guard(() => this.configuration());
+        const verifier = client.randomPKCECodeVerifier();
+        const state = client.randomState();
+        const nonce = client.randomNonce();
+        const url = client.buildAuthorizationUrl(config, {
+            redirect_uri: redirectUri,
+            // The realm declares its own scopes and none of Keycloak's built-ins; `openid` is the one asked
+            // for, and the control plane's scope is a default of the client, so the access token carries
+            // the audience and claims the control plane reads.
+            scope: "openid",
+            code_challenge: await client.calculatePKCECodeChallenge(verifier),
+            code_challenge_method: "S256",
+            state,
+            nonce,
+        });
+        return { url, state, nonce, verifier };
+    }
+    /** Exchanges the callback's code, having checked state, nonce, PKCE and the identity token. */
+    async finishSignIn(callbackUrl, checks) {
+        const config = await this.#guard(() => this.configuration());
+        const response = await this.#guard(() => client.authorizationCodeGrant(config, callbackUrl, {
+            pkceCodeVerifier: checks.verifier,
+            expectedState: checks.state,
+            expectedNonce: checks.nonce,
+            idTokenExpected: true,
+        }));
+        return this.#tokens(response, undefined);
+    }
+    async refresh(refreshToken) {
+        const config = await this.#guard(() => this.configuration());
+        try {
+            const response = await client.refreshTokenGrant(config, refreshToken);
+            return this.#tokens(response, refreshToken);
+        }
+        catch (e) {
+            if (isInvalidGrant(e))
+                throw new SessionEnded();
+            if (isNetworkFailure(e))
+                throw new IdentityProviderUnavailable(e);
+            throw e;
+        }
+    }
+    /**
+     * Ends the person's session at the identity provider, server to server: Keycloak's logout
+     * endpoint accepts a confidential client's refresh token and ends the user session it belongs to,
+     * so no identity token has to be kept for sign-out and no confirmation page is shown.
+     */
+    async endSession(refreshToken) {
+        const config = await this.#guard(() => this.configuration());
+        const endpoint = config.serverMetadata().end_session_endpoint;
+        if (endpoint) {
+            const body = new URLSearchParams({ refresh_token: refreshToken });
+            const credentials = Buffer.from(`${encodeURIComponent(this.#options.clientId)}:${encodeURIComponent(this.#options.clientSecret)}`).toString("base64");
+            const response = await this.#guard(() => this.#fetch()(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/x-www-form-urlencoded", authorization: `Basic ${credentials}` },
+                body,
+            }));
+            // 400 means the session had already ended, which is what was asked for.
+            if (!response.ok && response.status !== 400)
+                throw new IdentityProviderUnavailable(new Error(`logout answered ${response.status}`));
+            await response.body?.cancel();
+        }
+        await this.#guard(() => client.tokenRevocation(config, refreshToken, { token_type_hint: "refresh_token" })).catch(() => undefined);
+    }
+    #tokens(response, previousRefresh) {
+        const refreshToken = response.refresh_token ?? previousRefresh;
+        if (!refreshToken)
+            throw new Error("the identity provider issued no refresh token");
+        return { accessToken: response.access_token, refreshToken, expiresIn: response.expires_in ?? 60 };
+    }
+    async #guard(f) {
+        try {
+            return await f();
+        }
+        catch (e) {
+            if (e instanceof IdentityProviderUnavailable || e instanceof SessionEnded)
+                throw e;
+            if (isNetworkFailure(e))
+                throw new IdentityProviderUnavailable(e);
+            throw e;
+        }
+    }
+}

package/dist/client/control-plane.d.ts

@@ -0,0 +1,67 @@
+import { type AuthDiscovery, type CreateDeployToken, type CreateOrganization, type DeployTokenCreated, type DeployTokenSummary, type HistoryEntry, type LogsResponse, type MembersResponse, type OrganizationSummary, type ProjectDetail, type ProjectSummary, type Quota, type Role, type ServiceStatus, type SetRegistry, type Whoami } from "./schemas.ts";
+/** `fetch`'s shape; the server supplies one that presents the console's certificate. */
+export type Transport = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Where the bearer comes from. Called once per request; `refresh: true` means the last one was
+ * refused and a new one must be obtained. `null` means nobody is signed in.
+ */
+export type BearerSource = (options: {
+    refresh: boolean;
+}) => Promise<string | null>;
+export interface LogsQuery {
+    instance?: string;
+    previous?: boolean;
+    tail?: number;
+    since?: number;
+}
+export interface ControlPlaneClientOptions {
+    baseUrl: string;
+    bearer: BearerSource;
+    transport?: Transport;
+}
+/**
+ * The control plane's HTTP API, one method per route the console uses, as the signed-in person.
+ *
+ * A `401` is retried once with a refreshed bearer and then surfaces as `SignInRequired`; any other
+ * refusal is a `ControlPlaneError` carrying the body's reason. Responses are decoded against the
+ * wire schemas, with unknown fields dropped.
+ */
+export declare class ControlPlaneClient {
+    #private;
+    constructor(options: ControlPlaneClientOptions);
+    authDiscovery(): Promise<AuthDiscovery>;
+    whoami(): Promise<Whoami>;
+    listOrganizations(): Promise<OrganizationSummary[]>;
+    getOrganization(id: string): Promise<OrganizationSummary>;
+    createOrganization(id: string, body: CreateOrganization): Promise<void>;
+    renameOrganization(id: string, name: string): Promise<void>;
+    deleteOrganization(id: string): Promise<void>;
+    disableOrganization(id: string): Promise<void>;
+    enableOrganization(id: string): Promise<void>;
+    setQuota(id: string, quota: Quota): Promise<void>;
+    clearQuota(id: string): Promise<void>;
+    members(id: string): Promise<MembersResponse>;
+    invite(id: string, email: string, role: Role): Promise<void>;
+    removeMember(id: string, subject: string): Promise<void>;
+    changeRole(id: string, subject: string, role: Role): Promise<void>;
+    withdrawInvitation(id: string, email: string): Promise<void>;
+    repair(id: string, subject: string, role: Role): Promise<void>;
+    tokens(id: string): Promise<DeployTokenSummary[]>;
+    createToken(id: string, body: CreateDeployToken): Promise<DeployTokenCreated>;
+    revokeToken(id: string, tokenId: string): Promise<void>;
+    listProjects(): Promise<ProjectSummary[]>;
+    getProject(id: string): Promise<ProjectDetail>;
+    createProject(id: string, name: string, organizationId: string): Promise<void>;
+    renameProject(id: string, name: string): Promise<void>;
+    deleteProject(id: string): Promise<void>;
+    setRegistry(id: string, body: SetRegistry): Promise<void>;
+    clearRegistry(id: string): Promise<void>;
+    listServices(projectId: string): Promise<ServiceStatus[]>;
+    getService(projectId: string, name: string): Promise<ServiceStatus>;
+    /** The descriptor is sent as the text the person gave; the control plane is the one that validates it. */
+    applyService(projectId: string, name: string, descriptor: string): Promise<ServiceStatus>;
+    serviceOperation(projectId: string, name: string, operation: "pause" | "resume" | "restart" | "expose" | "unexpose"): Promise<void>;
+    deleteService(projectId: string, name: string): Promise<void>;
+    history(projectId: string, name: string): Promise<HistoryEntry[]>;
+    logs(projectId: string, name: string, query?: LogsQuery): Promise<LogsResponse>;
+}

package/dist/client/control-plane.js

@@ -0,0 +1,208 @@
+import { ControlPlaneError, ControlPlaneUnreachable, SignInRequired } from "./errors.js";
+import { authDiscoverySchema, deployTokenCreatedSchema, deployTokenSummarySchema, historyEntrySchema, logsResponseSchema, membersResponseSchema, organizationSummarySchema, projectDetailSchema, projectSummarySchema, serviceStatusSchema, whoamiSchema, } from "./schemas.js";
+const arrayOf = (schema) => ({
+    parse: (value) => {
+        if (!Array.isArray(value))
+            throw new TypeError("expected a JSON array");
+        return value.map((item) => schema.parse(item));
+    },
+});
+const segment = encodeURIComponent;
+/**
+ * The control plane's HTTP API, one method per route the console uses, as the signed-in person.
+ *
+ * A `401` is retried once with a refreshed bearer and then surfaces as `SignInRequired`; any other
+ * refusal is a `ControlPlaneError` carrying the body's reason. Responses are decoded against the
+ * wire schemas, with unknown fields dropped.
+ */
+export class ControlPlaneClient {
+    #baseUrl;
+    #bearer;
+    #transport;
+    constructor(options) {
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#bearer = options.bearer;
+        this.#transport = options.transport ?? ((url, init) => fetch(url, init));
+    }
+    // ── Identity ──────────────────────────────────────────────────────────────
+    authDiscovery() {
+        return this.#call("GET", "/auth", { schema: authDiscoverySchema, anonymous: true });
+    }
+    whoami() {
+        return this.#call("GET", "/auth/whoami", { schema: whoamiSchema });
+    }
+    // ── Organizations ─────────────────────────────────────────────────────────
+    listOrganizations() {
+        return this.#call("GET", "/organizations", { schema: arrayOf(organizationSummarySchema) });
+    }
+    getOrganization(id) {
+        return this.#call("GET", `/organizations/${segment(id)}`, { schema: organizationSummarySchema });
+    }
+    createOrganization(id, body) {
+        return this.#call("POST", `/organizations/${segment(id)}`, { body });
+    }
+    renameOrganization(id, name) {
+        return this.#call("PUT", `/organizations/${segment(id)}/name`, { body: { name } });
+    }
+    deleteOrganization(id) {
+        return this.#call("DELETE", `/organizations/${segment(id)}`);
+    }
+    disableOrganization(id) {
+        return this.#call("POST", `/organizations/${segment(id)}/disable`);
+    }
+    enableOrganization(id) {
+        return this.#call("POST", `/organizations/${segment(id)}/enable`);
+    }
+    setQuota(id, quota) {
+        return this.#call("PUT", `/organizations/${segment(id)}/quota`, { body: quota });
+    }
+    clearQuota(id) {
+        return this.#call("DELETE", `/organizations/${segment(id)}/quota`);
+    }
+    // ── Members and invitations ───────────────────────────────────────────────
+    members(id) {
+        return this.#call("GET", `/organizations/${segment(id)}/members`, { schema: membersResponseSchema });
+    }
+    invite(id, email, role) {
+        return this.#call("POST", `/organizations/${segment(id)}/members`, { body: { email, role } });
+    }
+    removeMember(id, subject) {
+        return this.#call("DELETE", `/organizations/${segment(id)}/members/${segment(subject)}`);
+    }
+    changeRole(id, subject, role) {
+        return this.#call("PUT", `/organizations/${segment(id)}/members/${segment(subject)}/role`, {
+            body: { role },
+        });
+    }
+    withdrawInvitation(id, email) {
+        return this.#call("DELETE", `/organizations/${segment(id)}/invitations/${segment(email)}`);
+    }
+    repair(id, subject, role) {
+        return this.#call("POST", `/organizations/${segment(id)}/members/${segment(subject)}/repair`, {
+            body: { role },
+        });
+    }
+    // ── Deploy tokens ─────────────────────────────────────────────────────────
+    tokens(id) {
+        return this.#call("GET", `/organizations/${segment(id)}/tokens`, {
+            schema: arrayOf(deployTokenSummarySchema),
+        });
+    }
+    createToken(id, body) {
+        return this.#call("POST", `/organizations/${segment(id)}/tokens`, {
+            body,
+            schema: deployTokenCreatedSchema,
+        });
+    }
+    revokeToken(id, tokenId) {
+        return this.#call("DELETE", `/organizations/${segment(id)}/tokens/${segment(tokenId)}`);
+    }
+    // ── Projects ──────────────────────────────────────────────────────────────
+    listProjects() {
+        return this.#call("GET", "/projects", { schema: arrayOf(projectSummarySchema) });
+    }
+    getProject(id) {
+        return this.#call("GET", `/projects/${segment(id)}`, { schema: projectDetailSchema });
+    }
+    createProject(id, name, organizationId) {
+        return this.#call("POST", `/projects/${segment(id)}`, { body: { name, organizationId } });
+    }
+    renameProject(id, name) {
+        return this.#call("PUT", `/projects/${segment(id)}/name`, { body: { name } });
+    }
+    deleteProject(id) {
+        return this.#call("DELETE", `/projects/${segment(id)}`);
+    }
+    setRegistry(id, body) {
+        return this.#call("PUT", `/projects/${segment(id)}/registry`, { body });
+    }
+    clearRegistry(id) {
+        return this.#call("DELETE", `/projects/${segment(id)}/registry`);
+    }
+    // ── Services ──────────────────────────────────────────────────────────────
+    listServices(projectId) {
+        return this.#call("GET", `/services/${segment(projectId)}`, { schema: arrayOf(serviceStatusSchema) });
+    }
+    getService(projectId, name) {
+        return this.#call("GET", `/services/${segment(projectId)}/${segment(name)}`, { schema: serviceStatusSchema });
+    }
+    /** The descriptor is sent as the text the person gave; the control plane is the one that validates it. */
+    applyService(projectId, name, descriptor) {
+        return this.#call("PUT", `/services/${segment(projectId)}/${segment(name)}`, {
+            rawBody: descriptor,
+            schema: serviceStatusSchema,
+        });
+    }
+    serviceOperation(projectId, name, operation) {
+        return this.#call("POST", `/services/${segment(projectId)}/${segment(name)}/${operation}`);
+    }
+    deleteService(projectId, name) {
+        return this.#call("DELETE", `/services/${segment(projectId)}/${segment(name)}`);
+    }
+    history(projectId, name) {
+        return this.#call("GET", `/services/${segment(projectId)}/${segment(name)}/history`, {
+            schema: arrayOf(historyEntrySchema),
+        });
+    }
+    logs(projectId, name, query = {}) {
+        const params = new URLSearchParams();
+        if (query.instance)
+            params.set("instance", query.instance);
+        if (query.previous)
+            params.set("previous", "true");
+        if (query.tail !== undefined)
+            params.set("tail", String(query.tail));
+        if (query.since !== undefined)
+            params.set("since", String(query.since));
+        const q = params.size > 0 ? `?${params}` : "";
+        return this.#call("GET", `/services/${segment(projectId)}/${segment(name)}/logs${q}`, {
+            schema: logsResponseSchema,
+        });
+    }
+    // ── Transport ─────────────────────────────────────────────────────────────
+    async #call(method, path, options = {}) {
+        const url = this.#baseUrl + path;
+        const body = options.rawBody ?? (options.body === undefined ? undefined : JSON.stringify(options.body));
+        const send = async (bearer) => {
+            const headers = { accept: "application/json" };
+            if (bearer)
+                headers.authorization = `Bearer ${bearer}`;
+            if (body !== undefined)
+                headers["content-type"] = "application/json";
+            try {
+                return await this.#transport(url, { method, headers, body });
+            }
+            catch (cause) {
+                throw new ControlPlaneUnreachable(this.#baseUrl, cause);
+            }
+        };
+        let response;
+        if (options.anonymous) {
+            response = await send(null);
+        }
+        else {
+            const bearer = await this.#bearer({ refresh: false });
+            if (bearer === null)
+                throw new SignInRequired();
+            response = await send(bearer);
+            if (response.status === 401) {
+                await response.body?.cancel();
+                const fresh = await this.#bearer({ refresh: true });
+                if (fresh === null)
+                    throw new SignInRequired();
+                response = await send(fresh);
+                if (response.status === 401) {
+                    await response.body?.cancel();
+                    throw new SignInRequired();
+                }
+            }
+        }
+        if (!response.ok)
+            throw await ControlPlaneError.from(response);
+        if (!options.schema) {
+            await response.body?.cancel();
+            return undefined;
+        }
+        return options.schema.parse(await response.json());
+    }
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A refusal or failure from the control plane: its HTTP status and the reason its body gave, which
+ * the console shows verbatim beside the thing refused. A refusal is a value the person should read,
+ * not a crash.
+ */
+export declare class ControlPlaneError extends Error {
+    readonly status: number;
+    readonly reason: string;
+    constructor(status: number, reason: string);
+    /** Whether sending the same request again, unchanged, could succeed. */
+    get retryable(): boolean;
+    /**
+     * The individual problems of a refused descriptor. The control plane joins them into one message,
+     * `invalid descriptor: a; b`; anything else is one problem, the whole reason.
+     */
+    get problems(): string[];
+    static from(response: Response): Promise<ControlPlaneError>;
+}
+/** The control plane could not be reached at all: no status, only the transport's failure. */
+export declare class ControlPlaneUnreachable extends Error {
+    constructor(url: string, cause: unknown);
+}
+/** The request's access token was refused, and a fresh one was refused too: sign in again. */
+export declare class SignInRequired extends Error {
+    constructor();
+}

package/dist/client/errors.js

@@ -0,0 +1,59 @@
+import { errorBodySchema } from "./schemas.js";
+/**
+ * A refusal or failure from the control plane: its HTTP status and the reason its body gave, which
+ * the console shows verbatim beside the thing refused. A refusal is a value the person should read,
+ * not a crash.
+ */
+export class ControlPlaneError extends Error {
+    status;
+    reason;
+    constructor(status, reason) {
+        super(`control plane answered ${status}: ${reason}`);
+        this.name = "ControlPlaneError";
+        this.status = status;
+        this.reason = reason;
+    }
+    /** Whether sending the same request again, unchanged, could succeed. */
+    get retryable() {
+        return this.status === 503 || this.status === 504;
+    }
+    /**
+     * The individual problems of a refused descriptor. The control plane joins them into one message,
+     * `invalid descriptor: a; b`; anything else is one problem, the whole reason.
+     */
+    get problems() {
+        const prefix = "invalid descriptor: ";
+        return this.reason.startsWith(prefix)
+            ? this.reason.slice(prefix.length).split("; ").filter((p) => p.length > 0)
+            : [this.reason];
+    }
+    static async from(response) {
+        const text = await response.text().catch(() => "");
+        let reason = text.trim() || response.statusText || `HTTP ${response.status}`;
+        try {
+            const body = errorBodySchema.safeParse(JSON.parse(text));
+            if (body.success)
+                reason = body.data.error;
+        }
+        catch {
+            // Not JSON: a proxy's page, say. The status is still the truth.
+        }
+        return new ControlPlaneError(response.status, reason);
+    }
+}
+/** The control plane could not be reached at all: no status, only the transport's failure. */
+export class ControlPlaneUnreachable extends Error {
+    constructor(url, cause) {
+        super(`could not reach the control plane at ${url}: ${cause instanceof Error ? cause.message : String(cause)}`, {
+            cause,
+        });
+        this.name = "ControlPlaneUnreachable";
+    }
+}
+/** The request's access token was refused, and a fresh one was refused too: sign in again. */
+export class SignInRequired extends Error {
+    constructor() {
+        super("sign-in required");
+        this.name = "SignInRequired";
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { ControlPlaneClient } from "./control-plane.ts";
+export type { BearerSource, ControlPlaneClientOptions, LogsQuery, Transport } from "./control-plane.ts";
+export { ControlPlaneError, ControlPlaneUnreachable, SignInRequired } from "./errors.ts";
+export * from "./schemas.ts";

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { ControlPlaneClient } from "./control-plane.js";
+export { ControlPlaneError, ControlPlaneUnreachable, SignInRequired } from "./errors.js";
+export * from "./schemas.js";