@conciergeprotocol/server 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @conciergeprotocol/server
 
-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.
+Run a [Concierge Agent Protocol](https://conciergeprotocol.org) front door. You write one function, `answer`. The package serves `agent.txt`, keeps the thread, hides one caller's reply from another, and enforces the daily message cap.
+
+The protocol is at [conciergeprotocol.org](https://conciergeprotocol.org). Publishing a door is described in [Publish a door](https://conciergeprotocol.org/publish).
+
+## Install
+
+```sh
+npm install @conciergeprotocol/server
+```
+
+Node.js 22 or newer. Messages are stored in SQLite. Set `DATABASE_URL` to a Postgres connection string to use Postgres, and install `pg`.
+
+## Answer
+
+`answer` receives the question and returns the reply. A string, or `{ reply }`. Keys, tools, and records stay inside this function. The caller only sees the reply.
+
+```js
+import { createCapServer } from '@conciergeprotocol/server'
+
+const cap = await createCapServer({
+  agent: { name: 'Harbor Goods', chat: 'https://harborgoods.example/chat' },
+  answer: async ({ message, context, history }) => {
+    const res = await fetch('https://support.example/api/ask', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${process.env.SUPPORT_BOT_KEY}`,
+      },
+      body: JSON.stringify({ question: message, brief: context, history }),
+    })
+    if (!res.ok) return { error: { code: 'failed', message: 'The agent could not answer.' } }
+    const { text } = await res.json()
+    return { reply: text }
+  },
+})
+
+await cap.listen(8088)
+```
+
+`history` is the earlier turns, oldest first. The caller sends `previous_message_id` and does not resend them. `context` is the optional brief from the visiting agent. `account` and `scope` are null until someone logs in.
+
+Return `{ error: { code: 'login_required', message: '...' } }` when the question needs an account. While a message is still running, the caller gets `202` and no reply.
+
+The server waits `waitSeconds` (default 20). A longer answer finishes in the background. `dailyLimit` caps messages per caller per UTC day. `0` turns the cap off. Finished messages stay readable for `retentionHours` (default 24).
+
+Without `sqlitePath` or `DATABASE_URL`, messages go to `data/cap.sqlite` in the working directory. Pass `sqlitePath: ':memory:'` for a process that keeps nothing.
+
+## The file on the company domain
+
+This process can run on any host. The company domain still serves `agent.txt`. Point `CAP` at this server, or rewrite `/cap/v1` to it. Set `publicUrl` when the public origin differs from the request host.
+
+```text
+Protocol: CAP/1.0
+Name: Harbor Goods
+Chat: https://harborgoods.example/chat
+CAP: https://cap.harborgoods.example/cap/v1
+Spec: https://conciergeprotocol.org/cap.txt
+```
+
+Check it:
+
+```sh
+npx cap-check https://cap.harborgoods.example
+```
+
+`cap-check` reads `agent.txt`, asks one question, and confirms a second caller cannot read the reply.
+
+## Next.js
+
+`createCapHandler` returns a Fetch handler. Use a durable store (`sqlitePath` on a disk, or `databaseUrl`). A memory store loses an in-flight answer when the function instance stops.
+
+```js
+import { createCapHandler } from '@conciergeprotocol/server'
+import { answer } from './answer.js'
+
+const door = await createCapHandler({
+  agent: { name: 'Harbor Goods' },
+  answer,
+  databaseUrl: process.env.DATABASE_URL,
+})
+
+export const GET = (request) => door.handle(request)
+export const POST = (request) => door.handle(request)
+export const OPTIONS = (request) => door.handle(request)
+```
+
+Serve `agent.txt` from the company domain. The handler above also serves it at `/agent.txt` on this app.
+
+## Log in
+
+Pass `login` to turn on the built-in OAuth server. It adds the `OAuth` line to `agent.txt`. `login` checks the company's own user store and returns an account id, or null.
+
+```js
+const cap = await createCapServer({
+  agent: { name: 'Harbor Goods' },
+  answer,
+  login: async ({ username, password }) => verifyUser(username, password),
+})
+```
+
+With a token, `answer` receives `account` and `scope` (`read` or `write`). A token sent by a different agent is `403`.
+
+If people are usually signed in to your site already, pass `currentAccount` too. It reads your own session from the request headers and returns the account id, or null. When it finds one, the login and confirm pages show only Allow or Approve. Without a session, they fall back to `login`. A confirm page asks for a login when the session is for a different account than the request.
+
+```js
+const cap = await createCapServer({
+  agent: { name: 'Harbor Goods' },
+  answer,
+  login: async ({ username, password }) => verifyUser(username, password),
+  currentAccount: async ({ headers }) => accountFromSessionCookie(headers.cookie),
+})
+```
+
+Serve `/oauth` on the same origin as your sign-in, so your session cookie reaches it. A signed-in approval also needs a `SameSite=Strict` cookie the page sets, so a form on another site cannot submit it.
+
+To hold a change for the person's approval, return `{ confirm: { summary, authorization_details }, reply }` instead of running it. After they approve, the server calls `act` once.
+
+## Account routes
+
+Another agent can call your own JSON routes with the same token, for example a hosted agent that answers public questions itself and fetches account data from you. `accountFor(request)` checks the bearer token against the agent in `CAP-From` and returns `{ account, scope, caller }`, or null. Filter every query by `account`.
+
+```js
+export async function GET(request) {
+  const access = await door.accountFor(request)
+  if (!access) return Response.json({ error: { code: 'login_required' } }, { status: 401 })
+  return Response.json({ account: access.account, orders: await ordersFor(access.account) })
+}
+```
+
+`requestApproval(request, { summary, authorization_details })` holds a change for the person's OK and returns `{ confirmation: { id, url, summary } }`. It needs a write login and `act`, which runs once after approval.
+
+## cap.json
+
+`cap-server` reads `cap.json` from the working directory, or `CAP_CONFIG`. The same file the reference server uses:
+
+```json
+{
+  "agent": { "name": "Harbor Goods", "chat": "https://harborgoods.example/chat" },
+  "handler": { "type": "http", "url": "https://support.example/cap-hook" },
+  "daily_limit": 500
+}
+```
+
+`static` returns fixed text. `echo` returns the message. `http` POSTs `{ message, context, history, account, scope }` to a URL and expects `{ "reply": "..." }`. Set `handler.secret_env` to send that environment variable as `X-Cap-Secret`.
+
+```sh
+npx cap-server
+```
+
+The HTTP, storage, and OAuth modules match the reference server in the protocol repository. A spec change belongs in both places.
+
+## License
+
+Apache 2.0

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@conciergeprotocol/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Run a Concierge Agent Protocol front door. You write the answer.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "bin": {
+    "cap-server": "./src/cli.js",
+    "cap-check": "./src/check.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://conciergeprotocol.org",
+  "keywords": [
+    "concierge",
+    "cap",
+    "agents",
+    "protocol",
+    "server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conciergeprotocol/js.git",
+    "directory": "packages/server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "pg": "^8.16.0"
+  }
+}

package/src/check.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { checkDoor } from './check.mjs'
+
+const origin = process.argv[2]
+if (!origin) {
+  console.error('Usage: cap-check <origin>')
+  process.exit(1)
+}
+
+const result = await checkDoor(origin)
+if (result.ok) {
+  console.log(`${origin} passes.`)
+} else {
+  for (const failure of result.failures) console.error(failure)
+  process.exit(1)
+}

package/src/check.mjs

@@ -0,0 +1,91 @@
+const FROM = 'agent:cap-check'
+const OTHER = 'agent:cap-check-other'
+
+/**
+ * Four checks a door has to pass: agent.txt, one answered question,
+ * and a second caller who cannot read that reply.
+ */
+export async function checkDoor(origin, options = {}) {
+  const fetchImpl = options.fetch || fetch
+  const root = String(origin || '').replace(/\/$/, '')
+  const failures = []
+  const fail = (message) => failures.push(message)
+  if (!root) return { ok: false, failures: ['Pass the door origin, such as http://127.0.0.1:8088.'] }
+
+  let card = ''
+  try {
+    const cardRes = await fetchImpl(`${root}/agent.txt`)
+    card = await cardRes.text()
+    if (cardRes.status !== 200) fail(`agent.txt returned ${cardRes.status}.`)
+  } catch (err) {
+    fail(`agent.txt could not be fetched: ${err.message}`)
+  }
+  if (card && !card.startsWith('Protocol: CAP/1.0')) fail('agent.txt must start with Protocol: CAP/1.0.')
+  const capLine = card.split('\n').find((line) => line.startsWith('CAP: '))
+  const capUrl = capLine ? capLine.slice(5).trim() : ''
+  if (capLine && !/^https?:\/\//.test(capUrl)) fail('agent.txt needs an http or https CAP URL.')
+  if (card && !capLine) fail('agent.txt needs a CAP line.')
+
+  const headers = {
+    'content-type': 'application/json',
+    'cap-version': '1.0',
+    'cap-from': FROM,
+  }
+  const timeoutMs = options.timeoutMs ?? 25_000
+  let id = ''
+  try {
+    const done = await ask(fetchImpl, root, headers, options.message || 'What can you help with?', timeoutMs)
+    if (done.body?.status !== 'done' || typeof done.body.reply !== 'string') {
+      fail('The question did not finish with a reply.')
+    }
+    id = done.body?.id || ''
+  } catch (err) {
+    fail(err.message)
+  }
+
+  if (id) {
+    try {
+      const other = await fetchImpl(`${root}/cap/v1/messages/${encodeURIComponent(id)}`, {
+        headers: { ...headers, 'cap-from': OTHER },
+      })
+      if (other.status !== 404) fail('A second caller could read the reply.')
+    } catch (err) {
+      fail(`The second caller check failed: ${err.message}`)
+    }
+  }
+
+  return { ok: failures.length === 0, failures }
+}
+
+async function ask(fetchImpl, root, headers, message, timeoutMs) {
+  let res = await fetchImpl(`${root}/cap/v1/messages`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ message }),
+  })
+  let body = await readJson(res)
+  const deadline = Date.now() + timeoutMs
+  while (res.status === 202 || body?.status === 'working') {
+    if (Date.now() > deadline) throw new Error('The question was not answered in time.')
+    const loc = res.headers.get('location')
+    const url = loc
+      ? (loc.startsWith('http') ? loc : `${root}${loc.startsWith('/') ? '' : '/'}${loc}`)
+      : `${root}/cap/v1/messages/${encodeURIComponent(body?.id || '')}`
+    const retryAfter = Number(res.headers.get('retry-after') || 1)
+    const wait = Math.min((Number.isFinite(retryAfter) ? retryAfter : 1) * 1000, 2000)
+    await new Promise((resolve) => setTimeout(resolve, wait))
+    res = await fetchImpl(url, { headers })
+    body = await readJson(res)
+  }
+  return { res, body }
+}
+
+async function readJson(res) {
+  const text = await res.text()
+  if (!text) return null
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}

package/src/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { boot } from './config.mjs'
+
+const { server } = await boot()
+const port = Number(process.env.PORT || 8088)
+const host = process.env.HOST || '0.0.0.0'
+server.listen(port, host, () => {
+  console.log(`CAP server on http://${host}:${port}`)
+})

