@janux/server 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@janux/server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Janux fullstack server: SSR, api() RPC endpoints that double as agent tools, manifest service and MCP surface.",
   "repository": {
     "type": "git",
@@ -17,7 +17,8 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "janux": "0.1.0"
+    "janux": "0.1.0",
+    "web-bot-auth": "^0.1.3"
   },
   "homepage": "https://github.com/aralroca/Janux#readme",
   "bugs": "https://github.com/aralroca/Janux/issues",

package/src/__fixtures__/routes/about.tsx

@@ -0,0 +1,10 @@
+import { jsx } from 'janux';
+
+export const meta = {
+  title: 'About — Janux fixture',
+  description: 'Route-level metadata fixture.',
+};
+
+export default function About() {
+  return jsx('main', { children: 'About page' });
+}

package/src/__fixtures__/routes/evil.tsx

@@ -0,0 +1,9 @@
+import { jsx } from 'janux';
+
+export const meta = {
+  title: '</title><script>alert(1)</script>',
+};
+
+export default function Evil() {
+  return jsx('main', { children: 'safe' });
+}

package/src/__fixtures__/routes/orders/[id].tsx

@@ -0,0 +1,9 @@
+import { jsx } from 'janux';
+
+export function staticParams() {
+  return [{ id: '1' }, { id: '2' }];
+}
+
+export default function Order({ params }: { params: { id: string } }) {
+  return jsx('main', { children: `Order ${params.id}` });
+}

package/src/__fixtures__/routes/tags/[tag].tsx

@@ -0,0 +1,5 @@
+import { jsx } from 'janux';
+
+export default function Tag({ params }: { params: { tag: string } }) {
+  return jsx('main', { children: `Tag ${params.tag}` });
+}

package/src/agent-auth.test.ts

