@toa.io/extensions.exposition 1.0.0-alpha.31 → 1.0.0-alpha.310

package/components/identity.clients/operations/lib/cimd.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { ERR_UNKNOWN_CLIENT } from './errors.js';
+/**
+ * A Client ID Metadata Document: the client publishes what it is at an https URL, and that
+ * URL is its `client_id`. Control of the origin is what proves the identity, so nothing is
+ * registered and nothing is written — the document is read and held for a while.
+ */
+export async function read(id, context) {
+    // before anything is fetched: the id is the caller's to choose, and this runs inside
+    // the cluster. An origin the configuration does not name is not reached at all.
+    if (!trusted(id, context.configuration.trust))
+        return ERR_UNKNOWN_CLIENT;
+    const key = CACHE + createHash('sha256').update(id).digest('hex');
+    const cached = await context.stash.get(key);
+    if (cached !== null)
+        return cached === MISS ? ERR_UNKNOWN_CLIENT : JSON.parse(cached);
+    const client = await fetch(id, context);
+    // a document that does not answer is remembered too, or a bad id is fetched per request
+    await context.stash.set(key, client instanceof Error ? MISS : JSON.stringify(client), 'EX', context.configuration.lifetime);
+    return client;
+}
+/**
+ * An https URL whose origin the configuration names. Compared by origin so that a path on a
+ * trusted host cannot be escaped by one that merely starts the same way.
+ */
+function trusted(id, trust) {
+    let url;
+    try {
+        url = new URL(id);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== 'https:')
+        return false;
+    return trust.some((origin) => {
+        try {
+            return new URL(origin).origin === url.origin;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+async function fetch(id, context) {
+    const { size, timeout } = context.configuration;
+    try {
+        const response = await context.fetch(id, {
+            redirect: 'error', // a redirect leaves the origin that was trusted
+            signal: AbortSignal.timeout(timeout),
+            headers: { accept: 'application/json' }
+        });
+        if (!response.ok)
+            return ERR_UNKNOWN_CLIENT;
+        const text = await response.text();
+        if (text.length > size)
+            return ERR_UNKNOWN_CLIENT;
+        return validate(id, JSON.parse(text));
+    }
+    catch (error) {
+        context.logs.debug('Client metadata document is unreadable', {
+            client: id,
+            error: error?.toString?.()
+        });
+        return ERR_UNKNOWN_CLIENT;
+    }
+}
+function validate(id, metadata) {
+    // the document names itself, so one client's cannot claim another's identity
+    if (metadata.client_id !== id)
+        return ERR_UNKNOWN_CLIENT;
+    if (!Array.isArray(metadata.redirect_uris) ||
+        metadata.redirect_uris.length === 0 ||
+        metadata.redirect_uris.some((uri) => typeof uri !== 'string'))
+        return ERR_UNKNOWN_CLIENT;
+    return {
+        client_id: id,
+        client_name: metadata.client_name,
+        client_uri: metadata.client_uri,
+        logo_uri: metadata.logo_uri,
+        redirect_uris: metadata.redirect_uris
+    };
+}
+const CACHE = 'cimd:';
+/** Held in place of a document that could not be read, so a bad id is not refetched. */
+const MISS = '';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2ltZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NvdXJjZS9saWIvY2ltZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sYUFBYSxDQUFBO0FBQ3hDLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGFBQWEsQ0FBQTtBQUloRDs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxJQUFJLENBQUMsRUFBVSxFQUFFLE9BQWdCO0lBQ3JELHFGQUFxRjtJQUNyRixnRkFBZ0Y7SUFDaEYsSUFBSSxDQUFDLE9BQU8sQ0FBQyxFQUFFLEVBQUUsT0FBTyxDQUFDLGFBQWEsQ0FBQyxLQUFLLENBQUM7UUFBRSxPQUFPLGtCQUFrQixDQUFBO0lBRXhFLE1BQU0sR0FBRyxHQUFHLEtBQUssR0FBRyxVQUFVLENBQUMsUUFBUSxDQUFDLENBQUMsTUFBTSxDQUFDLEVBQUUsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQTtJQUNqRSxNQUFNLE1BQU0sR0FBRyxNQUFNLE9BQU8sQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxDQUFBO0lBRTNDLElBQUksTUFBTSxLQUFLLElBQUk7UUFDakIsT0FBTyxNQUFNLEtBQUssSUFBSSxDQUFDLENBQUMsQ0FBQyxrQkFBa0IsQ0FBQyxDQUFDLENBQUUsSUFBSSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQVksQ0FBQTtJQUU5RSxNQUFNLE1BQU0sR0FBRyxNQUFNLEtBQUssQ0FBQyxFQUFFLEVBQUUsT0FBTyxDQUFDLENBQUE7SUFFdkMsd0ZBQXdGO0lBQ3hGLE1BQU0sT0FBTyxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQ3JCLEdBQUcsRUFDSCxNQUFNLFlBQVksS0FBSyxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxTQUFTLENBQUMsTUFBTSxDQUFDLEVBQ3ZELElBQUksRUFDSixPQUFPLENB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

package/components/identity.clients/operations/lib/errors.js

@@ -0,0 +1,5 @@
+export const ERR_UNKNOWN_CLIENT = new (class UnknownClientError extends Error {
+    code = 'UNKNOWN_CLIENT';
+    message = 'No such client';
+})();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc291cmNlL2xpYi9lcnJvcnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsSUFBSSxDQUFDLE1BQU0sa0JBQW1CLFNBQVEsS0FBSztJQUMzRCxJQUFJLEdBQUcsZ0JBQWdCLENBQUE7SUFDZCxPQUFPLEdBQUcsZ0JBQWdCLENBQUE7Q0FDcEQsQ0FBQyxFQUFFLENBQUEifQ==

package/components/identity.clients/operations/lib/index.js

@@ -0,0 +1,7 @@
+export * from './canonical.js';
+export * from './cimd.js';
+export * from './Context.js';
+export * from './Entity.js';
+export * from './errors.js';
+export * from './redirect.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zb3VyY2UvbGliL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZ0JBQWdCLENBQUE7QUFDOUIsY0FBYyxXQUFXLENBQUE7QUFDekIsY0FBYyxjQUFjLENBQUE7QUFDNUIsY0FBYyxhQUFhLENBQUE7QUFDM0IsY0FBYyxhQUFhLENBQUE7QUFDM0IsY0FBYyxlQUFlLENBQUEifQ==

package/components/identity.clients/operations/lib/redirect.js

@@ -0,0 +1,35 @@
+/**
+ * Whether a client may receive a code at this address.
+ *
+ * Exact string comparison, which RFC 6749 §3.1.2.3 requires, except for a loopback
+ * address: a native client binds whatever port is free when it starts, so RFC 8252 §7.3
+ * has the port ignored there. Claude Code registers `http://localhost/callback` and
+ * `http://127.0.0.1/callback` and comes back on an ephemeral port; comparing those
+ * literally would refuse every one of them.
+ */
+export function permits(registered, redirect) {
+    return registered.some((uri) => uri === redirect || loopback(uri, redirect));
+}
+function loopback(registered, redirect) {
+    const a = parse(registered);
+    const b = parse(redirect);
+    if (a === null || b === null)
+        return false;
+    return (a.protocol === 'http:' &&
+        b.protocol === 'http:' &&
+        LOOPBACK.has(a.hostname) &&
+        a.hostname === b.hostname &&
+        a.pathname === b.pathname &&
+        a.search === b.search);
+}
+function parse(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+/** `localhost` resolves through the host's own configuration, which RFC 8252 §8.3 warns of. */
+const LOOPBACK = new Set(['127.0.0.1', '[::1]', 'localhost']);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVkaXJlY3QuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zb3VyY2UvbGliL3JlZGlyZWN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxVQUFVLE9BQU8sQ0FBQyxVQUFvQixFQUFFLFFBQWdCO0lBQzVELE9BQU8sVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDLEdBQUcsRUFBRSxFQUFFLENBQUMsR0FBRyxLQUFLLFFBQVEsSUFBSSxRQUFRLENBQUMsR0FBRyxFQUFFLFFBQVEsQ0FBQyxDQUFDLENBQUE7QUFDOUUsQ0FBQztBQUVELFNBQVMsUUFBUSxDQUFDLFVBQWtCLEVBQUUsUUFBZ0I7SUFDcEQsTUFBTSxDQUFDLEdBQUcsS0FBSyxDQUFDLFVBQVUsQ0FBQyxDQUFBO0lBQzNCLE1BQU0sQ0FBQyxHQUFHLEtBQUssQ0FBQyxRQUFRLENBQUMsQ0FBQTtJQUV6QixJQUFJLENBQUMsS0FBSyxJQUFJLElBQUksQ0FBQyxLQUFLLElBQUk7UUFBRSxPQUFPLEtBQUssQ0FBQTtJQUUxQyxPQUFPLENBQ0wsQ0FBQyxDQUFDLFFBQVEsS0FBSyxPQUFPO1FBQ3RCLENBQUMsQ0FBQyxRQUFRLEtBQUssT0FBTztRQUN0QixRQUFRLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxRQUFRLENBQUM7UUFDeEIsQ0FBQyxDQUFDLFFBQVEsS0FBSyxDQUFDLENBQUMsUUFBUTtRQUN6QixDQUFDLENBQUMsUUFBUSxLQUFLLENBQUMsQ0FBQyxRQUFRO1FBQ3pCLENBQUMsQ0FBQyxNQUFNLEtBQUssQ0FBQyxDQUFDLE1BQU0sQ0FDdEIsQ0FBQTtBQUNILENBQUM7QUFFRCxTQUFTLEtBQUssQ0FBQyxLQUFhO0lBQzFCLElBQUksQ0FBQztRQUNILE9BQU8sSUFBSSxHQUFHLENBQUMsS0FBSyxDQUFDLENBQUE7SUFDdkIsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLE9BQU8sSUFBSSxDQUFBO0lBQ2IsQ0FBQztBQUNILENBQUM7QUFFRCwrRkFBK0Y7QUFDL0YsTUFBTSxRQUFRLEdBQUcsSUFBSSxHQUFHLENBQUMsQ0FBQyxXQUFXLEVBQUUsT0FBTyxFQUFFLFdBQVcsQ0FBQyxDQUFDLENBQUEifQ==

package/components/identity.clients/operations/register.js

@@ -0,0 +1,84 @@
+import { identify } from './lib/index.js';
+/**
+ * Dynamic Client Registration, RFC 7591: the client sends what it is and is given an
+ * identifier for it. Unauthenticated, as the specification has it — a registration grants
+ * nothing on its own, and stays inert until a user consents to the client on a page that
+ * shows them its name and where it would send them.
+ *
+ * The identifier is a hash of the metadata, so registering the same thing twice is the
+ * same client rather than another row. A client cannot remember it registered here.
+ */
+export class Effect {
+    transit;
+    ttl;
+    mount(context) {
+        this.transit = context.local.transit;
+        this.ttl = context.configuration.ttl;
+    }
+    async execute(input) {
+        const { authority } = input;
+        if (input.token_endpoint_auth_method !== undefined &&
+            input.token_endpoint_auth_method !== 'none')
+            return invalid('invalid_client_metadata', 'Only public clients are supported: token_endpoint_auth_method must be `none`');
+        const uris = input.redirect_uris.map(normalize);
+        for (const uri of uris)
+            if (uri instanceof Error)
+                return invalid('invalid_redirect_uri', uri.message);
+        const metadata = {
+            client_name: input.client_name,
+            client_uri: input.client_uri,
+            logo_uri: input.logo_uri,
+            scope: input.scope,
+            redirect_uris: uris
+        };
+        const id = identify(authority, metadata);
+        const entity = await this.transit({
+            query: { id },
+            input: {
+                authority,
+                name: metadata.client_name,
+                uri: metadata.client_uri,
+                logo: metadata.logo_uri,
+                scope: metadata.scope,
+                uris: metadata.redirect_uris,
+                expires: Date.now() + this.ttl * 1000
+            }
+        });
+        return {
+            client_id: id,
+            // of the record, not of this request: registering again answers what it answered
+            client_id_issued_at: Math.floor((entity.CREATED ?? Date.now()) / 1000),
+            client_name: entity.name,
+            client_uri: entity.uri,
+            logo_uri: entity.logo,
+            redirect_uris: entity.uris,
+            grant_types: ['authorization_code'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none'
+        };
+    }
+}
+/** Absolute, no fragment, and either https or a loopback address (RFC 8252 §7.3). */
+function normalize(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return new Error(`\`${value}\` is not an absolute URI`);
+    }
+    if (url.hash !== '')
+        return new Error(`\`${value}\` carries a fragment`);
+    if (url.protocol === 'https:')
+        return url.href;
+    if (url.protocol === 'http:' && LOOPBACK.has(url.hostname))
+        return url.href;
+    return new Error(`\`${value}\` is neither https nor a loopback address`);
+}
+/** RFC 7591 §3.2.2: a registration error is a body, and `map:status` makes it the status. */
+function invalid(error, description) {
+    return { status: BAD_REQUEST, error, error_description: description };
+}
+const BAD_REQUEST = 400;
+const LOOPBACK = new Set(['127.0.0.1', '[::1]', 'localhost']);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVnaXN0ZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zb3VyY2UvcmVnaXN0ZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLGdCQUFnQixDQUFBO0FBS3pDOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxPQUFPLE1BQU07SUFDVCxPQUFPLENBQThCO0lBQ3JDLEdBQUcsQ0FBUztJQUViLEtBQUssQ0FBQyxPQUFnQjtRQUMzQixJQUFJLENBQUMsT0FBTyxHQUFHLE9BQU8sQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFBO1FBQ3BDLElBQUksQ0FBQyxHQUFHLEdBQUcsT0FBTyxDQUFDLGFBQWEsQ0FBQyxHQUFHLENBQUE7SUFDdEMsQ0FBQztJQUVNLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBWTtRQUMvQixNQUFNLEVBQUUsU0FBUyxFQUFFLEdBQUcsS0FBSyxDQUFBO1FBRTNCLElBQ0UsS0FBSyxDQUFDLDBCQUEwQixLQUFLLFNBQVM7WUFDOUMsS0FBSyxDQUFDLDBCQUEwQixLQUFLLE1BQU07WUFFM0MsT0FBTyxPQUFPLENBQ1oseUJBQXlCLEVBQ3pCLDhFQUE4RSxDQUMvRSxDQUFBO1FBRUgsTUFBTSxJQUFJLEdBQUcsS0FBSyxDQUFDLGFBQWEsQ0FBQyxHQUFHLENBQUMsU0FBUyxDQUFDLENBQUE7UUFFL0MsS0FBSyxNQUFNLEdBQUcsSUFBSSxJQUFJO1lBQ3BCLElBQUksR0FBRyxZQUFZLEtBQUs7Z0JBQUUsT0FBTyxPQUFPLENBQUMsc0JBQXNCLEVBQUUsR0FBRyxDQUFDLE9BQU8sQ0FBQyxDQUFBO1FBRS9FLE1BQU0sUUFBUSxHQUFhO1lBQ3pCLFdBQVcsRUFBRSxLQUFLLENBQUMsV0FBVztZQUM5QixVQUFVLEVBQUUsS0FBSyxDQUFDLFVBQVU7WUFDNUIsUUFBUSxFQUFFLEtBQUssQ0FBQyxRQUFRO1lBQ3hCLEtBQUssRUFBRSxLQUFLLENBQUMsS0FBSztZQUNsQixhQUFhLEVBQUUs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

package/components/identity.clients/source/describe.ts

@@ -0,0 +1,63 @@
+import { ERR_UNKNOWN_CLIENT, permits, read } from './lib/index.ts'
+import type { Maybe } from '@toa.io/core/types'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Client, Context } from './lib/index.ts'
+
+/**
+ * What a client is, whichever way it came to be known: a `client_id` that is an https URL
+ * publishes its own metadata, and anything else was registered here. The caller is not told
+ * which, and neither mechanism is visible past this operation.
+ *
+ * Whether a redirect is one the client may receive a code at is answered here too. The rule
+ * is this component's — nothing else knows a loopback port is ignored — and asking for it
+ * with the client saves a second call on the path a person is waiting on.
+ */
+export class Computation implements Operation {
+  private context!: Context
+
+  public mount(context: Context): void {
+    this.context = context
+  }
+
+  public async execute(input: Input): Promise<Maybe<Output>> {
+    const client = input.id.startsWith(HTTPS)
+      ? await read(input.id, this.context)
+      : await this.registered(input)
+
+    if (client instanceof Error) return client
+
+    return {
+      ...client,
+      ...(input.redirect === undefined
+        ? {}
+        : { permitted: permits(client.redirect_uris, input.redirect) })
+    }
+  }
+
+  private async registered(input: Input): Promise<Client | Error> {
+    const entity = await this.context.local.observe({ query: { id: input.id } })
+
+    // credentials are scoped to an authority, and so is what may act for them
+    if (entity === null || entity.authority !== input.authority) return ERR_UNKNOWN_CLIENT
+
+    return {
+      client_id: entity.id,
+      client_name: entity.name,
+      client_uri: entity.uri,
+      logo_uri: entity.logo,
+      redirect_uris: entity.uris
+    }
+  }
+}
+
+const HTTPS = 'https://'
+
+interface Input {
+  authority: string
+  id: string
+  redirect?: string
+}
+
+interface Output extends Client {
+  permitted?: boolean
+}

package/components/identity.clients/source/lib/Context.ts

@@ -0,0 +1,40 @@
+import type { Call, Observation } from '@toa.io/core/types'
+export type { Transition } from '@toa.io/core/types'
+import type { Stash } from '@toa.io/extensions.stash'
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type { Entity } from './Entity.ts'
+
+export interface Context {
+  stash: Stash
+  fetch: Fetch
+  logs: Logs
+  local: {
+    observe: Observation<Entity>
+    transit: Call<Entity, TransitInput>
+  }
+  configuration: Configuration
+}
+
+export type Fetch = (
+  input: string | URL | Request,
+  init?: RequestInit
+) => Promise<Response>
+
+export type TransitInput = Omit<Entity, 'id' | 'CREATED'>
+
+export interface Configuration {
+  /** Origins whose Client ID Metadata Documents may be read. Empty admits nobody. */
+  readonly trust: string[]
+
+  /** Seconds a document is held before it is read again. */
+  readonly lifetime: number
+
+  /** Seconds a registration nothing has used is kept. */
+  readonly ttl: number
+
+  /** Bytes of a document that are read. */
+  readonly size: number
+
+  /** Milliseconds a document has to arrive. */
+  readonly timeout: number
+}

package/components/identity.clients/source/lib/Entity.ts

@@ -0,0 +1,31 @@
+export interface Entity {
+  id: string
+  authority: string
+  name?: string
+  uris: string[]
+  uri?: string
+  logo?: string
+  scope?: string
+  expires?: number
+  CREATED?: number
+}
+
+/** What a client says about itself, in the shape both mechanisms carry it. */
+export interface Metadata {
+  client_name?: string
+  client_uri?: string
+  logo_uri?: string
+  redirect_uris: string[]
+  scope?: string
+  token_endpoint_auth_method?: string
+}
+
+/** A client, however it came to be known. */
+export interface Client {
+  client_id: string
+  client_name?: string
+  client_uri?: string
+  logo_uri?: string
+  redirect_uris: string[]
+  issued?: number
+}

package/components/identity.clients/source/lib/canonical.ts

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto'
+import type { Metadata } from './Entity.ts'
+
+/**
+ * The id of a registration: a hash of what it says, so identical metadata is one client
+ * however many times it arrives. A client cannot remember that it registered here, and
+ * registers again on every fresh connection; without this the registry only grows.
+ *
+ * Only what is honoured is hashed. A field this component ignores would otherwise mint a
+ * client per release of whoever sends it, and the authority is in there because credentials
+ * are scoped to one.
+ */
+export function identify(authority: string, metadata: Metadata): string {
+  const canonical = JSON.stringify([
+    authority,
+    metadata.client_name ?? null,
+    metadata.client_uri ?? null,
+    metadata.logo_uri ?? null,
+    metadata.scope ?? null,
+    [...metadata.redirect_uris].sort()
+  ])
+
+  return createHash('sha256').update(canonical).digest('hex').slice(0, LENGTH)
+}
+
+/** What the entity prototype accepts as an id. */
+const LENGTH = 32

package/components/identity.clients/source/lib/cimd.ts

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto'
+import { ERR_UNKNOWN_CLIENT } from './errors.ts'
+import type { Context } from './Context.ts'
+import type { Client, Metadata } from './Entity.ts'
+
+/**
+ * A Client ID Metadata Document: the client publishes what it is at an https URL, and that
+ * URL is its `client_id`. Control of the origin is what proves the identity, so nothing is
+ * registered and nothing is written — the document is read and held for a while.
+ */
+export async function read(id: string, context: Context): Promise<Client | Error> {
+  // before anything is fetched: the id is the caller's to choose, and this runs inside
+  // the cluster. An origin the configuration does not name is not reached at all.
+  if (!trusted(id, context.configuration.trust)) return ERR_UNKNOWN_CLIENT
+
+  const key = CACHE + createHash('sha256').update(id).digest('hex')
+  const cached = await context.stash.get(key)
+
+  if (cached !== null)
+    return cached === MISS ? ERR_UNKNOWN_CLIENT : (JSON.parse(cached) as Client)
+
+  const client = await fetch(id, context)
+
+  // a document that does not answer is remembered too, or a bad id is fetched per request
+  await context.stash.set(
+    key,
+    client instanceof Error ? MISS : JSON.stringify(client),
+    'EX',
+    context.configuration.lifetime
+  )
+
+  return client
+}
+
+/**
+ * An https URL whose origin the configuration names. Compared by origin so that a path on a
+ * trusted host cannot be escaped by one that merely starts the same way.
+ */
+function trusted(id: string, trust: string[]): boolean {
+  let url: URL
+
+  try {
+    url = new URL(id)
+  } catch {
+    return false
+  }
+
+  if (url.protocol !== 'https:') return false
+
+  return trust.some((origin) => {
+    try {
+      return new URL(origin).origin === url.origin
+    } catch {
+      return false
+    }
+  })
+}
+
+async function fetch(id: string, context: Context): Promise<Client | Error> {
+  const { size, timeout } = context.configuration
+
+  try {
+    const response = await context.fetch(id, {
+      redirect: 'error', // a redirect leaves the origin that was trusted
+      signal: AbortSignal.timeout(timeout),
+      headers: { accept: 'application/json' }
+    })
+
+    if (!response.ok) return ERR_UNKNOWN_CLIENT
+
+    const text = await response.text()
+
+    if (text.length > size) return ERR_UNKNOWN_CLIENT
+
+    return validate(id, JSON.parse(text) as Metadata & { client_id?: string })
+  } catch (error: unknown) {
+    context.logs.debug('Client metadata document is unreadable', {
+      client: id,
+      error: error?.toString?.()
+    })
+
+    return ERR_UNKNOWN_CLIENT
+  }
+}
+
+function validate(
+  id: string,
+  metadata: Metadata & { client_id?: string }
+): Client | Error {
+  // the document names itself, so one client's cannot claim another's identity
+  if (metadata.client_id !== id) return ERR_UNKNOWN_CLIENT
+
+  if (
+    !Array.isArray(metadata.redirect_uris) ||
+    metadata.redirect_uris.length === 0 ||
+    metadata.redirect_uris.some((uri) => typeof uri !== 'string')
+  )
+    return ERR_UNKNOWN_CLIENT
+
+  return {
+    client_id: id,
+    client_name: metadata.client_name,
+    client_uri: metadata.client_uri,
+    logo_uri: metadata.logo_uri,
+    redirect_uris: metadata.redirect_uris
+  }
+}
+
+const CACHE = 'cimd:'
+
+/** Held in place of a document that could not be read, so a bad id is not refetched. */
+const MISS = ''

package/components/identity.clients/source/lib/errors.ts

@@ -0,0 +1,4 @@
+export const ERR_UNKNOWN_CLIENT = new (class UnknownClientError extends Error {
+  public readonly code = 'UNKNOWN_CLIENT'
+  public override readonly message = 'No such client'
+})()

package/components/identity.clients/source/lib/index.ts

@@ -0,0 +1,6 @@
+export * from './canonical.ts'
+export * from './cimd.ts'
+export * from './Context.ts'
+export * from './Entity.ts'
+export * from './errors.ts'
+export * from './redirect.ts'

package/components/identity.clients/source/lib/redirect.ts

@@ -0,0 +1,39 @@
+/**
+ * Whether a client may receive a code at this address.
+ *
+ * Exact string comparison, which RFC 6749 §3.1.2.3 requires, except for a loopback
+ * address: a native client binds whatever port is free when it starts, so RFC 8252 §7.3
+ * has the port ignored there. Claude Code registers `http://localhost/callback` and
+ * `http://127.0.0.1/callback` and comes back on an ephemeral port; comparing those
+ * literally would refuse every one of them.
+ */
+export function permits(registered: string[], redirect: string): boolean {
+  return registered.some((uri) => uri === redirect || loopback(uri, redirect))
+}
+
+function loopback(registered: string, redirect: string): boolean {
+  const a = parse(registered)
+  const b = parse(redirect)
+
+  if (a === null || b === null) return false
+
+  return (
+    a.protocol === 'http:' &&
+    b.protocol === 'http:' &&
+    LOOPBACK.has(a.hostname) &&
+    a.hostname === b.hostname &&
+    a.pathname === b.pathname &&
+    a.search === b.search
+  )
+}
+
+function parse(value: string): URL | null {
+  try {
+    return new URL(value)
+  } catch {
+    return null
+  }
+}
+
+/** `localhost` resolves through the host's own configuration, which RFC 8252 §8.3 warns of. */
+const LOOPBACK = new Set(['127.0.0.1', '[::1]', 'localhost'])