@toa.io/extensions.exposition 1.0.0-alpha.282 → 1.0.0-alpha.284

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

@@ -0,0 +1,65 @@
+import { ERR_UNKNOWN_CLIENT, permits, read } from './lib/index.js'
+import type { Maybe } from '@toa.io/core'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Client, Context } from './lib/index.js'
+
+/**
+ * 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,38 @@
+import type { Call, Observation, Transition } from '@toa.io/core'
+import type { Stash } from '@toa.io/extensions.stash'
+import type { Logs } from '@toa.io/extensions.telemetry'
+import type { Entity } from './Entity.js'
+
+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
+}
+
+export type { Transition }

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.test.ts

@@ -0,0 +1,43 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { identify } from './canonical.js'
+import type { Metadata } from './Entity.js'
+
+const metadata: Metadata = {
+  client_name: 'Claude',
+  redirect_uris: ['https://claude.ai/api/mcp/auth_callback', 'http://localhost/callback']
+}
+
+it('should be the id the entity accepts', () => {
+  assert.match(identify('nex', metadata), /^[a-f0-9]{32}$/)
+})
+
+it('should give the same client the same id, however many times it registers', () => {
+  assert.equal(identify('nex', metadata), identify('nex', { ...metadata }))
+})
+
+it('should not depend on the order the redirects were written in', () => {
+  const reordered = { ...metadata, redirect_uris: [...metadata.redirect_uris].reverse() }
+
+  assert.equal(identify('nex', metadata), identify('nex', reordered))
+})
+
+it('should not depend on what is not honoured', () => {
+  const noisy = { ...metadata, token_endpoint_auth_method: 'none' } as Metadata
+
+  assert.equal(identify('nex', metadata), identify('nex', noisy))
+})
+
+it('should separate authorities, which credentials are scoped to', () => {
+  assert.notEqual(identify('nex', metadata), identify('other', metadata))
+})
+
+it('should separate what differs', () => {
+  for (const changed of [
+    { ...metadata, client_name: 'Not Claude' },
+    { ...metadata, redirect_uris: ['https://claude.ai/api/mcp/auth_callback'] },
+    { ...metadata, scope: 'app:notes' }
+  ])
+    assert.notEqual(identify('nex', metadata), identify('nex', changed))
+})

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

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto'
+import type { Metadata } from './Entity.js'
+
+/**
+ * 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.test.ts

@@ -0,0 +1,120 @@
+import { it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { read } from './cimd.js'
+import type { Context } from './Context.js'
+
+const ID = 'https://claude.ai/oauth/claude-code-client-metadata'
+
+const document = {
+  client_id: ID,
+  client_name: 'Claude Code',
+  redirect_uris: ['http://localhost/callback', 'http://127.0.0.1/callback']
+}
+
+let context: Context
+let fetched: string[]
+let stored: Record<string, string>
+
+function respond (body: unknown, ok = true): Response {
+  return {
+    ok,
+    text: async () => JSON.stringify(body)
+  } as unknown as Response
+}
+
+beforeEach(() => {
+  fetched = []
+  stored = {}
+
+  context = {
+    configuration: {
+      trust: ['https://claude.ai'],
+      lifetime: 3600,
+      ttl: 2592000,
+      size: 16384,
+      timeout: 3000
+    },
+    stash: {
+      get: mock.fn(async (key: string) => stored[key] ?? null),
+      set: mock.fn(async (key: string, value: string) => {
+        stored[key] = value
+      })
+    },
+    fetch: mock.fn(async (input: string) => {
+      fetched.push(input)
+
+      return respond(document)
+    }),
+    logs: { debug: mock.fn() }
+  } as unknown as Context
+})
+
+it('should read what the client publishes', async () => {
+  const client = await read(ID, context)
+
+  assert.deepEqual(client, {
+    client_id: ID,
+    client_name: 'Claude Code',
+    client_uri: undefined,
+    logo_uri: undefined,
+    redirect_uris: document.redirect_uris
+  })
+})
+
+it('should hold it, rather than read it per request', async () => {
+  await read(ID, context)
+  await read(ID, context)
+
+  assert.equal(fetched.length, 1)
+})
+
+it('should not reach an origin the configuration does not name', async () => {
+  const client = await read('https://evil.example/metadata', context)
+
+  assert.ok(client instanceof Error)
+  assert.equal(fetched.length, 0, 'an untrusted origin must not be fetched at all')
+})
+
+it('should not reach a host that merely starts like a trusted one', async () => {
+  const client = await read('https://claude.ai.evil.example/metadata', context)
+
+  assert.ok(client instanceof Error)
+  assert.equal(fetched.length, 0)
+})
+
+it('should refuse anything but https', async () => {
+  for (const id of ['http://claude.ai/metadata', 'file:///etc/passwd', 'not a url']) {
+    const client = await read(id, context)
+
+    assert.ok(client instanceof Error, id)
+  }
+
+  assert.equal(fetched.length, 0)
+})
+
+it('should refuse a document that names another client', async () => {
+  context.fetch = mock.fn(async () => respond({ ...document, client_id: 'https://claude.ai/other' }))
+
+  assert.ok(await read(ID, context) instanceof Error)
+})
+
+it('should refuse a document with no redirect to send a code to', async () => {
+  context.fetch = mock.fn(async () => respond({ client_id: ID, redirect_uris: [] }))
+
+  assert.ok(await read(ID, context) instanceof Error)
+})
+
+it('should remember that a document did not answer', async () => {
+  let calls = 0
+
+  context.fetch = mock.fn(async () => {
+    calls++
+
+    return respond({}, false)
+  })
+
+  assert.ok(await read(ID, context) instanceof Error)
+  assert.ok(await read(ID, context) instanceof Error)
+  assert.equal(calls, 1, 'a document that failed must not be refetched per request')
+})

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

@@ -0,0 +1,107 @@
+import { createHash } from 'node:crypto'
+import { ERR_UNKNOWN_CLIENT } from './errors.js'
+import type { Context } from './Context.js'
+import type { Client, Metadata } from './Entity.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: 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.js'
+export * from './cimd.js'
+export * from './Context.js'
+export * from './Entity.js'
+export * from './errors.js'
+export * from './redirect.js'

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

@@ -0,0 +1,41 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { permits } from './redirect.js'
+
+const hosted = ['https://claude.ai/api/mcp/auth_callback']
+const native = ['http://localhost/callback', 'http://127.0.0.1/callback']
+
+it('should permit an exact match', () => {
+  assert.equal(permits(hosted, 'https://claude.ai/api/mcp/auth_callback'), true)
+})
+
+it('should refuse anything else on a registered host', () => {
+  assert.equal(permits(hosted, 'https://claude.ai/api/mcp/auth_callback/x'), false)
+  assert.equal(permits(hosted, 'https://claude.ai/'), false)
+})
+
+it('should refuse a host that merely starts the same way', () => {
+  assert.equal(permits(hosted, 'https://claude.ai.evil.example/api/mcp/auth_callback'), false)
+})
+
+it('should ignore the port of a loopback address', () => {
+  for (const redirect of [
+    'http://localhost:3118/callback',
+    'http://localhost:51234/callback',
+    'http://127.0.0.1:3118/callback'
+  ])
+    assert.equal(permits(native, redirect), true)
+})
+
+it('should not ignore the path of a loopback address', () => {
+  assert.equal(permits(native, 'http://localhost:3118/stolen'), false)
+})
+
+it('should not treat a remote address as loopback', () => {
+  assert.equal(permits(['http://example.com/callback'], 'http://example.com:8080/callback'), false)
+})
+
+it('should not cross schemes', () => {
+  assert.equal(permits(native, 'https://localhost:3118/callback'), false)
+})

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

@@ -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: 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'])

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

@@ -0,0 +1,125 @@
+import { identify } from './lib/index.js'
+import type { Maybe } from '@toa.io/core'
+import type { Operation } from '@toa.io/bridges.node'
+import type { Context, Metadata } 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 implements Operation {
+  private transit!: Context['local']['transit']
+  private ttl!: number
+
+  public mount (context: Context): void {
+    this.transit = context.local.transit
+    this.ttl = context.configuration.ttl
+  }
+
+  public async execute (input: Input): Promise<Maybe<Output>> {
+    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: Metadata = {
+      client_name: input.client_name,
+      client_uri: input.client_uri,
+      logo_uri: input.logo_uri,
+      scope: input.scope,
+      redirect_uris: uris as string[]
+    }
+
+    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: string): string | Error {
+  let url: 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: string, description: string): Output {
+  return { status: BAD_REQUEST, error, error_description: description }
+}
+
+const BAD_REQUEST = 400
+
+const LOOPBACK = new Set(['127.0.0.1', '[::1]', 'localhost'])
+
+interface Input extends Metadata {
+  authority: string
+}
+
+interface Output {
+  /** Read and removed by `map:status`; absent on a success, which answers 201. */
+  status?: number
+  client_id?: string
+  client_id_issued_at?: number
+  client_name?: string
+  client_uri?: string
+  logo_uri?: string
+  redirect_uris?: string[]
+  grant_types?: string[]
+  response_types?: string[]
+  token_endpoint_auth_method?: string
+  error?: string
+  error_description?: string
+}

package/components/identity.clients/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.component.json",
+  "compilerOptions": {
+    "outDir": "./operations",
+    "rootDir": "./source"
+  },
+  "include": [
+    "source"
+  ]
+}