@nervur-org/dock 0.3.0

package/dist/mcp/oauth.js

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: Apache-2.0
+// OAuth on the mcp route: the wire protocol a remote MCP client speaks to
+// end with a grant. An authorization server small enough to read, and
+// nothing a client does not need: metadata, dynamic registration, PKCE with
+// S256, the code grant, refresh, opaque tokens. It is a route, not Quo. Its
+// one job is to end with a client identity, which the front desk trades for
+// an invitation and the avatar knocks with; the grant it issues is the
+// box's, `dock/grants.ts`, honoured on every route, and what this file
+// keeps for itself is only the dance: clients, pending requests and codes.
+// No secret of Quo's is ever here.
+//
+//   GET  /.well-known/oauth-authorization-server     who issues, and where
+//   GET  /.well-known/oauth-protected-resource[/mcp] which issuer guards the MCP endpoint
+//   POST /register                                    a client names itself and its redirects
+//   GET  /authorize                                   starts a request; sent to the web route to finish
+//   POST /token                                       code or refresh for an access token
+//
+// The web route finishes a request by calling `complete(request, identity)`
+// after its allow page, where the human hands the invitation the root minted;
+// that returns the redirect that carries the code back to the client.
+import { REFRESH_TTL } from '../dock/grants.js';
+export { ACCESS_TTL, REFRESH_TTL } from '../dock/grants.js';
+// A code, a client id: every key here is a string the far side chose, and a
+// bare lookup would find `__proto__` and hand back an object with no
+// identity. Own keys only.
+const own = (rec, key) => (Object.hasOwn(rec, key) ? rec[key] : undefined);
+export const CODE_TTL = 10 * 60 * 1000; // a code, and a pending request, live ten minutes
+export const emptyDance = () => ({ clients: {}, pending: {}, codes: {} });
+// The randomness and the hash are the web crypto every runtime has, so the
+// dance runs on a worker as it runs on a daemon: nothing of node is named in
+// this route, and a terrain only says where the dance is kept.
+const b64url = (bytes) => {
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+};
+const token = () => b64url(globalThis.crypto.getRandomValues(new Uint8Array(32)));
+const s256 = async (v) => b64url(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(v))));
+export class OAuth {
+    o;
+    dance;
+    // The dance is in hand from the first request, so every lookup here is
+    // plain: `open` is where the terrain is waited on, once.
+    static async open(o) {
+        return new OAuth(o, await o.store.load());
+    }
+    constructor(o, dance) {
+        this.o = o;
+        this.dance = dance;
+    }
+    keep() {
+        return this.o.store.save(this.dance);
+    }
+    now() {
+        return this.o.now?.() ?? this.o.grants.now();
+    }
+    metadata() {
+        const i = this.o.issuer;
+        return {
+            issuer: i,
+            authorization_endpoint: `${i}/authorize`,
+            token_endpoint: `${i}/token`,
+            registration_endpoint: `${i}/register`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            code_challenge_methods_supported: ['S256'],
+            token_endpoint_auth_methods_supported: ['none'],
+            scopes_supported: ['quo'],
+        };
+    }
+    protectedResource() {
+        return { resource: this.o.resource, authorization_servers: [this.o.issuer], bearer_methods_supported: ['header'] };
+    }
+    async register(body) {
+        const b = body;
+        const uris = Array.isArray(b.redirect_uris) ? b.redirect_uris.filter((u) => typeof u === 'string' && /^https?:\/\//.test(u)) : [];
+        if (uris.length === 0)
+            return { error: 'invalid_redirect_uri' };
+        const client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris, exp: this.now() + CODE_TTL };
+        this.dance.clients[client.client_id] = client;
+        this.sweep();
+        await this.keep();
+        const { exp: _, ...shown } = client;
+        return shown;
+    }
+    // A client still alive, by id.
+    client(id) {
+        const c = own(this.dance.clients, id);
+        return c && c.exp >= this.now() ? c : undefined;
+    }
+    // Start a request. What comes back is where to send the browser: the web
+    // route with the request id, or the client's redirect with an error.
+    async authorize(q) {
+        const client = this.client(q.get('client_id') ?? '');
+        const redirect = q.get('redirect_uri') ?? client?.redirect_uris[0] ?? null;
+        if (!client || redirect === null || !client.redirect_uris.includes(redirect))
+            return { error: 'invalid_client' };
+        const back = (error) => ({ redirect: withQuery(redirect, { error, state: q.get('state') }) });
+        if (q.get('response_type') !== 'code')
+            return back('unsupported_response_type');
+        const challenge = q.get('code_challenge');
+        if (!challenge || q.get('code_challenge_method') !== 'S256')
+            return back('invalid_request');
+        const id = token();
+        this.dance.pending[id] = { client_id: client.client_id, redirect_uri: redirect, challenge, state: q.get('state'), resource: q.get('resource'), exp: this.now() + CODE_TTL };
+        this.sweep();
+        await this.keep();
+        return { redirect: this.o.finish(id) };
+    }
+    // What the web route shows: who is asking. Null if the request is gone.
+    pending(id) {
+        const p = own(this.dance.pending, id);
+        if (!p || p.exp < this.now())
+            return null;
+        const client = this.client(p.client_id);
+        return client ? { ...p, client } : null;
+    }
+    // The web route's last step: the human allowed this client as this
+    // identity, into this world.
+    async complete(id, identity, ward) {
+        const p = this.pending(id);
+        if (!p)
+            return { error: 'expired' };
+        delete this.dance.pending[id];
+        const code = token();
+        this.dance.codes[code] = { ...p, identity, ward, exp: this.now() + CODE_TTL };
+        await this.keep();
+        return { redirect: withQuery(p.redirect_uri, { code, state: p.state }) };
+    }
+    // The human refused, or the request died: the client hears that.
+    async deny(id) {
+        const p = this.pending(id);
+        if (!p)
+            return { error: 'expired' };
+        delete this.dance.pending[id];
+        await this.keep();
+        return { redirect: withQuery(p.redirect_uri, { error: 'access_denied', state: p.state }) };
+    }
+    async token(body) {
+        const grant = body.get('grant_type');
+        if (grant === 'authorization_code') {
+            const c = own(this.dance.codes, body.get('code') ?? '');
+            if (!c || c.exp < this.now())
+                return { error: 'invalid_grant' };
+            delete this.dance.codes[body.get('code') ?? '']; // a code is spent the first time it is offered, right or wrong
+            const verifier = body.get('code_verifier') ?? '';
+            if ((await s256(verifier)) !== c.challenge || (body.get('client_id') ?? c.client_id) !== c.client_id || (body.get('redirect_uri') ?? c.redirect_uri) !== c.redirect_uri) {
+                await this.keep();
+                return { error: 'invalid_grant' };
+            }
+            return this.issue(c.identity, c.ward, c.client_id);
+        }
+        if (grant === 'refresh_token') {
+            const t = await this.o.grants.refresh(body.get('refresh_token') ?? '');
+            return t ?? { error: 'invalid_grant' };
+        }
+        return { error: 'unsupported_grant_type' };
+    }
+    // The dance ends: the box issues the grant, and the client lives as long
+    // as what it was granted.
+    async issue(identity, ward, client_id) {
+        const t = await this.o.grants.issue(identity, ward, client_id);
+        const c = own(this.dance.clients, client_id);
+        if (c)
+            c.exp = this.now() + REFRESH_TTL;
+        this.sweep();
+        await this.keep();
+        return t;
+    }
+    sweep() {
+        const now = this.now();
+        for (const k of ['clients', 'pending', 'codes'])
+            for (const [t, g] of Object.entries(this.dance[k]))
+                if (!(g.exp >= now))
+                    delete this.dance[k][t];
+    }
+    // The HTTP face. `rest` is the path under the route, and a path that is
+    // none of the dance's is answered nothing, which is how a handler declines.
+    async handle(req, rest) {
+        const url = new URL(req.url);
+        const json = (status, body) => Response.json(body, { status, headers: { 'cache-control': 'no-store' } });
+        if (rest === '/.well-known/oauth-authorization-server' && req.method === 'GET')
+            return json(200, this.metadata());
+        if ((rest === '/.well-known/oauth-protected-resource' || rest === '/.well-known/oauth-protected-resource/mcp') && req.method === 'GET')
+            return json(200, this.protectedResource());
+        if (rest === '/register' && req.method === 'POST') {
+            const out = await this.register(await readJson(req));
+            return json('error' in out ? 400 : 201, out);
+        }
+        if (rest === '/authorize' && req.method === 'GET') {
+            const out = await this.authorize(url.searchParams);
+            if ('error' in out)
+                return json(400, out);
+            return new Response(null, { status: 302, headers: { location: out.redirect, 'cache-control': 'no-store' } });
+        }
+        if (rest === '/token' && req.method === 'POST') {
+            const out = await this.token(await readForm(req));
+            return json('error' in out ? 400 : 200, out);
+        }
+        return undefined;
+    }
+    // What an unauthenticated MCP request is told: where to go.
+    challenge() {
+        return Response.json({ error: 'unauthorized' }, { status: 401, headers: { 'www-authenticate': `Bearer resource_metadata="${this.o.issuer}/.well-known/oauth-protected-resource/mcp"` } });
+    }
+}
+function withQuery(base, params) {
+    const u = new URL(base);
+    for (const [k, v] of Object.entries(params))
+        if (v !== null)
+            u.searchParams.set(k, v);
+    return u.toString();
+}
+export async function readBody(req, limit = 64 * 1024) {
+    const s = await req.text();
+    if (s.length > limit)
+        throw new Error('too large');
+    return s;
+}
+async function readJson(req) {
+    try {
+        return JSON.parse(await readBody(req));
+    }
+    catch {
+        return {};
+    }
+}
+export async function readForm(req) {
+    const body = await readBody(req);
+    if ((req.headers.get('content-type') ?? '').includes('application/json')) {
+        try {
+            const o = JSON.parse(body);
+            return new URLSearchParams(Object.entries(o).map(([k, v]) => [k, String(v)]));
+        }
+        catch {
+            return new URLSearchParams();
+        }
+    }
+    return new URLSearchParams(body);
+}

