@zero-server/sdk 0.9.6 → 0.9.7

package/README.md

@@ -12,14 +12,14 @@
 
 <p align="center">
   <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/github/actions/workflow/status/tonywied17/zero-server/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI" alt="CI"></a>
-  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-7443%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
-  <a href="https://github.com/tonywied17/zero-server"><img src="https://img.shields.io/badge/coverage-96.97%25-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="coverage"></a>
+  <a href="https://github.com/tonywied17/zero-server/actions"><img src="https://img.shields.io/badge/tests-7767%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="tests"></a>
+  <a href="https://github.com/tonywied17/zero-server"><img src="https://img.shields.io/badge/coverage-95.85%25-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="coverage"></a>
   <a href="https://z-server.dev"><img src="https://img.shields.io/badge/docs-z--server.dev-00d8e0?style=flat-square&logo=readthedocs&logoColor=white" alt="docs"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-00d8e0?style=flat-square&logo=opensourceinitiative&logoColor=white" alt="MIT"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=nodedotjs&logoColor=white" alt="node >=18"></a>
 </p>
 
-> **Zero-dependency backend framework for Node.js — routing, ORM, auth, WebSocket, SSE, observability, and 20+ middleware as one SDK or focused scoped packages.**
+> **Zero-dependency backend framework for Node.js - routing, ORM, auth, WebSocket, SSE, observability, and 20+ middleware as one SDK or focused scoped packages.**
 
 <p align="center">
   <strong>
