@20syldev/api 4.4.0 → 4.6.0

package/src/routes/patch.ts

@@ -1,4 +1,5 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
 import { ticTacToeStorage } from '../storage/index.js';
 import { error } from '../utils/response.js';
 

package/src/routes/post.ts

@@ -1,9 +1,10 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
+import { MAX_TOKEN_LENGTH, MIN_TOKEN_LENGTH } from '../constants.js';
+import type { HashResult } from '../modules/v4/hash.js';
 import { chatStorage, ticTacToeStorage } from '../storage/index.js';
-import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../constants.js';
-import { error } from '../utils/response.js';
 import { since } from '../utils/helpers.js';
-import type { HashResult } from '../modules/v4/hash.js';
+import { error } from '../utils/response.js';
 
 const router = Router();
 

package/src/storage/index.ts

@@ -1,4 +1,4 @@
-import type { ChatStorage, TicTacToeStorage, IpLimits } from '../types/storage.js';
+import type { ChatStorage, IpLimits, TicTacToeStorage } from '../types/storage.js';
 
 export const ipLimits: IpLimits = {};
 

package/src/utils/response.ts

@@ -1,4 +1,5 @@
 import type { Response } from 'express';
+
 import { DOCS_URL, STATUS_MESSAGES } from '../constants.js';
 
 /**
@@ -10,10 +11,18 @@ import { DOCS_URL, STATUS_MESSAGES } from '../constants.js';
  * @param docPath - Optional documentation path appended to the base URL
  */
 export function error(res: Response, status: number, message: string, docPath?: string): void {
-    res.status(status).jsonResponse({
+    const body = {
         message: STATUS_MESSAGES[status] ?? 'Error',
         error: message,
         documentation: docPath ? `${DOCS_URL}/${docPath}` : DOCS_URL,
         status: String(status),
-    });
+    };
+
+    if (typeof res.jsonResponse === 'function') {
+        res.status(status).jsonResponse(body);
+    } else {
+        res.status(status)
+            .setHeader('Content-Type', 'application/json')
+            .send(JSON.stringify(body, null, 2));
+    }
 }

package/tests/integration/api.test.ts

@@ -1,7 +1,8 @@
-import { test, describe, before, after } from 'node:test';
 import { strict as assert } from 'node:assert';
-import type { AddressInfo } from 'node:net';
 import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { after, before, describe, test } from 'node:test';
+
 import app from '../../src/app.js';
 
 let server: Server;
@@ -536,3 +537,125 @@ describe('POST /v4/token', () => {
         assert.equal(status, 400);
     });
 });