package/dist/mcp/route.d.ts

@@ -0,0 +1,15 @@
+import { OAuth, type Store } from './oauth.ts';
+import type { McpHttp } from './http.ts';
+import type { Handler } from '../harbor/http.ts';
+import type { Grants } from '../dock/grants.ts';
+export type Routes = {
+    mcp: string;
+    web: string;
+    quo?: string;
+    api?: string;
+};
+export declare function mcpRoute(store: Store, routes: Routes, mcp: McpHttp | null, grants: Grants): Promise<{
+    oauth: OAuth;
+    handler: Handler;
+    wellKnown: Handler;
+}>;

package/dist/mcp/route.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// The mcp. route: the OAuth dance and the MCP endpoint, served by the
+// daemon under `/mcp` and mapped by the proxy from the mcp. hostname. The
+// dance's own state, clients, pending requests and codes, each living
+// minutes, is kept in a store the terrain hands in: a file for the daemon,
+// the object's storage on the edge. Where it ends is the box's grants, which
+// every route honours; a bearer names an identity in a world, and the
+// endpoint hands both to the model side, which runs beside her avatar.
+import { OAuth } from './oauth.js';
+// `wellKnown` is the same discovery at the origin's root, for a box whose
+// routes are paths under one origin rather than hostnames: an issuer with
+// a path is looked up at `/.well-known/<document>` followed by that path,
+// which no route's prefix can catch, so the daemon mounts this at
+// `/.well-known`. Under a hostname per route the issuer has no path and
+// the route's own `.well-known` is the root's already.
+export async function mcpRoute(store, routes, mcp, grants) {
+    const oauth = await OAuth.open({ issuer: routes.mcp, resource: `${routes.mcp}/mcp`, finish: (id) => `${routes.web}/allow?request=${id}`, store, grants });
+    // The dance first, then the endpoint: both answer a `Response`, and the
+    // dance declines a path that is not one of its own by answering nothing.
+    const handler = async (req, rest) => {
+        const danced = await oauth.handle(req, rest);
+        if (danced)
+            return danced;
+        if (rest === '/mcp') {
+            const grant = grants.bearer(req);
+            if (grant === null || !mcp)
+                return oauth.challenge();
+            return mcp.handle(req, grant.identity, grant.ward);
+        }
+        return Response.json({ error: 'no such route' }, { status: 404 });
+    };
+    const issuerPath = new URL(routes.mcp).pathname.replace(/\/$/, '');
+    const wellKnown = (req, rest) => {
+        const json = (body) => Response.json(body, { headers: { 'access-control-allow-origin': '*' } });
+        if (req.method === 'GET' && rest === `/oauth-authorization-server${issuerPath}`)
+            return json(oauth.metadata());
+        if (req.method === 'GET' && (rest === `/oauth-protected-resource${issuerPath}` || rest === `/oauth-protected-resource${issuerPath}/mcp`))
+            return json(oauth.protectedResource());
+        return Response.json({ error: 'no such route' }, { status: 404 });
+    };
+    return { oauth, handler, wellKnown };
+}