package/src/config.mjs

@@ -0,0 +1,112 @@
+import { timingSafeEqual } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createOAuth } from './oauth.mjs'
+import { createCapServer } from './node-server.mjs'
+import { createStore } from './store.mjs'
+
+const HANDLERS = ['static', 'echo', 'http']
+
+export function loadConfig(path) {
+  const config = JSON.parse(readFileSync(path, 'utf8'))
+  if (!config.agent?.name) throw new Error('cap.json needs agent.name.')
+  config.agent.status = config.agent.status || 'active'
+  const type = config.handler?.type || 'echo'
+  if (!HANDLERS.includes(type)) throw new Error(`Unknown handler type: ${type}.`)
+  return config
+}
+
+async function postHook(handler, payload) {
+  const url = handler.url || process.env[handler.url_env || 'HOOK_URL']
+  if (!url) return { error: { code: 'failed', message: 'The agent could not answer.' } }
+  const secret = process.env[handler.secret_env || 'HOOK_SECRET'] || ''
+  const headers = { 'content-type': 'application/json' }
+  if (secret) headers['x-cap-secret'] = secret
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) })
+  const body = await res.json().catch(() => ({}))
+  if (!res.ok || body.error) return { error: body.error || { code: 'failed', message: 'The agent could not answer.' } }
+  return body
+}
+
+export function handlerAnswer(handler = { type: 'echo' }) {
+  const login = { error: { code: 'login_required', message: 'Log in to your account to ask about it.' } }
+  return async ({ message, context, history, account, scope }) => {
+    if (handler.account && !account) return login
+    if (handler.type === 'static') return { reply: String(handler.reply ?? '') }
+    if (handler.type === 'echo') return { reply: message }
+    const body = await postHook(handler, { message, context, history, account, scope })
+    if (body.error) return body
+    if (body.confirm) return { confirm: body.confirm, reply: typeof body.reply === 'string' ? body.reply : '' }
+    return { reply: typeof body.reply === 'string' ? body.reply : '' }
+  }
+}
+
+/** With `http`, an approved action goes back to the same hook as `{ confirmed }`. */
+export function handlerAct(handler = { type: 'echo' }) {
+  if (handler.type !== 'http') return null
+  return async ({ account, authorization_details, caller }) => {
+    const body = await postHook(handler, { confirmed: { account, authorization_details, caller } })
+    if (body.error) return { error: { message: body.error.message } }
+    return { message: typeof body.message === 'string' ? body.message : '' }
+  }
+}
+
+const sameText = (a, b) => {
+  const left = Buffer.from(String(a))
+  const right = Buffer.from(String(b))
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+/** Demo logins from cap.json. A real owner passes `boot({ login })` and checks its own user store. */
+export function accountsLogin(accounts = []) {
+  return async ({ username, password }) => {
+    const match = accounts.find((entry) => entry.account === username)
+    const expected = match ? (match.password_env ? process.env[match.password_env] : match.password) : ''
+    return match && expected && sameText(password, expected) ? match.account : null
+  }
+}
+
+export async function boot(options = {}) {
+  const configPath = options.configPath || process.env.CAP_CONFIG || join(process.cwd(), 'cap.json')
+  const config = options.config || loadConfig(configPath)
+  const store = await createStore({
+    databaseUrl: options.databaseUrl ?? process.env.DATABASE_URL,
+    sqlitePath: options.sqlitePath ?? process.env.SQLITE_PATH ?? join(process.cwd(), 'data', 'cap.sqlite'),
+  })
+  for (const grant of config.grants || []) {
+    if (grant.token && grant.account && grant.client) {
+      await store.upsertGrant({ token: grant.token, account: grant.account, clientId: grant.client, scope: grant.scope === 'write' ? 'write' : 'read' })
+    }
+  }
+  const oauthConfig = config.oauth
+  const oauth = oauthConfig || options.login || options.currentAccount
+    ? createOAuth({
+      store,
+      agentName: config.agent.name,
+      login: options.login || accountsLogin(oauthConfig?.accounts),
+      currentAccount: options.currentAccount || null,
+      write: Boolean(oauthConfig?.write),
+      act: options.act || handlerAct(config.handler),
+      accessTokenSeconds: oauthConfig?.access_token_seconds ?? 3600,
+      writeAccessTokenSeconds: oauthConfig?.write_access_token_seconds ?? 900,
+      allowHttpClients: Boolean(oauthConfig?.allow_http_clients),
+      hint: oauthConfig?.hint || '',
+      fetchImpl: options.fetch,
+      deviceInterval: oauthConfig?.device_interval ?? 5,
+    })
+    : null
+  const cap = createCapServer({
+    store,
+    agent: config.agent,
+    answer: options.answer || handlerAnswer(config.handler),
+    waitMs: options.waitMs ?? (config.wait_seconds ?? 20) * 1000,
+    retryAfter: config.retry_after ?? 5,
+    retentionHours: config.retention_hours ?? 24,
+    dailyLimit: config.daily_limit ?? 0,
+    maxTurns: config.max_turns ?? 20,
+    oauth,
+    publicUrl: options.publicUrl ?? process.env.PUBLIC_URL ?? '',
+    extraRoutes: options.extraRoutes,
+  })
+  return { store, config, ...cap }
+}

package/src/http.mjs

@@ -0,0 +1,43 @@
+const MAX_BODY = 1_000_000
+
+export function send(res, status, body, extra = {}) {
+  res.writeHead(status, {
+    'content-type': extra.type || 'application/json; charset=utf-8',
+    'access-control-allow-origin': '*',
+    'access-control-allow-headers': 'authorization, content-type, cap-version, cap-from, idempotency-key',
+    'access-control-allow-methods': 'GET, POST, OPTIONS',
+    'access-control-expose-headers': 'location, retry-after',
+    'cache-control': 'no-store',
+    ...(extra.headers || {}),
+  })
+  res.end(extra.raw ?? JSON.stringify(body))
+}
+
+export function fail(res, status, code, message, headers) {
+  send(res, status, { error: { code, message } }, { headers })
+}
+
+export function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY) {
+        reject(Object.assign(new Error('Body is too large.'), { status: 400 }))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+export function requestOrigin(req, publicUrl = '') {
+  if (publicUrl) return publicUrl.replace(/\/$/, '')
+  const host = req.headers['x-forwarded-host'] || req.headers.host || '127.0.0.1'
+  const proto = req.headers['x-forwarded-proto'] || 'http'
+  return `${proto}://${host}`
+}

package/src/index.d.ts

@@ -0,0 +1,106 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+export type AgentCard = {
+  name: string
+  chat?: string
+  status?: 'active' | 'paused' | 'draft' | 'archived' | string
+  spec?: string
+  oauth?: string
+}
+
+export type Turn = {
+  message: string
+  context: Record<string, unknown>
+  reply: string | null
+}
+
+export type AnswerInput = {
+  message: string
+  context: Record<string, unknown>
+  history: Turn[]
+  account: string | null
+  scope: 'read' | 'write' | null
+  caller: string
+}
+
+export type AnswerError = { error: { code: string; message: string } }
+
+export type AnswerResult =
+  | string
+  | { reply: string }
+  | AnswerError
+  | { confirm: { summary: string; authorization_details?: unknown[] }; reply?: string }
+
+export type Answer = (input: AnswerInput) => AnswerResult | Promise<AnswerResult>
+
+export type CapServerOptions = {
+  agent: AgentCard
+  answer: Answer
+  /** Checks the company's own user store. Returning an account id turns on OAuth. */
+  login?: (input: { username: string; password: string }) => string | null | Promise<string | null>
+  /**
+   * Reads the company's own session from the request headers and returns the
+   * signed-in account id. The login and confirm pages then ask only for the decision.
+   */
+  currentAccount?: (input: { headers: Record<string, string | string[] | undefined> }) => string | null | Promise<string | null>
+  /** Runs once after a person approves a held action. */
+  act?: (input: { account: string; authorization_details: unknown; caller: string }) => { message: string } | { error: { message: string } } | Promise<{ message: string } | { error: { message: string } }>
+  write?: boolean
+  allowHttpClients?: boolean
+  grants?: { token: string; account: string; client: string; scope?: 'read' | 'write' }[]
+  waitSeconds?: number
+  waitMs?: number
+  retryAfter?: number
+  retentionHours?: number
+  dailyLimit?: number
+  maxTurns?: number
+  publicUrl?: string
+  databaseUrl?: string
+  /** SQLite file, or `:memory:`. Ignored when databaseUrl is a Postgres URL. */
+  sqlitePath?: string
+  accessTokenSeconds?: number
+  writeAccessTokenSeconds?: number
+  deviceInterval?: number
+  hint?: string
+  fetch?: typeof fetch
+  extraRoutes?: (req: IncomingMessage, res: ServerResponse, url: URL) => boolean | Promise<boolean>
+}
+
+export type ListenAddress = {
+  port: number
+  address: string
+  family: string
+}
+
+export type AccountAccess = { account: string; scope: 'read' | 'write'; caller: string }
+
+export type ApprovalResult =
+  | { confirmation: { id: string; status: 'pending'; url: string; summary: string; expires_at: string } }
+  | AnswerError
+
+export type AccountHelpers = {
+  /** The account behind the request's bearer token, for your own account routes. Null without a valid token for the agent in CAP-From. */
+  accountFor(request: Request | IncomingMessage): Promise<AccountAccess | null>
+  /** Holds an action until the person approves it on the confirm page. `act` runs it once after. */
+  requestApproval(request: Request | IncomingMessage, input: { summary: string; authorization_details?: unknown[] }): Promise<ApprovalResult>
+}
+
+export type CapServer = AccountHelpers & {
+  listen(port?: number, host?: string): Promise<ListenAddress | string | null>
+  close(): Promise<void>
+  fetch(request: Request): Promise<Response>
+  handle(req: IncomingMessage, res: ServerResponse): Promise<void>
+}
+
+export function createCapServer(options: CapServerOptions): Promise<CapServer>
+
+export function createCapHandler(options: CapServerOptions): Promise<AccountHelpers & {
+  handle(request: Request): Promise<Response>
+  close(): Promise<void>
+}>
+
+export function checkDoor(origin: string, options?: {
+  message?: string
+  timeoutMs?: number
+  fetch?: typeof fetch
+}): Promise<{ ok: boolean; failures: string[] }>