@conciergeprotocol/client 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@conciergeprotocol/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Call any Concierge Agent Protocol front door.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conciergeprotocol/js.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.js

@@ -0,0 +1,446 @@
+import { CapError, NoDoorError } from './errors.js'
+import { fetchDoor } from './door.js'
+
+const MAX_CONTEXT = 4 * 1024
+const SENSITIVE_KEY = /password|secret|token/i
+const FROM = /^agent:[A-Za-z0-9_.-]{1,64}$/
+
+function memoryCache(now) {
+  const store = new Map()
+  return {
+    get(key) {
+      const hit = store.get(key)
+      if (!hit || hit.expiresAt <= now()) {
+        store.delete(key)
+        return undefined
+      }
+      return hit
+    },
+    set(key, value) {
+      store.set(key, value)
+    },
+  }
+}
+
+function assertFrom(from) {
+  if (typeof from !== 'string' || !FROM.test(from)) {
+    throw new CapError('invalid_request', 0, 'from must be agent:{id}.')
+  }
+}
+
+function assertContext(context) {
+  if (context == null) return
+  if (typeof context !== 'object' || Array.isArray(context)) {
+    throw new CapError('invalid_request', 0, 'context must be an object.')
+  }
+  if (JSON.stringify(context).length > MAX_CONTEXT) {
+    throw new CapError('invalid_request', 0, 'context is too long.')
+  }
+  const walk = (value) => {
+    if (!value || typeof value !== 'object') return
+    for (const [key, child] of Object.entries(value)) {
+      if (SENSITIVE_KEY.test(key)) {
+        throw new CapError('invalid_request', 0, 'context cannot include a password, secret, or token.')
+      }
+      walk(child)
+    }
+  }
+  walk(context)
+}
+
+function parseRetryAfter(header) {
+  if (!header) return null
+  const seconds = Number(header)
+  if (Number.isFinite(seconds)) return Math.max(0, seconds)
+  const date = Date.parse(header)
+  if (Number.isNaN(date)) return null
+  return Math.max(0, Math.round((date - Date.now()) / 1000))
+}
+
+function defaultCode(status) {
+  if (status === 401) return 'unauthorized'
+  if (status === 403) return 'forbidden'
+  if (status === 404) return 'not_found'
+  if (status === 409) return 'conflict'
+  if (status === 429) return 'rate_limited'
+  if (status === 503) return 'unavailable'
+  if (status === 400) return 'invalid_request'
+  return 'unavailable'
+}
+
+async function errorFrom(response) {
+  let body = null
+  try {
+    body = await response.json()
+  } catch {
+    body = null
+  }
+  const code = body?.error?.code || defaultCode(response.status)
+  const message = body?.error?.message || 'Request failed.'
+  const retryAfter = parseRetryAfter(response.headers.get('retry-after'))
+  return new CapError(code, response.status, message, { retryAfter })
+}
+
+function normalize(body) {
+  if (!body || typeof body !== 'object' || typeof body.id !== 'string') {
+    throw new CapError('invalid_request', 0, 'The owner returned an unreadable message.')
+  }
+  if (body.status !== 'working' && body.status !== 'done' && body.status !== 'failed') {
+    throw new CapError('invalid_request', 0, 'The owner returned an unreadable message.')
+  }
+  const message = {
+    id: body.id,
+    status: body.status,
+    created_at: body.created_at,
+    finished_at: body.finished_at ?? null,
+  }
+  if (body.status === 'done' && typeof body.reply === 'string') message.reply = body.reply
+  if (body.status === 'failed' && body.error && typeof body.error === 'object') {
+    message.error = { code: String(body.error.code || 'failed'), message: String(body.error.message || '') }
+  }
+  if (body.status === 'done' && body.confirmation) message.confirmation = body.confirmation
+  return message
+}
+
+function base64url(bytes) {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+async function pkcePair() {
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  const verifier = base64url(bytes)
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  return { verifier, challenge: base64url(new Uint8Array(digest)) }
+}
+
+function metadataUrl(oauth) {
+  const issuer = new URL(oauth)
+  const path = issuer.pathname.replace(/\/$/, '')
+  return new URL(`/.well-known/oauth-authorization-server${path}`, issuer.origin).toString()
+}
+
+function messagesUrl(door, id) {
+  const base = door.cap.replace(/\/$/, '')
+  return id ? `${base}/messages/${encodeURIComponent(id)}` : `${base}/messages`
+}
+
+export function createClient(options = {}) {
+  const from = options.from
+  assertFrom(from)
+  const fetchImpl = options.fetch || globalThis.fetch
+  const tokens = options.tokens || null
+  const maxWaitMs = options.maxWaitMs ?? 120_000
+  const now = options.now || (() => Date.now())
+  const sleep = options.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  const cache = options.cache || memoryCache(now)
+  const pendingLogins = new Map()
+
+  async function cachedDoor(target) {
+    if (target && typeof target === 'object' && typeof target.cap === 'string') return target
+    const key = String(target || '').trim().toLowerCase()
+    const hit = await cache.get(key)
+    if (hit && hit.expiresAt > now()) return hit.value
+    let loaded
+    try {
+      loaded = await fetchDoor(target, fetchImpl)
+    } catch (err) {
+      if (err?.name === 'AbortError') throw err
+      throw new CapError('unavailable', 0, 'The front door could not be reached.')
+    }
+    await cache.set(key, { value: loaded.door, expiresAt: now() + loaded.ttl })
+    return loaded.door
+  }
+
+  async function doorFor(target) {
+    const door = await cachedDoor(target)
+    if (!door) throw new NoDoorError(typeof target === 'string' ? target : 'this target')
+    return door
+  }
+
+  function originOf(door) {
+    return door.origin || new URL(door.cap).origin
+  }
+
+  async function currentToken(door) {
+    if (!tokens) return null
+    return (await tokens.get(originOf(door))) || null
+  }
+
+  async function wait(ms, signal) {
+    if (signal?.aborted) throw new DOMException('The operation was aborted.', 'AbortError')
+    await sleep(ms)
+    if (signal?.aborted) throw new DOMException('The operation was aborted.', 'AbortError')
+  }
+
+  async function refresh(token) {
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: token.refreshToken,
+      client_id: token.clientId,
+    })
+    const response = await fetchImpl(token.tokenEndpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body,
+    })
+    if (!response.ok) throw new CapError('unauthorized', response.status, 'The login could not be renewed.')
+    const json = await response.json()
+    if (!json?.access_token) throw new CapError('unauthorized', response.status, 'The login could not be renewed.')
+    return {
+      ...token,
+      accessToken: json.access_token,
+      refreshToken: json.refresh_token || token.refreshToken,
+      scope: json.scope || token.scope,
+      expiresAt: json.expires_in ? now() + Number(json.expires_in) * 1000 : token.expiresAt,
+    }
+  }
+
+  async function send(url, { method, json, token, idempotencyKey, signal }) {
+    const headers = {
+      'cap-version': '1.0',
+      'cap-from': from,
+      accept: 'application/json',
+    }
+    if (json) headers['content-type'] = 'application/json'
+    if (idempotencyKey) headers['idempotency-key'] = idempotencyKey
+    if (token?.accessToken) headers.authorization = `Bearer ${token.accessToken}`
+    return fetchImpl(url, {
+      method,
+      headers,
+      body: json ? JSON.stringify(json) : undefined,
+      signal,
+    })
+  }
+
+  async function call(door, makeRequest, { signal, deadline, allowNetworkRetry }) {
+    let token = await currentToken(door)
+    let refreshed = false
+    let networkRetried = false
+    let rateRetried = false
+    for (;;) {
+      let response
+      try {
+        response = await makeRequest(token)
+      } catch (err) {
+        if (err?.name === 'AbortError') throw err
+        if (allowNetworkRetry && !networkRetried) {
+          networkRetried = true
+          continue
+        }
+        throw new CapError('unavailable', 0, 'The front door could not be reached.')
+      }
+      if (response.status === 401 && tokens) {
+        if (!refreshed && token?.refreshToken && token.tokenEndpoint) {
+          refreshed = true
+          try {
+            token = await refresh(token)
+            await tokens.set(originOf(door), token)
+            continue
+          } catch {
+            await tokens.delete(originOf(door))
+          }
+        } else {
+          await tokens.delete(originOf(door))
+        }
+        throw await errorFrom(response)
+      }
+      if ((response.status === 429 || response.status === 503) && !rateRetried) {
+        const retryAfter = parseRetryAfter(response.headers.get('retry-after')) ?? 1
+        const delay = Math.max(1, retryAfter) * 1000
+        if (deadline - now() >= delay) {
+          rateRetried = true
+          await wait(delay, signal)
+          continue
+        }
+        throw await errorFrom(response)
+      }
+      if (response.status >= 400) throw await errorFrom(response)
+      return response
+    }
+  }
+
+  async function readMessage(door, id, { signal, deadline }) {
+    const response = await call(door, (token) => send(messagesUrl(door, id), { method: 'GET', token, signal }), {
+      signal,
+      deadline,
+      allowNetworkRetry: true,
+    })
+    const retryAfter = parseRetryAfter(response.headers.get('retry-after'))
+    const message = normalize(await response.json())
+    return { message, retryAfter }
+  }
+
+  async function ask(target, message, askOptions = {}) {
+    if (typeof message !== 'string' || !message.trim()) {
+      throw new CapError('invalid_request', 0, 'message is required.')
+    }
+    assertContext(askOptions.context)
+    const door = await doorFor(target)
+    const deadline = now() + maxWaitMs
+    const idempotencyKey = askOptions.idempotencyKey || crypto.randomUUID()
+    const payload = { message }
+    if (askOptions.context) payload.context = askOptions.context
+    if (askOptions.previousMessageId) payload.previous_message_id = askOptions.previousMessageId
+    const response = await call(
+      door,
+      (token) => send(messagesUrl(door), { method: 'POST', json: payload, token, idempotencyKey, signal: askOptions.signal }),
+      { signal: askOptions.signal, deadline, allowNetworkRetry: true }
+    )
+    let current = normalize(await response.json())
+    let retryAfter = parseRetryAfter(response.headers.get('retry-after'))
+    while (current.status === 'working') {
+      const delay = Math.max(1, retryAfter ?? 1) * 1000
+      if (deadline - now() < delay) return current
+      await wait(delay, askOptions.signal)
+      const next = await readMessage(door, current.id, { signal: askOptions.signal, deadline })
+      current = next.message
+      retryAfter = next.retryAfter
+    }
+    return current
+  }
+
+  async function get(target, id) {
+    if (typeof id !== 'string' || !id) throw new CapError('invalid_request', 0, 'message id is required.')
+    const door = await doorFor(target)
+    const read = await readMessage(door, id, { deadline: now() + maxWaitMs })
+    return read.message
+  }
+
+  function thread(target) {
+    let previousId = null
+    const api = {
+      restarted: false,
+      async ask(message, askOptions = {}) {
+        api.restarted = false
+        const options = { ...askOptions, previousMessageId: previousId || undefined }
+        try {
+          const result = await ask(target, message, options)
+          previousId = result.id
+          return result
+        } catch (err) {
+          if (err instanceof CapError && err.code === 'not_found') previousId = null
+          if (err instanceof CapError && err.code === 'conflict' && previousId) {
+            previousId = null
+            api.restarted = true
+            const { previousMessageId: _ignored, ...rest } = askOptions
+            const result = await ask(target, message, rest)
+            previousId = result.id
+            return result
+          }
+          throw err
+        }
+      },
+    }
+    return api
+  }
+
+  async function login(target, loginOptions) {
+    const door = await doorFor(target)
+    if (!door.oauth) throw new CapError('invalid_request', 0, 'This front door has no login.')
+    const metaResponse = await fetchImpl(metadataUrl(door.oauth), { headers: { accept: 'application/json' } })
+    if (!metaResponse.ok) throw new CapError('unavailable', metaResponse.status, 'The login server could not be read.')
+    const metadata = await metaResponse.json()
+    if (!metadata?.authorization_endpoint || !metadata?.token_endpoint) {
+      throw new CapError('invalid_request', 0, 'This front door has no redirect login.')
+    }
+    const { verifier, challenge } = await pkcePair()
+    const state = crypto.randomUUID()
+    const url = new URL(metadata.authorization_endpoint)
+    url.searchParams.set('response_type', 'code')
+    url.searchParams.set('client_id', loginOptions.clientId)
+    url.searchParams.set('redirect_uri', loginOptions.redirectUri)
+    url.searchParams.set('state', state)
+    url.searchParams.set('code_challenge', challenge)
+    url.searchParams.set('code_challenge_method', 'S256')
+    if (loginOptions.scope) url.searchParams.set('scope', loginOptions.scope)
+    const result = new Promise((resolve, reject) => {
+      pendingLogins.set(state, {
+        resolve,
+        reject,
+        verifier,
+        clientId: loginOptions.clientId,
+        redirectUri: loginOptions.redirectUri,
+        door,
+        metadata,
+      })
+    })
+    try {
+      await loginOptions.open(url.toString())
+    } catch (err) {
+      pendingLogins.delete(state)
+      throw err
+    }
+    return result
+  }
+
+  async function finishLogin(callbackUrl) {
+    const url = new URL(callbackUrl)
+    const state = url.searchParams.get('state')
+    const pending = state ? pendingLogins.get(state) : null
+    if (!pending) throw new CapError('invalid_request', 0, 'This login session is unknown.')
+    pendingLogins.delete(state)
+    const fail = (error) => {
+      pending.reject(error)
+      throw error
+    }
+    const oauthError = url.searchParams.get('error')
+    if (oauthError) {
+      fail(new CapError(oauthError, 0, url.searchParams.get('error_description') || 'Login was denied.'))
+    }
+    const code = url.searchParams.get('code')
+    if (!code) fail(new CapError('invalid_request', 0, 'The login redirect had no code.'))
+    try {
+      const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: pending.redirectUri,
+        client_id: pending.clientId,
+        code_verifier: pending.verifier,
+      })
+      const response = await fetchImpl(pending.metadata.token_endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body,
+      })
+      if (!response.ok) throw new CapError('unauthorized', response.status, 'The login could not be completed.')
+      const json = await response.json()
+      if (!json?.access_token) throw new CapError('unauthorized', response.status, 'The login could not be completed.')
+      const token = {
+        accessToken: json.access_token,
+        refreshToken: json.refresh_token,
+        scope: json.scope,
+        expiresAt: json.expires_in ? now() + Number(json.expires_in) * 1000 : undefined,
+        clientId: pending.clientId,
+        tokenEndpoint: pending.metadata.token_endpoint,
+        revocationEndpoint: pending.metadata.revocation_endpoint,
+      }
+      if (tokens) await tokens.set(originOf(pending.door), token)
+      pending.resolve(token)
+      return token
+    } catch (err) {
+      pending.reject(err)
+      throw err
+    }
+  }
+
+  async function logout(target) {
+    const door = await doorFor(target)
+    if (!tokens) return
+    const key = originOf(door)
+    const token = await tokens.get(key)
+    if (token?.refreshToken && token.revocationEndpoint) {
+      const body = new URLSearchParams({ token: token.refreshToken, client_id: token.clientId || '' })
+      await fetchImpl(token.revocationEndpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body,
+      }).catch(() => {})
+    }
+    await tokens.delete(key)
+  }
+
+  return { discover: cachedDoor, ask, get, thread, login, finishLogin, logout }
+}

