@dszp/netsapiens-lib 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@ Portable, **Node-free** NetSapiens toolkit. The same code runs unchanged in a Cl
 Node, or in the browser — it uses only Web APIs (`fetch`, `atob`, `TextDecoder`, `crypto.subtle`),
 never `node:*`.
 
-Three capabilities, one dependency-free package:
+Five capabilities, one dependency-free package:
 
 - **Read-only NS API v2 client** — `NsClient` (bearer auth, injectable `fetch`) +
   `fetchDomainSnapshot(client, domain)` which assembles a routing-relevant domain snapshot.
@@ -14,6 +14,12 @@ Three capabilities, one dependency-free package:
 - **Call-flow resolver + renderers** — `resolveFlow(snapshot, ref)` walks a NetSapiens domain snapshot
   into a normalized `FlowGraph`; `toMermaid()` renders it to a Mermaid flowchart; `renderGalleryHtml()`
   / `renderFlowCards()` return HTML strings the caller can place anywhere.
+- **Identity + policy** — `toPrincipal()` normalizes a validated token into an effective identity
+  (masking-aware: the effective user is the masked one, the `operator` is the reseller behind a
+  `mask_chain`), and `can()` / `isAllowed()` gate features against it with a declarative,
+  **fail-closed** policy. So "who is this, and may they?" isn't re-invented per consumer.
+- **Themes** — `THEMES`, a vendor-neutral registry (node palettes + Mermaid base/look + app chrome)
+  as plain data. Add one here and every host picks it up; nothing is bound to one deployment's brand.
 
 ## Install
 

package/dist/html.d.ts

@@ -1,11 +1,14 @@
 /**
  * FlowGraph[] -> a self-contained gallery HTML string. Portable (no Node deps): the caller
  * decides where the string goes — a file (CLI), an HTTP response (Worker), or embedded in
- * ns-onboard's review page / build-preview. Mermaid renders client-side from a CDN.
+ * a host review page / build-preview. Mermaid renders client-side from a CDN.
  */
 import type { FlowGraph } from './model.js';
 import { type FlowTheme } from './mermaid.js';
