@nextrush/router 3.0.7 → 4.0.0-beta.1

package/src/__tests__/allowed-methods.test.ts

@@ -0,0 +1,144 @@
+/**
+ * @nextrush/router - allowedMethods() middleware characterization
+ *
+ * `allowedMethods()` (public) wraps `findAllowedMethods()` -> `findNode()`
+ * (both private, matching-engine cluster). Before the T014 split moves this
+ * cluster into `matching.ts`, this file characterizes its CURRENT end-to-end
+ * behavior through the only legitimate entry point — the public middleware —
+ * closing a real coverage gap: previously only `typeof middleware ===
+ * 'function'` was asserted, and `findNode`'s static/param/wildcard branches
+ * were never exercised via any public code path.
+ */
+
+import type { Context } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, Router } from '../router';
+
+function createMockContext(overrides: Partial<Context> = {}): Context {
+  return {
+    method: 'GET',
+    path: '/',
+    params: {},
+    query: {},
+    body: undefined,
+    headers: {},
+    status: 404,
+    state: {},
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    next: vi.fn(),
+    raw: {
+      req: {} as never,
+      res: {} as never,
+    },
+    ...overrides,
+  } as Context;
+}
+
+describe('allowedMethods() middleware — end-to-end characterization', () => {
+  let router: Router;
+
+  beforeEach(() => {
+    router = createRouter();
+  });
+
+  it('sets the Allow header and 200 status on an OPTIONS request to a known static path', async () => {
+    router.get('/r', vi.fn());
+    router.post('/r', vi.fn());
+
+    const ctx = createMockContext({ method: 'OPTIONS', path: '/r', status: 404 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(200);
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('GET'));
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('POST'));
+    expect(ctx.body).toBe('');
+  });
+
+  it('sets 405 and Allow header when the method is not registered for a known path', async () => {
+    router.get('/r', vi.fn());
+    router.post('/r', vi.fn());
+
+    const ctx = createMockContext({ method: 'DELETE', path: '/r', status: 404 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(405);
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('GET'));
+  });
+
+  it('leaves status untouched when the path is completely unknown (findNode returns null)', async () => {
+    router.get('/known', vi.fn());
+
+    const ctx = createMockContext({ method: 'GET', path: '/totally-unknown', status: 404 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    // No node found for the path at all -> findAllowedMethods returns [] ->
+    // early return, status stays 404 (whatever routes() already set).
+    expect(ctx.status).toBe(404);
+    expect(ctx.set).not.toHaveBeenCalled();
+  });
+
+  it('resolves a param route via findNode (paramChild branch)', async () => {
+    router.get('/users/:id', vi.fn());
+
+    const ctx = createMockContext({ method: 'OPTIONS', path: '/users/42', status: 404 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(200);
+    expect(ctx.set).toHaveBeenCalledWith('Allow', 'GET, HEAD');
+  });
+
+  it('resolves a wildcard route via findNode (wildcardChild branch)', async () => {
+    router.get('/files/*', vi.fn());
+
+    const ctx = createMockContext({ method: 'OPTIONS', path: '/files/a/b/c', status: 404 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(200);
+    expect(ctx.set).toHaveBeenCalledWith('Allow', 'GET, HEAD');
+  });
+
+  it('resolves a static-child branch deeper than one segment (findNode recursion)', async () => {
+    router.get('/api/v1/users', vi.fn());
+    router.post('/api/v1/users', vi.fn());
+
+    const ctx = createMockContext({ method: 'OPTIONS', path: '/api/v1/users', status: 404 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(200);
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('GET'));
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('POST'));
+  });
+
+  it('does not act when ctx.status is not 404 (route already matched successfully)', async () => {
+    router.get('/r', vi.fn());
+
+    const ctx = createMockContext({ method: 'GET', path: '/r', status: 200 });
+    const middleware = router.allowedMethods();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.set).not.toHaveBeenCalled();
+  });
+
+  it('reports allowed methods for a path via the public allowedMethods() middleware (replaces prior direct-private-call test)', async () => {
+    router.get('/r', vi.fn());
+    router.post('/r', vi.fn());
+
+    const ctx = createMockContext({ method: 'OPTIONS', path: '/r', status: 404 });
+    await router.allowedMethods()(ctx, async () => {});
+
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('GET'));
+    expect(ctx.set).toHaveBeenCalledWith('Allow', expect.stringContaining('POST'));
+    expect(ctx.set).not.toHaveBeenCalledWith('Allow', expect.stringContaining('DELETE'));
+  });
+});

package/src/__tests__/audit-fixes.test.ts

@@ -0,0 +1,59 @@
+/**
+ * @nextrush/router - Audit Remediation Tests
+ *
+ * RT-1 (reset clears the introspection registry), RT-5 (param-name conflict
+ * throws at registration), RT-7 (routes() is idempotent — no double-seal).
+ */
+
+import type { Context } from '@nextrush/types';
+import { describe, expect, it, vi } from 'vitest';
+import { createRouter } from '../router';
+
+describe('RT-1: reset() clears the introspection registry', () => {
+  it('getRoutes() is empty after reset()', () => {
+    const router = createRouter();
+    router.get('/users', vi.fn());
+    router.get('/users/:id', vi.fn());
+    expect(router.getRoutes().length).toBeGreaterThan(0);
+
+    router.reset();
+    expect(router.getRoutes()).toHaveLength(0);
+  });
+});
+
+describe('RT-5: param-name conflict throws at registration', () => {
+  it('throws when the same position uses two different param names', () => {
+    const router = createRouter();
+    router.get('/users/:id', vi.fn());
+    expect(() => router.get('/users/:userId/posts', vi.fn())).toThrow(/param/i);
+  });
+
+  it('does not throw when the param name is consistent', () => {
+    const router = createRouter();
+    router.get('/users/:id', vi.fn());
+    expect(() => router.get('/users/:id/posts', vi.fn())).not.toThrow();
+  });
+});
+
+describe('RT-7: routes() is idempotent w.r.t. router middleware sealing', () => {
+  it('runs router-level middleware exactly once even if routes() is called twice', async () => {
+    const router = createRouter();
+    const calls = { n: 0 };
+    router.use(async (_ctx: Context, next) => {
+      calls.n++;
+      if (next) await next();
+    });
+    router.get('/x', (ctx: Context) => {
+      ctx.body = 'ok';
+    });
+
+    router.routes();
+    router.routes(); // second call must not re-seal
+
+    const match = router.match('GET', '/x');
+    expect(match).not.toBeNull();
+    const ctx = { method: 'GET', path: '/x', params: {}, body: undefined } as unknown as Context;
+    await match!.executor!(ctx);
+    expect(calls.n).toBe(1);
+  });
+});

package/src/__tests__/canonical-path-security.test.ts

@@ -0,0 +1,198 @@
+/**
+ * @nextrush/router - SEC-02 / SEC-09 canonical-path security regression suite
+ *
+ * RED tests (tasks 3.1-3.3) for RFC-029: the router folds case and collapses
+ * structure for its own lookup, but never publishes that decision, and never
+ * rejects a dot segment. A path-based policy comparing raw `ctx.path` (the
+ * idiomatic prefix-guard pattern shown in this framework's own README) sees a
+ * different string than the one the router matched on.
+ *
+ * @see docs/RFC/request-data/029-canonical-request-path.md
+ */
+
+import type { Context, RouteHandler } from '@nextrush/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRouter, Router } from '../router';
+
+function createMockContext(overrides: Partial<Context> = {}): Context {
+  return {
+    method: 'GET',
+    path: '/',
+    params: {},
+    query: {},
+    body: undefined,
+    headers: {},
+    status: 200,
+    state: {},
+    json: vi.fn(),
+    send: vi.fn(),
+    html: vi.fn(),
+    redirect: vi.fn(),
+    set: vi.fn(),
+    get: vi.fn(),
+    next: vi.fn(),
+    raw: {
+      req: {} as never,
+      res: {} as never,
+    },
+    ...overrides,
+  } as Context;
+}
+
+describe('SEC-02: case-fold path-prefix authorization bypass (P1)', () => {
+  let router: Router;
+  let handler: RouteHandler;
+
+  beforeEach(() => {
+    router = createRouter();
+    handler = vi.fn();
+    router.get('/admin/users', handler);
+  });
+
+  it('3.1: dispatches a mixed-case request while a naive raw-ctx.path prefix guard never fires', () => {
+    // The exact PoC from report/security-review.md SEC-02: a policy comparing
+    // ctx.path.startsWith('/admin') against the RAW request target, guarding a
+    // route the router matches after folding.
+    const rawPath = '/ADMIN/users';
+    const guardWouldFire = rawPath.startsWith('/admin');
+
+    const match = router.match('GET', rawPath);
+
+    expect(guardWouldFire).toBe(false); // the guard never runs
+    expect(match).not.toBeNull(); // the router dispatches anyway
+    expect(match?.handler).toBe(handler);
+  });
+
+  it('3.1: a trailing-slash variant also dispatches while failing a naive equality guard', () => {
+    const rawPath = '/admin/users/';
+    const guardWouldFire = rawPath === '/admin/users';
+
+    const match = router.match('GET', rawPath);
+
+    expect(guardWouldFire).toBe(false);
+    expect(match).not.toBeNull();
+  });
+
+  it('3.1: a repeated-slash variant also dispatches while failing a naive equality guard', () => {
+    const rawPath = '//admin//users';
+    const guardWouldFire = rawPath === '/admin/users';
+
+    const match = router.match('GET', rawPath);
+
+    expect(guardWouldFire).toBe(false);
+    expect(match).not.toBeNull();
+  });
+});
+
+describe('SEC-09: no dot-segment normalization (P2)', () => {
+  let router: Router;
+
+  beforeEach(() => {
+    router = createRouter();
+    router.get('/api/webhooks/handler', vi.fn());
+    router.get('/admin', vi.fn());
+    router.get('/users/:id', vi.fn());
+    router.get('/files/*', vi.fn());
+  });
+
+  it.each([
+    ['/api/webhooks/../admin', 'literal dot segment'],
+    ['/api/./users', 'single-dot segment'],
+    ['/../..', 'leading dot segments past root'],
+  ])(
+    '3.2: %s (%s) is never rejected — it either 404s or resolves past its own directory, both unsafe for a canonical-path contract',
+    (path) => {
+      // TODAY: the router has no dot-segment concept at all — a dot segment is
+      // just an opaque path component. This test documents the RED state: no
+      // 400 is ever produced, because nothing in matching.ts/match-route.ts
+      // inspects segments for `.`/`..`. Once RFC-029 P0 lands, dot-segment
+      // paths must be rejected with 400 before reaching match() at all — this
+      // test's premise (the router matches or 404s, never rejects) must flip.
+      const match = router.match('GET', path);
+
+      // Current behavior: no route happens to be registered at the resolved
+      // literal segments, so this 404s (null) today — proving the absence of
+      // any dot-segment handling, not proving safety. A registered route at
+      // the resolved target would dispatch silently instead.
+      expect(match).toBeNull();
+    }
+  );
+
+  it('3.2: a percent-encoded double-dot segment is likewise passed through as an opaque literal segment', () => {
+    // %2e%2e is never decoded by matchRoute for structural purposes — only
+    // param VALUES are percent-decoded (decodeParam), and only after a param
+    // slot in the trie already matched. A dot segment used for traversal
+    // purposes is a static path segment, so it is compared literally as
+    // `%2e%2e`, which matches nothing today.
+    const match = router.match('GET', '/api/%2e%2e/admin');
+    expect(match).toBeNull();
+  });
+
+  it('3.2: a two-character segment starting with a dot but not a double-dot is not flagged as a traversal segment', () => {
+    router.get('/files/.x', vi.fn());
+    const match = router.match('GET', '/files/.x');
+    expect(match).not.toBeNull();
+  });
+
+  it('3.2: a dot as filename content (not a traversal segment) is accepted and dispatches normally', () => {
+    router.get('/files/archive.tar.gz', vi.fn());
+    const match = router.match('GET', '/files/archive.tar.gz');
+    expect(match).not.toBeNull();
+  });
+});
+
+describe('3.3: published-path contract (ctx.path / ctx.originalPath)', () => {
+  it('3.3: the router publishes the canonical path onto ctx.path and preserves the raw target on ctx.originalPath', async () => {
+    const router = createRouter();
+    let seenPath = '';
+    let seenOriginal: string | undefined;
+    router.get('/admin/users', (ctx) => {
+      seenPath = ctx.path;
+      seenOriginal = ctx.originalPath;
+    });
+
+    const ctx = createMockContext({ path: '/ADMIN/users?x=1' });
+    const middleware = router.routes();
+    await middleware(ctx, async () => {});
+
+    expect(seenPath).toBe('/admin/users');
+    expect(seenOriginal).toBe('/ADMIN/users?x=1');
+    expect(seenPath).not.toContain('?');
+  });
+
+  it('3.3: both ctx.path and ctx.originalPath are populated on a 404 (no route matched)', async () => {
+    const router = createRouter();
+    router.get('/users', () => undefined);
+
+    const ctx = createMockContext({ path: '/USERS/999' });
+    const middleware = router.routes();
+    await middleware(ctx, async () => {});
+
+    expect(ctx.status).toBe(404);
+    expect(ctx.path).toBe('/users/999');
+    expect((ctx as unknown as { originalPath?: string }).originalPath).toBe('/USERS/999');
+  });
+
+  it('a mocked ctx not yet touched by router dispatch has no originalPath — optional field, absent by default', () => {
+    const ctx = createMockContext({ path: '/ADMIN/users' });
+    expect((ctx as unknown as { originalPath?: string }).originalPath).toBeUndefined();
+  });
+
+  it('3.3: a dot-segment request rejected by dispatch sets 400 and still populates ctx.originalPath', async () => {
+    const router = createRouter();
+    router.get('/admin', vi.fn());
+
+    const ctx = createMockContext({ path: '/../admin' });
+    const middleware = router.routes();
+    let nextCalled = false;
+    await middleware(ctx, async () => {
+      nextCalled = true;
+    });
+
+    expect(ctx.status).toBe(400);
+    expect((ctx as unknown as { originalPath?: string }).originalPath).toBe('/../admin');
+    // A dot-segment rejection stops the chain outright — it never falls
+    // through to a 404/allowedMethods handler the way a plain miss does.
+    expect(nextCalled).toBe(false);
+  });
+});

package/src/__tests__/canonicalize-memo.test.ts

@@ -0,0 +1,108 @@
+/**
+ * @nextrush/router - Canonicalization memo correctness
+ *
+ * `canonicalizePath` memoizes its most recent result, and `matchesMountPrefix`
+ * memoizes the canonical form of its (registration-fixed) prefix. Both exist to
+ * remove the O(mounts) canonicalization cost a request paid falling through
+ * prefix mounts — measured at ~557 ns per mounted router before, ~190 ns after.
+ *
+ * A memo is only sound if it can never return an answer that differs from
+ * recomputing. The hazard is options: `caseSensitive` and `strict` change the
+ * result for the same input string, and two routers with different options can
+ * be mounted in the same application. These tests pin that.
+ *
+ * @see reports/investigations/post-audit-invariant-erosion-review.md F-1
+ */
+
+import { describe, expect, it } from 'vitest';
+import { canonicalizePath } from '../canonicalize';
+import { createRouter } from '../router';
+
+describe('canonicalizePath memo cannot leak across option combinations', () => {
+  it('returns the folded path for caseSensitive=false and the raw path for true', () => {
+    // Same input, alternating options — a memo keyed only on the string would
+    // return the first answer for both.
+    for (let i = 0; i < 3; i++) {
+      expect(canonicalizePath('/Users/List', false, false).path).toBe('/users/list');
+      expect(canonicalizePath('/Users/List', true, false).path).toBe('/Users/List');
+    }
+  });
+
+  it('respects strict for the same input string', () => {
+    for (let i = 0; i < 3; i++) {
+      expect(canonicalizePath('/users/', false, false).path).toBe('/users');
+      expect(canonicalizePath('/users/', false, true).path).toBe('/users/');
+    }
+  });
+
+  it('still rejects a dot segment after a non-rejected call for another path', () => {
+    expect(canonicalizePath('/safe/path', false, false).rejected).toBe(false);
+    expect(canonicalizePath('/a/../b', false, false).rejected).toBe(true);
+    expect(canonicalizePath('/safe/path', false, false).rejected).toBe(false);
+    expect(canonicalizePath('/a/./b', false, false).rejected).toBe(true);
+  });
+
+  it('is stable under repetition and equal to a first-call result', () => {
+    const first = canonicalizePath('/A//b/', false, false);
+    canonicalizePath('/something/else', true, true);
+    const again = canonicalizePath('/A//b/', false, false);
+    expect(again.path).toBe(first.path);
+    expect(again.rejected).toBe(first.rejected);
+    expect(again.path).toBe('/a/b');
+  });
+
+  it('strips the query string consistently whether memoized or not', () => {
+    expect(canonicalizePath('/users?a=1', false, false).path).toBe('/users');
+    expect(canonicalizePath('/users?a=1', false, false).path).toBe('/users');
+    expect(canonicalizePath('/users?b=2', false, false).path).toBe('/users');
+  });
+});
+
+describe('matchesMountPrefix prefix memo', () => {
+  it('returns the correct remainder repeatedly for one prefix', () => {
+    const router = createRouter();
+    for (let i = 0; i < 3; i++) {
+      expect(router.matchesMountPrefix('/api/v1/users/42', '/api/v1')).toBe('/users/42');
+    }
+  });
+
+  it('handles a router tested against two different prefixes (memo miss path)', () => {
+    const router = createRouter();
+    expect(router.matchesMountPrefix('/api/users', '/api')).toBe('/users');
+    expect(router.matchesMountPrefix('/admin/users', '/admin')).toBe('/users');
+    expect(router.matchesMountPrefix('/api/users', '/api')).toBe('/users');
+    // A prefix that does not match must still miss after the memo warmed.
+    expect(router.matchesMountPrefix('/api/users', '/admin')).toBeUndefined();
+  });
+
+  it('folds the prefix per the router own caseSensitive option', () => {
+    const insensitive = createRouter();
+    expect(insensitive.matchesMountPrefix('/ADMIN/Users', '/admin')).toBe('/users');
+
+    const sensitive = createRouter({ caseSensitive: true });
+    expect(sensitive.matchesMountPrefix('/ADMIN/Users', '/admin')).toBeUndefined();
+    expect(sensitive.matchesMountPrefix('/admin/Users', '/admin')).toBe('/Users');
+  });
+
+  it('enforces the segment boundary rather than a bare string prefix', () => {
+    const router = createRouter();
+    expect(router.matchesMountPrefix('/apifoo/bar', '/api')).toBeUndefined();
+    expect(router.matchesMountPrefix('/api/bar', '/api')).toBe('/bar');
+    expect(router.matchesMountPrefix('/api', '/api')).toBe('/');
+  });
+
+  it('rejects a dot-segment path', () => {
+    const router = createRouter();
+    expect(router.matchesMountPrefix('/api/../secret', '/api')).toBeUndefined();
+  });
+
+  it('gives two routers with different options independent answers', () => {
+    const a = createRouter({ caseSensitive: false });
+    const b = createRouter({ caseSensitive: true });
+    // Interleaved, so a shared memo keyed only on the string would cross over.
+    for (let i = 0; i < 3; i++) {
+      expect(a.matchesMountPrefix('/API/x', '/api')).toBe('/x');
+      expect(b.matchesMountPrefix('/API/x', '/api')).toBeUndefined();
+    }
+  });
+});