package/src/door.js

@@ -0,0 +1,120 @@
+const MAX_FILE = 16 * 1024
+const FOUND_TTL = 60 * 60 * 1000
+const MISSING_TTL = 10 * 60 * 1000
+const KNOWN = new Set(['protocol', 'name', 'chat', 'cap', 'oauth', 'spec'])
+
+export function isLoopback(hostname) {
+  const host = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '')
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1'
+}
+
+function siteHost(hostname) {
+  return String(hostname || '').toLowerCase().replace(/\.$/, '').replace(/^www\./, '')
+}
+
+export function sameSite(left, right) {
+  const a = siteHost(left)
+  const b = siteHost(right)
+  if (!a || !b) return false
+  return a === b || a.endsWith(`.${b}`) || b.endsWith(`.${a}`)
+}
+
+function allowedProtocol(url) {
+  return url.protocol === 'https:' || (url.protocol === 'http:' && isLoopback(url.hostname))
+}
+
+export function agentTxtUrl(input) {
+  const raw = String(input || '').trim()
+  if (!raw) return null
+  let url
+  try {
+    url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`)
+  } catch {
+    return null
+  }
+  if (!allowedProtocol(url)) return null
+  url.pathname = '/agent.txt'
+  url.search = ''
+  url.hash = ''
+  url.username = ''
+  url.password = ''
+  return url
+}
+
+function cacheTtl(header, fallback) {
+  const match = /max-age=(\d+)/i.exec(header || '')
+  return match ? Number(match[1]) * 1000 : fallback
+}
+
+export function parseAgentTxt(text, origin) {
+  const fields = {}
+  const extra = {}
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    const split = trimmed.indexOf(':')
+    if (split <= 0) continue
+    const key = trimmed.slice(0, split).trim().toLowerCase()
+    const value = trimmed.slice(split + 1).trim()
+    if (!key || !value) continue
+    if (KNOWN.has(key)) fields[key] = value
+    else extra[key] = value
+  }
+  let cap
+  try {
+    const url = new URL(fields.cap || '')
+    if (!allowedProtocol(url) || url.username || url.password) return null
+    cap = url.toString().replace(/\/$/, '')
+  } catch {
+    return null
+  }
+  return {
+    protocol: fields.protocol || null,
+    name: fields.name || null,
+    chat: fields.chat || null,
+    cap,
+    oauth: fields.oauth || null,
+    spec: fields.spec || null,
+    origin,
+    extra,
+  }
+}
+
+async function readDoor(response, finalUrl) {
+  if (response.status !== 200) return { door: null, ttl: MISSING_TTL }
+  const type = response.headers.get('content-type') || ''
+  if (/text\/html|application\/xhtml/i.test(type)) return { door: null, ttl: MISSING_TTL }
+  const length = Number(response.headers.get('content-length'))
+  if (Number.isFinite(length) && length > MAX_FILE) return { door: null, ttl: MISSING_TTL }
+  const text = await response.text()
+  if (text.length > MAX_FILE || text.trimStart().startsWith('<')) return { door: null, ttl: MISSING_TTL }
+  const door = parseAgentTxt(text, new URL(finalUrl).origin)
+  if (!door) return { door: null, ttl: MISSING_TTL }
+  return { door, ttl: cacheTtl(response.headers.get('cache-control'), FOUND_TTL) }
+}
+
+export async function fetchDoor(input, fetchImpl) {
+  const start = agentTxtUrl(input)
+  if (!start) return { door: null, ttl: MISSING_TTL }
+  let current = start
+  for (let hop = 0; hop < 5; hop += 1) {
+    const response = await fetchImpl(current, {
+      redirect: 'manual',
+      headers: { accept: 'text/plain, text/markdown, */*' },
+    })
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const location = response.headers.get('location')
+      if (!location) return { door: null, ttl: MISSING_TTL }
+      const next = new URL(location, current)
+      if (!allowedProtocol(next) || !sameSite(start.hostname, next.hostname)) {
+        return { door: null, ttl: MISSING_TTL }
+      }
+      next.username = ''
+      next.password = ''
+      current = next
+      continue
+    }
+    return readDoor(response, current)
+  }
+  return { door: null, ttl: MISSING_TTL }
+}

package/src/errors.js

@@ -0,0 +1,17 @@
+export class CapError extends Error {
+  constructor(code, status, message, options = {}) {
+    super(message)
+    this.name = 'CapError'
+    this.code = code
+    this.status = status
+    if (options.retryAfter != null) this.retryAfter = options.retryAfter
+  }
+}
+
+export class NoDoorError extends Error {
+  constructor(domain) {
+    super(`${domain} has no CAP front door.`)
+    this.name = 'NoDoorError'
+    this.domain = domain
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,88 @@
+export class CapError extends Error {
+  code: string
+  status: number
+  retryAfter?: number
+  constructor(code: string, status: number, message: string, options?: { retryAfter?: number })
+}
+
+export class NoDoorError extends Error {
+  domain: string
+  constructor(domain: string)
+}
+
+export type Door = {
+  protocol: string | null
+  name: string | null
+  chat: string | null
+  cap: string
+  oauth: string | null
+  spec: string | null
+  origin: string
+  extra: Record<string, string>
+}
+
+export type Message = {
+  id: string
+  status: 'working' | 'done' | 'failed'
+  reply?: string
+  error?: { code: string; message: string }
+  confirmation?: unknown
+  created_at?: string
+  finished_at?: string | null
+}
+
+export type Token = {
+  accessToken: string
+  refreshToken?: string
+  scope?: string
+  expiresAt?: number
+  clientId?: string
+  tokenEndpoint?: string
+  revocationEndpoint?: string
+}
+
+export type TokenStore = {
+  get(origin: string): Token | undefined | Promise<Token | undefined>
+  set(origin: string, token: Token): void | Promise<void>
+  delete(origin: string): void | Promise<void>
+}
+
+export type AskOptions = {
+  context?: Record<string, unknown>
+  previousMessageId?: string
+  idempotencyKey?: string
+  signal?: AbortSignal
+}
+
+export type Thread = {
+  restarted: boolean
+  ask(message: string, options?: AskOptions): Promise<Message>
+}
+
+export type Client = {
+  discover(domain: string): Promise<Door | null>
+  ask(target: string | Door, message: string, options?: AskOptions): Promise<Message>
+  get(target: string | Door, id: string): Promise<Message>
+  thread(target: string | Door): Thread
+  login(target: string | Door, options: {
+    clientId: string
+    redirectUri: string
+    open: (url: string) => void | Promise<void>
+    scope?: string
+  }): Promise<Token>
+  finishLogin(callbackUrl: string): Promise<Token>
+  logout(target: string | Door): Promise<void>
+}
+
+export function createClient(options: {
+  from: string
+  fetch?: typeof fetch
+  tokens?: TokenStore
+  maxWaitMs?: number
+  cache?: {
+    get(key: string): unknown
+    set(key: string, value: unknown): unknown
+  }
+  now?: () => number
+  sleep?: (ms: number) => Promise<void> | void
+}): Client

package/src/index.js

@@ -0,0 +1,2 @@
+export { CapError, NoDoorError } from './errors.js'
+export { createClient } from './client.js'

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.