@@ -0,0 +1,169 @@
+import { beforeAll, describe, expect, it } from 'bun:test';
+import { signatureHeaders } from 'web-bot-auth';
+import { signerFromJWK } from 'web-bot-auth/crypto';
+import { jsx, schema, str, type AuditEntry } from 'janux';
+import { api } from './api';
+import { createJanuxServer, type ServerOptions } from './server';
+
+let goodJwk: JsonWebKey;
+let goodPrivate: JsonWebKey;
+let strangerPrivate: JsonWebKey;
+
+async function generateEd25519(): Promise<{ publicJwk: JsonWebKey; privateJwk: JsonWebKey }> {
+  const pair = (await crypto.subtle.generateKey('Ed25519', true, ['sign', 'verify'])) as CryptoKeyPair;
+
+  return {
+    publicJwk: await crypto.subtle.exportKey('jwk', pair.publicKey),
+    privateJwk: await crypto.subtle.exportKey('jwk', pair.privateKey),
+  };
+}
+
+beforeAll(async () => {
+  const good = await generateEd25519();
+  const stranger = await generateEd25519();
+
+  goodJwk = good.publicJwk;
+  goodPrivate = good.privateJwk;
+  strangerPrivate = stranger.privateJwk;
+});
+
+function makeServer(overrides: Partial<ServerOptions> = {}, audit?: AuditEntry[]) {
+  return createJanuxServer({
+    routes: { '/': () => jsx('main', {}) },
+    apis: {
+      shop: {
+        echoAgent: api({
+          description: 'Echo the verified agent',
+          run: ({ ctx }) => ({ agent: ctx.agent ?? null }),
+        }),
+        pay: api({
+          description: 'Charge. Irreversible.',
+          input: schema({ total: str() }),
+          guard: 'confirm',
+          run: ({ input }) => ({ charged: input.total }),
+        }),
+        search: api({
+          description: 'Search products',
+          input: schema({ q: str() }),
+          run: ({ input }) => [input.q],
+        }),
+      },
+    },
+    onAudit: audit ? (entry) => audit.push(entry) : undefined,
+    ...overrides,
+  });
+}
+
+async function signedRequest(path: string, body: unknown, privateJwk: JsonWebKey, expiresInMs = 60_000): Promise<Request> {
+  const request = new Request(`http://test${path}`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+    headers: { 'content-type': 'application/json', 'x-janux-origin': 'agent' },
+  });
+  const expires = Date.now() + expiresInMs;
+  const headers = await signatureHeaders(request, await signerFromJWK(privateJwk), {
+    created: new Date(expires - 60_000),
+    expires: new Date(expires),
+  });
+
+  return new Request(request, {
+    headers: {
+      'content-type': 'application/json',
+      'x-janux-origin': 'agent',
+      Signature: headers['Signature'],
+      'Signature-Input': headers['Signature-Input'],
+    },
+  });
+}
+
+const agentPost = (server: ReturnType<typeof createJanuxServer>, path: string, body: unknown) =>
+  server.fetch(
+    new Request(`http://test${path}`, {
+      method: 'POST',
+      body: JSON.stringify(body),
+      headers: { 'content-type': 'application/json', 'x-janux-origin': 'agent' },
+    }),
+  );
+
+describe('web bot auth', () => {
+  it('observe policy serves unsigned agent calls with no identity', async () => {
+    const server = makeServer({ agents: { webBotAuth: { keys: [] }, policy: 'observe' } });
+    const body: any = await (await agentPost(server, '/_janux/api/shop.echoAgent', {})).json();
+
+    expect(body).toEqual({ ok: true, result: { agent: null } });
+  });
+
+  it('require policy rejects unsigned agent calls with 401 and never gates humans', async () => {
+    const server = makeServer({ agents: { webBotAuth: { keys: [] }, policy: 'require' } });
+    const denied = await agentPost(server, '/_janux/api/shop.echoAgent', {});
+    const human = await server.fetch(
+      new Request('http://test/_janux/api/shop.echoAgent', {
+        method: 'POST',
+        body: '{}',
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+
+    expect(denied.status).toBe(401);
+    expect(((await denied.json()) as any).error).toBe('agent_required');
+    expect(human.status).toBe(200);
+  });
+
+  it('require policy accepts a signed request and exposes ctx.agent', async () => {
+    const server = makeServer({ agents: { webBotAuth: { keys: [goodJwk] }, policy: 'require' } });
+    const res = await server.fetch(await signedRequest('/_janux/api/shop.echoAgent', {}, goodPrivate));
+    const body: any = await res.json();
+
+    expect(res.status).toBe(200);
+    expect(body.result.agent.verified).toBe(true);
+    expect(typeof body.result.agent.keyId).toBe('string');
+  });
+
+  it('fails closed on unknown keys and expired signatures', async () => {
+    const server = makeServer({ agents: { webBotAuth: { keys: [goodJwk] }, policy: 'require' } });
+    const stranger = await server.fetch(await signedRequest('/_janux/api/shop.echoAgent', {}, strangerPrivate));
+    const expired = await server.fetch(await signedRequest('/_janux/api/shop.echoAgent', {}, goodPrivate, -1000));
+
+    expect(stranger.status).toBe(401);
+    expect(expired.status).toBe(401);
+  });
+});
+
+describe('api audit trail', () => {
+  it('audits human and agent api calls, including failures', async () => {
+    const entries: AuditEntry[] = [];
+    const server = makeServer({}, entries);
+
+    await server.fetch(
+      new Request('http://test/_janux/api/shop.echoAgent', {
+        method: 'POST',
+        body: '{}',
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+    await agentPost(server, '/_janux/api/shop.search', { q: 42 });
+
+    expect(entries).toHaveLength(2);
+    expect(entries[0]).toMatchObject({ tool: 'api.shop.echoAgent', origin: 'human', ok: true });
+    expect(entries[1]).toMatchObject({ tool: 'api.shop.search', origin: 'agent', ok: false });
+  });
+
+  it('audits the proposal → approve flow with the verified agent key', async () => {
+    const entries: AuditEntry[] = [];
+    const server = makeServer({ agents: { webBotAuth: { keys: [goodJwk] }, policy: 'require' } }, entries);
+    const proposalRes = await server.fetch(await signedRequest('/_janux/api/shop.pay', { total: '10' }, goodPrivate));
+    const proposal: any = ((await proposalRes.json()) as any).result;
+
+    await server.fetch(
+      new Request('http://test/_janux/approve', {
+        method: 'POST',
+        body: JSON.stringify({ id: proposal.id }),
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+
+    expect(entries[0]).toMatchObject({ tool: 'api.shop.pay', origin: 'agent', guard: 'confirm', ok: true });
+    expect(typeof entries[0]?.agent).toBe('string');
+    expect(entries[1]).toMatchObject({ tool: 'api.shop.pay', origin: 'human', ok: true });
+  });
+});

package/src/agent-auth.ts

@@ -0,0 +1,67 @@
+import { helpers, jwkToKeyID, verify } from 'web-bot-auth';
+import { verifierFromJWK } from 'web-bot-auth/crypto';
+
+export interface AgentIdentity {
+  verified: boolean;
+  keyId?: string;
+}
+
+export interface AgentsConfig {
+  webBotAuth: { keys: JsonWebKey[] };
+  policy?: 'observe' | 'require';
+}
+
+type KeyVerifier = (data: string, signature: Uint8Array, params: VerifyParams) => Promise<void>;
+
+interface VerifyParams {
+  keyid: string;
+  expires: Date;
+}
+
+async function keyEntry(jwk: JsonWebKey): Promise<[string, KeyVerifier]> {
+  const keyId = await jwkToKeyID(jwk, helpers.WEBCRYPTO_SHA256, helpers.BASE64URL_DECODE);
+
+  return [keyId, (await verifierFromJWK(jwk)) as unknown as KeyVerifier];
+}
+
+async function loadKeys(config: AgentsConfig): Promise<Map<string, KeyVerifier>> {
+  return new Map(await Promise.all(config.webBotAuth.keys.map(keyEntry)));
+}
+
+function dispatchVerifier(keys: Map<string, KeyVerifier>) {
+  return async (data: string, signature: Uint8Array, params: VerifyParams): Promise<string> => {
+    const verifyKey = keys.get(params.keyid);
+
+    if (!verifyKey) throw new Error(`Janux: unknown agent keyid "${params.keyid}"`);
+    if (params.expires.getTime() < Date.now()) throw new Error('Janux: agent signature expired');
+    await verifyKey(data, signature, params);
+
+    return params.keyid;
+  };
+}
+
+/**
+ * Web Bot Auth (RFC 9421) verification against an allowlist of agent JWKs.
+ * Fail closed: unknown key, bad signature or expired window ⇒ `verified: false`.
+ */
+export function createAgentAuth(config: AgentsConfig) {
+  let dispatchPromise: Promise<ReturnType<typeof dispatchVerifier>> | undefined;
+
+  const dispatch = () => (dispatchPromise ??= loadKeys(config).then(dispatchVerifier));
+
+  return {
+    policy: config.policy ?? 'observe',
+
+    async identify(req: Request): Promise<AgentIdentity | null> {
+      if (!req.headers.get('signature')) return null;
+
+      try {
+        return { verified: true, keyId: await verify(req, await dispatch()) };
+      } catch {
+        return { verified: false };
+      }
+    },
+  };
+}
+
+export type AgentAuth = ReturnType<typeof createAgentAuth>;

package/src/api.ts

@@ -1,5 +1,5 @@
 import { JxType, validate, toJsonSchema, JanuxIntentError } from 'janux';
-import type { Ctx, Guard, GuardValue, Origin } from 'janux';
+import type { AuditEntry, Ctx, Guard, GuardValue, Origin } from 'janux';
 
 export interface ApiDef {
   description?: string;
@@ -70,25 +70,61 @@ function parseApiInput(tool: ApiTool, input: unknown): unknown {
   return result.value;
 }
 
-/** Single invocation pipeline for api() tools: guard → validate → run → validate output. */
-export async function invokeApi(tool: ApiTool, input: unknown, ctx: Ctx, origin: Origin): Promise<unknown> {
-  const guard = resolveApiGuard(tool, ctx);
+function checkOutput(tool: ApiTool, result: unknown): unknown {
+  if (!tool.output) return result;
+  const check = validate(tool.output, result);
 
-  if (origin === 'agent' && guard === 'forbidden') {
-    throw new JanuxIntentError('forbidden', `Tool "${tool.name}" is not available`);
-  }
-  const parsed = parseApiInput(tool, input);
-  const result = await tool.run({ input: parsed, ctx });
+  if (!check.ok) throw new Error(`Janux: api "${tool.name}" returned an invalid output`);
 
-  if (tool.output) {
-    const check = validate(tool.output, result);
+  return check.value;
+}
 
-    if (!check.ok) throw new Error(`Janux: api "${tool.name}" returned an invalid output`);
+/** The verified agent key id on the request context, if Web Bot Auth identified one. */
+export function agentKeyId(ctx: Ctx): string | undefined {
+  const agent = ctx.agent as { verified?: boolean; keyId?: string } | undefined;
 
-    return check.value;
-  }
+  return agent?.verified ? agent.keyId : undefined;
+}
 
-  return result;
+export type ApiAudit = (entry: AuditEntry) => void;
+
+/** The single place the api() audit-entry shape is assembled (used by the pipeline and the proposal path). */
+export function apiAuditEntry(
+  tool: ApiTool,
+  origin: Origin,
+  guard: GuardValue,
+  ctx: Ctx,
+  extra: { input: unknown; ok: boolean; error?: string },
+): AuditEntry {
+  return { tool: `api.${tool.name}`, origin, guard, at: Date.now(), agent: agentKeyId(ctx), ...extra };
+}
+
+/** Single invocation pipeline for api() tools: guard → validate → run → validate output. */
+export async function invokeApi(
+  tool: ApiTool,
+  input: unknown,
+  ctx: Ctx,
+  origin: Origin,
+  onAudit?: ApiAudit,
+): Promise<unknown> {
+  const guard = resolveApiGuard(tool, ctx);
+  const audit = (extra: { input: unknown; ok: boolean; error?: string }) =>
+    onAudit?.(apiAuditEntry(tool, origin, guard, ctx, extra));
+
+  try {
+    if (origin === 'agent' && guard === 'forbidden') {
+      throw new JanuxIntentError('forbidden', `Tool "${tool.name}" is not available`);
+    }
+    const parsed = parseApiInput(tool, input);
+    const result = checkOutput(tool, await tool.run({ input: parsed, ctx }));
+
+    audit({ input: parsed, ok: true });
+
+    return result;
+  } catch (error) {
+    audit({ input, ok: false, error: String(error) });
+    throw error;
+  }
 }
 
 export function apiManifestTools(tools: ApiTool[], ctx: Ctx) {

package/src/html-shell.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'bun:test';
+import { htmlDocument, type ShellOptions } from './html-shell';
+
+const base: ShellOptions = {
+  html: '<main>hi</main>',
+  snapshots: [],
+  islandNames: [],
+};
+
+// These guard the SPA-navigation FOUC fix: head resource links must be keyed
+// (matched by identity across the diff) and the conditional description meta
+// must sit AFTER the stylesheets, so omitting it never shifts the stylesheet's
+// position — otherwise the diff re-resolves it and the page flashes unstyled.
+describe('htmlDocument head keying (SPA-navigation FOUC guard)', () => {
+  it('gives stylesheet, favicon and manifest links a stable id', () => {
+    const html = htmlDocument({
+      ...base,
+      stylesheets: ['/styles.css'],
+      favicon: '/favicon.svg',
+      manifestUrl: '/_janux/manifest',
+    });
+
+    expect(html).toContain('<link rel="stylesheet" id="jx-style-0" href="/styles.css">');
+    expect(html).toContain('<link rel="icon" id="jx-favicon" href="/favicon.svg">');
+    expect(html).toContain('id="jx-manifest"');
+  });
+
+  it('places the conditional description meta after the stylesheet links', () => {
+    const html = htmlDocument({ ...base, stylesheets: ['/styles.css'], description: 'D' });
+
+    expect(html.indexOf('id="jx-style-0"')).toBeLessThan(html.indexOf('name="description"'));
+  });
+});

package/src/html-shell.ts

@@ -1,12 +1,14 @@
 export interface ShellOptions {
   html: string;
   title?: string;
+  description?: string;
   snapshots: { uri: string; state: Record<string, unknown>; sources?: Record<string, unknown> }[];
   islandNames: string[];
   islandModules?: Record<string, string>;
   runtimeUrl?: string;
   manifestUrl?: string;
   stylesheets?: string[];
+  favicon?: string;
 }
 
 function safeJson(value: unknown): string {
@@ -45,16 +47,31 @@ function runtimeScripts(options: ShellOptions): string {
  */
 export function htmlDocument(options: ShellOptions): string {
   const manifestLink = options.manifestUrl
-    ? `<link rel="janux-manifest" href="${options.manifestUrl}">`
+    ? `<link rel="janux-manifest" id="jx-manifest" href="${options.manifestUrl}">`
     : '';
+  // Stable ids key these head links across an SPA-navigation diff so the diff
+  // matches them by identity instead of by position. Without a key, a page
+  // whose head has a different node count (e.g. a description meta present on
+  // one page, absent on another) shifts every following node, making the diff
+  // re-resolve the stylesheet link — a brief unstyled flash. See navigate.ts.
   const styleLinks = (options.stylesheets ?? [])
-    .map((href) => `<link rel="stylesheet" href="${safeAttr(href)}">`)
+    .map((href, index) => `<link rel="stylesheet" id="jx-style-${index}" href="${safeAttr(href)}">`)
     .join('');
+  const description = options.description
+    ? `<meta name="description" id="jx-description" content="${safeAttr(options.description)}">`
+    : '';
+  const favicon = options.favicon
+    ? `<link rel="icon" id="jx-favicon" href="${safeAttr(options.favicon)}">`
+    : '';
 
   return [
     '<!doctype html>',
     '<html>',
-    `<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${options.title ?? 'Janux app'}</title>${manifestLink}${styleLinks}</head>`,
+    // Order matters for SPA-navigation diffing: persistent, keyed resource
+    // links (favicon, stylesheets) sit before the conditional description meta,
+    // so a page that omits the description never shifts the stylesheet's
+    // position — it stays put across the diff instead of being moved/re-resolved.
+    `<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${safeAttr(options.title ?? 'Janux app')}</title>${favicon}${manifestLink}${styleLinks}${description}</head>`,
     '<body>',
     options.html,
     options.islandNames.length > 0 ? stateScripts(options.snapshots) : '',

package/src/http.ts

@@ -0,0 +1,44 @@
+import { validate } from 'janux';
+
+export interface PendingApiProposal {
+  id: string;
+  tool: string;
+  input: unknown;
+  execute: () => Promise<unknown>;
+}
+
+const MAX_PENDING_PROPOSALS = 100;
+
+export function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+export function errorStatus(error: unknown): number {
+  const code = (error as any)?.code;
+
+  return code === 'forbidden' ? 403 : code === 'invalid_input' ? 400 : 500;
+}
+
+export function evictOldestProposal(proposals: Map<string, PendingApiProposal>): void {
+  if (proposals.size < MAX_PENDING_PROPOSALS) return;
+  const oldest = proposals.keys().next().value;
+
+  if (oldest) proposals.delete(oldest);
+}
+
+export function assertValidInput(tool: { name: string; input?: any }, input: unknown): unknown {
+  const result = validate(tool.input, input ?? {});
+
+  if (!result.ok) {
+    const detail = result.errors.map((e: any) => `${e.path}: ${e.message}`).join('; ');
+
+    throw Object.assign(new Error(`Invalid input for "${tool.name}" — ${detail}`), {
+      code: 'invalid_input',
+    });
+  }
+
+  return result.value;
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 export { api, collectApis, invokeApi, apiManifestTools, isApi, type ApiDef, type ApiTool } from './api';
 export { createJanuxServer, type ServerOptions, type AgentMount, type AgentDeps } from './server';
 export { createFsRouter, type RouteMatch } from './router';
+export { buildLlmsTxt, type LlmsTxtConfig, type LlmsTxtTool } from './llms-txt';
+export { createAgentAuth, type AgentAuth, type AgentIdentity, type AgentsConfig } from './agent-auth';
 export { htmlDocument, type ShellOptions } from './html-shell';

package/src/llms-txt.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'bun:test';
+import { jsx, schema, str } from 'janux';
+import { api } from './api';
+import { buildLlmsTxt, expandPattern } from './llms-txt';
+import { createJanuxServer } from './server';
+
+describe('expandPattern', () => {
+  it('substitutes every dynamic segment per params record, URI-encoded', () => {
+    const paths = expandPattern('/docs/[section]/[slug]', [
+      { section: 'guide', slug: 'getting-started' },
+      { section: 'more', slug: 'a b' },
+    ]);
+
+    expect(paths).toEqual(['/docs/guide/getting-started', '/docs/more/a%20b']);
+  });
+
+  it('drops records missing a param', () => {
+    expect(expandPattern('/docs/[section]/[slug]', [{ section: 'guide' }])).toEqual([]);
+  });
+});
+
+describe('buildLlmsTxt', () => {
+  it('renders title, pages and annotated tools', () => {
+    const output = buildLlmsTxt(
+      { title: 'Shop', description: 'A demo shop.' },
+      ['/', '/cart'],
+      [
+        { name: 'api.shop.catalog', description: 'List products', guard: 'auto' },
+        { name: 'api.shop.pay', description: 'Charge the cart', guard: 'confirm' },
+      ],
+    );
+
+    expect(output).toContain('# Shop');
+    expect(output).toContain('> A demo shop.');
+    expect(output).toContain('- [/cart](/cart)');
+    expect(output).toContain('- [api.shop.catalog](/_janux/api/shop.catalog): List products');
+    expect(output).toContain('- [api.shop.pay](/_janux/api/shop.pay): Charge the cart (requires human approval)');
+  });
+
+  it('is byte-stable for an app without pages or tools', () => {
+    expect(buildLlmsTxt({}, [], [])).toBe('# Janux app\n');
+  });
+});
+
+describe('GET /llms.txt', () => {
+  const apis = {
+    pay: api({ description: 'Charge', input: schema({ total: str() }), guard: 'confirm', run: () => ({}) }),
+    hidden: api({ guard: 'forbidden', run: () => 'secret' }),
+  };
+
+  it('serves the index when llmsTxt is configured, excluding forbidden tools', async () => {
+    const server = createJanuxServer({
+      routes: { '/': () => jsx('main', {}) },
+      apis: { shop: apis },
+      title: 'Shop',
+      llmsTxt: { description: 'A demo shop.' },
+    });
+    const res = await server.fetch(new Request('http://test/llms.txt'));
+    const body = await res.text();
+
+    expect(res.headers.get('content-type')).toContain('text/plain');
+    expect(body).toContain('# Shop');
+    expect(body).toContain('api.shop.pay');
+    expect(body).not.toContain('hidden');
+    expect(await (await server.fetch(new Request('http://test/llms.txt'))).text()).toBe(body);
+  });
+
+  it('expands dynamic fs routes via staticParams and keeps the pattern without it', async () => {
+    const server = createJanuxServer({
+      routesDir: `${import.meta.dirname}/__fixtures__/routes`,
+      llmsTxt: {},
+    });
+    const body = await (await server.fetch(new Request('http://test/llms.txt'))).text();
+
+    expect(body).toContain('- [/orders/1](/orders/1)');
+    expect(body).toContain('- [/orders/2](/orders/2)');
+    expect(body).not.toContain('[id]');
+    expect(body).toContain('- [/tags/[tag]](/tags/[tag])');
+  });
+
+  it('listPages returns concrete paths, keeping unexpandable patterns', async () => {
+    const server = createJanuxServer({ routesDir: `${import.meta.dirname}/__fixtures__/routes` });
+
+    expect(await server.listPages()).toEqual(['/about', '/evil', '/orders/1', '/orders/2', '/tags/[tag]']);
+  });
+
+  it('404s when llmsTxt is not configured', async () => {
+    const server = createJanuxServer({ routes: { '/': () => jsx('main', {}) } });
+
+    expect((await server.fetch(new Request('http://test/llms.txt'))).status).toBe(404);
+  });
+});

package/src/llms-txt.ts

@@ -0,0 +1,51 @@
+export interface LlmsTxtConfig {
+  title?: string;
+  description?: string;
+}
+
+export interface LlmsTxtTool {
+  name: string;
+  description?: string;
+  guard: string;
+}
+
+const PARAM_SEGMENT = /\[([^\]]+)\]/g;
+
+function fillPattern(pattern: string, params: Record<string, unknown>): string | undefined {
+  const names = [...pattern.matchAll(PARAM_SEGMENT)].map((match) => match[1]!);
+
+  if (!names.every((name) => params[name] != null)) return undefined;
+
+  return pattern.replace(PARAM_SEGMENT, (_, name) => encodeURIComponent(String(params[name])));
+}
+
+/** Expands a dynamic route pattern with each params record; records missing a param are dropped. */
+export function expandPattern(pattern: string, paramsList: Array<Record<string, unknown>>): string[] {
+  return paramsList
+    .map((params) => fillPattern(pattern, params))
+    .filter((path): path is string => path !== undefined);
+}
+
+const TOOLS_INTRO =
+  'Server tools callable via `POST /_janux/api/<name>` (JSON body). ' +
+  'Per-page tools and resources: `GET /_janux/manifest?path=<page>`.';
+
+function toolLine(tool: LlmsTxtTool): string {
+  const wire = tool.name.replace(/^api\./, '');
+  const approval = tool.guard === 'confirm' ? ' (requires human approval)' : '';
+  const description = tool.description ? `: ${tool.description}` : ':';
+
+  return `- [${tool.name}](/_janux/api/${wire})${description}${approval}`;
+}
+
+/** Renders the llms.txt markdown index: title, pages and the agent tool surface. */
+export function buildLlmsTxt(config: LlmsTxtConfig, pages: string[], tools: LlmsTxtTool[]): string {
+  const blocks = [
+    `# ${config.title ?? 'Janux app'}`,
+    config.description ? `> ${config.description}` : undefined,
+    pages.length > 0 ? `## Pages\n\n${pages.map((page) => `- [${page}](${page})`).join('\n')}` : undefined,
+    tools.length > 0 ? `## Agent tools\n\n${TOOLS_INTRO}\n\n${tools.map(toolLine).join('\n')}` : undefined,
+  ];
+
+  return `${blocks.filter(Boolean).join('\n\n')}\n`;
+}

package/src/server.test.ts

@@ -116,6 +116,27 @@ describe('api endpoints', () => {
   });
 });
 
+describe('route meta', () => {
+  it('uses route-level meta for title and description', async () => {
+    const fsServer = createJanuxServer({ routesDir: `${import.meta.dirname}/__fixtures__/routes` });
+    const html = await (await fsServer.fetch(new Request('http://test/about'))).text();
+
+    expect(html).toContain('<title>About — Janux fixture</title>');
+    expect(html).toContain('<meta name="description" id="jx-description" content="Route-level metadata fixture.">');
+    expect(html).toContain('<main>About page</main>');
+  });
+});
+
+describe('title escaping (XSS regression)', () => {
+  it('escapes route meta titles', async () => {
+    const fsServer = createJanuxServer({ routesDir: `${import.meta.dirname}/__fixtures__/routes` });
+    const html = await (await fsServer.fetch(new Request('http://test/evil'))).text();
+
+    expect(html).not.toContain('</title><script>');
+    expect(html).toContain('&lt;/title>&lt;script>');
+  });
+});
+
 describe('manifest endpoint', () => {
   it('merges mounted islands and api tools per route', async () => {
     const manifest: any = await (await get('/_janux/manifest?path=/shop')).json();

package/src/server.ts

@@ -1,7 +1,10 @@
-import { buildManifest, renderToString, validate, type ComponentDef, type Ctx } from 'janux';
-import { apiManifestTools, collectApis, invokeApi, resolveApiGuard, type ApiTool } from './api';
-import { createFsRouter } from './router';
+import { buildManifest, renderToString, type AuditEntry, type ComponentDef, type Ctx } from 'janux';
+import { assertValidInput, errorStatus, evictOldestProposal, json, type PendingApiProposal } from './http';
+import { apiAuditEntry, apiManifestTools, collectApis, invokeApi, resolveApiGuard, type ApiTool } from './api';
+import { createAgentAuth, type AgentIdentity, type AgentsConfig } from './agent-auth';
+import { createFsRouter, type Route } from './router';
 import { htmlDocument } from './html-shell';
+import { buildLlmsTxt, expandPattern, type LlmsTxtConfig, type LlmsTxtTool } from './llms-txt';
 
 export interface AgentMount {
   handle(req: Request, deps: AgentDeps): Promise<Response>;
@@ -25,49 +28,32 @@ export interface ServerOptions {
   islandModules?: Record<string, string>;
   title?: string;
   stylesheets?: string[];
+  favicon?: string;
+  llmsTxt?: LlmsTxtConfig;
+  agents?: AgentsConfig;
+  onAudit?: (entry: AuditEntry) => void;
 }
 
-interface PendingApiProposal {
-  id: string;
-  tool: string;
-  input: unknown;
-  execute: () => Promise<unknown>;
-}
-
-function json(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { 'content-type': 'application/json' },
-  });
-}
-
-const MAX_PENDING_PROPOSALS = 100;
-
-function evictOldestProposal(proposals: Map<string, PendingApiProposal>): void {
-  if (proposals.size < MAX_PENDING_PROPOSALS) return;
-  const oldest = proposals.keys().next().value;
-
-  if (oldest) proposals.delete(oldest);
-}
-
-function assertValidInput(tool: { name: string; input?: any }, input: unknown): unknown {
-  const result = validate(tool.input, input ?? {});
-
-  if (!result.ok) {
-    const detail = result.errors.map((e: any) => `${e.path}: ${e.message}`).join('; ');
-
-    throw Object.assign(new Error(`Invalid input for "${tool.name}" — ${detail}`), {
-      code: 'invalid_input',
-    });
+async function resolveMeta(
+  rawMeta: unknown,
+  ctx: Ctx,
+  params: Record<string, string>,
+): Promise<{ title?: string; description?: string } | undefined> {
+  try {
+    return typeof rawMeta === 'function' ? await rawMeta({ ctx, params }) : (rawMeta as any);
+  } catch {
+    return undefined;
   }
-
-  return result.value;
 }
 
-function errorStatus(error: unknown): number {
-  const code = (error as any)?.code;
+async function resolveStaticParams(rawParams: unknown): Promise<Array<Record<string, unknown>>> {
+  try {
+    const value = typeof rawParams === 'function' ? await rawParams() : rawParams;
 
-  return code === 'forbidden' ? 403 : code === 'invalid_input' ? 400 : 500;
+    return Array.isArray(value) ? value : [];
+  } catch {
+    return [];
+  }
 }
 
 let proposalSeq = 0;
@@ -81,6 +67,34 @@ export function createJanuxServer(options: ServerOptions = {}) {
 
   const resolveCtx = async (req: Request): Promise<Ctx> => (await options.ctxFor?.(req)) ?? {};
 
+  const agentAuth = options.agents ? createAgentAuth(options.agents) : undefined;
+
+  let llmsTxtBody: string | undefined;
+
+  const expandRoute = async (route: Route): Promise<string[]> => {
+    if (!route.pattern.includes('[')) return [route.pattern];
+    const module = (await loadRoute(route.filePath).catch(() => undefined)) as any;
+    const expanded = expandPattern(route.pattern, await resolveStaticParams(module?.staticParams));
+
+    return expanded.length > 0 ? expanded : [route.pattern];
+  };
+
+  const listPages = async (): Promise<string[]> => {
+    const fsPages = (await Promise.all(router?.routes.map(expandRoute) ?? [])).flat();
+
+    return [...Object.keys(options.routes ?? {}), ...fsPages];
+  };
+
+  const renderLlmsTxt = async (): Promise<string> =>
+    buildLlmsTxt({ title: options.title, ...options.llmsTxt }, await listPages(), apiManifestTools(apiTools, {}) as LlmsTxtTool[]);
+
+  const ctxWithAgent = async (req: Request): Promise<Ctx> => {
+    const ctx = await resolveCtx(req);
+    const identity = (await agentAuth?.identify(req)) ?? null;
+
+    return identity ? { ...ctx, agent: identity } : ctx;
+  };
+
   const findRoute = (pathname: string) => {
     if (options.routes?.[pathname]) {
       return { render: options.routes[pathname]!, params: {} as Record<string, string> };
@@ -94,10 +108,13 @@ export function createJanuxServer(options: ServerOptions = {}) {
     const route = findRoute(pathname);
 
     if (!route) return undefined;
-    const render = 'render' in route ? route.render : ((await loadRoute(route.load)) as any).default;
-    const vnode = render({ ctx, params: route.params });
+    const module = 'render' in route ? undefined : ((await loadRoute(route.load)) as any);
+    const render = 'render' in route ? route.render : module.default;
+    const meta = await resolveMeta(module?.meta, ctx, route.params);
+    const vnode = await render({ ctx, params: route.params });
+    const result = await renderToString(vnode, { ctx, storeDefs: options.storeDefs });
 
-    return renderToString(vnode, { ctx, storeDefs: options.storeDefs });
+    return { ...result, meta };
   };
 
   const manifestFor = async (pathname: string, ctx: Ctx): Promise<unknown> => {
@@ -118,7 +135,7 @@ export function createJanuxServer(options: ServerOptions = {}) {
 
     if (!tool) throw Object.assign(new Error(`Unknown api tool "${name}"`), { code: 'invalid_input' });
 
-    return invokeApi(tool, input, ctx, 'agent');
+    return invokeApi(tool, input, ctx, 'agent', options.onAudit);
   };
 
   const handleApi = async (req: Request, name: string): Promise<Response> => {
@@ -127,7 +144,11 @@ export function createJanuxServer(options: ServerOptions = {}) {
     if (!tool) return json({ ok: false, error: `Unknown api "${name}"` }, 404);
     const origin = req.headers.get('x-janux-origin') === 'agent' ? 'agent' : 'human';
     const input = await req.json().catch(() => ({}));
-    const ctx = await resolveCtx(req);
+    const ctx = await ctxWithAgent(req);
+
+    if (origin === 'agent' && agentAuth?.policy === 'require' && !(ctx.agent as AgentIdentity | undefined)?.verified) {
+      return json({ ok: false, error: 'agent_required' }, 401);
+    }
 
     try {
       if (origin === 'agent' && resolveApiGuard(tool, ctx) === 'confirm') {
@@ -135,12 +156,13 @@ export function createJanuxServer(options: ServerOptions = {}) {
         const id = `prop_api_${(proposalSeq += 1)}`;
 
         evictOldestProposal(proposals);
-        proposals.set(id, { id, tool: tool.name, input: parsed, execute: () => invokeApi(tool, parsed, ctx, 'human') });
+        proposals.set(id, { id, tool: tool.name, input: parsed, execute: () => invokeApi(tool, parsed, ctx, 'human', options.onAudit) });
+        options.onAudit?.(apiAuditEntry(tool, origin, 'confirm', ctx, { input: parsed, ok: true }));
 
         return json({ ok: true, result: { status: 'proposal', id, tool: tool.name, input: parsed } });
       }
 
-      return json({ ok: true, result: await invokeApi(tool, input, ctx, origin) });
+      return json({ ok: true, result: await invokeApi(tool, input, ctx, origin, options.onAudit) });
     } catch (error) {
       return json({ ok: false, error: String(error) }, errorStatus(error));
     }
@@ -164,13 +186,15 @@ export function createJanuxServer(options: ServerOptions = {}) {
     const islandNames = [...new Set(result.registry.islands.map(({ def }) => def.name))];
     const html = htmlDocument({
       html: result.html,
-      title: options.title,
+      title: result.meta?.title ?? options.title,
+      description: result.meta?.description,
       snapshots: result.snapshots,
       islandNames,
       islandModules: options.islandModules,
       runtimeUrl: islandNames.length > 0 ? options.runtimeUrl : undefined,
       manifestUrl: `/_janux/manifest?path=${encodeURIComponent(pathname)}`,
       stylesheets: options.stylesheets,
+      favicon: options.favicon,
     });
 
     return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } });
@@ -187,11 +211,16 @@ export function createJanuxServer(options: ServerOptions = {}) {
 
       return json({ ok: id ? proposals.delete(id) : false });
     }
+    if (pathname === '/llms.txt' && options.llmsTxt) {
+      llmsTxtBody ??= await renderLlmsTxt();
+
+      return new Response(llmsTxtBody, { headers: { 'content-type': 'text/plain; charset=utf-8' } });
+    }
     if (pathname === '/_janux/manifest') {
       return json(await manifestFor(url.searchParams.get('path') ?? '/', await resolveCtx(req)));
     }
     if (pathname === '/_janux/agent' && options.agent) {
-      const ctx = await resolveCtx(req);
+      const ctx = await ctxWithAgent(req);
 
       return options.agent.handle(req, {
         tools: apiTools,
@@ -203,5 +232,5 @@ export function createJanuxServer(options: ServerOptions = {}) {
     return handlePage(req, pathname);
   };
 
-  return { fetch, apiTools, manifestFor };
+  return { fetch, apiTools, manifestFor, listPages };
 }