Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

22.9 KB
Raw Blame
import { createServer } from 'node:http';
import { describe, expect, test } from 'vitest';
import { parseProblem, rawRequest } from '../composition-rig.test-helper.ts';
import { buildIngressPolicy } from '../ingress-policy.ts';
import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
import {
  type ApiRouteTable,
  createApiRequestPipeline,
  createApiRouteGroup,
} from './api-pipeline.ts';
import { createContentDispatch } from './content-dispatch.ts';
import { createHttpApp, type NativeApiHandle } from './http-app.ts';

const fakeLog = {
  error: () => {},
  warn: () => {},
  info: () => {},
  debug: () => {},
  child: () => fakeLog,
} as never;

const EXPECTED_ALLOW_HEADERS =
  'Content-Type, Authorization, traceparent, tracestate, baggage, x-request-id, x-ok-client-protocol, x-ok-client-runtime, x-ok-client-kind';

interface NativeRig {
  port: number;
  baseUrl: string;
  legacyCalls: string[];
  dispatched: string[];
  close: () => Promise<void>;
}

async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<NativeRig> {
  const legacyCalls: string[] = [];
  const dispatched: string[] = [];
  const table: ApiRouteTable = {
    resolve(pathname) {
      if (
        pathname === '/api/native-ping' ||
        pathname === '/api/agent-write-md' ||
        pathname === '/api/native-mutating' ||
        pathname === '/api/native-upload'
      ) {
        return {
          template: pathname,
          dispatch: async (req, res) => {
            dispatched.push(`${req.method} ${pathname}`);
            res.writeHead(200, { 'Content-Type': 'application/json' });
            res.end(JSON.stringify({ pong: true }));
          },
        };
      }
      if (pathname === '/api/native-revalidated') {
        return {
          template: pathname,
          dispatch: async (_req, res) => {
            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache' });
            res.end('{}');
          },
        };
      }
      if (pathname === '/api/native-throw') {
        return {
          template: pathname,
          dispatch: async () => {
            throw new Error('handler boom');
          },
        };
      }
      if (pathname === '/api/native-empty') {
        return { template: '/api/native-empty' };
      }
      return null;
    },
    isMutating: (pathname) =>
      pathname === '/api/native-mutating' || pathname === '/api/agent-write-md',
  };
  const nativeApi: NativeApiHandle = {
    paths: [
      '/api/native-ping',
      '/api/agent-write-md',
      '/api/native-mutating',
      '/api/native-upload',
      '/api/native-revalidated',
      '/api/native-throw',
      '/api/native-empty',
      '/api/native-declined',
    ],
    dispatch: createApiRequestPipeline({
      log: fakeLog,
      ephemeral: opts.ephemeral,
      table,
    }),
  };
  const { requestListener } = createHttpApp({
    nativeApi,
    contentDispatch: createContentDispatch({ ingressPolicy: buildIngressPolicy({}), log: fakeLog }),
    legacyDispatch: (req, res) => {
      legacyCalls.push(req.url ?? '');
      res.writeHead(299, { 'Content-Type': 'text/plain' });
      res.end('legacy');
    },
    log: fakeLog,
  });
  const server = createServer(requestListener);
  const { port, baseUrl } = await listenOnLoopback(server);
  return {
    port,
    baseUrl,
    legacyCalls,
    dispatched,
    close: () =>
      new Promise<void>((resolvePromise, reject) => {
        server.close((err) => (err ? reject(err) : resolvePromise()));
      }),
  };
}