-/** Stable, collision-safe DOM id for a flow card so a host page can deep-link one diagram. */
+/** Stable, collision-safe DOM id for a flow card so a host page can deep-link one diagram.
+ *  `kind` is sanitized alongside `ref`: resolveFlow only ever emits the four literals, but
+ *  FlowGraph.entity.kind is typed `string` and hand-built graphs are a supported use, so an
+ *  unsanitized kind would land unescaped in `id="…"`/`href="#…"`. */
 export declare function flowAnchorId(g: FlowGraph): string;
 export interface CardOptions {
     /** Themed rendering (light/dark palette + `look: neo` + a card anchor id). OMIT for the
@@ -23,10 +26,15 @@ export interface GalleryOptions extends CardOptions {
     mermaidSrc?: string;
     /** Extra note shown under the title. */
     subtitle?: string;
-    /** Brand accent (hex) for subtle highlights — links, the "Legend:" lead, the card's top rule, and
-     *  the pan/zoom controls' hover. Themed path only; defaults to the theme's link color. Pass your
-     *  own brand color here (from your host's config) rather than baking one into a theme, e.g.
-     *  `accent: '#1a6bb0'`. */
+    /** Brand accent for subtle highlights — links, the "Legend:" lead, the card's top rule, and the
+     *  pan/zoom controls' hover. Themed path only; defaults to the theme's link color. Pass your own
+     *  brand color here (from your host's config) rather than baking one into a theme, e.g.
+     *  `accent: '#1a6bb0'`.
+     *
+     *  MUST be a CSS hex color (`#rgb` … `#rrggbbaa`); this value is interpolated into a `<style>`
+     *  block, so anything else is IGNORED in favour of the theme's link color rather than escaped.
+     *  If you source it per-tenant, that rejection is the only thing between a hostile value and a
+     *  `</style><script>` breakout — don't defeat it by pre-formatting the string. */
     accent?: string;
     /** Themed galleries only: anchor ids ({@link flowAnchorId}) to render pre-expanded. Cards not in
      *  the set render collapsed. A themed gallery is always collapsible with a table-of-contents. */
@@ -39,7 +47,7 @@ export declare function renderFlowCard(g: FlowGraph, opts?: CardOptions): string
 export declare function renderFlowCards(graphs: FlowGraph[], opts?: CardOptions): string;
 /**
  * The `<script>` tags a host page needs to render embedded `.mermaid` blocks itself
- * (e.g. ns-onboard's review report). `securityLevel: 'strict'` is MANDATORY — it is the
+ * (e.g. a review report). `securityLevel: 'strict'` is MANDATORY — it is the
  * second escaping layer `mermaid.ts` depends on; do not make it caller-configurable.
  */
 export declare function mermaidBootstrap(opts?: {
@@ -48,4 +56,3 @@ export declare function mermaidBootstrap(opts?: {
 }): string;
 /** Full standalone HTML document for a set of flows. */
 export declare function renderGalleryHtml(domain: string, graphs: FlowGraph[], opts?: GalleryOptions): string;
-//# sourceMappingURL=html.d.ts.map

package/dist/html.js

@@ -1,7 +1,7 @@
 /**
  * FlowGraph[] -> a self-contained gallery HTML string. Portable (no Node deps): the caller
  * decides where the string goes — a file (CLI), an HTTP response (Worker), or embedded in
- * ns-onboard's review page / build-preview. Mermaid renders client-side from a CDN.
+ * a host review page / build-preview. Mermaid renders client-side from a CDN.
  */
 import { toMermaid } from './mermaid.js';
 // Pinned Mermaid build + Subresource Integrity. A floating `mermaid@11` tag lets jsDelivr serve whatever
@@ -40,15 +40,34 @@ const FLOW_LABEL_CSS = `.mermaid g.agents div, .mermaid g.agents span, .mermaid
  *  not by padding — so this keeps Mermaid's default node padding (a larger override made wide nodes
  *  like AAs balloon). */
 const FLOWCHART_CFG = `htmlLabels:true, curve:'basis', nodeSpacing:45, rankSpacing:55`;
+/** Escapes for BOTH text and quoted-attribute contexts — `mermaidScriptTag` interpolates into
+ *  `src="…"`, so omitting the quote entities made `escapeHtml(url)` look safe while allowing
+ *  `x.js" onload="…`. Over-escaping in text position is inert, so one function covers both. */
 function escapeHtml(t) {
-    return String(t).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return String(t)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
 }
 function cap(t) {
     return t.charAt(0).toUpperCase() + t.slice(1);
 }
-/** Stable, collision-safe DOM id for a flow card so a host page can deep-link one diagram. */
+/** Stable, collision-safe DOM id for a flow card so a host page can deep-link one diagram.
+ *  `kind` is sanitized alongside `ref`: resolveFlow only ever emits the four literals, but
+ *  FlowGraph.entity.kind is typed `string` and hand-built graphs are a supported use, so an
+ *  unsanitized kind would land unescaped in `id="…"`/`href="#…"`. */
 export function flowAnchorId(g) {
-    return `flow-${g.entity.kind}-${String(g.entity.ref).replace(/[^A-Za-z0-9_-]/g, '-')}`;
+    const safe = (s) => String(s).replace(/[^A-Za-z0-9_-]/g, '-');
+    return `flow-${safe(g.entity.kind)}-${safe(g.entity.ref)}`;
+}
+/** A CSS color safe to interpolate into a `<style>` block. Anything else is refused rather than
+ *  escaped: `accent` is documented as host-supplied config, and a white-label host that sources it
+ *  per-tenant would otherwise hand any tenant a `</style><script>` breakout. Callers that were
+ *  already passing hex (the documented contract) see no change. */
+function safeAccent(accent, fallback) {
+    return accent && /^#[0-9a-fA-F]{3,8}$/.test(accent) ? accent : fallback;
 }
 /** Render one flow as a gallery `<section>` card. Themed cards carry an `id` anchor
  *  ({@link flowAnchorId}); the legacy (no-theme) card is byte-identical to the original. */
@@ -78,7 +97,7 @@ export function renderFlowCards(graphs, opts = {}) {
 }
 /**
  * The `<script>` tags a host page needs to render embedded `.mermaid` blocks itself
- * (e.g. ns-onboard's review report). `securityLevel: 'strict'` is MANDATORY — it is the
+ * (e.g. a review report). `securityLevel: 'strict'` is MANDATORY — it is the
  * second escaping layer `mermaid.ts` depends on; do not make it caller-configurable.
  */
 export function mermaidBootstrap(opts = {}) {
@@ -91,7 +110,7 @@ ${mermaidScriptTag(opts.mermaidSrc)}
 export function renderGalleryHtml(domain, graphs, opts = {}) {
     const mermaidSrc = opts.mermaidSrc ?? MERMAID_CDN;
     const subtitle = opts.subtitle ?? `resolved from snapshot · ${graphs.length} flows`;
-    // Themed path (light for ns-onboard, or explicit dark-neo). No theme → the original dark
+    // Themed path (light for a review context, or explicit dark-neo). No theme → the original dark
     // document below, byte-identical (the Worker depends on this).
     if (opts.theme)
         return themedGalleryHtml(domain, graphs, mermaidSrc, subtitle, opts.theme, opts.expand, opts.accent);
@@ -156,7 +175,7 @@ ${mermaidScriptTag(mermaidSrc)}
   </script>
 </body></html>`;
 }
-/** Themed gallery document — light (ns-onboard review context) or explicit dark-neo. Parallel to
+/** Themed gallery document — light (review context) or explicit dark-neo. Parallel to
  *  the legacy dark document in {@link renderGalleryHtml}; kept separate so that path stays byte-identical. */
 function themedGalleryHtml(domain, graphs, mermaidSrc, subtitle, theme, expand, accent) {
     const light = theme === 'light';
@@ -164,7 +183,7 @@ function themedGalleryHtml(domain, graphs, mermaidSrc, subtitle, theme, expand,
         ? { scheme: 'light', pageBg: '#fafafa', text: '#1e293b', sub: '#64748b', cardBg: '#ffffff', cardBorder: '#e2e8f0', meta: '#64748b', mermaidBg: '#f8fafc', notes: '#b45309', legendText: '#475569', legendBg: '#ffffff', lightboxBg: 'rgba(248,250,252,.96)', hint: '#64748b', shadow: 'box-shadow:0 1px 2px rgba(0,0,0,.04);', link: '#21618c' }
         : { scheme: 'dark', pageBg: '#0f1115', text: '#e6e6e6', sub: '#8a94a6', cardBg: '#161a22', cardBorder: '#232a36', meta: '#7b8494', mermaidBg: '#0c0e12', notes: '#c9a24a', legendText: '#aab', legendBg: '#161a22', lightboxBg: 'rgba(6,8,12,.95)', hint: '#8a94a6', shadow: '', link: '#7db3e6' };
     const initTheme = light ? 'base' : 'dark';
-    const brandAccent = accent || c.link;
+    const brandAccent = safeAccent(accent, c.link);
     const single = graphs.length === 1; // a one-flow gallery (e.g. the portal modal) needs no contents nav
     const isOpen = (g) => single || (!!expand && expand.has(flowAnchorId(g)));
     // Table of contents grouped by entity kind; ● marks the pre-expanded (notable) flows.
@@ -329,4 +348,3 @@ function mermaidBootstrapInline(initTheme) {
     }
   </script>`;
 }
-//# sourceMappingURL=html.js.map

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Public API of the portable call-flow library — the surface any host imports (Cloudflare
- * Worker, ns-onboard CLI / review page / build-preview, the portal viewer). Everything
- * re-exported here is Node-free and runtime-portable. The Node-only CLI (`cli.ts`) is NOT
- * part of this surface.
+ * Worker, an onboarding CLI / review page / build-preview, the portal viewer). Everything
+ * re-exported here is Node-free and runtime-portable; any Node-only host code (e.g. a CLI) lives
+ * outside this surface.
  *
  * Typical use in another project:
  *   import { resolveFlow, toMermaid, renderGalleryHtml, verify } from '@dszp/netsapiens-lib';
@@ -15,9 +15,8 @@ export { toMermaid, type FlowTheme, type MermaidOptions } from './mermaid.js';
 export { THEMES, DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME, NODE_LIGHT, NODE_DARK, NODE_SLATE, NODE_A11Y, type ThemeDef, type ThemeChrome, type ThemeMode, type NodePalette, } from './themes.js';
 export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, flowAnchorId, type GalleryOptions, type CardOptions, } from './html.js';
 export { resolveSvgSize, rasterizerScript } from './raster.js';
-export { NsClient, NsApiError, fetchDomainSnapshot, listDomains, asArray, type NsClientConfig, type FetchSnapshotOptions } from './nsClient.js';
+export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray, type NsClientConfig, type FetchSnapshotOptions } from './nsClient.js';
 export { verify, validateJwtFormat, extractContext, assertClaims, verifyHs256Signature, normalizeToken, tokenKey, MemoryVerdictCache, type JwtVerdict, type JwtContext, type ClaimExpectations, type VerdictCache, type VerifyOptions, type FormatResult, } from './jwt.js';
 export { type CallSensitivity, needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
 export { toPrincipal, parseOperator, isResellerScope, isAdminScope, type Principal, type Operator, type Scope, } from './principal.js';
 export { ruleMatches, isAllowed, can, type PolicyRule, type Policy, type FeaturePolicies, } from './policy.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,8 @@
 /**
  * Public API of the portable call-flow library — the surface any host imports (Cloudflare
- * Worker, ns-onboard CLI / review page / build-preview, the portal viewer). Everything
- * re-exported here is Node-free and runtime-portable. The Node-only CLI (`cli.ts`) is NOT
- * part of this surface.
+ * Worker, an onboarding CLI / review page / build-preview, the portal viewer). Everything
+ * re-exported here is Node-free and runtime-portable; any Node-only host code (e.g. a CLI) lives
+ * outside this surface.
  *
  * Typical use in another project:
  *   import { resolveFlow, toMermaid, renderGalleryHtml, verify } from '@dszp/netsapiens-lib';
@@ -14,9 +14,8 @@ export { toMermaid } from './mermaid.js';
 export { THEMES, DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME, NODE_LIGHT, NODE_DARK, NODE_SLATE, NODE_A11Y, } from './themes.js';
 export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, flowAnchorId, } from './html.js';
 export { resolveSvgSize, rasterizerScript } from './raster.js';
-export { NsClient, NsApiError, fetchDomainSnapshot, listDomains, asArray } from './nsClient.js';
+export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray } from './nsClient.js';
 export { verify, validateJwtFormat, extractContext, assertClaims, verifyHs256Signature, normalizeToken, tokenKey, MemoryVerdictCache, } from './jwt.js';
 export { needsFreshAuth, SENSITIVITY_NOTE } from './sensitivity.js';
 export { toPrincipal, parseOperator, isResellerScope, isAdminScope, } from './principal.js';
 export { ruleMatches, isAllowed, can, } from './policy.js';
-//# sourceMappingURL=index.js.map

package/dist/jwt.d.ts

@@ -13,7 +13,7 @@
  * with a TTL capped by the token's own `exp`. A bad or expired token never reaches the server.
  *
  * Uses only Web-standard globals (atob, TextDecoder, crypto.subtle, fetch) — no Node Buffer — so
- * the same file runs in a Worker and in the ns-onboard CLI.
+ * the same file runs in a Worker and in an onboarding CLI.
  */
 export interface JwtContext {
     /** The token's domain (from claims). Scopes downstream NS reads. When masking, this is the
@@ -105,6 +105,8 @@ export declare function extractContext(payload: Record<string, unknown>): JwtCon
 export interface FormatResult {
     validFormat: boolean;
     unexpired: boolean;
+    /** `nbf` is set and still in the future (beyond the skew leeway) ⇒ the token is not yet valid. */
+    notYetValid?: boolean;
     expiresAt?: string;
     expiresInSeconds?: number;
     reason?: string;
@@ -122,14 +124,27 @@ export interface VerdictCache {
     /** ttlSeconds is a hint; the store may evict earlier. */
     set(key: string, verdict: JwtVerdict, ttlSeconds: number): Promise<void>;
 }
-/** Simple in-isolate cache for dev / a single Worker isolate (not shared across isolates). */
+/**
+ * Simple in-isolate cache for dev / a single Worker isolate (not shared across isolates).
+ *
+ * BOUNDED ON PURPOSE. Expiry alone is not a bound: entries expire lazily, on a `get()` for that
+ * exact key, so an attacker who uses each token once never triggers a sweep and every verdict is
+ * retained until the isolate dies. Since a *negative* verdict is cached for a token anyone can mint
+ * (correct `aud`/`iss`/`exp` need no signing key), an unbounded map is a remote OOM. Hence: sweep on
+ * insert, and hard-cap with FIFO eviction. `maxEntries` is generous — a real portal's working set is
+ * its live sessions, far below the cap, so eviction only ever bites the pathological case.
+ */
 export declare class MemoryVerdictCache implements VerdictCache {
+    private readonly maxEntries;
     private store;
+    constructor(maxEntries?: number);
     get(key: string): Promise<JwtVerdict | undefined>;
     set(key: string, verdict: JwtVerdict, ttlSeconds: number): Promise<void>;
+    /** Live entry count. Exposed for tests/observability; not part of the VerdictCache contract. */
+    get size(): number;
 }
 /** SHA-256 hex of the token — cache key that never stores the raw token. */
-export declare function tokenKey(token: string): Promise<string>;
+export declare function tokenKey(token: string, server?: string): Promise<string>;
 export interface VerifyOptions {
     /** NS API host, e.g. "api.example.com". */
     server: string;
@@ -171,4 +186,3 @@ export interface VerifyOptions {
  * A malformed/expired token returns immediately and never touches the server.
  */
 export declare function verify(token: string, opts: VerifyOptions): Promise<JwtVerdict>;
-//# sourceMappingURL=jwt.d.ts.map

package/dist/jwt.js

@@ -13,8 +13,9 @@
  * with a TTL capped by the token's own `exp`. A bad or expired token never reaches the server.
  *
  * Uses only Web-standard globals (atob, TextDecoder, crypto.subtle, fetch) — no Node Buffer — so
- * the same file runs in a Worker and in the ns-onboard CLI.
+ * the same file runs in a Worker and in an onboarding CLI.
  */
+import { assertBareServer } from './nsClient.js';
 // ---------------------------------------------------------------------------
 // Local decode (base64url) — Buffer-free
 // ---------------------------------------------------------------------------
@@ -130,6 +131,9 @@ export function extractContext(payload) {
         territory: pick('territory'),
     };
 }
+/** Clock-skew leeway for `nbf`, in seconds. Matches the Cloudflare-Access verifier (access.ts) so
+ *  the two JWT paths treat "not yet valid" identically and a small clock drift can't lock anyone out. */
+const NBF_LEEWAY_SECONDS = 60;
 /**
  * Local format + expiry check. No network, no signature verification.
  * `nowMs` is injectable for testing.
@@ -155,6 +159,24 @@ export function validateJwtFormat(token, nowMs = Date.now()) {
     if (expSeconds === undefined) {
         return { validFormat: true, unexpired: false, reason: 'Missing or invalid exp claim', payload, context };
     }
+    // nbf: a token dated in the future is not yet valid. Without this it passes every local check and
+    // still triggers an upstream /jwt roundtrip a local gate should have refused; and format-mode
+    // callers (verify(..., {mode:'format', signingSecret})) would return ok:true for a not-yet-valid
+    // token. Defense-in-depth for the live path (the server is the real authority), authoritative for
+    // format mode. Leeway matches access.ts.
+    const nbfSeconds = toEpochSeconds(payload.nbf);
+    if (nbfSeconds !== undefined && nbfSeconds > nowSeconds + NBF_LEEWAY_SECONDS) {
+        return {
+            validFormat: true,
+            unexpired: expSeconds - nowSeconds > 0,
+            notYetValid: true,
+            expiresAt: new Date(expSeconds * 1000).toISOString(),
+            expiresInSeconds: expSeconds - nowSeconds,
+            reason: 'Token not yet valid (nbf is in the future)',
+            payload,
+            context,
+        };
+    }
     const expiresInSeconds = expSeconds - nowSeconds;
     return {
         validFormat: true,
@@ -166,9 +188,22 @@ export function validateJwtFormat(token, nowMs = Date.now()) {
         context,
     };
 }
-/** Simple in-isolate cache for dev / a single Worker isolate (not shared across isolates). */
+/**
+ * Simple in-isolate cache for dev / a single Worker isolate (not shared across isolates).
+ *
+ * BOUNDED ON PURPOSE. Expiry alone is not a bound: entries expire lazily, on a `get()` for that
+ * exact key, so an attacker who uses each token once never triggers a sweep and every verdict is
+ * retained until the isolate dies. Since a *negative* verdict is cached for a token anyone can mint
+ * (correct `aud`/`iss`/`exp` need no signing key), an unbounded map is a remote OOM. Hence: sweep on
+ * insert, and hard-cap with FIFO eviction. `maxEntries` is generous — a real portal's working set is
+ * its live sessions, far below the cap, so eviction only ever bites the pathological case.
+ */
 export class MemoryVerdictCache {
+    maxEntries;
     store = new Map();
+    constructor(maxEntries = 1000) {
+        this.maxEntries = maxEntries;
+    }
     async get(key) {
         const hit = this.store.get(key);
         if (!hit)
@@ -180,12 +215,32 @@ export class MemoryVerdictCache {
         return hit.verdict;
     }
     async set(key, verdict, ttlSeconds) {
-        this.store.set(key, { verdict, expiresAtMs: Date.now() + ttlSeconds * 1000 });
+        const now = Date.now();
+        for (const [k, v] of this.store)
+            if (v.expiresAtMs <= now)
+                this.store.delete(k);
+        this.store.delete(key); // re-insert so Map iteration order == insertion order == eviction order
+        this.store.set(key, { verdict, expiresAtMs: now + ttlSeconds * 1000 });
+        while (this.store.size > this.maxEntries) {
+            const oldest = this.store.keys().next();
+            if (oldest.done)
+                break;
+            this.store.delete(oldest.value);
+        }
+    }
+    /** Live entry count. Exposed for tests/observability; not part of the VerdictCache contract. */
+    get size() {
+        return this.store.size;
     }
 }
 /** SHA-256 hex of the token — cache key that never stores the raw token. */
-export async function tokenKey(token) {
-    const data = new TextEncoder().encode(normalizeToken(token));
+export async function tokenKey(token, server) {
+    // Scope the key by `server` when given: a consumer that fronts two NS cores with ONE cache (a
+    // reseller tool, or prod+staging sharing a KV namespace) would otherwise serve a token validated
+    // against server A as ok:true for a request bound to server B — B never contacted. verify() passes
+    // its server; the NUL separator can't appear in a hostname, so the two fields can't collide.
+    const material = server ? `${server}\u0000${normalizeToken(token)}` : normalizeToken(token);
+    const data = new TextEncoder().encode(material);
     const digest = await crypto.subtle.digest('SHA-256', data);
     return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
 }
@@ -209,8 +264,8 @@ export async function verify(token, opts) {
         payload: fmt.payload,
         checkedAt,
     };
-    // Local gate: bad format or expired ⇒ reject without a roundtrip.
-    if (!fmt.validFormat || !fmt.unexpired)
+    // Local gate: bad format, expired, or not-yet-valid (nbf) ⇒ reject without a roundtrip.
+    if (!fmt.validFormat || !fmt.unexpired || fmt.notYetValid)
         return base;
     // Claim assertions (always, no key needed): aud must be "ns"; iss must match unless opted out.
     const claims = assertClaims(fmt.payload ?? {}, { aud: opts.expectedAud, iss: opts.expectedIss, validateIss: opts.validateIss });
@@ -235,8 +290,19 @@ export async function verify(token, opts) {
             ? { ...withSig, live: 'skipped', ok: true }
             : { ...withSig, live: 'skipped', ok: false, reason: 'Signature not verified (format mode without signingSecret)' };
     }
+    // Validate the server host BEFORE it reaches the URL: a caller that derives `server` from request
+    // input would otherwise let `host@evil` / `host#…` redirect the Bearer token off-origin. Fail
+    // closed (uncached error) rather than throw, so a misconfigured server can't crash the caller.
+    let safeServer;
+    try {
+        safeServer = assertBareServer(opts.server);
+    }
+    catch (err) {
+        return { ...withSig, live: 'error', ok: false, reason: err.message };
+    }
     // Live mode — consult cache first (unless force-fresh: writes/sensitive reads always re-check).
-    const key = await tokenKey(token);
+    // Key is scoped by server: one cache fronting two NS cores must not cross-serve verdicts.
+    const key = await tokenKey(token, safeServer);
     if (opts.cache && !opts.forceFresh) {
         const cached = await opts.cache.get(key);
         if (cached)
@@ -250,7 +316,7 @@ export async function verify(token, opts) {
     const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 4000);
     let verdict;
     try {
-        const res = await doFetch(`https://${opts.server}/ns-api/v2/jwt`, {
+        const res = await doFetch(`https://${safeServer}/ns-api/v2/jwt`, {
             method: 'GET',
             headers: { Authorization: `Bearer ${normalizeToken(token)}` },
             redirect: 'manual',
@@ -287,4 +353,3 @@ export async function verify(token, opts) {
     }
     return verdict;
 }
-//# sourceMappingURL=jwt.js.map

package/dist/mermaid.d.ts

@@ -4,11 +4,10 @@
  */
 import type { FlowGraph } from './model.js';
 /** Diagram theme. `dark` is the original palette (Cloudflare Worker / live-chart use);
- *  `light` matches ns-onboard's light review report. */
+ *  `light` matches a light review report. */
 export type FlowTheme = 'light' | 'dark';
 export interface MermaidOptions {
     /** Emit a themed diagram. OMIT for byte-identical legacy output (the Worker relies on this). */
     theme?: FlowTheme;
 }
 export declare function toMermaid(g: FlowGraph, opts?: MermaidOptions): string;
-//# sourceMappingURL=mermaid.d.ts.map

package/dist/model.d.ts

@@ -4,7 +4,7 @@
  * consumes it. This is the "real IP" contract from the handoff: a normalized graph JSON.
  *
  * Runtime-portable by design: no Node-only imports here or in resolver.ts, so the same
- * code can run in the ns-onboard CLI and in a Cloudflare Worker.
+ * code can run in an onboarding CLI and in a Cloudflare Worker.
  */
 export type NodeKind = 'did' | 'timeframe' | 'user' | 'devices' | 'queue' | 'agents' | 'attendant' | 'prompt' | 'voicemail' | 'external' | 'trunk' | 'hangup' | 'unknown';
 export type EdgeKind = 'route' | 'time' | 'always' | 'noanswer' | 'busy' | 'unreg' | 'dnd' | 'dispatch' | 'overflow' | 'menu' | 'ref';
@@ -62,7 +62,7 @@ export interface Snapshot {
      *
      * Two shapes are accepted:
      *  - `attendantDetails[ext]`        — a single detail (current live fetch; SV builds AAs on `*`).
-     *  - `attendantDetailsByUser[ext]`  — an ARRAY of details (ns-onboard enriched backup: an AA may
+     *  - `attendantDetailsByUser[ext]`  — an ARRAY of details (an enriched backup: an AA may
      *    have multiple prompts/timeframes). The resolver picks the `*`/Default one as primary and
      *    flags the rest as a deviation (see the AA backup enrichment spec, Addendum 2026-07-11).
      */
@@ -72,9 +72,8 @@ export interface Snapshot {
      * Per-AA dialplan dialrules, keyed by AA extension — the AUTHORITATIVE menu + default routing that
      * the /autoattendants detail omits (no-key/star/option). From GET /domains/{d}/dialplans/{domain}_{ext}/dialrules.
      * The resolver reads `Prompt_<startingPrompt-id>.<suffix>` rules: .Default (no-key/timeout), .* (unassigned),
-     * .<digit> (press N), .Case_[...] (dial-by-ext). See CLAUDE.md → NetSapiens API notes.
+     * .<digit> (press N), .Case_[...] (dial-by-ext). See ARCHITECTURE.md → NetSapiens routing model.
      */
     attendantDialrulesByExt?: Record<string, Rec[]>;
     [k: string]: any;
 }
-//# sourceMappingURL=model.d.ts.map

package/dist/model.js

@@ -4,7 +4,6 @@
  * consumes it. This is the "real IP" contract from the handoff: a normalized graph JSON.
  *
  * Runtime-portable by design: no Node-only imports here or in resolver.ts, so the same
- * code can run in the ns-onboard CLI and in a Cloudflare Worker.
+ * code can run in an onboarding CLI and in a Cloudflare Worker.
  */
 export {};
-//# sourceMappingURL=model.js.map

package/dist/nsClient.d.ts

@@ -1,6 +1,6 @@
 /**
  * Portable NetSapiens API read client — the seed of the eventual "NS API for Worker/Node"
- * library (see CLAUDE.md → North star). Ported from NetSapiens-Onboarding-Backup (`src/api/client.ts`
+ * library. Ported from an internal onboarding tool (its API client
  * NsClient + `src/backup/snapshot.ts` backupDomain), trimmed to the READ-ONLY routing subset the
  * resolver needs, and kept Node-free (fetch/URL only) so it runs in a Cloudflare Worker unchanged.
  *
@@ -32,10 +32,17 @@ export interface NsClientConfig {
  * mutating method here. Any write capability must be a separate, explicitly-reviewed client, not a
  * quiet addition to this one. This is the single choke point every NS call in the Worker flows through.
  */
+/**
+ * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from
+ * request input (a multi-tenant tool) would otherwise let `api.example.com@evil.example` or
+ * `evil.example#…` redirect the Bearer token to another origin — `new URL('https://'+server).host`
+ * is what actually gets contacted, not the string. Comparing the parsed host back to the input
+ * catches an embedded `@`, `/path`, `?query`, `#frag`, or scheme; credentials are refused explicitly.
+ * Host comparison is case-insensitive (URL lowercases the host; NS hostnames are case-insensitive).
+ */
+export declare function assertBareServer(server: string): string;
 export declare class NsClient {
-    private readonly baseUrl;
-    private readonly token;
-    private readonly fetchImpl;
+    #private;
     constructor(cfg: NsClientConfig);
     get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T>;
 }
@@ -76,4 +83,3 @@ export interface FetchSnapshotOptions {
  * whole flow — the resolver tolerates gaps. A failing top-level read (e.g. 401) DOES throw.
  */
 export declare function fetchDomainSnapshot(client: NsClient, domain: string, opts?: FetchSnapshotOptions): Promise<Snapshot>;
-//# sourceMappingURL=nsClient.d.ts.map

package/dist/nsClient.js

@@ -1,6 +1,6 @@
 /**
  * Portable NetSapiens API read client — the seed of the eventual "NS API for Worker/Node"
- * library (see CLAUDE.md → North star). Ported from NetSapiens-Onboarding-Backup (`src/api/client.ts`
+ * library. Ported from an internal onboarding tool (its API client
  * NsClient + `src/backup/snapshot.ts` backupDomain), trimmed to the READ-ONLY routing subset the
  * resolver needs, and kept Node-free (fetch/URL only) so it runs in a Cloudflare Worker unchanged.
  *
@@ -29,25 +29,47 @@ export class NsApiError extends Error {
  * mutating method here. Any write capability must be a separate, explicitly-reviewed client, not a
  * quiet addition to this one. This is the single choke point every NS call in the Worker flows through.
  */
+/**
+ * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from
+ * request input (a multi-tenant tool) would otherwise let `api.example.com@evil.example` or
+ * `evil.example#…` redirect the Bearer token to another origin — `new URL('https://'+server).host`
+ * is what actually gets contacted, not the string. Comparing the parsed host back to the input
+ * catches an embedded `@`, `/path`, `?query`, `#frag`, or scheme; credentials are refused explicitly.
+ * Host comparison is case-insensitive (URL lowercases the host; NS hostnames are case-insensitive).
+ */
+export function assertBareServer(server) {
+    const s = String(server ?? '').trim().replace(/\/+$/, '');
+    let u;
+    try {
+        u = new URL(`https://${s}`);
+    }
+    catch {
+        throw new Error(`Invalid NS server "${server}": expected a bare host or host:port`);
+    }
+    if (u.host !== s.toLowerCase() || u.username || u.password) {
+        throw new Error(`Invalid NS server "${server}": expected a bare host or host:port (no scheme, path, query, fragment, or credentials)`);
+    }
+    return u.host;
+}
 export class NsClient {
-    baseUrl;
-    token;
-    fetchImpl;
+    #baseUrl;
+    #token;
+    #fetchImpl;
     constructor(cfg) {
-        this.baseUrl = `https://${cfg.server.replace(/\/+$/, '')}/ns-api/v2`;
-        this.token = cfg.token;
-        this.fetchImpl = cfg.fetchImpl ?? fetch;
+        this.#baseUrl = `https://${assertBareServer(cfg.server)}/ns-api/v2`;
+        this.#token = cfg.token;
+        this.#fetchImpl = cfg.fetchImpl ?? fetch;
     }
     async get(path, query) {
-        const url = new URL(this.baseUrl + path);
+        const url = new URL(this.#baseUrl + path);
         for (const [k, v] of Object.entries(query ?? {}))
             url.searchParams.set(k, String(v));
-        // Call via a local, NOT `this.fetchImpl(...)`: invoking the global fetch as a method of this
+        // Call via a local, NOT `this.#fetchImpl(...)`: invoking the global fetch as a method of this
         // instance throws "Illegal invocation" in workerd (the global fetch requires a global `this`).
-        const doFetch = this.fetchImpl;
+        const doFetch = this.#fetchImpl;
         const res = await doFetch(url.toString(), {
             method: 'GET',
-            headers: { Authorization: `Bearer ${this.token}`, Accept: 'application/json' },
+            headers: { Authorization: `Bearer ${this.#token}`, Accept: 'application/json' },
         });
         const text = await res.text();
         let parsed = text;
@@ -60,7 +82,10 @@ export class NsClient {
             }
         }
         if (!res.ok) {
-            const detail = typeof parsed === 'object' && parsed !== null ? JSON.stringify(parsed) : String(parsed).slice(0, 500);
+            // Truncate BOTH branches to 500 chars: the object branch used to JSON.stringify the whole
+            // upstream body unbounded, so a consumer that logs err.message could log an arbitrarily large
+            // NS response. No credential is ever in it, but size alone is a footgun.
+            const detail = (typeof parsed === 'object' && parsed !== null ? JSON.stringify(parsed) : String(parsed)).slice(0, 500);
             const hint = res.status === 401 ? ' (token expired/invalid or domain out of scope)' : res.status === 403 ? ' (token lacks permission)' : '';
             throw new NsApiError(`GET ${path} → ${res.status}${hint}: ${detail}`, res.status, path, parsed);
         }
@@ -163,7 +188,7 @@ export async function fetchDomainSnapshot(client, domain, opts = {}) {
     // One list row per (user, prompt); an AA may have several (multi-timeframe). Collect ALL detail
     // records per user (array) so the resolver can flag multi-prompt deviations, not just last-wins.
     // Also fetch each AA's OWN dialplan dialrules ({domain}_{ext}) — the authoritative menu/default
-    // routing the /autoattendants detail omits (no-key/star/option). See CLAUDE.md → API notes.
+    // routing the /autoattendants detail omits (no-key/star/option). See ARCHITECTURE.md → NetSapiens routing model.
     let attendantDetailsByUser;
     let attendantDialrulesByExt;
     if (opts.includeAttendantMenus ?? true) {
@@ -202,4 +227,3 @@ export async function fetchDomainSnapshot(client, domain, opts = {}) {
         ...(dialrulesByPlan ? { dialrulesByPlan } : {}),
     };
 }
-//# sourceMappingURL=nsClient.js.map

package/dist/policy.d.ts

@@ -46,4 +46,3 @@ export declare function ruleMatches(p: Principal, rule: PolicyRule): boolean;
 export declare function isAllowed(p: Principal, policy: Policy | undefined): boolean;
 /** Check a named feature against a registry. Unknown feature ⇒ deny (fail closed). */
 export declare function can(p: Principal, feature: string, policies: FeaturePolicies): boolean;
-//# sourceMappingURL=policy.d.ts.map

package/dist/policy.js

@@ -3,6 +3,19 @@ const inList = (value, list) => {
     const v = lc(value);
     return list.some((x) => lc(x) === v);
 };
+/** Collapse the interchangeable Super User spellings a NetSapiens core may emit ("Super User",
+ *  "superuser", "super-user") to one canonical token. None of these is a valid OTHER scope, so this
+ *  only ever unifies synonyms — a policy written with any one spelling matches a token carrying
+ *  another, closing a fail-closed lockout where e.g. `user_scope: "superuser"` was denied at a rule
+ *  listing `"Super User"`. */
+const canonScope = (s) => {
+    const v = lc(s);
+    return v === 'superuser' || v === 'super-user' || v === 'super user' ? 'super user' : v;
+};
+const scopeInList = (value, list) => {
+    const v = canonScope(value);
+    return list.some((x) => canonScope(x) === v);
+};
 /** Does the principal satisfy every condition in this single rule? */
 export function ruleMatches(p, rule) {
     // A rule with NO matchable condition (e.g. `{}` or only `description`) is NOT allow-all — that would
@@ -14,7 +27,7 @@ export function ruleMatches(p, rule) {
         rule.masking !== undefined;
     if (!hasCondition)
         return false;
-    if (rule.scopes && !inList(p.scope, rule.scopes))
+    if (rule.scopes && !scopeInList(p.scope, rule.scopes))
         return false;
     if (rule.domains && !(rule.domains.includes('*') || inList(p.domain, rule.domains)))
         return false;
@@ -36,4 +49,3 @@ export function isAllowed(p, policy) {
 export function can(p, feature, policies) {
     return isAllowed(p, policies[feature]);
 }
-//# sourceMappingURL=policy.js.map

package/dist/principal.d.ts

@@ -49,4 +49,3 @@ export declare function isAdminScope(scope: string | undefined): boolean;
 export declare function parseOperator(maskChain: string | undefined): Operator | null;
 /** Build a Principal from decoded ns_t context (a JwtContext / JwtVerdict — both carry the claims). */
 export declare function toPrincipal(ctx: JwtContext): Principal;
-//# sourceMappingURL=principal.d.ts.map

package/dist/principal.js

@@ -42,4 +42,3 @@ export function toPrincipal(ctx) {
         operator,
     };
 }
-//# sourceMappingURL=principal.js.map

package/dist/raster.d.ts

@@ -18,4 +18,3 @@ export declare function resolveSvgSize(svgString: string): {
  * (no eval/new Function; uses a data: image URL — ensure any host CSP allows `img-src data:`).
  */
 export declare function rasterizerScript(): string;
-//# sourceMappingURL=raster.d.ts.map

package/dist/raster.js

@@ -78,4 +78,3 @@ async function svgToPngBlob(svg, opts) {
 }
 `.trim();
 }
-//# sourceMappingURL=raster.js.map

package/dist/resolver.d.ts

@@ -55,4 +55,3 @@ export declare function listEntities(snap: Snapshot): {
         label: string;
     }[];
 };
-//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.js

@@ -37,7 +37,7 @@ const trim = (v, max = GREET_MAX) => (v.length > max ? `${v.slice(0, max - 1).tr
  *   wp → SNAPmobile Web (browser phone) · t → Microsoft Teams · m → SNAPmobile (mobile) ·
  *   r → mobile/desktop app · b / other lower letters → usually a desk phone.
  * Exact device info (model, MAC, transport) IS available via the device API but isn't pulled yet —
- * see CLAUDE.md → API notes; this suffix guess is the cheap approximation.
+ * see ARCHITECTURE.md → NetSapiens routing model; this suffix guess is the cheap approximation.
  */
 function deviceKindBySuffix(suffix) {
     switch (suffix.toLowerCase()) {
@@ -907,7 +907,7 @@ function ensureAttendant(ext, idx, b) {
     const greet = s(detail?.audio?.['file-script-text']);
     // SV builds AAs on the always-available `*` timeframe; a specific timeframe is unusual. Show it
     // plainly on the node (clear display) rather than as a loud warning — the loud validation belongs
-    // in the ns-onboard/backup path, not the viewer.
+    // in the backup path, not the viewer.
     const aaTf = s(detail?.['time-frame']);
     const tfTag = aaTf && aaTf !== '*' ? ` · timeframe ${aaTf}` : '';
     b.node(id, 'attendant', `🔀 Auto Attendant ${ext}${nm ? ` · ${nm}` : ''}`, (greet ? `“${trim(greet)}”` : 'plays menu') + tfTag, undefined, greet.length > GREET_MAX ? greet : undefined);
@@ -1089,4 +1089,3 @@ export function listEntities(snap) {
         attendants: (snap.autoattendants ?? []).map((a) => ({ ref: s(a.user), label: s(a['attendant-name']) })),
     };
 }
-//# sourceMappingURL=resolver.js.map

package/dist/sensitivity.d.ts

@@ -29,4 +29,3 @@ export interface RouteAuth {
 }
 /** Human note surfaced in docs/registries so the rule is visible where routes are defined. */
 export declare const SENSITIVITY_NOTE: string;
-//# sourceMappingURL=sensitivity.d.ts.map

package/dist/sensitivity.js

@@ -27,4 +27,3 @@ export function needsFreshAuth(sensitivity) {
 export const SENSITIVITY_NOTE = 'Every portal route MUST declare `sensitivity` (read | sensitive | write). write/sensitive ⇒ verify ' +
     'with forceFresh (bypass the JWT verdict cache) so logout/revocation is caught immediately; read ⇒ ' +
     'cache-fronted verify. A missing classification is a compile error via `satisfies Record<string, RouteAuth>`.';
-//# sourceMappingURL=sensitivity.js.map

package/dist/themes.d.ts

@@ -68,4 +68,3 @@ export declare const THEMES: Record<string, ThemeDef>;
 /** System-auto defaults (host picks by `prefers-color-scheme` on first load). */
 export declare const DEFAULT_LIGHT_THEME = "light-neo";
 export declare const DEFAULT_DARK_THEME = "slate-dark";
-//# sourceMappingURL=themes.d.ts.map

package/dist/themes.js

@@ -101,4 +101,3 @@ export const THEMES = {
 /** System-auto defaults (host picks by `prefers-color-scheme` on first load). */
 export const DEFAULT_LIGHT_THEME = 'light-neo';
 export const DEFAULT_DARK_THEME = 'slate-dark';
-//# sourceMappingURL=themes.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Portable, Node-free NetSapiens toolkit: read-only API client, JWT (ns_t) validation, and a snapshot -> FlowGraph -> Mermaid call-flow resolver/renderer. Runs unchanged in a Cloudflare Worker, Node, or the browser.",
   "type": "module",
   "license": "MIT",
@@ -27,8 +27,12 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+      "import": "./dist/index.js",
+      "//require": "ESM-only package. This `require` condition lets Node >=22.12 load it via require(esm); older Node still gets an accurate ERR_REQUIRE_ESM here instead of the confusing ERR_PACKAGE_PATH_NOT_EXPORTED the bare export map produced.",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
   "module": "./dist/index.js",
@@ -43,7 +47,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "build:watch": "tsc -p tsconfig.json --watch",
-    "prepublishOnly": "tsc -p tsconfig.json",
+    "//prepublishOnly": "Publish-only build with sourcemaps OFF. The `files` globs exclude dist/**/*.map on purpose (they point at src/, which does not ship), but tsc still emits a //# sourceMappingURL pointer into every .js/.d.ts -- so consumers' devtools 404 chasing maps that were never published. Dropping the pointer at publish time is what the exclusion always meant. A normal `pnpm build` keeps maps for link: consumers.",
+    "prepublishOnly": "tsc -p tsconfig.json --sourceMap false --declarationMap false",
     "//test": "The offline suite — green on a fresh clone with no credentials and no fixtures. test:ns is NOT included: it needs a domain snapshot that (correctly) isn't in the repo.",
     "test": "pnpm run test:jwt && pnpm run test:principal && pnpm run test:resolver && pnpm run test:raster",
     "test:jwt": "tsx src/jwt.selftest.ts",