package/dist/mcp/runner.d.ts

@@ -0,0 +1,45 @@
+import type { Blueprint, JsonObject } from '@nervur-org/nervur';
+import type { Avatar } from '../beings/avatar.ts';
+import { type Serving } from '../beings/side.ts';
+export type Model = {
+    url: string;
+    model: string;
+    key?: string;
+    turns?: number;
+};
+export declare const TURNS = 10;
+export type Tool = {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: JsonObject;
+    };
+};
+export type ToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type Message = {
+    role: 'system' | 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string | null;
+    tool_calls?: ToolCall[];
+} | {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+};
+export declare function tools(bp: Blueprint): Tool[];
+export declare function result(avatar: Avatar, call: ToolCall): Promise<string>;
+export type Runner = Serving & {
+    say(text: string): Promise<string | null>;
+    readonly messages: readonly Message[];
+};
+export declare function runnerSide(avatar: Avatar, model: Model, hear?: (text: string) => void, after?: () => Promise<void>): Runner;

package/dist/mcp/runner.js

@@ -0,0 +1,99 @@
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+import { presentation } from '../beings/look.js';
+export const TURNS = 10;
+// Her describe, spoken as a tools array. Name, description and input are
+// verbatim, with the one narrowing an endpoint has asked for: an ask that
+// declares no properties is sent with an empty `properties`, because
+// LM Studio refuses a parameters schema without one. Her look, her page and
+// every carried page are presentation, for a screen, and are not functions.
+export function tools(bp) {
+    const shown = presentation(bp);
+    return bp.asks
+        .filter((a) => !shown.has(a.name))
+        .map((a) => {
+        const t = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
+        if (a.description !== undefined)
+            t.function.description = a.description;
+        return t;
+    });
+}
+// One tool call, one ask, one tool message: the three words cross as the
+// table in quo-mcp.md says, and a tool message is text, so the two words
+// that carry nothing cross as the text the trunk gives them.
+export async function result(avatar, call) {
+    let args = {};
+    try {
+        const parsed = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+            args = parsed;
+    }
+    catch {
+        return JSON.stringify({ error: 'arguments are not JSON' });
+    }
+    const w = word(await avatar.call(call.function.name, args));
+    if (w.word === 'object' || w.word === 'error')
+        return JSON.stringify(w.value);
+    return w.word === 'silence' ? SILENCE_TEXT : w.word === 'quo' ? wordText(w.name) : UNREACHED_TEXT;
+}
+// `hear` gets every final text the model says, whoever started the turn.
+// `after` runs when an ask is done, as in the MCP server: a harbor that must
+// write what the ward changed hooks it.
+export function runnerSide(avatar, model, hear = () => { }, after = async () => { }) {
+    const messages = [];
+    const ceiling = model.turns ?? TURNS;
+    let busy = Promise.resolve();
+    async function complete(t) {
+        const headers = { 'content-type': 'application/json' };
+        if (model.key !== undefined)
+            headers.authorization = `Bearer ${model.key}`;
+        const res = await fetch(`${model.url.replace(/\/$/, '')}/chat/completions`, { method: 'POST', headers, body: JSON.stringify({ model: model.model, messages, tools: t }) });
+        const body = (await res.json());
+        const m = body.choices?.[0]?.message;
+        if (!res.ok || !m)
+            throw new Error(`model: ${res.status} ${JSON.stringify(body.error ?? body)}`);
+        return m;
+    }
+    // One turn: from the last appended message to the model's final text.
+    async function turn() {
+        const bp = await avatar.tools();
+        const t = 'asks' in bp ? tools(bp) : [];
+        for (let i = 0; i < ceiling; i++) {
+            const m = await complete(t);
+            const reply = { role: 'assistant', content: m.content };
+            if (m.tool_calls?.length)
+                reply.tool_calls = m.tool_calls;
+            messages.push(reply);
+            if (!m.tool_calls?.length) {
+                const text = m.content ?? '';
+                hear(text);
+                return text;
+            }
+            for (const call of m.tool_calls) {
+                messages.push({ role: 'tool', tool_call_id: call.id, content: await result(avatar, call) });
+                await after();
+            }
+        }
+        return null;
+    }
+    // Turns never overlap: one conversation, one train of thought.
+    function start(message) {
+        const next = busy.then(async () => {
+            messages.push(message);
+            return turn();
+        });
+        busy = next.catch(() => { });
+        return next;
+    }
+    const ear = (object) => {
+        void start({ role: 'user', content: JSON.stringify(object) }).catch(() => { });
+    };
+    avatar.ears.add(ear);
+    return {
+        messages,
+        say: (text) => start({ role: 'user', content: text }),
+        close: async () => {
+            avatar.ears.delete(ear);
+            await busy;
+        },
+    };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,11 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { Blueprint } from '@nervur-org/nervur';
+import { type Serving, type Subject } from '../beings/side.ts';
+import { type Look } from '../beings/look.ts';
+export declare const NAME = "quo";
+export declare const VERSION = "0.0.0";
+export type { Subject } from '../beings/side.ts';
+export declare const DESCRIBE: Tool;
+export declare function tools(bp: Blueprint, look?: Look): Tool[];
+export declare function mcpSide(avatar: Subject, transport: Transport, after?: () => Promise<void>): Promise<Serving>;

package/dist/mcp/server.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+// The model side as an MCP server: one subject, one transport. The subject
+// is whoever answers the empty ask and a named one: an avatar on her one
+// standing, or a ward's owner asks through the pilot. The mapping is total
+// and needs nothing beyond this envelope. tools/list is her describe, and
+// the empty ask itself is the first tool, so the notes of the describe are
+// readable; tools/call is a named ask, a push is a logging notification,
+// and the three words for "no object" each cross as the table in
+// quo-mcp.md says. The transport is whatever the caller connected: the
+// SDK's in-memory pair in a test, stdio for a local client, HTTP on a route.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT } from '../beings/side.js';
+import { hintFor, presentation, sanitise } from '../beings/look.js';
+import { isSilence, isWord, digest } from '@nervur-org/nervur';
+export const NAME = 'quo';
+export const VERSION = '0.0.0';
+// The empty ask as a tool: her describe whole, asks and notes.
+export const DESCRIBE = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
+// Her describe, spoken as tools, the empty ask first. Name, description and
+// input are verbatim; an output schema crosses when she declared one. Her
+// look, when she has one, is the hints: a title, and the annotations a host
+// reads. Her look, her page and every carried page are presentation, for a
+// screen, and are not tools.
+export function tools(bp, look = {}) {
+    const shown = presentation(bp);
+    const asks = bp.asks
+        .filter((a) => !shown.has(a.name))
+        .map((a) => {
+        const t = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
+        if (a.description !== undefined)
+            t.description = a.description;
+        if (a.output !== undefined)
+            t.outputSchema = { ...a.output, type: 'object' };
+        const h = hintFor(bp, look, a.name);
+        if (h.title !== undefined)
+            t.title = h.title;
+        const notes = {};
+        if (h.readOnly !== undefined)
+            notes.readOnlyHint = h.readOnly;
+        if (h.destructive !== undefined)
+            notes.destructiveHint = h.destructive;
+        if (h.idempotent !== undefined)
+            notes.idempotentHint = h.idempotent;
+        if (Object.keys(notes).length)
+            t.annotations = notes;
+        return t;
+    });
+    return [DESCRIBE, ...asks];
+}
+// `after` runs when a call is done: a harbor that must write what the ward
+// changed hooks it, since a same-ward ask never crosses the harbor.
+export async function mcpSide(avatar, transport, after = async () => { }) {
+    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
+    // Her look, asked once per digest of her describe.
+    let seen = null;
+    let look = {};
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const bp = await avatar.tools();
+        if ('error' in bp && !('asks' in bp))
+            return { tools: [] }; // not joined: nothing to show, and nothing to call
+        const d = await digest(bp);
+        if (d !== seen) {
+            seen = d;
+            if (bp.asks.some((a) => a.name === 'look')) {
+                const l = await avatar.call('look', {});
+                look = isSilence(l) || isWord(l) ? {} : sanitise(l);
+            }
+            else
+                look = {};
+        }
+        return { tools: tools(bp, look) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const w = word(req.params.name === DESCRIBE.name ? await avatar.tools() : await avatar.call(req.params.name, (req.params.arguments ?? {})));
+        await after();
+        if (w.word === 'object') {
+            const structured = w.value !== null && typeof w.value === 'object' && !Array.isArray(w.value) ? { structuredContent: w.value } : {};
+            return { content: [{ type: 'text', text: JSON.stringify(w.value) }], ...structured };
+        }
+        if (w.word === 'error')
+            return { content: [{ type: 'text', text: JSON.stringify(w.value) }], structuredContent: w.value, isError: true };
+        if (w.word === 'silence')
+            return { content: [{ type: 'text', text: SILENCE_TEXT }], structuredContent: { error: 'silence' }, isError: true };
+        if (w.word === 'quo')
+            return { content: [{ type: 'text', text: wordText(w.name) }], structuredContent: { error: w.name }, isError: true };
+        return { content: [{ type: 'text', text: UNREACHED_TEXT }], structuredContent: { error: 'unreached' }, isError: true };
+    });
+    // A push from the user being is a notification to the client. If the
+    // transport is gone, the push is dropped, as the side says it is.
+    const ear = (object) => {
+        void server.sendLoggingMessage({ level: 'info', logger: NAME, data: object }).catch(() => { });
+    };
+    avatar.ears.add(ear);
+    await server.connect(transport);
+    return {
+        close: async () => {
+            avatar.ears.delete(ear);
+            await server.close();
+        },
+    };
+}