describe('natively-mounted /api routes run the shared admission pipeline', () => {
  test('a claimed route is served natively — the legacy dispatch never sees it', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-ping`);
      expect(res.status).toBe(200);
      expect(await res.json()).toEqual({ pong: true });
      expect(rig.legacyCalls).toEqual([]);
    } finally {
      await rig.close();
    }
  });

  test('an unclaimed route still flows through the legacy dispatch', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/anything-else`);
      expect(res.status).toBe(299);
      expect(rig.legacyCalls).toEqual(['/api/anything-else']);
    } finally {
      await rig.close();
    }
  });

  test('a claimed path the table declines falls through to the legacy dispatch', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-declined`);
      expect(res.status).toBe(299);
      expect(rig.legacyCalls).toEqual(['/api/native-declined']);
      expect(res.headers.get('x-request-id')).toBeNull();
      expect(res.headers.get('access-control-allow-methods')).toBeNull();
    } finally {
      await rig.close();
    }
  });

  test('a declined path skips the gates too — foreign Origin falls through, not 403', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-declined`, {
        headers: { Origin: 'https://evil.example' },
      });
      expect(res.status).toBe(299);
      expect(rig.legacyCalls).toEqual(['/api/native-declined']);
    } finally {
      await rig.close();
    }
  });

  test('a dot-segment URL the router normalizes onto a claimed path still gets a response', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await rawRequest(rig.port, '/api/./native-ping', {});
      expect(res.status).toBe(299);
      expect(rig.legacyCalls).toEqual(['/api/./native-ping']);
    } finally {
      await rig.close();
    }
  });

  test('responses carry the x-request-id echo, honoring a well-formed inbound ID', async () => {
    const rig = await bootNativeRig();
    try {
      const minted = await fetch(`${rig.baseUrl}/api/native-ping`);
      expect(minted.headers.get('x-request-id')).toMatch(/^[A-Za-z0-9._-]{1,128}$/);

      const echoed = await fetch(`${rig.baseUrl}/api/native-ping`, {
        headers: { 'x-request-id': 'caller-chosen.id-42' },
      });
      expect(echoed.headers.get('x-request-id')).toBe('caller-chosen.id-42');
    } finally {
      await rig.close();
    }
  });

  test('API answers default to Cache-Control: no-store, refusals included', async () => {
    const rig = await bootNativeRig();
    try {
      const served = await fetch(`${rig.baseUrl}/api/native-ping`);
      expect(served.status).toBe(200);
      expect(served.headers.get('cache-control')).toBe('no-store');

      const refused = await fetch(`${rig.baseUrl}/api/native-ping`, {
        headers: { Origin: 'https://evil.example' },
      });
      expect(refused.status).toBe(403);
      expect(refused.headers.get('cache-control')).toBe('no-store');
    } finally {
      await rig.close();
    }
  });

  test('a route that names its own Cache-Control keeps it over the default', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-revalidated`);
      expect(res.status).toBe(200);
      expect(res.headers.get('cache-control')).toBe('no-cache');
    } finally {
      await rig.close();
    }
  });

  test('a foreign Origin is refused before dispatch with the legacy problem shape', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-ping`, {
        headers: { Origin: 'https://evil.example' },
      });
      expect(res.status).toBe(403);
      expect(res.headers.get('content-type')).toBe('application/problem+json');
      const body = (await res.json()) as { type?: string; title?: string; detail?: string };
      expect(body.type).toBe('urn:ok:error:invalid-origin');
      expect(body.title).toBe('Origin not allowed.');
      expect(body.detail).toBeUndefined();
      expect(res.headers.get('x-request-id')).not.toBeNull();
    } finally {
      await rig.close();
    }
  });

  test('an allowed browser Origin gets verbatim CORS reflection with the exact header list', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-ping`, {
        headers: { Origin: 'http://localhost:5173' },
      });
      expect(res.status).toBe(200);
      expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');
      expect(res.headers.get('vary')).toContain('Origin');
      expect(res.headers.get('access-control-allow-methods')).toBe(
        'GET, POST, PUT, DELETE, OPTIONS',
      );
      expect(res.headers.get('access-control-allow-headers')).toBe(EXPECTED_ALLOW_HEADERS);
      expect(res.headers.get('access-control-expose-headers')).toBe('x-request-id');
    } finally {
      await rig.close();
    }
  });

  test('OPTIONS preflight answers 204 with the CORS headers', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-ping`, {
        method: 'OPTIONS',
        headers: { Origin: 'http://localhost:5173' },
      });
      expect(res.status).toBe(204);
      expect(res.headers.get('access-control-allow-methods')).toBe(
        'GET, POST, PUT, DELETE, OPTIONS',
      );
    } finally {
      await rig.close();
    }
  });

  test('any forwarding header trips the proxied-request refusal on a native route', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await rawRequest(rig.port, '/api/native-ping', {
        headers: { 'X-Forwarded-For': '203.0.113.7' },
      });
      expect(res.status).toBe(403);
      const body = parseProblem(res.body);
      expect(body.type).toBe('urn:ok:error:host-not-allowed');
      expect(body.detail ?? body.title).toContain('Proxied request refused');
    } finally {
      await rig.close();
    }
  });

  test('native routes under a rebound Host are refused — mutating AND read', async () => {
    const rig = await bootNativeRig();
    try {
      const refused = await rawRequest(rig.port, '/api/native-mutating', {
        headers: { Host: 'evil.example' },
      });
      expect(refused.status).toBe(403);
      expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');

      const read = await rawRequest(rig.port, '/api/native-ping', {
        headers: { Host: 'evil.example' },
      });
      expect(read.status).toBe(403);
      expect(parseProblem(read.body).type).toBe('urn:ok:error:host-not-allowed');

      const allowed = await rawRequest(rig.port, '/api/native-mutating', {
        headers: { Host: 'localhost' },
      });
      expect(allowed.status).toBe(200);
    } finally {
      await rig.close();
    }
  });

  test('ephemeral mode Host-gates EVERY native /api route, including reads', async () => {
    const rig = await bootNativeRig({ ephemeral: true });
    try {
      const refused = await rawRequest(rig.port, '/api/native-ping', {
        headers: { Host: 'evil.example' },
      });
      expect(refused.status).toBe(403);
      expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');

      const allowed = await rawRequest(rig.port, '/api/native-ping', {
        headers: { Host: 'localhost' },
      });
      expect(allowed.status).toBe(200);
    } finally {
      await rig.close();
    }
  });

  test('previews reject project mutations while retaining document edits and reads', async () => {
    const rig = await bootNativeRig({ ephemeral: true });
    try {
      const blocked = await rawRequest(rig.port, '/api/native-mutating', { method: 'POST' });
      expect(blocked.status).toBe(403);
      expect(parseProblem(blocked.body).title).toBe(
        'Single-file previews cannot manage project files.',
      );
      const edit = await rawRequest(rig.port, '/api/agent-write-md', { method: 'POST' });
      expect(edit.status).toBe(200);
      const read = await rawRequest(rig.port, '/api/native-ping');
      expect(read.status).toBe(200);
      expect(rig.dispatched).toEqual(['POST /api/agent-write-md', 'GET /api/native-ping']);
    } finally {
      await rig.close();
    }
  });

  test('an owned URL with no handler gets the explicit RFC 9457 404', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-empty`);
      expect(res.status).toBe(404);
      expect(res.headers.get('content-type')).toBe('application/problem+json');
      const body = (await res.json()) as { type?: string; title?: string };
      expect(body.type).toBe('urn:ok:error:not-found');
      expect(body.title).toBe('API endpoint not found.');
      expect(rig.legacyCalls).toEqual([]);
    } finally {
      await rig.close();
    }
  });

  test('a throwing handler surfaces as the typed 500 envelope, not a reset', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await fetch(`${rig.baseUrl}/api/native-throw`);
      expect(res.status).toBe(500);
      expect(res.headers.get('content-type')).toBe('application/problem+json');
      const body = (await res.json()) as { type?: string };
      expect(body.type).toBe('urn:ok:error:internal-server-error');
    } finally {
      await rig.close();
    }
  });
});

describe('opaque origins and request body media types', () => {
  const OPAQUE_ORIGINS = ['null', 'file://', 'file://127.0.0.1'];
  const FILE_ORIGINS = ['file://', 'file://127.0.0.1'];
  const OPAQUE_DETAIL =
    'Requests from a null origin, and writes from a file: origin, are refused. Send the request from a loopback page, the OpenKnowledge app, or a client that sends no Origin header.';

  function expectNoCorsGrant(headers: Record<string, string | string[] | undefined>): void {
    expect(headers['access-control-allow-origin']).toBeUndefined();
    expect(headers['access-control-allow-methods']).toBeUndefined();
    expect(headers['access-control-allow-headers']).toBeUndefined();
    expect(headers['access-control-expose-headers']).toBeUndefined();
  }

  test('a read from a null Origin is refused 403 before dispatch', async () => {
    const rig = await bootNativeRig();
    try {
      const res = await rawRequest(rig.port, '/api/native-ping', { headers: { Origin: 'null' } });
      expect(res.status).toBe(403);
      const problem = parseProblem(res.body);
      expect(problem.type).toBe('urn:ok:error:invalid-origin');
      expect(problem.detail).toBe(OPAQUE_DETAIL);
      expectNoCorsGrant(res.headers);
      expect(rig.dispatched).toEqual([]);
    } finally {
      await rig.close();
    }
  });

  test('a read from a file: Origin is served with no CORS grant, so a browser cannot read it', async () => {
    const rig = await bootNativeRig();
    try {
      for (const origin of FILE_ORIGINS) {
        const res = await rawRequest(rig.port, '/api/native-ping', { headers: { Origin: origin } });
        expect(res.status, origin).toBe(200);
        expectNoCorsGrant(res.headers);
        expect(res.headers.vary, origin).toContain('Origin');
      }
    } finally {
      await rig.close();
    }
  });

  test('an opaque-Origin preflight is not granted; a loopback preflight still is', async () => {
    const rig = await bootNativeRig();
    try {
      const preflight = (origin: string) =>
        rawRequest(rig.port, '/api/native-mutating', {
          method: 'OPTIONS',
          headers: {
            Origin: origin,
            'Access-Control-Request-Method': 'POST',
            'Access-Control-Request-Headers': 'content-type',
          },
        });
      for (const origin of OPAQUE_ORIGINS) {
        const res = await preflight(origin);
        expect(res.status, origin).toBe(origin === 'null' ? 403 : 204);
        expectNoCorsGrant(res.headers);
      }
      const loopback = await preflight('http://localhost:5173');
      expect(loopback.status).toBe(204);
      expect(loopback.headers['access-control-allow-origin']).toBe('http://localhost:5173');
      expect(loopback.headers['access-control-allow-headers']).toBe(EXPECTED_ALLOW_HEADERS);
      expect(rig.dispatched).toEqual([]);
    } finally {
      await rig.close();
    }
  });

  test('every write from an opaque Origin is refused 403 before dispatch, whatever its body', async () => {
    const rig = await bootNativeRig();
    try {
      const bodies: Array<{ headers: Record<string, string>; body?: string }> = [
        { headers: { 'Content-Type': 'application/json' }, body: '{"path":"x.md"}' },
        { headers: { 'Content-Type': 'text/plain' }, body: '{"path":"x.md"}' },
        { headers: { 'Content-Type': 'multipart/form-data; boundary=b' }, body: '--b--\r\n' },
        { headers: {} },
      ];
      for (const origin of OPAQUE_ORIGINS) {
        for (const method of ['POST', 'PUT', 'PATCH', 'DELETE']) {
          for (const path of ['/api/native-mutating', '/api/native-upload']) {
            for (const shape of bodies) {
              const res = await rawRequest(rig.port, path, {
                method,
                headers: { ...shape.headers, Origin: origin },
                ...(shape.body !== undefined ? { body: shape.body } : {}),
              });
              const label = `${origin} ${method} ${path} ${shape.headers['Content-Type'] ?? 'bodyless'}`;
              expect(res.status, label).toBe(403);
              const problem = parseProblem(res.body);
              expect(problem.type, label).toBe('urn:ok:error:invalid-origin');
              expect(problem.detail, label).toBe(OPAQUE_DETAIL);
              expectNoCorsGrant(res.headers);
            }
          }
        }
      }
      expect(rig.dispatched).toEqual([]);
    } finally {
      await rig.close();
    }
  });

  test('body media types are not gated at the pipeline layer: every shape reaches dispatch', async () => {
    const rig = await bootNativeRig();
    try {
      for (const [method, contentType, hasBody] of [
        ['POST', 'application/json', true],
        ['POST', 'text/plain', true],
        ['POST', 'multipart/form-data; boundary=b', true],
        ['POST', undefined, false],
        ['DELETE', 'text/plain', true],
        ['GET', 'text/plain', false],
      ] as const) {
        const res = await rawRequest(rig.port, '/api/native-mutating', {
          method,
          headers: contentType === undefined ? {} : { 'Content-Type': contentType },
          ...(hasBody ? { body: '{"path":"x.md"}' } : {}),
        });
        expect(res.status, `${method} ${contentType ?? 'bodyless'}`).toBe(200);
      }
      expect(rig.dispatched).toEqual([
        'POST /api/native-mutating',
        'POST /api/native-mutating',
        'POST /api/native-mutating',
        'POST /api/native-mutating',
        'DELETE /api/native-mutating',
        'GET /api/native-mutating',
      ]);
    } finally {
      await rig.close();
    }
  });
});

describe('createApiRouteGroup', () => {
  const handler = async () => {};

  test('exact paths resolve with the URL as template; everything else declines', () => {
    const group = createApiRouteGroup({ '/api/alpha': handler, '/api/beta': handler });
    expect(group.paths).toEqual(['/api/alpha', '/api/beta']);
    const hit = group.table.resolve('/api/alpha');
    expect(hit?.template).toBe('/api/alpha');
    expect(hit?.dispatch).toBeDefined();
    expect(group.table.resolve('/api/gamma')).toBeNull();
  });

  test('mutating membership is URL-keyed and defaults to none', () => {
    const readOnly = createApiRouteGroup({ '/api/alpha': handler });
    expect(readOnly.table.isMutating('/api/alpha')).toBe(false);
    const mixed = createApiRouteGroup(
      { '/api/alpha': handler, '/api/beta': handler },
      { mutating: ['/api/beta'] },
    );
    expect(mixed.table.isMutating('/api/alpha')).toBe(false);
    expect(mixed.table.isMutating('/api/beta')).toBe(true);
  });

  test('mutatingPrefixes protect a namespace family by default, matching the legacy prefix rule', () => {
    const group = createApiRouteGroup(
      { '/api/local-op/clone': handler },
      { mutatingPrefixes: ['/api/local-op/'] },
    );
    expect(group.table.isMutating('/api/local-op/clone')).toBe(true);
    expect(group.table.isMutating('/api/local-op/brand-new-route')).toBe(true);
    expect(group.table.isMutating('/api/alpha')).toBe(false);
  });

  test('a mutating dynamic namespace declares its prefix in mutatingPrefixes', () => {
    const group = createApiRouteGroup(
      {},
      {
        mutatingPrefixes: ['/api/thing/'],
        dynamic: {
          prefix: '/api/thing/',
          template: '/api/thing/:id',
          dispatch: () => undefined,
        },
      },
    );
    expect(group.table.isMutating('/api/thing/abc')).toBe(true);
    expect(group.table.isMutating('/api/other')).toBe(false);
  });

  test('a malformed or orphaned mutatingPrefixes entry fails at construction', () => {
    expect(() =>
      createApiRouteGroup(
        { '/api/local-op/clone': handler },
        { mutatingPrefixes: ['/api/local-op'] },
      ),
    ).toThrow(/must end in '\/'/);
    expect(() =>
      createApiRouteGroup(
        { '/api/local-op/clone': handler },
        { mutatingPrefixes: ['/api/loca-op/'] },
      ),
    ).toThrow(/covers no registered route/);
  });

  test('a namespace-subsuming family collapses to the wildcard claim; keys outside the prefix stay mounted', () => {
    const group = createApiRouteGroup(
      { '/api/thing/alpha': handler, '/api/thing/nested/beta': handler, '/api/other': handler },
      {
        dynamic: {
          prefix: '/api/thing/',
          template: '/api/thing/:op',
          dispatch: () => undefined,
        },
      },
    );
    expect([...group.paths].sort()).toEqual(['/api/other', '/api/thing/*']);
    const member = group.table.resolve('/api/thing/alpha');
    expect(member?.template).toBe('/api/thing/alpha');
    expect(member?.dispatch).toBeDefined();
    const unknown = group.table.resolve('/api/thing/some-future-op');
    expect(unknown?.template).toBe('/api/thing/:op');
    expect(unknown?.dispatch).toBeUndefined();
  });

  test('a bare dynamic.prefix fails at construction — its wildcard would swallow unrelated siblings', () => {
    expect(() =>
      createApiRouteGroup(
        { '/api/local-op/clone': handler },
        {
          dynamic: {
            prefix: '/api/local-op',
            template: '/api/local-op/:op',
            dispatch: () => undefined,
          },
        },
      ),
    ).toThrow(/must end in '\/'/);
  });

  test('a dynamic leg claims its namespace: wildcard path, bound template, 404-able empty tail', () => {
    const seen: string[] = [];
    const group = createApiRouteGroup(
      { '/api/tags': handler },
      {
        dynamic: {
          prefix: '/api/tags/',
          template: '/api/tags/:name',
          dispatch: (suffix) => {
            if (!suffix) return undefined;
            return async () => {
              seen.push(suffix);
            };
          },
        },
      },
    );
    expect(group.paths).toEqual(['/api/tags', '/api/tags/*']);
    const named = group.table.resolve('/api/tags/til');
    expect(named?.template).toBe('/api/tags/:name');
    expect(named?.dispatch).toBeDefined();
    const empty = group.table.resolve('/api/tags/');
    expect(empty?.template).toBe('/api/tags/:name');
    expect(empty?.dispatch).toBeUndefined();
    expect(group.table.resolve('/api/other')).toBeNull();
  });
});