@@ -35,9 +35,9 @@
 npm install @zero-server/sdk
 ```
 
-Requires Node.js 18+. No external dependencies — everything is built on Node.js core APIs.
+Requires Node.js 18+. No external dependencies - everything is built on Node.js core APIs.
 
-`@zero-server/sdk` is the recommended install — it re-exports the entire framework from a single import. Use it for new projects, demos, and most production apps.
+`@zero-server/sdk` is the recommended install - it re-exports the entire framework from a single import. Use it for new projects, demos, and most production apps.
 
 ### Or install only what you need (scoped packages)
 
@@ -63,7 +63,7 @@ npm install @zero-server/core @zero-server/body @zero-server/middleware
 | `@zero-server/errors` | every typed `HttpError` class plus ORM/framework errors |
 | `@zero-server/cli` | programmatic `CLI` / `runCLI` entry points for `zh` / `zs` |
 
-> Each scoped package is fully standalone at runtime — its own `index.js`, its own bundled lib, its own types. Mix and match freely; versions stay aligned across the `@zero-server/*` release set.
+> Each scoped package is fully standalone at runtime - its own `index.js`, its own bundled lib, its own types. Mix and match freely; versions stay aligned across the `@zero-server/*` release set.
 
 ---
 
@@ -92,7 +92,7 @@ app.listen(3000, () => console.log('Listening on :3000'))
 
 ### Middleware
 
-20+ built-in middleware — all zero-dependency:
+20+ built-in middleware - all zero-dependency:
 
 | Middleware | Purpose |
 |---|---|
@@ -113,14 +113,14 @@ app.listen(3000, () => console.log('Listening on :3000'))
 
 Full auth stack with no external libraries:
 
-- **JWT** — `jwt()` middleware, `jwtSign()`, `jwtVerify()`, `jwtDecode()`, JWKS key sets, access/refresh token pairs
-- **Sessions** — `session()` middleware with in-memory store (pluggable)
-- **OAuth 2.0** — `oauth()` middleware with PKCE, pre-configured providers (Google, GitHub, Microsoft, etc.)
-- **Authorization** — `authorize()` policies, `can()` / `canAny()` permission checks, `gate()` middleware
+- **JWT** - `jwt()` middleware, `jwtSign()`, `jwtVerify()`, `jwtDecode()`, JWKS key sets, access/refresh token pairs
+- **Sessions** - `session()` middleware with in-memory store (pluggable)
+- **OAuth 2.0** - `oauth()` middleware with PKCE, pre-configured providers (Google, GitHub, Microsoft, etc.)
+- **Authorization** - `authorize()` policies, `can()` / `canAny()` permission checks, `gate()` middleware
 
 ### ORM & Database
 
-Full-featured ORM with 7 adapters — memory, JSON file, SQLite, MySQL, PostgreSQL, MongoDB, and Redis:
+Full-featured ORM with 7 adapters - memory, JSON file, SQLite, MySQL, PostgreSQL, MongoDB, and Redis:
 
 ```js
 const { Database, Model, TYPES } = require('@zero-server/sdk')
@@ -142,7 +142,7 @@ await User.create({ name: 'Alice', email: 'alice@example.com' })
 const users = await User.find({ name: 'Alice' })
 ```
 
-**Query builder** — `where()`, `select()`, `orderBy()`, `limit()`, `offset()`, `join()`, `groupBy()`, `having()`, `paginate()`, `findOrCreate()`
+**Query builder** - `where()`, `select()`, `orderBy()`, `limit()`, `offset()`, `join()`, `groupBy()`, `having()`, `paginate()`, `findOrCreate()`
 
 **Advanced ORM features:**
 
@@ -163,12 +163,12 @@ const users = await User.find({ name: 'Alice' })
 
 ### Real-Time
 
-- **WebSocket** — `app.ws(path, handler)` with RFC 6455, `WebSocketPool` for rooms, broadcasting, and sub-protocols
-- **Server-Sent Events** — `res.sse()` with auto-IDs, named events, and keep-alive
+- **WebSocket** - `app.ws(path, handler)` with RFC 6455, `WebSocketPool` for rooms, broadcasting, and sub-protocols
+- **Server-Sent Events** - `res.sse()` with auto-IDs, named events, and keep-alive
 
 ### Observability
 
-Built-in Prometheus metrics, health checks, distributed tracing, and structured logging — zero dependencies.
+Built-in Prometheus metrics, health checks, distributed tracing, and structured logging - zero dependencies.
 
 ```js
 const { createApp, metricsMiddleware } = require('@zero-server/sdk')
@@ -193,7 +193,7 @@ logins.inc({ provider: 'github' })
 app.listen(3000)
 ```
 
-**Scrape with Prometheus** — create a `prometheus.yml`:
+**Scrape with Prometheus** - create a `prometheus.yml`:
 
 ```yaml
 scrape_configs:
@@ -209,13 +209,13 @@ docker run -d -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml pr
 ```
 
 **Also includes:**
-- **Distributed tracing** — `Tracer` and `Span` with W3C Trace Context (`traceparent` propagation), `instrumentFetch()` for outgoing requests
-- **Structured logging** — `Logger` with levels, JSON output, and namespaced `debug()` logger
+- **Distributed tracing** - `Tracer` and `Span` with W3C Trace Context (`traceparent` propagation), `instrumentFetch()` for outgoing requests
+- **Structured logging** - `Logger` with levels, JSON output, and namespaced `debug()` logger
 
 ### Lifecycle & Clustering
 
-- **Graceful shutdown** — signal handlers (SIGTERM/SIGINT), in-flight request draining, automatic WebSocket/SSE/database cleanup
-- **Clustering** — `clusterize()` for multi-worker processes with auto-respawn and exponential backoff
+- **Graceful shutdown** - signal handlers (SIGTERM/SIGINT), in-flight request draining, automatic WebSocket/SSE/database cleanup
+- **Clustering** - `clusterize()` for multi-worker processes with auto-respawn and exponential backoff
 
 ### CLI
 
@@ -419,35 +419,35 @@ npm run docs
 
 ```
 lib/
-  app.js              — App class (middleware, routing, listen, ws upgrade, lifecycle)
-  auth/               — JWT, OAuth 2.0, sessions, MFA (TOTP/WebAuthn), authorization
-  body/               — body parsers (json, urlencoded, text, raw, multipart)
-  cli.js              — CLI runner (migrate, seed, scaffold commands)
-  cluster.js          — multi-worker clustering with auto-respawn
-  debug.js            — namespaced debug logger
-  env/                — typed .env loader with schema validation
-  errors.js           — 25+ HttpError / framework / ORM error classes
-  fetch/              — HTTP/HTTPS client (mTLS, AbortSignal, retries)
-  grpc/               — HTTP/2 gRPC stack: server, client, codec, framing,
+  app.js              - App class (middleware, routing, listen, ws upgrade, lifecycle)
+  auth/               - JWT, OAuth 2.0, sessions, MFA (TOTP/WebAuthn), authorization
+  body/               - body parsers (json, urlencoded, text, raw, multipart)
+  cli.js              - CLI runner (migrate, seed, scaffold commands)
+  cluster.js          - multi-worker clustering with auto-respawn
+  debug.js            - namespaced debug logger
+  env/                - typed .env loader with schema validation
+  errors.js           - 25+ HttpError / framework / ORM error classes
+  fetch/              - HTTP/HTTPS client (mTLS, AbortSignal, retries)
+  grpc/               - HTTP/2 gRPC stack: server, client, codec, framing,
                          status, metadata, health, reflection, balancer, watch
-  http/               — Request & Response wrappers
-  lifecycle.js        — graceful shutdown and lifecycle management
-  middleware/         — cors, helmet, logger, rateLimit, compress, static, timeout,
+  http/               - Request & Response wrappers
+  lifecycle.js        - graceful shutdown and lifecycle management
+  middleware/         - cors, helmet, logger, rateLimit, compress, static, timeout,
                          requestId, cookieParser, csrf, validate, errorHandler
-  observe/            — Prometheus metrics, W3C tracing, health checks, structured logging
-  orm/                — Database, Model, Query, adapters, migrations, seeds, cache,
+  observe/            - Prometheus metrics, W3C tracing, health checks, structured logging
+  orm/                - Database, Model, Query, adapters, migrations, seeds, cache,
                          replicas, search, geo, tenancy, audit, views, procedures, plugins
-  router/             — Router with sub-app mounting and pattern matching
-  sse/                — SSE stream controller
-  ws/                 — WebSocket connection, handshake, and room management
-packages/             — generated scoped @zero-server/* re-exports (one dir per scope)
+  router/             - Router with sub-app mounting and pattern matching
+  sse/                - SSE stream controller
+  ws/                 - WebSocket connection, handshake, and room management
+packages/             - generated scoped @zero-server/* re-exports (one dir per scope)
 .tools/
-  scope-manifest.js   — single source of truth for scoped packages & their surface
+  scope-manifest.js   - single source of truth for scoped packages & their surface
   generate-package-stubs.js
   generate-scope-docs.js
-types/                — full TypeScript definitions
-website-docs/         — live demo server, controllers, and playground UI
-test/                 — vitest test suite (7000+ tests, 95%+ coverage)
+types/                - full TypeScript definitions
+website-docs/         - live demo server, controllers, and playground UI
+test/                 - vitest test suite (7000+ tests, 95%+ coverage)
 ```
 
 ## Testing

package/index.js

@@ -59,6 +59,23 @@ const {
     ChannelCredentials, createRotatingCredentials,
     watchProto,
 } = require('./lib/grpc');
+const {
+    createWebRTC, SignalingHub, Room, Peer,
+    parseSdp, stringifySdp,
+    parseCandidate, stringifyCandidate, filterCandidates,
+    isPrivateIp, isLoopbackIp, isLinkLocalIp, isMdnsHostname,
+    stunBinding, encodeBindingRequest, decodeMessage,
+    encodeXorMappedAddress, decodeXorMappedAddress,
+    STUN_MAGIC_COOKIE, STUN_METHOD, STUN_CLASS, STUN_ATTR,
+    issueTurnCredentials, TurnServer,
+    SfuAdapter, MemorySfuAdapter, MediasoupSfuAdapter, LiveKitSfuAdapter, loadSfuAdapter, signJoinToken, verifyJoinToken,
+    spawnBotPeer,
+    bindObservability,
+    E2eeChannel, attachE2ee, generateE2eeKeyPair, sealKey, openSealedKey,
+    useCluster, ClusterCoordinator, MemoryClusterAdapter,
+    runWebRTCCommand,
+    WebRTCError, SignalingError, IceError, TurnError, SdpError,
+} = require('./lib/webrtc');
 const { version } = require('./package.json');
 
 module.exports = {
@@ -247,12 +264,12 @@ module.exports = {
     ClusterManager,
     /** @see module:cluster */
     cluster: clusterize,