+
+// --- Security ---
+
+describe('Security headers', () => {
+    test('returns X-Content-Type-Options and X-Frame-Options', async () => {
+        const res = await fetch(`${baseUrl}/v4/color`);
+        assert.equal(res.headers.get('x-content-type-options'), 'nosniff');
+        assert.equal(res.headers.get('x-frame-options'), 'DENY');
+    });
+});
+
+describe('Payload size limit', () => {
+    test('body > 10kb returns 413', async () => {
+        const res = await fetch(`${baseUrl}/v4/hash`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ text: 'A'.repeat(20000), method: 'sha256' }),
+        });
+        assert.equal(res.status, 413);
+    });
+});
+
+describe('GET /v4/headers', () => {
+    test('returns headers object with count, ip, method, url', async () => {
+        const { status, body } = await getJson('/v4/headers');
+        assert.equal(status, 200);
+        assert.ok(typeof body.count === 'number');
+        assert.ok(typeof body.headers === 'object');
+        assert.ok('method' in body);
+        assert.equal(body.method, 'GET');
+        assert.ok((body.url as string).includes('/v4/headers'));
+    });
+
+    test('filter param returns only matching headers', async () => {
+        const { body } = await getJson('/v4/headers?filter=host');
+        const headers = body.headers as Record<string, unknown>;
+        assert.ok('host' in headers);
+        assert.equal(body.count, 1);
+    });
+
+    test('cookie header is redacted', async () => {
+        const res = await fetch(`${baseUrl}/v4/headers`, {
+            headers: { Cookie: 'session=secret123' },
+        });
+        const body = (await res.json()) as Record<string, unknown>;
+        const headers = body.headers as Record<string, unknown>;
+        assert.equal(headers['cookie'], '[redacted]');
+    });
+});
+
+describe('GET /v4/ip', () => {
+    test('returns valid ip result with no address param', async () => {
+        const { status, body } = await getJson('/v4/ip');
+        assert.equal(status, 200);
+        assert.ok(['IPv4', 'IPv6'].includes(body.version as string));
+        assert.ok(typeof body.binary === 'string');
+        assert.ok(typeof body.reverse === 'string');
+    });
+
+    test('loopback 127.0.0.1', async () => {
+        const { status, body } = await getJson('/v4/ip?address=127.0.0.1');
+        assert.equal(status, 200);
+        assert.equal(body.type, 'loopback');
+        assert.equal(body.version, 'IPv4');
+    });
+
+    test('private 192.168.1.1', async () => {
+        const { body } = await getJson('/v4/ip?address=192.168.1.1');
+        assert.equal(body.type, 'private');
+        assert.equal(body.decimal, 3232235777);
+    });
+
+    test('invalid address returns 400', async () => {
+        const { status } = await getJson('/v4/ip?address=notanip');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/agent', () => {
+    test('returns parsed result with browser, os, device, engine, bot', async () => {
+        const { status, body } = await getJson('/v4/agent');
+        assert.equal(status, 200);
+        assert.ok(typeof body.browser === 'object');
+        assert.ok(typeof body.os === 'object');
+        assert.ok(typeof body.device === 'object');
+        assert.ok(typeof body.engine === 'object');
+        assert.ok(typeof body.bot === 'boolean');
+    });
+
+    test('custom ua param is parsed', async () => {
+        const ua = encodeURIComponent(
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+        );
+        const { body } = await getJson(`/v4/agent?ua=${ua}`);
+        const browser = body.browser as Record<string, string>;
+        assert.equal(browser.name, 'Firefox');
+        assert.equal(browser.major, '121');
+    });
+
+    test('bot ua detected', async () => {
+        const ua = encodeURIComponent('Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)');
+        const { body } = await getJson(`/v4/agent?ua=${ua}`);
+        assert.equal(body.bot, true);
+    });
+});
+
+describe('Prototype access on dynamic endpoints', () => {
+    test('algorithms?method=toString returns 400', async () => {
+        const { status } = await getJson('/v4/algorithms?method=toString');
+        assert.equal(status, 400);
+    });
+
+    test('encode?method=constructor returns 400', async () => {
+        const { status } = await getJson('/v4/encode?method=constructor&text=hello');
+        assert.equal(status, 400);
+    });
+
+    test('validate?type=hasOwnProperty returns 400', async () => {
+        const { status } = await getJson('/v4/validate?type=hasOwnProperty&value=test');
+        assert.equal(status, 400);
+    });
+});

package/tests/unit/agent.test.ts

@@ -0,0 +1,113 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import agent from '../../src/modules/v4/agent.js';
+
+const CHROME_MAC =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+const FIREFOX_WIN = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0';
+const SAFARI_IPHONE =
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+const EDGE_WIN =
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0';
+const GOOGLEBOT = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+const IPAD =
+    'Mozilla/5.0 (iPad; CPU OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1';
+
+describe('agent', () => {
+    describe('browser detection', () => {
+        test('Chrome on macOS', () => {
+            const r = agent(CHROME_MAC);
+            assert.equal(r.browser.name, 'Chrome');
+            assert.equal(r.browser.major, '120');
+        });
+
+        test('Firefox on Windows', () => {
+            const r = agent(FIREFOX_WIN);
+            assert.equal(r.browser.name, 'Firefox');
+            assert.equal(r.browser.major, '121');
+        });
+
+        test('Safari on iPhone', () => {
+            const r = agent(SAFARI_IPHONE);
+            assert.equal(r.browser.name, 'Safari');
+        });
+
+        test('Edge detected before Chrome (both present in UA)', () => {
+            const r = agent(EDGE_WIN);
+            assert.equal(r.browser.name, 'Edge');
+        });
+
+        test('unknown browser returns unknown', () => {
+            const r = agent('UnknownBrowser/1.0');
+            assert.equal(r.browser.name, 'unknown');
+        });
+    });
+
+    describe('OS detection', () => {
+        test('macOS from Chrome UA', () => {
+            const r = agent(CHROME_MAC);
+            assert.equal(r.os.name, 'macOS');
+            assert.equal(r.os.version, '10.15.7');
+        });
+
+        test('Windows 10/11 from Firefox UA', () => {
+            const r = agent(FIREFOX_WIN);
+            assert.equal(r.os.name, 'Windows 10/11');
+        });
+
+        test('iOS from iPhone UA', () => {
+            const r = agent(SAFARI_IPHONE);
+            assert.equal(r.os.name, 'iOS');
+            assert.equal(r.os.version, '17.0');
+        });
+    });
+
+    describe('device detection', () => {
+        test('desktop from Chrome macOS', () => {
+            assert.equal(agent(CHROME_MAC).device.type, 'desktop');
+        });
+
+        test('mobile from iPhone UA', () => {
+            assert.equal(agent(SAFARI_IPHONE).device.type, 'mobile');
+        });
+
+        test('tablet from iPad UA', () => {
+            assert.equal(agent(IPAD).device.type, 'tablet');
+        });
+
+        test('Apple vendor from iPhone', () => {
+            assert.equal(agent(SAFARI_IPHONE).device.vendor, 'Apple');
+        });
+    });
+
+    describe('engine detection', () => {
+        test('Chrome uses Blink', () => {
+            assert.equal(agent(CHROME_MAC).engine.name, 'Blink');
+        });
+
+        test('Firefox uses Gecko', () => {
+            assert.equal(agent(FIREFOX_WIN).engine.name, 'Gecko');
+        });
+
+        test('Edge uses Blink', () => {
+            assert.equal(agent(EDGE_WIN).engine.name, 'Blink');
+        });
+    });
+
+    describe('bot detection', () => {
+        test('Googlebot is a bot', () => {
+            assert.equal(agent(GOOGLEBOT).bot, true);
+        });
+
+        test('Chrome is not a bot', () => {
+            assert.equal(agent(CHROME_MAC).bot, false);
+        });
+    });
+
+    describe('errors', () => {
+        test('throws on empty string', () => {
+            assert.throws(() => agent(''), /required/);
+        });
+    });
+});

package/tests/unit/algorithms.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import {
     anagram,
     factorial,

package/tests/unit/captcha.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import captcha from '../../src/modules/v4/captcha.js';
 
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);

package/tests/unit/chat.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import chat from '../../src/modules/v4/chat.js';
 import type { ChatStorage } from '../../src/types/storage.js';
 

package/tests/unit/color.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import color from '../../src/modules/v4/color.js';
 
 describe('color', () => {

package/tests/unit/convert.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import convert from '../../src/modules/v4/convert.js';
 
 describe('convert', () => {

package/tests/unit/dice.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import dice from '../../src/modules/v4/dice.js';
 
 describe('dice', () => {

package/tests/unit/domain.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import domain from '../../src/modules/v4/domain.js';
 
 describe('domain', () => {

package/tests/unit/encode.test.ts

@@ -1,16 +1,17 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import {
-    base64encode,
     base64decode,
-    urlencode,
-    urldecode,
+    base64encode,
+    binary,
+    caesar,
     morse,
-    unmorse,
     rot13,
-    caesar,
-    binary,
     unbinary,
+    unmorse,
+    urldecode,
+    urlencode,
 } from '../../src/modules/v4/encode.js';
 
 describe('encode', () => {

package/tests/unit/geo.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import geo from '../../src/modules/v4/geo.js';
 
 describe('geo', () => {

package/tests/unit/hash.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import hash from '../../src/modules/v4/hash.js';
 
 describe('hash', () => {

package/tests/unit/hyperplanning.test.ts

@@ -1,5 +1,6 @@
-import { test, describe, before, after } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { after, before, describe, test } from 'node:test';
+
 import hyperplanning from '../../src/modules/v4/hyperplanning.js';
 
 const ORIGINAL_FETCH = globalThis.fetch;
@@ -70,6 +71,25 @@ describe('hyperplanning', () => {
         const events = await hyperplanning('https://fake.test/cal.ics');
         assert.equal(events.length, 0);
     });
+
+    test('throws on HTTP URL', async () => {
+        await assert.rejects(() => hyperplanning('http://fake.test/cal.ics'), /Only HTTPS/);
+    });
+
+    test('throws on private IP', async () => {
+        await assert.rejects(() => hyperplanning('https://127.0.0.1/cal.ics'), /private/);
+        await assert.rejects(() => hyperplanning('https://192.168.1.1/cal.ics'), /private/);
+        await assert.rejects(() => hyperplanning('https://10.0.0.1/cal.ics'), /private/);
+        await assert.rejects(() => hyperplanning('https://169.254.169.254/latest'), /private/);
+    });
+
+    test('throws on localhost', async () => {
+        await assert.rejects(() => hyperplanning('https://localhost/cal.ics'), /private/);
+    });
+
+    test('throws on invalid URL', async () => {
+        await assert.rejects(() => hyperplanning('not-a-url'), /Invalid URL/);
+    });
 });
 
 before(() => {

package/tests/unit/ip.test.ts

@@ -0,0 +1,140 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import ip from '../../src/modules/v4/ip.js';
+
+describe('ip', () => {
+    describe('IPv4 — type detection', () => {
+        test('public IP returns public type and class A', () => {
+            const result = ip('8.8.8.8');
+            assert.equal(result.version, 'IPv4');
+            assert.equal(result.type, 'public');
+            assert.equal(result.class, 'A');
+        });
+
+        test('private 10.x.x.x', () => {
+            const result = ip('10.0.0.1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.range, '10.0.0.0/8');
+        });
+
+        test('private 172.16-31.x.x', () => {
+            const result = ip('172.16.0.1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.range, '172.16.0.0/12');
+        });
+
+        test('private 192.168.x.x', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.class, 'C');
+            assert.equal(result.range, '192.168.0.0/16');
+        });
+
+        test('loopback 127.0.0.1', () => {
+            const result = ip('127.0.0.1');
+            assert.equal(result.type, 'loopback');
+            assert.equal(result.range, '127.0.0.0/8');
+        });
+
+        test('link-local 169.254.x.x', () => {
+            const result = ip('169.254.1.1');
+            assert.equal(result.type, 'link-local');
+        });
+
+        test('multicast 224.x.x.x', () => {
+            const result = ip('224.0.0.1');
+            assert.equal(result.type, 'multicast');
+        });
+
+        test('broadcast 255.255.255.255', () => {
+            const result = ip('255.255.255.255');
+            assert.equal(result.type, 'broadcast');
+            assert.equal(result.class, 'E');
+        });
+    });
+
+    describe('IPv4 — representations', () => {
+        test('binary of 192.168.1.1', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.binary, '11000000.10101000.00000001.00000001');
+        });
+
+        test('decimal of 192.168.1.1', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.decimal, 3232235777);
+        });
+
+        test('decimal of 8.8.8.8', () => {
+            const result = ip('8.8.8.8');
+            assert.equal(result.decimal, 134744072);
+        });
+
+        test('reverse DNS of 192.168.1.1', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.reverse, '1.1.168.192.in-addr.arpa');
+        });
+
+        test('class B for 128.x', () => {
+            assert.equal(ip('128.0.0.1').class, 'B');
+        });
+
+        test('class C for 192.x (non-private)', () => {
+            assert.equal(ip('200.0.0.1').class, 'C');
+        });
+    });
+
+    describe('IPv6', () => {
+        test('loopback ::1', () => {
+            const result = ip('::1');
+            assert.equal(result.version, 'IPv6');
+            assert.equal(result.type, 'loopback');
+            assert.equal(result.range, '::1/128');
+        });
+
+        test('link-local fe80::1', () => {
+            const result = ip('fe80::1');
+            assert.equal(result.type, 'link-local');
+            assert.equal(result.range, 'fe80::/10');
+        });
+
+        test('unique-local fc00::1', () => {
+            const result = ip('fc00::1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.range, 'fc00::/7');
+        });
+
+        test('multicast ff02::1', () => {
+            const result = ip('ff02::1');
+            assert.equal(result.type, 'multicast');
+        });
+
+        test(':: expansion produces 8 groups', () => {
+            const result = ip('::1');
+            assert.equal(result.ip.split(':').length, 8);
+        });
+
+        test('reverse DNS ends in .ip6.arpa', () => {
+            const result = ip('::1');
+            assert.ok(result.reverse.endsWith('.ip6.arpa'));
+        });
+    });
+
+    describe('errors', () => {
+        test('throws on empty string', () => {
+            assert.throws(() => ip(''), /required/);
+        });
+
+        test('throws on invalid IPv4 octet > 255', () => {
+            assert.throws(() => ip('256.0.0.1'), /Invalid IPv4/);
+        });
+
+        test('throws on incomplete IPv4', () => {
+            assert.throws(() => ip('192.168.1'), /Invalid IPv4/);
+        });
+
+        test('throws on plain string', () => {
+            assert.throws(() => ip('notanip'), /Invalid IP address format/);
+        });
+    });
+});

package/tests/unit/levenshtein.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import levenshtein from '../../src/modules/v4/levenshtein.js';
 
 describe('levenshtein', () => {

package/tests/unit/palette.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import palette from '../../src/modules/v4/palette.js';
 
 describe('palette', () => {

package/tests/unit/personal.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import personal from '../../src/modules/v4/personal.js';
 
 describe('personal', () => {

package/tests/unit/placeholder.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import placeholder from '../../src/modules/v4/placeholder.js';
 
 describe('placeholder', () => {

package/tests/unit/qrcode.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import qrcode from '../../src/modules/v4/qrcode.js';
 
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);

package/tests/unit/statistics.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import statistics from '../../src/modules/v4/statistics.js';
 
 describe('statistics', () => {

package/tests/unit/text.test.ts

@@ -1,6 +1,7 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { slug, stats, lorem, number } from '../../src/modules/v4/text.js';
+import { describe, test } from 'node:test';
+
+import { lorem, number, slug, stats } from '../../src/modules/v4/text.js';
 
 describe('text', () => {
     describe('slug', () => {

package/tests/unit/tic_tac_toe.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import tic_tac_toe from '../../src/modules/v4/tic_tac_toe.js';
 import type { TicTacToeStorage } from '../../src/types/storage.js';