@dszp/netsapiens-lib 0.1.3 → 0.1.5

package/README.md

@@ -6,8 +6,10 @@ never `node:*`.
 
 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.
+- **NS API v2 client (read + write)** — `NsClient` (read-only: `get()` + `fetchDomainSnapshot(client,
+  domain)` which assembles a routing-relevant domain snapshot) plus `NsWriteClient`, a **separate** write
+  client (device provisioning). Both are bearer-auth with an injectable `fetch`; holding the read client
+  still cannot write.
 - **JWT (`ns_t`) validation** — `verify()` (cheap local format gate → cached live `/jwt` check) and
   `validateJwtFormat()`. Pluggable `VerdictCache` (inject the Workers Cache API / KV / DO;
   `MemoryVerdictCache` for dev). Anti-overload by design — a bad/expired token never hits the server.
@@ -61,13 +63,14 @@ Two composites are provided because they're multi-read and worth getting right o
 
 The snapshot is the routing subset — what `resolveFlow()` needs. It is not a full domain export.
 
-### Read-only by charter
+### Read/write split by charter
 
 `NsClient` exposes **`get()` and nothing else**, and `verify()` only ever issues `GET /jwt`. That is a
 deliberate boundary, not a missing feature: this library is built for tools that visualize and audit a
 NetSapiens domain, where "it cannot possibly write" is a property worth having structurally rather
-than by convention. Writes belong in a separate, explicitly-reviewed client. If a write surface is
-added here later it will be a distinct class, never new methods on `NsClient`.
+than by convention. Writes live in a **separate** class — `NsWriteClient`, a small, explicitly-reviewed
+surface (device provisioning) — never as new methods on `NsClient`. So a consumer that holds the read
+client still cannot write; that guarantee holds by construction, not by convention.
 
 ### Configuration binds to *your* deployment
 

package/dist/eligibility.d.ts

@@ -0,0 +1,64 @@
+/**
+ * evaluateEligibility — is a NetSapiens user a real end-user candidate for an app integration (Ringotel,
+ * or any other)? Pure and deployment-neutral. The name is generic on purpose: the config/rules define the
+ * purpose. Consumers supply an EligibilityConfig; env parsing lives in each consumer, never here.
+ *
+ *   HARD  — system/service users (srv_code) + structurally-invalid extensions. Never eligible, not even a
+ *           reseller override.
+ *   SOFT  — name matchers, extension lists, no-device heuristic. Default-excluded, reseller-overridable
+ *           per configured category (or via an explicit per-request `force`).
+ *   email — a precondition: activation typically emails credentials, so it can't proceed without an address.
+ * Precedence: HARD → SOFT (names, exts) → precondition → ok.
+ */
+export type SoftCategory = 'names' | 'exts' | 'no_devices';
+export interface EligibilityConfig {
+    /** Lowercased name-contains matchers (checked against first/last/display). Caller lowercases. */
+    excludeNames: string[];
+    /** Global extension exclusions (exact, or trailing-`*` prefix). */
+    excludeExts: string[];
+    /** Per-domain override of the extension list (add/remove relative to global). */
+    excludeExtsByDomain: Record<string, {
+        add?: string[];
+        remove?: string[];
+    }>;
+    /** No-device heuristic: TIGHTENS a name match (never decides alone). */
+    excludeNoDevices: boolean;
+    /** Soft categories a reseller may override. */
+    resellerOverride: Set<SoftCategory>;
+}
+export interface EligUser {
+    ext: string;
+    srvCode?: string;
+    email?: string;
+    names?: string[];
+    deviceCount?: number;
+}
+export interface EligContext {
+    domain: string;
+    isReseller: boolean;
+    /** Reseller RUNTIME force: bypass ALL soft categories — never HARD, never the email precondition. */
+    force?: boolean;
+    /**
+     * Credentials are delivered by LOGIN, not email, so the email precondition does not apply. Set this on
+     * an SSO/JIT path, where the account is created from the user's own directory credentials on first
+     * sign-in and nothing is mailed. It waives ONLY the email precondition — never HARD, never SOFT.
+     *
+     * The caller decides WHEN to set it; the engine only guarantees the outcome is the same everywhere it
+     * is set. A waived result stays distinguishable via `emailWaived`, so a caller can still branch on
+     * "eligible, but there is no address to mail anything to".
+     */
+    emailNotRequired?: boolean;
+}
+export type EligTier = 'ok' | 'hard' | 'soft' | 'precondition';
+export interface EligResult {
+    activatable: boolean;
+    tier: EligTier;
+    reasons: string[];
+    /**
+     * The user has no email address and `emailNotRequired` waived the precondition. `tier` is `'ok'` —
+     * they are eligible — but there is no address, so a caller must not try to mail them credentials.
+     * Absent whenever an address is present or the precondition was not reached.
+     */
+    emailWaived?: true;
+}
+export declare function evaluateEligibility(user: EligUser, ctx: EligContext, config: EligibilityConfig): EligResult;