-    // Observability — Structured Logging
+    // Observability - Structured Logging
     /** @see module:observe/logger */
     Logger,
     /** @see module:observe/logger */
     structuredLogger,
-    // Observability — Metrics
+    // Observability - Metrics
     /** @see module:observe/metrics */
     Counter,
     /** @see module:observe/metrics */
@@ -269,7 +286,7 @@ module.exports = {
     metricsMiddleware,
     /** @see module:observe/metrics */
     metricsEndpoint: metricsEndpointHandler,
-    // Observability — Tracing
+    // Observability - Tracing
     /** @see module:observe/tracing */
     Span,
     /** @see module:observe/tracing */
@@ -282,7 +299,7 @@ module.exports = {
     tracingMiddleware,
     /** @see module:observe/tracing */
     instrumentFetch,
-    // Observability — Health Checks
+    // Observability - Health Checks
     /** @see module:observe/health */
     healthCheck,
     /** @see module:observe/health */
@@ -409,6 +426,101 @@ module.exports = {
     // gRPC: Proto hot-reload
     /** @see module:grpc/watch */
     watchProto,
+    // WebRTC
+    /** @see module:webrtc */
+    createWebRTC,
+    /** @see module:webrtc/signaling */
+    SignalingHub,
+    /** @see module:webrtc/room */
+    Room,
+    /** @see module:webrtc/peer */
+    Peer,
+    /** @see module:webrtc/sdp */
+    parseSdp,
+    /** @see module:webrtc/sdp */
+    stringifySdp,
+    /** @see module:webrtc/ice */
+    parseCandidate,
+    /** @see module:webrtc/ice */
+    stringifyCandidate,
+    /** @see module:webrtc/ice */
+    filterCandidates,
+    /** @see module:webrtc/ice */
+    isPrivateIp,
+    /** @see module:webrtc/ice */
+    isLoopbackIp,
+    /** @see module:webrtc/ice */
+    isLinkLocalIp,
+    /** @see module:webrtc/ice */
+    isMdnsHostname,
+    /** @see module:webrtc/stun */
+    stunBinding,
+    /** @see module:webrtc/stun */
+    encodeBindingRequest,
+    /** @see module:webrtc/stun */
+    decodeMessage,
+    /** @see module:webrtc/stun */
+    encodeXorMappedAddress,
+    /** @see module:webrtc/stun */
+    decodeXorMappedAddress,
+    /** @see module:webrtc/stun */
+    STUN_MAGIC_COOKIE,
+    /** @see module:webrtc/stun */
+    STUN_METHOD,
+    /** @see module:webrtc/stun */
+    STUN_CLASS,
+    /** @see module:webrtc/stun */
+    STUN_ATTR,
+    /** @see module:webrtc/turn/credentials */
+    issueTurnCredentials,
+    /** @see module:webrtc/turn/server */
+    TurnServer,
+    /** @see module:webrtc/sfu */
+    SfuAdapter,
+    /** @see module:webrtc/sfu/memory */
+    MemorySfuAdapter,
+    /** @see module:webrtc/sfu/mediasoup */
+    MediasoupSfuAdapter,
+    /** @see module:webrtc/sfu/livekit */
+    LiveKitSfuAdapter,
+    /** @see module:webrtc/sfu */
+    loadSfuAdapter,
+    /** @see module:webrtc/signaling */
+    signJoinToken,
+    /** @see module:webrtc/signaling */
+    verifyJoinToken,
+    /** @see module:webrtc/bot */
+    spawnBotPeer,
+    /** @see module:webrtc/observe */
+    bindObservability,
+    /** @see module:webrtc/e2ee */
+    E2eeChannel,
+    /** @see module:webrtc/e2ee */
+    attachE2ee,
+    /** @see module:webrtc/e2ee */
+    generateE2eeKeyPair,
+    /** @see module:webrtc/e2ee */
+    sealKey,
+    /** @see module:webrtc/e2ee */
+    openSealedKey,
+    /** @see module:webrtc/cluster */
+    useCluster,
+    /** @see module:webrtc/cluster */
+    ClusterCoordinator,
+    /** @see module:webrtc/cluster */
+    MemoryClusterAdapter,
+    /** @see module:webrtc/cli */
+    runWebRTCCommand,
+    /** @see module:errors */
+    WebRTCError,
+    /** @see module:errors */
+    SignalingError,
+    /** @see module:errors */
+    IceError,
+    /** @see module:errors */
+    TurnError,
+    /** @see module:errors */
+    SdpError,
     /** Package version */
     version,
 };

package/lib/app.js

@@ -74,7 +74,7 @@ class App
         this._settings = {};
 
         /**
-         * Application-level locals — persistent across the app lifecycle.
+         * Application-level locals - persistent across the app lifecycle.
          * Merged into every `req.locals` and `res.locals` on every request.
          * @type {Object<string, *>}
          */
@@ -167,10 +167,10 @@ class App
 
     /**
      * Register middleware or mount a sub-router.
-     * - `use(fn)` — global middleware applied to every request.
-     * - `use('/prefix', fn)` — path-scoped middleware (strips the prefix
+     * - `use(fn)` - global middleware applied to every request.
+     * - `use('/prefix', fn)` - path-scoped middleware (strips the prefix
      *   before calling `fn` so downstream sees relative paths).
-     * - `use('/prefix', router)` — mount a Router sub-app at the given prefix.
+     * - `use('/prefix', router)` - mount a Router sub-app at the given prefix.
      *
      * @param {string|Function}       pathOrFn - A path prefix string, or middleware function.
      * @param {Function|Router}       [fn]     - Middleware function or Router when first arg is a path.
@@ -254,7 +254,7 @@ class App
      */
     handle(req, res)
     {
-        // Skip gRPC requests — already handled via server.on('stream')
+        // Skip gRPC requests - already handled via server.on('stream')
         if (this._grpcRegistry && req.headers['content-type']?.startsWith('application/grpc'))
             return;
 
@@ -356,7 +356,7 @@ class App
      */
     listen(port = 3000, opts, cb)
     {
-        // Normalise arguments — allow `listen(port, cb)` without opts
+        // Normalise arguments - allow `listen(port, cb)` without opts
         if (typeof opts === 'function') { cb = opts; opts = undefined; }
 
         const isH2 = opts && opts.http2;
@@ -376,7 +376,7 @@ class App
         }
         else if (isH2)
         {
-            // HTTP/2 cleartext (h2c) — no TLS, for internal services
+            // HTTP/2 cleartext (h2c) - no TLS, for internal services
             const h2Opts = opts ? { ...opts } : {};
             delete h2Opts.http2;
             server = http2.createServer(h2Opts, this.handler);
@@ -402,7 +402,7 @@ class App
             {
                 if (this._grpcRegistry.handleStream(stream, headers))
                     return; // handled as gRPC
-                // Otherwise fall through — the compat handler fires the normal request event
+                // Otherwise fall through - the compat handler fires the normal request event
             });
         }
 
@@ -461,8 +461,8 @@ class App
      * Register a lifecycle event listener.
      *
      * Supported events:
-     * - `'beforeShutdown'` — fires before shutdown begins (flush caches, finish writes)
-     * - `'shutdown'`       — fires after shutdown is complete
+     * - `'beforeShutdown'` - fires before shutdown begins (flush caches, finish writes)
+     * - `'shutdown'`       - fires after shutdown is complete
      *
      * @param {'beforeShutdown'|'shutdown'} event - Lifecycle event name.
      * @param {Function} fn - Async or sync callback.
@@ -570,7 +570,7 @@ class App
     }
 
     /**
-     * Configure the shutdown timeout—the maximum time (ms) to wait for
+     * Configure the shutdown timeout-the maximum time (ms) to wait for
      * in-flight requests to finish before forcefully terminating them.
      *
      * @param {number} ms - Timeout in milliseconds.
@@ -730,7 +730,7 @@ class App
      * @param {object|Function} [opts] - Options object, or the handler function directly.
      * @param {number}   [opts.maxPayload=1048576]  - Maximum incoming frame size in bytes (default 1 MB).
      * @param {number}   [opts.pingInterval=30000]  - Auto-ping interval in ms. Set `0` to disable.
-     * @param {Function} [opts.verifyClient]        - `(req) => boolean` — return false to reject the upgrade.
+     * @param {Function} [opts.verifyClient]        - `(req) => boolean` - return false to reject the upgrade.
      * @param {Function} handler     - `(ws, req) => void`.
      *
      * @example | Simple
@@ -815,56 +815,56 @@ class App
     route(method, path, ...fns) { const o = this._extractOpts(fns); this.router.add(method, path, fns, o); }
 
     /**
-     * @see App#route — shortcut for GET requests.
+     * @see App#route - shortcut for GET requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     get(path, ...fns) { if (arguments.length === 1 && typeof path === 'string' && fns.length === 0) return this.set(path); this.route('GET', path, ...fns); return this; }
     /**
-     * @see App#route — shortcut for POST requests.
+     * @see App#route - shortcut for POST requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     post(path, ...fns) { this.route('POST', path, ...fns); return this; }
     /**
-     * @see App#route — shortcut for PUT requests.
+     * @see App#route - shortcut for PUT requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     put(path, ...fns) { this.route('PUT', path, ...fns); return this; }
     /**
-     * @see App#route — shortcut for DELETE requests.
+     * @see App#route - shortcut for DELETE requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     delete(path, ...fns) { this.route('DELETE', path, ...fns); return this; }
     /**
-     * @see App#route — shortcut for PATCH requests.
+     * @see App#route - shortcut for PATCH requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     patch(path, ...fns) { this.route('PATCH', path, ...fns); return this; }
     /**
-     * @see App#route — shortcut for OPTIONS requests.
+     * @see App#route - shortcut for OPTIONS requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     options(path, ...fns) { this.route('OPTIONS', path, ...fns); return this; }
     /**
-     * @see App#route — shortcut for HEAD requests.
+     * @see App#route - shortcut for HEAD requests.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
      */
     head(path, ...fns) { this.route('HEAD', path, ...fns); return this; }
     /**
-     * @see App#route — matches every HTTP method.
+     * @see App#route - matches every HTTP method.
      * @param {string} path - Route pattern.
      * @param {...Function} fns - Handler functions.
      * @returns {App} `this` for chaining.
@@ -872,7 +872,7 @@ class App
     all(path, ...fns) { this.route('ALL', path, ...fns); return this; }
 
     /**
-     * Chainable route builder — register multiple methods on the same path.
+     * Chainable route builder - register multiple methods on the same path.
      *
      * @param {string} path - Route pattern.
      * @returns {object} Chain object with HTTP verb methods.
@@ -1149,7 +1149,7 @@ class App
 
     /**
      * Create an OAuth2 client bound to this app.
-     * Returns the client — does NOT mount any middleware automatically.
+     * Returns the client - does NOT mount any middleware automatically.
      *
      * @param {object} opts - OAuth options (see `oauth()` for full documentation).
      * @returns {{ authorize: Function, callback: Function, refresh: Function, userInfo: Function }}

package/lib/auth/authorize.js

@@ -1,6 +1,6 @@
 /**
  * @module auth/authorize
- * @description Authorization helpers — role-based access control (RBAC),
+ * @description Authorization helpers - role-based access control (RBAC),
  *              permission-based access, and policy classes.
  *
  *              Works with any authentication middleware that sets `req.user`.
@@ -13,22 +13,22 @@
  *   app.use(jwt({ secret: process.env.JWT_SECRET }));
  *   app.use(attachUserHelpers());
  *
- *   // Role-based — only admins and editors can modify posts
+ *   // Role-based - only admins and editors can modify posts
  *   app.put('/posts/:id', authorize('admin', 'editor'), (req, res) => {
  *       res.json({ updated: true });
  *   });
  *
- *   // Permission-based — require ALL listed permissions
+ *   // Permission-based - require ALL listed permissions
  *   app.delete('/users/:id', can('users:read', 'users:delete'), (req, res) => {
  *       res.json({ deleted: true });
  *   });
  *
- *   // ANY permission — useful for overlapping access
+ *   // ANY permission - useful for overlapping access
  *   app.get('/reports', canAny('reports:read', 'admin:read'), (req, res) => {
  *       res.json({ reports: [] });
  *   });
  *
- *   // Policy class — resource-level authorization
+ *   // Policy class - resource-level authorization
  *   class PostPolicy extends Policy {
  *       before(user) { if (user.role === 'superadmin') return true; }
  *       update(user, post) { return user.id === post.authorId || user.role === 'admin'; }
@@ -114,9 +114,9 @@ function authorize(...roles)
  * Checks `req.user.permissions` (array or Set) for the required permission(s).
  *
  * Permission strings follow a `resource:action` convention:
- *   - `'posts:write'` — write access to posts
- *   - `'users:delete'` — delete users
- *   - `'*'` — superuser wildcard
+ *   - `'posts:write'` - write access to posts
+ *   - `'users:delete'` - delete users
+ *   - `'*'` - superuser wildcard
  *
  * @param {...string} permissions - Required permissions (ALL must be present unless `opts.any` is true).
  * @returns {Function} Middleware `(req, res, next) => void`.
@@ -293,7 +293,7 @@ function gate(policy, action, getResource)
             });
         }
 
-        // Attach resource if loaded — saves a redundant DB query in the handler
+        // Attach resource if loaded - saves a redundant DB query in the handler
         if (resource && !req.resource) req.resource = resource;
         next();
     };
@@ -306,8 +306,8 @@ function gate(policy, action, getResource)
  * Call this middleware after JWT/session middleware.
  *
  * Adds:
- *   - `req.user.is(...roles)` — check roles
- *   - `req.user.can(...perms)` — check permissions
+ *   - `req.user.is(...roles)` - check roles
+ *   - `req.user.can(...perms)` - check permissions
  *
  * @returns {Function} Middleware.
  *

package/lib/auth/enrollment.js

@@ -5,10 +5,10 @@
  *              for TOTP-based two-factor authentication.
  *
  *              Steps:
- *              1. `start()` — Generate secret + backup codes, store in session
- *              2. `verify()` — Confirm user can produce a valid TOTP code
- *              3. `complete()` — Persist the verified secret to the database
- *              4. `disable()` — Remove 2FA from the account
+ *              1. `start()` - Generate secret + backup codes, store in session
+ *              2. `verify()` - Confirm user can produce a valid TOTP code
+ *              3. `complete()` - Persist the verified secret to the database
+ *              4. `disable()` - Remove 2FA from the account
  *
  * @example | Full enrollment flow
  *   const { enrollment } = require('@zero-server/sdk');
@@ -356,7 +356,7 @@ function enrollment(opts = {})
 
 function _defaultGetAccount(req)
 {
-    if (!req.user) throw new Error('No user on request — authentication middleware required');
+    if (!req.user) throw new Error('No user on request - authentication middleware required');
     return req.user.email || req.user.id || req.user.sub;
 }
 

package/lib/auth/jwt.js

@@ -13,7 +13,7 @@
  *   const app = createApp();
  *   const SECRET = process.env.JWT_SECRET;
  *
- *   // Public — issue tokens
+ *   // Public - issue tokens
  *   app.post('/login', json(), async (req, res) => {
  *       const { email, password } = req.body;
  *       const user = await db.users.findOne({ email });
@@ -24,7 +24,7 @@
  *       res.json({ token });
  *   });
  *
- *   // Protected — everything under /api requires a valid token
+ *   // Protected - everything under /api requires a valid token
  *   const api = Router();
  *   api.use(jwt({ secret: SECRET }));
  *   api.get('/me', (req, res) => res.json({ id: req.user.sub, role: req.user.role }));
@@ -79,7 +79,7 @@ function _base64urlDecode(str)
 
 /**
  * Decode a JWT without verifying the signature.
- * Returns `null` for malformed tokens — never throws.
+ * Returns `null` for malformed tokens - never throws.
  *
  * @param {string} token - Raw JWT string.
  * @returns {{ header: object, payload: object, signature: string }|null}
@@ -268,7 +268,7 @@ function verify(token, secretOrKey, opts = {})
  * @param {Function} [opts.fetcher] - Custom fetch function (default: built-in fetch).
  * @param {number} [opts.cacheTtl=600000] - Cache TTL in ms (default 10 minutes).
  * @param {number} [opts.requestTimeout=5000] - Request timeout in ms.
- * @returns {Function} `async (header) => publicKey` — resolves the signing key for a JWT header.
+ * @returns {Function} `async (header) => publicKey` - resolves the signing key for a JWT header.
  *
  * @example
  *   const getKey = jwks('https://auth.example.com/.well-known/jwks.json');
@@ -330,7 +330,7 @@ function jwks(jwksUri, opts = {})
             return pem;
         }
 
-        // No kid — return the first RSA key
+        // No kid - return the first RSA key
         const first = keys.values().next().value;
         if (!first) throw _jwtError('No suitable key in JWKS', 'JWKS_NO_KEY');
         return first;
@@ -347,9 +347,9 @@ function jwks(jwksUri, opts = {})
  * Create JWT authentication middleware.
  *
  * On success, populates:
- *   - `req.user` — decoded payload
- *   - `req.auth` — `{ header, payload, token }` full decode info
- *   - `req.token` — raw JWT string
+ *   - `req.user` - decoded payload
+ *   - `req.auth` - `{ header, payload, token }` full decode info
+ *   - `req.token` - raw JWT string
  *
  * @param {object} opts - Configuration.
  * @param {string|Buffer} [opts.secret] - HMAC secret for HS* algorithms.
@@ -367,7 +367,7 @@ function jwks(jwksUri, opts = {})
  * @param {number} [opts.clockTolerance=0] - Clock skew tolerance in seconds.
  * @param {number} [opts.maxAge] - Maximum token age in seconds.
  * @param {boolean} [opts.credentialsRequired=true] - Return 401 if no token found (false = optional auth).
- * @param {Function} [opts.isRevoked] - `async (payload) => boolean` — check token revocation.
+ * @param {Function} [opts.isRevoked] - `async (payload) => boolean` - check token revocation.
  * @param {Function} [opts.onError] - Custom error handler `(err, req, res) => void`.
  * @returns {Function} Middleware `(req, res, next) => void`.
  *