v7.10.2

Introduce structured security headers support (CSP, HSTS, X-Frame-Options, COOP/COEP/CORP, Permissions-Policy, Referrer-Policy, X-XSS-Protection, etc.) and apply them to responses and OPTIONS preflight. Expose configuration via the server API and document usage. Also update UtilityWebsiteServer defaults (SPA fallback enabled by default) and related docs.

changelog.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 2025-12-05 - 7.10.2 - fix(docs)
+Update README with routing examples and utility server config; bump @cloudflare/workers-types and @push.rocks/smartserve versions
+
+- Bumped dependency @cloudflare/workers-types to ^4.20251205.0
+- Bumped dependency @push.rocks/smartserve to ^1.3.0
+- Expanded README: added decorator-based routing examples (Route/Get/Post) using smartserve
+- Added programmatic routing examples (addRoute) and SPA/wildcard route samples
+- Enhanced UtilityWebsiteServer and UtilityServiceServer docs: default port, ads.txt, feedMetadata, addCustomRoutes example and other config options
+- Clarified security headers descriptions and configuration reference
+- Updated Quick Start console message to show running port ("Server running on port 3000!")
+- Documented EdgeWorker/domain routing caching example and noted service worker version update behavior
+- Adjusted TypedSocket example tag to use 'allClients' in README
+
+## 2025-12-05 - 7.10.1 - fix(typedserver)
+Use smartserve ControllerRegistry for custom routes and remove custom route parsing
+
+- addRoute now delegates to plugins.smartserve.ControllerRegistry instead of building its own regex-based matcher
+- Backwards compatibility: incoming smartserve IRequestContext is converted to a Request and ctx.params is attached to request.params before invoking the handler
+- Removed internal IRegisteredRoute, customRoutes storage, and parseRouteParams helper
+- Request handling now uses ControllerRegistry.matchRoute and registered controllers are compiled via ControllerRegistry.compileRoutes()
+
+## 2025-12-05 - 7.10.0 - feat(website-server)
+Add configurable ads.txt support to website server
+
+- Introduce adsTxt?: string[] option to the server options to allow configuring ads.txt entries.
+- Serve /ads.txt only when adsTxt is provided; the route is not registered if no entries are configured.
+- Replace previous hard-coded Google ads.txt entry with values joined from the provided adsTxt array and served as text/plain.
+- Preserves existing behavior when adsTxt is not set (no /ads.txt endpoint will be exposed).
+
+## 2025-12-05 - 7.9.0 - feat(typedserver)
+Add configurable security headers and default SPA behavior
+
+Introduce structured security headers support (CSP, HSTS, X-Frame-Options, COOP/COEP/CORP, Permissions-Policy, Referrer-Policy, X-XSS-Protection, etc.) and apply them to responses and OPTIONS preflight. Expose configuration via the server API and document usage. Also update UtilityWebsiteServer defaults (SPA fallback enabled by default) and related docs.
+
+- Add ISecurityHeaders and IContentSecurityPolicy TypeScript interfaces to configure CSP, HSTS and other security-related headers.
+- Implement buildCspHeader to serialize CSP config and applyResponseHeaders to add CORS and all configured security headers to outgoing responses.
+- Apply security headers to OPTIONS preflight responses and all other responses by default when securityHeaders option is provided.
+- Add securityHeaders option to IServerOptions and wire it through TypedServer and UtilityWebsiteServer constructors.
+- Update UtilityWebsiteServer: renamed template to UtilityWebsiteServer, enable SPA fallback by default, expose options (cors, spaFallback, securityHeaders, forceSsl, port, feedMetadata, etc.) and forward them into the TypedServer instance.
+- Documentation: add Security Headers section and example usage to readme.md; document the UtilityWebsiteServer defaults and example.
+- Ensure CORS headers are only added when cors option is enabled.
+
 ## 2025-12-05 - 7.8.18 - fix(readme)
 Update README to reflect new features and updated examples (SPA/PWA/Edge/ServiceWorker) and clarify API usage
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api.global/typedserver",
-  "version": "7.8.18",
+  "version": "7.10.2",
   "description": "A TypeScript-based project for easy serving of static files with support for live reloading, compression, and typed requests.",
   "type": "module",
   "exports": {
@@ -61,7 +61,7 @@
     "@api.global/typedrequest": "^3.2.5",
     "@api.global/typedrequest-interfaces": "^3.0.19",
     "@api.global/typedsocket": "^4.1.0",
-    "@cloudflare/workers-types": "^4.20251202.0",
+    "@cloudflare/workers-types": "^4.20251205.0",
     "@design.estate/dees-catalog": "^2.0.3",
     "@design.estate/dees-comms": "^1.0.30",
     "@push.rocks/lik": "^6.2.2",
@@ -83,7 +83,7 @@
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrequest": "^5.0.1",
     "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/smartserve": "^1.1.2",
+    "@push.rocks/smartserve": "^1.3.0",
     "@push.rocks/smartsitemap": "^2.0.4",
     "@push.rocks/smartstream": "^3.2.5",
     "@push.rocks/smarttime": "^4.1.1",

pnpm-lock.yaml

@@ -16,10 +16,10 @@ importers:
         version: 3.0.19
       '@api.global/typedsocket':
         specifier: ^4.1.0
-        version: 4.1.0(@push.rocks/smartserve@1.1.2)
+        version: 4.1.0(@push.rocks/smartserve@1.3.0)
       '@cloudflare/workers-types':
-        specifier: ^4.20251202.0
-        version: 4.20251202.0
+        specifier: ^4.20251205.0
+        version: 4.20251205.0
       '@design.estate/dees-catalog':
         specifier: ^2.0.3
         version: 2.0.3(@tiptap/pm@2.27.1)
@@ -84,8 +84,8 @@ importers:
         specifier: ^3.0.10
         version: 3.0.10
       '@push.rocks/smartserve':
-        specifier: ^1.1.2
-        version: 1.1.2
+        specifier: ^1.3.0
+        version: 1.3.0
       '@push.rocks/smartsitemap':
         specifier: ^2.0.4
         version: 2.0.4
@@ -125,7 +125,7 @@ importers:
         version: 2.0.0
       '@git.zone/tstest':
         specifier: ^3.1.3
-        version: 3.1.3(@aws-sdk/credential-providers@3.787.0)(@push.rocks/smartserve@1.1.2)(socks@2.8.7)(typescript@5.9.3)
+        version: 3.1.3(@aws-sdk/credential-providers@3.787.0)(@push.rocks/smartserve@1.3.0)(socks@2.8.7)(typescript@5.9.3)
       '@types/node':
         specifier: ^24.10.1
         version: 24.10.1
@@ -543,8 +543,8 @@ packages:
   '@borewit/text-codec@0.1.1':
     resolution: {integrity: sha512-5L/uBxmjaCIX5h8Z+uu+kA9BQLkc/Wl06UGR5ajNRxu+/XjonB5i8JpgFMrPj3LXTCPA0pv8yxUvbUi+QthGGA==}
 
-  '@cloudflare/workers-types@4.20251202.0':
-    resolution: {integrity: sha512-Q7m1Ivu2fbKalOPm00KLpu6GfRaq4TlrPknqugvZgp/gDH96OYKINO4x7jvCIBvCz/aK9vVoOj8tlbSQBervVA==}
+  '@cloudflare/workers-types@4.20251205.0':
+    resolution: {integrity: sha512-7pup7fYkuQW5XD8RUS/vkxF9SXlrGyCXuZ4ro3uVQvca/GTeSa+8bZ8T4wbq1Aea5lmLIGSlKbhl2msME7bRBA==}
 
   '@configvault.io/interfaces@1.0.17':
     resolution: {integrity: sha512-bEcCUR2VBDJsTin8HQh8Uw/mlYl2v8A3jMIaQ+MTB9Hrqd6CZL2dL7iJdWyFl/3EIX+LDxWFR+Oq7liIq7w+1Q==}
@@ -1297,8 +1297,8 @@ packages:
   '@push.rocks/smarts3@3.0.3':
     resolution: {integrity: sha512-Y9nXMwurthJ9Z7yi0RwjhPFUC58aY8Mhia8kFo6Xj1tBM4LE8Oxg/ydejF7otHqQGr3QyqV5C4YrDEG17rUuzg==}
 
-  '@push.rocks/smartserve@1.1.2':
-    resolution: {integrity: sha512-NkJNgdDt/rfsd9AMheCxtFd5X+ubzffvxOxjb0Aw1A5JR3xmiWeRifqEV1oN7mMTGL9jyQVvIME6Yrdxr244dA==}
+  '@push.rocks/smartserve@1.3.0':
+    resolution: {integrity: sha512-4ZR9uKVWXVAPzU5wtCQ1mA9jNmOlUl3oGr50EceLT6803UwbNcst7Ek/BhzSaZ0qb2pz0jO5T/V+icgvZ1/5ww==}
 
   '@push.rocks/smartshell@3.3.0':
     resolution: {integrity: sha512-m0w618H6YBs+vXGz1CgS4nPi5CUAnqRtckcS9/koGwfcIx1IpjqmiP47BoCTbdgcv0IPUxQVBG1IXTHPuZ8Z5g==}
@@ -4298,12 +4298,12 @@ snapshots:
       '@push.rocks/webrequest': 3.0.37
       '@push.rocks/webstream': 1.0.10
 
-  '@api.global/typedserver@3.0.80(@push.rocks/smartserve@1.1.2)':
+  '@api.global/typedserver@3.0.80(@push.rocks/smartserve@1.3.0)':
     dependencies:
       '@api.global/typedrequest': 3.2.5
       '@api.global/typedrequest-interfaces': 3.0.19
-      '@api.global/typedsocket': 3.1.1(@push.rocks/smartserve@1.1.2)
-      '@cloudflare/workers-types': 4.20251202.0
+      '@api.global/typedsocket': 3.1.1(@push.rocks/smartserve@1.3.0)
+      '@cloudflare/workers-types': 4.20251205.0
       '@design.estate/dees-comms': 1.0.30
       '@push.rocks/lik': 6.2.2
       '@push.rocks/smartchok': 1.1.1
@@ -4346,7 +4346,7 @@ snapshots:
       - utf-8-validate
       - vue
 
-  '@api.global/typedsocket@3.1.1(@push.rocks/smartserve@1.1.2)':
+  '@api.global/typedsocket@3.1.1(@push.rocks/smartserve@1.3.0)':
     dependencies:
       '@api.global/typedrequest': 3.2.5
       '@api.global/typedrequest-interfaces': 3.0.19
@@ -4357,7 +4357,7 @@ snapshots:
       '@push.rocks/smartstring': 4.1.0
       '@push.rocks/smarturl': 3.1.0
     optionalDependencies:
-      '@push.rocks/smartserve': 1.1.2
+      '@push.rocks/smartserve': 1.3.0
     transitivePeerDependencies:
       - '@nuxt/kit'
       - bufferutil
@@ -4366,7 +4366,7 @@ snapshots:
       - utf-8-validate
       - vue
 
-  '@api.global/typedsocket@4.1.0(@push.rocks/smartserve@1.1.2)':
+  '@api.global/typedsocket@4.1.0(@push.rocks/smartserve@1.3.0)':
     dependencies:
       '@api.global/typedrequest': 3.2.5
       '@api.global/typedrequest-interfaces': 3.0.19
@@ -4375,7 +4375,7 @@ snapshots:
       '@push.rocks/smartjson': 5.2.0
       '@push.rocks/smartpromise': 4.2.3
       '@push.rocks/smartrx': 3.0.10
-      '@push.rocks/smartserve': 1.1.2
+      '@push.rocks/smartserve': 1.3.0
       '@push.rocks/smartstring': 4.1.0
       '@push.rocks/smarturl': 3.1.0
 
@@ -5639,7 +5639,7 @@ snapshots:
 
   '@borewit/text-codec@0.1.1': {}
 
-  '@cloudflare/workers-types@4.20251202.0': {}
+  '@cloudflare/workers-types@4.20251205.0': {}
 
   '@configvault.io/interfaces@1.0.17':
     dependencies:
@@ -6026,9 +6026,9 @@ snapshots:
       '@push.rocks/smartshell': 3.3.0
       tsx: 4.20.6
 
-  '@git.zone/tstest@3.1.3(@aws-sdk/credential-providers@3.787.0)(@push.rocks/smartserve@1.1.2)(socks@2.8.7)(typescript@5.9.3)':
+  '@git.zone/tstest@3.1.3(@aws-sdk/credential-providers@3.787.0)(@push.rocks/smartserve@1.3.0)(socks@2.8.7)(typescript@5.9.3)':
     dependencies:
-      '@api.global/typedserver': 3.0.80(@push.rocks/smartserve@1.1.2)
+      '@api.global/typedserver': 3.0.80(@push.rocks/smartserve@1.3.0)
       '@git.zone/tsbundle': 2.6.3
       '@git.zone/tsrun': 2.0.0
       '@push.rocks/consolecolor': 2.0.3
@@ -6874,7 +6874,7 @@ snapshots:
     transitivePeerDependencies:
       - aws-crt
 
-  '@push.rocks/smartserve@1.1.2':
+  '@push.rocks/smartserve@1.3.0':
     dependencies:
       '@api.global/typedrequest': 3.2.5
       '@push.rocks/lik': 6.2.2
@@ -6907,7 +6907,7 @@ snapshots:
   '@push.rocks/smartsocket@2.1.0':
     dependencies:
       '@api.global/typedrequest-interfaces': 3.0.19
-      '@api.global/typedserver': 3.0.80(@push.rocks/smartserve@1.1.2)
+      '@api.global/typedserver': 3.0.80(@push.rocks/smartserve@1.3.0)
       '@push.rocks/isohash': 2.0.1
       '@push.rocks/isounique': 1.0.5
       '@push.rocks/lik': 6.2.2

readme.md

@@ -1,6 +1,6 @@
 # @api.global/typedserver
 
-A TypeScript-first web server framework for building modern full-stack applications. Features static file serving, live reload, type-safe API integration, service worker support, and edge computing capabilities. Part of the `@api.global` ecosystem.
+A powerful TypeScript-first web server framework for building modern full-stack applications. Features static file serving, live reload, type-safe API integration, decorator-based routing, service worker support, and edge computing capabilities. Part of the `@api.global` ecosystem.
 
 ## Issue Reporting and Security
 
@@ -9,6 +9,8 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ## ✨ Features
 
 - 🔒 **Type-Safe API** - Full TypeScript support with `@api.global/typedrequest` and `@api.global/typedsocket`
+- 🎯 **Decorator Routing** - Clean, expressive routing with `@Route`, `@Get`, `@Post` decorators via smartserve
+- 🛡️ **Security Headers** - Built-in CSP, HSTS, X-Frame-Options, and comprehensive security configuration
 - ⚡ **Live Reload** - Automatic browser refresh on file changes during development
 - 🛠️ **Service Worker** - Advanced caching, offline support, and background sync
 - ☁️ **Edge Workers** - Cloudflare Workers compatible edge computing with domain routing
@@ -42,7 +44,7 @@ const server = new TypedServer({
 });
 
 await server.start();
-console.log('Server running!');
+console.log('Server running on port 3000!');
 ```
 
 ### Full Configuration
@@ -85,6 +87,85 @@ const server = new TypedServer({
 await server.start();
 ```
 
+## 🛣️ Routing
+
+TypedServer uses a unified routing system powered by `@push.rocks/smartserve`. You can add routes using decorators or the programmatic API.
+
+### Decorator-Based Routing
+
+Create clean, expressive controllers using decorators:
+
+```typescript
+import * as smartserve from '@push.rocks/smartserve';
+
+@smartserve.Route('/api/users')
+class UserController {
+  @smartserve.Get('/')
+  async listUsers(ctx: smartserve.IRequestContext): Promise<Response> {
+    const users = await getUsersFromDb();
+    return new Response(JSON.stringify(users), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  @smartserve.Get('/:id')
+  async getUser(ctx: smartserve.IRequestContext): Promise<Response> {
+    const userId = ctx.params.id;
+    const user = await getUserById(userId);
+    return new Response(JSON.stringify(user), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  @smartserve.Post('/')
+  async createUser(ctx: smartserve.IRequestContext): Promise<Response> {
+    const userData = ctx.body;
+    const newUser = await createUserInDb(userData);
+    return new Response(JSON.stringify(newUser), {
+      status: 201,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+}
+
+// Register the controller
+smartserve.ControllerRegistry.registerInstance(new UserController());
+```
+
+### Programmatic Routes with `addRoute()`
+
+Add routes dynamically using the `addRoute()` API:
+
+```typescript
+import { TypedServer } from '@api.global/typedserver';
+
+const server = new TypedServer({ serveDir: './public', cors: true });
+
+// Simple route
+server.addRoute('/api/health', 'GET', async (request) => {
+  return new Response(JSON.stringify({ status: 'ok' }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+
+// Route with parameters (Express-style :param syntax)
+server.addRoute('/api/items/:id', 'GET', async (request) => {
+  const itemId = (request as any).params.id;
+  return new Response(JSON.stringify({ id: itemId }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+
+// Wildcard routes
+server.addRoute('/files/*path', 'GET', async (request) => {
+  const filePath = (request as any).params.path;
+  // Handle file serving logic
+  return new Response(`Requested: ${filePath}`);
+});
+
+await server.start();
+```
+
 ## 🔌 Type-Safe API Integration
 
 ### Adding TypedRequest Handlers
@@ -138,20 +219,22 @@ server.typedrouter.addTypedHandler<IChatMessage>(
 await server.start();
 
 // Push messages to connected clients
-const connections = await server.typedsocket.findAllTargetConnectionsByTag('typedserver_frontend');
+const connections = await server.typedsocket.findAllTargetConnectionsByTag('allClients');
 for (const conn of connections) {
-  // Push to specific clients
+  // Push to specific clients via TypedSocket
 }
 ```
 
 ## ☁️ Edge Worker (Cloudflare Workers)
 
+Deploy your application to the edge with Cloudflare Workers:
+
 ```typescript
 import { EdgeWorker, DomainRouter } from '@api.global/typedserver/edgeworker';
 
 const worker = new EdgeWorker();
 
-// Configure domain routing
+// Configure domain routing with caching
 worker.domainRouter.addDomainInstruction({
   domainPattern: '*.example.com',
   originUrl: 'https://origin.example.com',
@@ -159,10 +242,11 @@ worker.domainRouter.addDomainInstruction({
   cacheConfig: { maxAge: 3600 },
 });
 
+// Pass-through to origin for API routes
 worker.domainRouter.addDomainInstruction({
   domainPattern: 'api.example.com',
   originUrl: 'https://api-origin.example.com',
-  type: 'origin',  // Pass through to origin
+  type: 'origin',
 });
 
 // Cloudflare Worker entry point
@@ -187,8 +271,76 @@ const swClient = await getServiceworkerClient({
 // - Cache invalidation from server
 // - Offline support
 // - Background sync
+// - Version updates
 ```
 
+## 🛡️ Security Headers
+
+Configure comprehensive security headers including CSP, HSTS, and more:
+
+```typescript
+import { TypedServer } from '@api.global/typedserver';
+
+const server = new TypedServer({
+  serveDir: './dist',
+  cors: true,
+
+  securityHeaders: {
+    // Content Security Policy
+    csp: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-inline'", 'https://cdn.example.com'],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      imgSrc: ["'self'", 'data:', 'https:'],
+      connectSrc: ["'self'", 'wss:', 'https://api.example.com'],
+      fontSrc: ["'self'", 'https://fonts.gstatic.com'],
+      frameAncestors: ["'none'"],
+      upgradeInsecureRequests: true,
+    },
+
+    // HSTS (HTTP Strict Transport Security)
+    hstsMaxAge: 31536000,         // 1 year
+    hstsIncludeSubDomains: true,
+    hstsPreload: true,
+
+    // Other security headers
+    xFrameOptions: 'DENY',
+    xContentTypeOptions: true,
+    xXssProtection: true,
+    referrerPolicy: 'strict-origin-when-cross-origin',
+
+    // Cross-Origin policies
+    crossOriginOpenerPolicy: 'same-origin',
+    crossOriginEmbedderPolicy: 'require-corp',
+    crossOriginResourcePolicy: 'same-origin',
+
+    // Permissions Policy
+    permissionsPolicy: {
+      camera: [],
+      microphone: [],
+      geolocation: ['self'],
+    },
+  },
+});
+
+await server.start();
+```
+
+### Security Headers Reference
+
+| Header | Option | Description |
+|--------|--------|-------------|
+| `Content-Security-Policy` | `csp` | Controls resources the browser can load |
+| `Strict-Transport-Security` | `hstsMaxAge`, `hstsIncludeSubDomains`, `hstsPreload` | Forces HTTPS connections |
+| `X-Frame-Options` | `xFrameOptions` | Prevents clickjacking attacks |
+| `X-Content-Type-Options` | `xContentTypeOptions` | Prevents MIME-sniffing |
+| `X-XSS-Protection` | `xXssProtection` | Legacy XSS filter |
+| `Referrer-Policy` | `referrerPolicy` | Controls referrer information |
+| `Permissions-Policy` | `permissionsPolicy` | Controls browser features |
+| `Cross-Origin-Opener-Policy` | `crossOriginOpenerPolicy` | Isolates browsing context |
+| `Cross-Origin-Embedder-Policy` | `crossOriginEmbedderPolicy` | Controls cross-origin embedding |
+| `Cross-Origin-Resource-Policy` | `crossOriginResourcePolicy` | Controls cross-origin resource sharing |
+
 ## 📋 Configuration Reference
 
 ### IServerOptions
@@ -213,6 +365,7 @@ const swClient = await getServiceworkerClient({
 | `defaultAnswer` | `function` | - | Custom default response handler |
 | `feedMetadata` | `object` | - | RSS feed metadata options |
 | `blockWaybackMachine` | `boolean` | `false` | Block Wayback Machine archiving |
+| `securityHeaders` | `ISecurityHeaders` | - | Security headers configuration |
 
 ## 🏗️ Package Exports
 
@@ -228,21 +381,108 @@ const swClient = await getServiceworkerClient({
 
 ## 🔄 Utility Servers
 
-Pre-configured server templates for common use cases:
+Pre-configured server templates with best practices built-in.
+
+### UtilityWebsiteServer
+
+Optimized for modern web applications with SPA support enabled by default:
 
 ```typescript
 import { utilityservers } from '@api.global/typedserver';
 
-// WebsiteServer - optimized for static websites
-const websiteServer = new utilityservers.WebsiteServer({
+const websiteServer = new utilityservers.UtilityWebsiteServer({
   serveDir: './dist',
   domain: 'example.com',
+
+  // SPA fallback enabled by default
+  spaFallback: true,   // default: true
+
+  // Security headers
+  securityHeaders: {
+    csp: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-inline'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+    },
+    xFrameOptions: 'SAMEORIGIN',
+    xContentTypeOptions: true,
+  },
+
+  // Other options
+  cors: true,          // default: true
+  forceSsl: false,     // default: false
+  appSemVer: '1.0.0',
+  port: 3000,          // default: 3000
+
+  // Optional ads.txt entries (only served if configured)
+  adsTxt: [
+    'google.com, pub-1234567890, DIRECT, f08c47fec0942fa0',
+  ],
+
+  // RSS feed metadata
+  feedMetadata: {
+    title: 'My Blog',
+    description: 'A cool blog',
+    link: 'https://example.com',
+  },
+
+  // Add custom routes
+  addCustomRoutes: async (typedserver) => {
+    typedserver.addRoute('/api/custom', 'GET', async () => {
+      return new Response('Custom route!');
+    });
+  },
 });
 
-// ServiceServer - optimized for API services
-const serviceServer = new utilityservers.ServiceServer({
-  cors: true,
+await websiteServer.start();
+```
+
+### UtilityServiceServer
+
+Optimized for API services with auto-generated info page:
+
+```typescript
+import { utilityservers } from '@api.global/typedserver';
+
+const serviceServer = new utilityservers.UtilityServiceServer({
+  serviceName: 'My API',
+  serviceVersion: '1.0.0',
+  serviceDomain: 'api.example.com',
+  port: 8080,
+
+  // Add custom routes
+  addCustomRoutes: async (typedserver) => {
+    typedserver.addRoute('/api/status', 'GET', async () => {
+      return new Response(JSON.stringify({ status: 'healthy' }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    });
+  },
 });
+
+await serviceServer.start();
+```
+
+## 🧩 Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      TypedServer                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
+│  │ SmartServe  │  │ TypedRouter │  │    TypedSocket      │ │
+│  │ (Routing)   │  │ (RPC)       │  │    (WebSocket)      │ │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
+│         │                │                    │             │
+│         ▼                ▼                    ▼             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              Request Handler Pipeline               │   │
+│  │  1. Controller Registry (Decorated Routes)          │   │
+│  │  2. TypedRequest/TypedSocket handlers               │   │
+│  │  3. Static File Serving                             │   │
+│  │  4. SPA Fallback                                    │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 ## License and Legal Information

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@api.global/typedserver',
-  version: '7.8.18',
+  version: '7.10.2',
   description: 'A TypeScript-based project for easy serving of static files with support for live reloading, compression, and typed requests.'
 }

ts/classes.typedserver.ts

@@ -1,10 +1,80 @@
 import * as plugins from './plugins.js';
-import * as paths from './paths.js';
 import * as interfaces from '../dist_ts_interfaces/index.js';
 import { DevToolsController } from './controllers/controller.devtools.js';
 import { TypedRequestController } from './controllers/controller.typedrequest.js';
 import { BuiltInRoutesController } from './controllers/controller.builtin.js';
 
+/**
+ * Content Security Policy configuration
+ * Each directive can be a string or array of sources
+ */
+export interface IContentSecurityPolicy {
+  /** Fallback for other directives */
+  defaultSrc?: string | string[];
+  /** Valid sources for scripts */
+  scriptSrc?: string | string[];
+  /** Valid sources for stylesheets */
+  styleSrc?: string | string[];
+  /** Valid sources for images */
+  imgSrc?: string | string[];
+  /** Valid sources for fonts */
+  fontSrc?: string | string[];
+  /** Valid sources for AJAX, WebSockets, etc. */
+  connectSrc?: string | string[];
+  /** Valid sources for media (audio/video) */
+  mediaSrc?: string | string[];
+  /** Valid sources for frames */
+  frameSrc?: string | string[];
+  /** Valid sources for <object>, <embed>, <applet> */
+  objectSrc?: string | string[];
+  /** Valid sources for web workers */
+  workerSrc?: string | string[];
+  /** Valid sources for form actions */
+  formAction?: string | string[];
+  /** Controls which URLs can embed the page */
+  frameAncestors?: string | string[];
+  /** Restricts URLs for <base> element */
+  baseUri?: string | string[];
+  /** Report violations to this URL */
+  reportUri?: string;
+  /** Report violations to this endpoint */
+  reportTo?: string;
+  /** Upgrade insecure requests to HTTPS */
+  upgradeInsecureRequests?: boolean;
+  /** Block all mixed content */
+  blockAllMixedContent?: boolean;
+}
+
+/**
+ * Security headers configuration
+ */
+export interface ISecurityHeaders {
+  /** Content Security Policy */
+  csp?: IContentSecurityPolicy;
+  /** X-Frame-Options: DENY, SAMEORIGIN, or ALLOW-FROM uri */
+  xFrameOptions?: 'DENY' | 'SAMEORIGIN' | string;
+  /** X-Content-Type-Options: nosniff */
+  xContentTypeOptions?: boolean;
+  /** X-XSS-Protection header (legacy, but still useful) */
+  xXssProtection?: boolean | string;
+  /** Referrer-Policy header */
+  referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+  /** Strict-Transport-Security (HSTS) max-age in seconds */
+  hstsMaxAge?: number;
+  /** Include subdomains in HSTS */
+  hstsIncludeSubDomains?: boolean;
+  /** HSTS preload flag */
+  hstsPreload?: boolean;
+  /** Permissions-Policy (formerly Feature-Policy) */
+  permissionsPolicy?: Record<string, string[]>;
+  /** Cross-Origin-Opener-Policy */
+  crossOriginOpenerPolicy?: 'unsafe-none' | 'same-origin-allow-popups' | 'same-origin';
+  /** Cross-Origin-Embedder-Policy */
+  crossOriginEmbedderPolicy?: 'unsafe-none' | 'require-corp' | 'credentialless';
+  /** Cross-Origin-Resource-Policy */
+  crossOriginResourcePolicy?: 'same-site' | 'same-origin' | 'cross-origin';
+}
+
 export interface IServerOptions {
   /**
    * serve a particular directory
@@ -62,6 +132,11 @@ export interface IServerOptions {
    * Useful for single-page applications with client-side routing
    */
   spaFallback?: boolean;
+
+  /**
+   * Security headers configuration (CSP, HSTS, X-Frame-Options, etc.)
+   */
+  securityHeaders?: ISecurityHeaders;
 }
 
 export type THttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'ALL';
@@ -70,14 +145,6 @@ export interface IRouteHandler {
   (request: Request): Promise<Response | null>;
 }
 
-export interface IRegisteredRoute {
-  pattern: string;
-  regex: RegExp;
-  paramNames: string[];
-  method: THttpMethod;
-  handler: IRouteHandler;
-}
-
 export class TypedServer {
   // instance
   public options: IServerOptions;
@@ -100,9 +167,6 @@ export class TypedServer {
   // File server for static files
   private fileServer: plugins.smartserve.FileServer;
 
-  // Custom route handlers (for addRoute API)
-  private customRoutes: IRegisteredRoute[] = [];
-
   public lastReload: number = Date.now();
   public ended = false;
 
@@ -135,49 +199,18 @@ export class TypedServer {
    * @param handler - Async function that receives Request and returns Response or null
    */
   public addRoute(path: string, method: THttpMethod, handler: IRouteHandler): void {
-    // Convert Express-style path to regex
-    const paramNames: string[] = [];
-    let regexPattern = path
-      // Handle named parameters :param
-      .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName) => {
-        paramNames.push(paramName);
-        return '([^/]+)';
-      })
-      // Handle wildcard *splat (matches everything including slashes)
-      .replace(/\*([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName) => {
-        paramNames.push(paramName);
-        return '(.*)';
+    // Delegate to smartserve's ControllerRegistry
+    plugins.smartserve.ControllerRegistry.addRoute(path, method, async (ctx: plugins.smartserve.IRequestContext) => {
+      // Convert context to Request for backwards compatibility
+      const request = new Request(ctx.url.toString(), {
+        method: ctx.method,
+        headers: ctx.headers,
       });
-
-    // Ensure exact match
-    regexPattern = `^${regexPattern}$`;
-
-    this.customRoutes.push({
-      pattern: path,
-      regex: new RegExp(regexPattern),
-      paramNames,
-      method,
-      handler,
+      (request as any).params = ctx.params;
+      return handler(request);
     });
   }
 
-  /**
-   * Parse route parameters from a path using a registered route
-   */
-  private parseRouteParams(
-    route: IRegisteredRoute,
-    pathname: string
-  ): Record<string, string> | null {
-    const match = pathname.match(route.regex);
-    if (!match) return null;
-
-    const params: Record<string, string> = {};
-    route.paramNames.forEach((name, index) => {
-      params[name] = match[index + 1];
-    });
-    return params;
-  }
-
   /**
    * inits and starts the server
    */
@@ -388,16 +421,133 @@ export class TypedServer {
   }
 
   /**
-   * Add CORS headers to a response
+   * Build CSP header string from configuration
    */
-  private addCorsHeaders(response: Response): Response {
-    if (!this.options.cors) return response;
+  private buildCspHeader(csp: IContentSecurityPolicy): string {
+    const directives: string[] = [];
 
+    const addDirective = (name: string, value: string | string[] | undefined) => {
+      if (value) {
+        const sources = Array.isArray(value) ? value.join(' ') : value;
+        directives.push(`${name} ${sources}`);
+      }
+    };
+
+    addDirective('default-src', csp.defaultSrc);
+    addDirective('script-src', csp.scriptSrc);
+    addDirective('style-src', csp.styleSrc);
+    addDirective('img-src', csp.imgSrc);
+    addDirective('font-src', csp.fontSrc);
+    addDirective('connect-src', csp.connectSrc);
+    addDirective('media-src', csp.mediaSrc);
+    addDirective('frame-src', csp.frameSrc);
+    addDirective('object-src', csp.objectSrc);
+    addDirective('worker-src', csp.workerSrc);
+    addDirective('form-action', csp.formAction);
+    addDirective('frame-ancestors', csp.frameAncestors);
+    addDirective('base-uri', csp.baseUri);
+
+    if (csp.reportUri) {
+      directives.push(`report-uri ${csp.reportUri}`);
+    }
+    if (csp.reportTo) {
+      directives.push(`report-to ${csp.reportTo}`);
+    }
+    if (csp.upgradeInsecureRequests) {
+      directives.push('upgrade-insecure-requests');
+    }
+    if (csp.blockAllMixedContent) {
+      directives.push('block-all-mixed-content');
+    }
+
+    return directives.join('; ');
+  }
+
+  /**
+   * Apply all configured headers (CORS, security) to a response
+   */
+  private applyResponseHeaders(response: Response): Response {
     const headers = new Headers(response.headers);
-    headers.set('Access-Control-Allow-Origin', '*');
-    headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS, PATCH');
-    headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
-    headers.set('Access-Control-Max-Age', '86400');
+
+    // CORS headers
+    if (this.options.cors) {
+      headers.set('Access-Control-Allow-Origin', '*');
+      headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS, PATCH');
+      headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');
+      headers.set('Access-Control-Max-Age', '86400');
+    }
+
+    // Security headers
+    const security = this.options.securityHeaders;
+    if (security) {
+      // Content Security Policy
+      if (security.csp) {
+        const cspHeader = this.buildCspHeader(security.csp);
+        if (cspHeader) {
+          headers.set('Content-Security-Policy', cspHeader);
+        }
+      }
+
+      // X-Frame-Options
+      if (security.xFrameOptions) {
+        headers.set('X-Frame-Options', security.xFrameOptions);
+      }
+
+      // X-Content-Type-Options
+      if (security.xContentTypeOptions) {
+        headers.set('X-Content-Type-Options', 'nosniff');
+      }
+
+      // X-XSS-Protection
+      if (security.xXssProtection) {
+        const value = typeof security.xXssProtection === 'string'
+          ? security.xXssProtection
+          : '1; mode=block';
+        headers.set('X-XSS-Protection', value);
+      }
+
+      // Referrer-Policy
+      if (security.referrerPolicy) {
+        headers.set('Referrer-Policy', security.referrerPolicy);
+      }
+
+      // Strict-Transport-Security (HSTS)
+      if (security.hstsMaxAge !== undefined) {
+        let hsts = `max-age=${security.hstsMaxAge}`;
+        if (security.hstsIncludeSubDomains) {
+          hsts += '; includeSubDomains';
+        }
+        if (security.hstsPreload) {
+          hsts += '; preload';
+        }
+        headers.set('Strict-Transport-Security', hsts);
+      }
+
+      // Permissions-Policy
+      if (security.permissionsPolicy) {
+        const policies = Object.entries(security.permissionsPolicy)
+          .map(([feature, allowlist]) => `${feature}=(${allowlist.join(' ')})`)
+          .join(', ');
+        if (policies) {
+          headers.set('Permissions-Policy', policies);
+        }
+      }
+
+      // Cross-Origin-Opener-Policy
+      if (security.crossOriginOpenerPolicy) {
+        headers.set('Cross-Origin-Opener-Policy', security.crossOriginOpenerPolicy);
+      }
+
+      // Cross-Origin-Embedder-Policy
+      if (security.crossOriginEmbedderPolicy) {
+        headers.set('Cross-Origin-Embedder-Policy', security.crossOriginEmbedderPolicy);
+      }
+
+      // Cross-Origin-Resource-Policy
+      if (security.crossOriginResourcePolicy) {
+        headers.set('Cross-Origin-Resource-Policy', security.crossOriginResourcePolicy);
+      }
+    }
 
     return new Response(response.body, {
       status: response.status,
@@ -416,12 +566,12 @@ export class TypedServer {
 
     // Handle OPTIONS preflight for CORS
     if (method === 'OPTIONS' && this.options.cors) {
-      return this.addCorsHeaders(new Response(null, { status: 204 }));
+      return this.applyResponseHeaders(new Response(null, { status: 204 }));
     }
 
-    // Process the request and wrap response with CORS headers
+    // Process the request and wrap response with all configured headers
     const response = await this.handleRequestInternal(request, url, path, method);
-    return this.addCorsHeaders(response);
+    return this.applyResponseHeaders(response);
   }
 
   /**
@@ -458,18 +608,6 @@ export class TypedServer {
       }
     }
 
-    // Custom routes (registered via addRoute)
-    for (const route of this.customRoutes) {
-      if (route.method === 'ALL' || route.method === method) {
-        const params = this.parseRouteParams(route, path);
-        if (params !== null) {
-          (request as any).params = params;
-          const response = await route.handler(request);
-          if (response) return response;
-        }
-      }
-    }
-
     // HTML injection for reload (if enabled)
     if (this.options.injectReload && this.options.serveDir) {
       const response = await this.handleHtmlWithInjection(request);

ts/utilityservers/classes.websiteserver.ts

@@ -1,13 +1,30 @@
 import * as interfaces from '../../dist_ts_interfaces/index.js';
-import { type IServerOptions, TypedServer } from '../classes.typedserver.js';
+import { type IServerOptions, type ISecurityHeaders, TypedServer } from '../classes.typedserver.js';
 import * as plugins from '../plugins.js';
 
 export interface IUtilityWebsiteServerConstructorOptions {
+  /** Custom route handler to add additional routes */
   addCustomRoutes?: (typedserver: TypedServer) => Promise<any>;
+  /** Application semantic version */
   appSemVer?: string;
+  /** Domain name for the website */
   domain: string;
+  /** Directory to serve static files from */
   serveDir: string;
-  feedMetadata: IServerOptions['feedMetadata'];
+  /** RSS feed metadata */
+  feedMetadata?: IServerOptions['feedMetadata'];
+  /** Enable/disable CORS (default: true) */
+  cors?: boolean;
+  /** Enable/disable SPA fallback (default: true) */
+  spaFallback?: boolean;
+  /** Security headers configuration */
+  securityHeaders?: ISecurityHeaders;
+  /** Force SSL redirect (default: false) */
+  forceSsl?: boolean;
+  /** Port to listen on (default: 3000) */
+  port?: number;
+  /** ads.txt entries (only served if configured) */
+  adsTxt?: string[];
 }
 
 /**
@@ -29,14 +46,28 @@ export class UtilityWebsiteServer {
   /**
    * Start the website server
    */
-  public async start(portArg = 3000) {
+  public async start(portArg?: number) {
+    const port = portArg ?? this.options.port ?? 3000;
+
     this.typedserver = new TypedServer({
-      cors: true,
-      injectReload: true,
-      watch: true,
+      // Core settings
+      cors: this.options.cors ?? true,
       serveDir: this.options.serveDir,
       domain: this.options.domain,
-      forceSsl: false,
+      port,
+
+      // Development features
+      injectReload: true,
+      watch: true,
+
+      // SPA support (enabled by default for modern web apps)
+      spaFallback: this.options.spaFallback ?? true,
+
+      // Security
+      forceSsl: this.options.forceSsl ?? false,
+      securityHeaders: this.options.securityHeaders,
+
+      // PWA manifest
       manifest: {
         name: this.options.domain,
         short_name: this.options.domain,
@@ -46,11 +77,11 @@ export class UtilityWebsiteServer {
         background_color: '#000000',
         scope: '/',
       },
-      port: portArg,
 
-      // features
+      // SEO features
       robots: true,
       sitemap: true,
+      feedMetadata: this.options.feedMetadata,
     });
 
     let lswData: interfaces.serviceworker.IRequest_Serviceworker_Backend_VersionInfo['response'] = {
@@ -65,15 +96,16 @@ export class UtilityWebsiteServer {
       })
     );
 
-    // ads.txt handler
-    this.typedserver.addRoute('/ads.txt', 'GET', async () => {
-      const adsTxt =
-        ['google.com, pub-4104137977476459, DIRECT, f08c47fec0942fa0'].join('\n') + '\n';
-      return new Response(adsTxt, {
-        status: 200,
-        headers: { 'Content-Type': 'text/plain' },
+    // ads.txt handler (only if configured)
+    if (this.options.adsTxt && this.options.adsTxt.length > 0) {
+      this.typedserver.addRoute('/ads.txt', 'GET', async () => {
+        const adsTxt = this.options.adsTxt.join('\n') + '\n';
+        return new Response(adsTxt, {
+          status: 200,
+          headers: { 'Content-Type': 'text/plain' },
+        });
       });
-    });
+    }
 
     // Asset broker manifest handler
     this.typedserver.addRoute(