package/dist/eligibility.js

@@ -0,0 +1,58 @@
+/**
+ * evaluateEligibility — is a NetSapiens user a real end-user candidate for an app integration (Ringotel,
+ * or any other)? Pure and deployment-neutral. The name is generic on purpose: the config/rules define the
+ * purpose. Consumers supply an EligibilityConfig; env parsing lives in each consumer, never here.
+ *
+ *   HARD  — system/service users (srv_code) + structurally-invalid extensions. Never eligible, not even a
+ *           reseller override.
+ *   SOFT  — name matchers, extension lists, no-device heuristic. Default-excluded, reseller-overridable
+ *           per configured category (or via an explicit per-request `force`).
+ *   email — a precondition: activation typically emails credentials, so it can't proceed without an address.
+ * Precedence: HARD → SOFT (names, exts) → precondition → ok.
+ */
+const blank = (s) => !s || s.trim() === '';
+function excludedExtsFor(config, domain) {
+    const dom = config.excludeExtsByDomain[domain] ?? {};
+    const set = new Set(config.excludeExts);
+    for (const a of dom.add ?? [])
+        set.add(a);
+    for (const r of dom.remove ?? [])
+        set.delete(r);
+    return [...set];
+}
+function extMatch(ext, patterns) {
+    return patterns.find((p) => (p.endsWith('*') ? ext.startsWith(p.slice(0, -1)) : ext === p));
+}
+export function evaluateEligibility(user, ctx, config) {
+    if (!blank(user.srvCode)) {
+        return { activatable: false, tier: 'hard', reasons: [`system/service user (srv_code="${user.srvCode.trim()}")`] };
+    }
+    if (!/^\d{3,4}$/.test(user.ext)) {
+        return { activatable: false, tier: 'hard', reasons: [`extension "${user.ext}" is not a 3-4 digit user extension`] };
+    }
+    const canOverride = (cat) => ctx.isReseller && (config.resellerOverride.has(cat) || !!ctx.force);
+    const names = (user.names ?? []).map((n) => (n || '').toLowerCase());
+    const nameMatch = config.excludeNames.find((m) => names.some((n) => n.includes(m)));
+    const nameHit = nameMatch && (!config.excludeNoDevices || (user.deviceCount ?? 0) === 0);
+    if (nameHit && !canOverride('names')) {
+        return { activatable: false, tier: 'soft', reasons: [`name matches excluded pattern "${nameMatch}"`] };
+    }
+    const extHit = extMatch(user.ext, excludedExtsFor(config, ctx.domain));
+    if (extHit && !canOverride('exts')) {
+        return { activatable: false, tier: 'soft', reasons: [`extension "${user.ext}" matches excluded pattern "${extHit}"`] };
+    }
+    if (blank(user.email)) {
+        if (!ctx.emailNotRequired) {
+            return { activatable: false, tier: 'precondition', reasons: ['an email address is required to activate'] };
+        }
+        // Waived: credentials arrive by login, not mail. Eligible — but say the address is missing, so a
+        // caller that WOULD have mailed something can still tell.
+        return {
+            activatable: true,
+            tier: 'ok',
+            reasons: ['no email address (precondition waived: credentials are not emailed)'],
+            emailWaived: true,
+        };
+    }
+    return { activatable: true, tier: 'ok', reasons: [] };
+}

package/dist/index.d.ts

@@ -17,7 +17,9 @@ export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, f
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray, type NsClientConfig, type FetchSnapshotOptions } from './nsClient.js';
 export { NsWriteClient, type NsWriteClientConfig } from './nsWriteClient.js';
+export { NsAuthClient, NsAuthError, type NsAuthClientConfig, type NsTokenResponse } from './nsAuthClient.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';
+export { evaluateEligibility, type SoftCategory, type EligibilityConfig, type EligUser, type EligContext, type EligTier, type EligResult, } from './eligibility.js';

package/dist/index.js

@@ -16,7 +16,9 @@ export { renderGalleryHtml, renderFlowCards, renderFlowCard, mermaidBootstrap, f
 export { resolveSvgSize, rasterizerScript } from './raster.js';
 export { NsClient, NsApiError, assertBareServer, fetchDomainSnapshot, listDomains, asArray } from './nsClient.js';
 export { NsWriteClient } from './nsWriteClient.js';
+export { NsAuthClient, NsAuthError } from './nsAuthClient.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';
+export { evaluateEligibility, } from './eligibility.js';

package/dist/nsAuthClient.d.ts

@@ -0,0 +1,51 @@
+/**
+ * NsAuthClient — the NetSapiens OAuth2 password-grant surface. Two jobs off one call:
+ *   - verifyCredentials(user, pass): confirm an END USER's credentials (the SSO webhook's auth check).
+ *   - passwordGrant(adminUser, adminPass): mint a reseller/admin access token to use as a write bearer,
+ *     an alternative to a static API key.
+ * Both use the deployment's "master key" (an OAuth application's client_id/client_secret). Node-free
+ * (fetch/URLSearchParams). The token endpoint is form-encoded and returns JSON.
+ *
+ * Fail-closed contract: passwordGrant throws NsAuthError on ANY non-2xx. verifyCredentials treats a 4xx as
+ * "bad credentials" ({ ok:false }) but RETHROWS a 5xx / network error, so a caller cannot mistake an
+ * upstream outage for a failed login.
+ */
+export declare class NsAuthError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export interface NsTokenResponse {
+    access_token?: string;
+    /** The authenticated user's extension (NetSapiens returns this on the token body). */
+    user?: string;
+    domain?: string;
+    scope?: string;
+    [k: string]: unknown;
+}
+export interface NsAuthClientConfig {
+    /** API host, e.g. "api.example.com" (bare — no scheme/path). Token endpoint = https://{server}/ns-api/oauth2/token/ */
+    server: string;
+    /** OAuth application client id (the "master key" id). */
+    clientId: string;
+    /** OAuth application client secret. */
+    clientSecret: string;
+    /** Injectable for tests / non-global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare class NsAuthClient {
+    #private;
+    constructor(cfg: NsAuthClientConfig);
+    passwordGrant(username: string, password: string): Promise<NsTokenResponse>;
+    /**
+     * Confirm an end user's credentials via OAuth2 password-grant.
+     *
+     * Contract: `ok` is true IF AND ONLY IF the token response carried a non-empty `access_token`.
+     * NetSapiens can return HTTP 200 with an empty/in-band-error body (no `access_token`) — that is
+     * NOT a successful login, so a bare 2xx is not sufficient. A 4xx maps to `{ ok: false }`; a 5xx /
+     * network error rethrows so a caller cannot mistake an upstream outage for a failed login.
+     */
+    verifyCredentials(username: string, password: string): Promise<{
+        ok: boolean;
+        token?: NsTokenResponse;
+    }>;
+}

package/dist/nsAuthClient.js

@@ -0,0 +1,84 @@
+/**
+ * NsAuthClient — the NetSapiens OAuth2 password-grant surface. Two jobs off one call:
+ *   - verifyCredentials(user, pass): confirm an END USER's credentials (the SSO webhook's auth check).
+ *   - passwordGrant(adminUser, adminPass): mint a reseller/admin access token to use as a write bearer,
+ *     an alternative to a static API key.
+ * Both use the deployment's "master key" (an OAuth application's client_id/client_secret). Node-free
+ * (fetch/URLSearchParams). The token endpoint is form-encoded and returns JSON.
+ *
+ * Fail-closed contract: passwordGrant throws NsAuthError on ANY non-2xx. verifyCredentials treats a 4xx as
+ * "bad credentials" ({ ok:false }) but RETHROWS a 5xx / network error, so a caller cannot mistake an
+ * upstream outage for a failed login.
+ */
+import { assertBareServer } from './nsClient.js';
+export class NsAuthError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'NsAuthError';
+    }
+}
+export class NsAuthClient {
+    #url;
+    #clientId;
+    #clientSecret;
+    #fetchImpl;
+    constructor(cfg) {
+        this.#url = `https://${assertBareServer(cfg.server)}/ns-api/oauth2/token/`;
+        this.#clientId = cfg.clientId;
+        this.#clientSecret = cfg.clientSecret;
+        this.#fetchImpl = cfg.fetchImpl ?? fetch;
+    }
+    async passwordGrant(username, password) {
+        const body = new URLSearchParams({
+            grant_type: 'password',
+            client_id: this.#clientId,
+            client_secret: this.#clientSecret,
+            username,
+            password,
+            format: 'json',
+        });
+        // Call via a local, NOT this.#fetchImpl(...): the global fetch requires a global `this` in workerd.
+        const doFetch = this.#fetchImpl;
+        const res = await doFetch(this.#url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: body.toString(),
+        });
+        const text = await res.text();
+        let parsed = text;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch { /* non-JSON error body */ }
+        }
+        if (!res.ok) {
+            const detail = (typeof parsed === 'object' && parsed !== null ? JSON.stringify(parsed) : String(parsed)).slice(0, 300);
+            throw new NsAuthError(`NS oauth2/token → ${res.status}: ${detail}`, res.status);
+        }
+        return (parsed && typeof parsed === 'object' ? parsed : {});
+    }
+    /**
+     * Confirm an end user's credentials via OAuth2 password-grant.
+     *
+     * Contract: `ok` is true IF AND ONLY IF the token response carried a non-empty `access_token`.
+     * NetSapiens can return HTTP 200 with an empty/in-band-error body (no `access_token`) — that is
+     * NOT a successful login, so a bare 2xx is not sufficient. A 4xx maps to `{ ok: false }`; a 5xx /
+     * network error rethrows so a caller cannot mistake an upstream outage for a failed login.
+     */
+    async verifyCredentials(username, password) {
+        try {
+            const token = await this.passwordGrant(username, password);
+            if (!token.access_token)
+                return { ok: false };
+            return { ok: true, token };
+        }
+        catch (e) {
+            if (e instanceof NsAuthError && e.status >= 400 && e.status < 500)
+                return { ok: false };
+            throw e; // 5xx / network → fail closed upstream
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",
@@ -50,13 +50,15 @@
     "//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 && pnpm run test:nswrite",
+    "test": "pnpm run test:jwt && pnpm run test:principal && pnpm run test:resolver && pnpm run test:raster && pnpm run test:nswrite && pnpm run test:eligibility && pnpm run test:nsauth",
     "test:jwt": "tsx src/jwt.selftest.ts",
     "test:ns": "tsx src/nsClient.selftest.ts",
     "test:nswrite": "tsx src/nsWriteClient.selftest.ts",
+    "test:nsauth": "tsx src/nsAuthClient.selftest.ts",
     "test:principal": "tsx src/principal.selftest.ts",
     "test:resolver": "tsx src/resolver.selftest.ts",
-    "test:raster": "tsx src/raster.selftest.ts"
+    "test:raster": "tsx src/raster.selftest.ts",
+    "test:eligibility": "tsx src/eligibility.selftest.ts"
   },
   "devDependencies": {
     "tsx": "^4.22.4",