@dszp/netsapiens-lib 0.1.6 → 0.1.8

package/README.md

@@ -72,6 +72,32 @@ than by convention. Writes live in a **separate** class — `NsWriteClient`, a s
 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.
 
+### Which writes actually confirm: `synchronous`
+
+`synchronous: 'yes'` asks the API to finish the write before replying, so you get **200 with the
+resulting resource inline** — including server-generated fields you could not otherwise learn without a
+second read, a new device's SIP registration password being the worked example. Without it you get
+**202 Accepted** and a bare `{code, message}`.
+
+It is a **per-operation capability, not a global one**: exactly 17 operations declare it in the v2
+specification (core 44.4.10), and almost all of them are creates. Sending it anywhere else is inert —
+NetSapiens ignores unrecognized body fields and still answers 202 — so code that adds it everywhere
+merely *looks* as though its writes are confirmed.
+
+`NsWriteClient` therefore injects the flag only where it is accepted, and exports the table so other
+NetSapiens clients can share one answer instead of each keeping a copy that drifts:
+
+```ts
+import { supportsSynchronous, SYNCHRONOUS_OPERATIONS } from '@dszp/netsapiens-lib';
+
+supportsSynchronous('POST', '/domains/acme.example/users');     // true  — user CREATE
+supportsSynchronous('PUT',  '/domains/acme.example/users/100'); // false — user UPDATE
+```
+
+`path` is the concrete request path relative to `/ns-api/v2`, dynamic segments already URI-encoded.
+The most consequential absence is that **user update** is not on the list even though user create is:
+there is no response that can confirm a user update, so confirm it by reading the record back.
+
 ### Configuration binds to *your* deployment
 
 Two values are required and have no defaults, on purpose — a default would silently bind you to

package/dist/index.d.ts

@@ -17,6 +17,7 @@ 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 { supportsSynchronous, SYNCHRONOUS_OPERATIONS, type SynchronousMethod, type SynchronousOperation, } from './nsSynchronous.js';
 export { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, type NsDeviceWriter, type EnsureNsDeviceOptions, type EnsureNsDeviceResult, } from './nsDevice.js';
 export { NsAuthClient, NsAuthError, type NsAuthClientConfig, type NsTokenResponse } from './nsAuthClient.js';
 export { NsSubscriptionsClient, NsSubscriptionConflictError, SUBSCRIPTION_MODELS, isSubscriptionModel, nsDatetime, parseNsDatetime, subscriptionFromWire, createInputToWire, updateInputToWire, planSubscriptions, type SubscriptionModel, type SubscriptionStatus, type Subscription, type CreateSubscriptionInput, type UpdateSubscriptionInput, type NsSubscriptionsClientConfig, type DesiredSubscription, type SubscriptionAction, type PlanSubscriptionsOptions, } from './nsSubscriptions.js';

package/dist/index.js

@@ -16,6 +16,7 @@ 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 { supportsSynchronous, SYNCHRONOUS_OPERATIONS, } from './nsSynchronous.js';
 export { ensureNsDevice, generateSipPassword, SIP_PW_FIELD, } from './nsDevice.js';
 export { NsAuthClient, NsAuthError } from './nsAuthClient.js';
 export { NsSubscriptionsClient, NsSubscriptionConflictError, SUBSCRIPTION_MODELS, isSubscriptionModel, nsDatetime, parseNsDatetime, subscriptionFromWire, createInputToWire, updateInputToWire, planSubscriptions, } from './nsSubscriptions.js';

package/dist/nsClient.d.ts

@@ -7,7 +7,7 @@
  * `fetchDomainSnapshot()` assembles the same `Snapshot` shape the resolver already consumes, so a
  * live domain flows end-to-end: domain + token → Snapshot → resolveFlow → FlowGraph.
  *
- * This tool never writes to NetSapiens — only GET is exposed.
+ * This client never writes — only GET is exposed. Writes live in the separate `NsWriteClient`.
  */
 import type { Rec, Snapshot } from './model.js';
 export declare class NsApiError extends Error {
@@ -29,12 +29,16 @@ export interface NsClientConfig {
     fetchImpl?: typeof fetch;
 }
 /**
- * NS API v2 client — READ-ONLY BY DESIGN (the central gate for this whole tool).
+ * NS API v2 client — READ-ONLY BY DESIGN.
  *
  * The ONLY method is `get()`, which hardcodes `method: 'GET'`. There is deliberately no
- * post/put/delete/patch — the viewer must never mutate NetSapiens. Keep it that way: do not add a
- * 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.
+ * post/put/delete/patch. Keep it that way: **do not add a mutating method here.** The point of this
+ * class is that holding one is proof you cannot write — a guarantee by construction, not convention,
+ * and adding a single mutating method destroys it for every consumer at once.
+ *
+ * Writes are a separate, explicitly-imported class: `NsWriteClient` (see `nsWriteClient.ts`). New
+ * write capability extends that one, never this one. `NsSubscriptionsClient` is a third client for
+ * the same reason — its `DELETE` semantics differ from `NsWriteClient`'s.
  */
 /**
  * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from

package/dist/nsClient.js

@@ -7,7 +7,7 @@
  * `fetchDomainSnapshot()` assembles the same `Snapshot` shape the resolver already consumes, so a
  * live domain flows end-to-end: domain + token → Snapshot → resolveFlow → FlowGraph.
  *
- * This tool never writes to NetSapiens — only GET is exposed.
+ * This client never writes — only GET is exposed. Writes live in the separate `NsWriteClient`.
  */
 export class NsApiError extends Error {
     status;
@@ -26,12 +26,16 @@ export class NsApiError extends Error {
     }
 }
 /**
- * NS API v2 client — READ-ONLY BY DESIGN (the central gate for this whole tool).
+ * NS API v2 client — READ-ONLY BY DESIGN.
  *
  * The ONLY method is `get()`, which hardcodes `method: 'GET'`. There is deliberately no
- * post/put/delete/patch — the viewer must never mutate NetSapiens. Keep it that way: do not add a
- * 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.
+ * post/put/delete/patch. Keep it that way: **do not add a mutating method here.** The point of this
+ * class is that holding one is proof you cannot write — a guarantee by construction, not convention,
+ * and adding a single mutating method destroys it for every consumer at once.
+ *
+ * Writes are a separate, explicitly-imported class: `NsWriteClient` (see `nsWriteClient.ts`). New
+ * write capability extends that one, never this one. `NsSubscriptionsClient` is a third client for
+ * the same reason — its `DELETE` semantics differ from `NsWriteClient`'s.
  */
 /**
  * Reject a `server` that isn't a bare host or `host:port`. A caller that derives `server` from

package/dist/nsSubscriptions.d.ts

@@ -3,10 +3,12 @@
  * pure reconciliation planner.
  *
  * This is its own class on purpose. `NsClient` is read-only by charter (a consumer holds one precisely to
- * know it cannot write), and `NsWriteClient` is unsuitable here for two concrete reasons: it injects
- * `synchronous: 'yes'` into every POST/PUT, and its `delete()` sends no body — while
- * `DELETE /subscriptions/{id}` *requires* a body (`subscription_id`, plus `domain` for scopes below Super
- * User). Node-free (fetch/URL/crypto only), so it runs unchanged in a Cloudflare Worker.
+ * know it cannot write), and `NsWriteClient`'s `delete()` sends no body — while
+ * `DELETE /subscriptions/{id}` *requires* one (`subscription_id`, plus `domain` for scopes below Super
+ * User). (A second reason applied until 0.1.7: `NsWriteClient` injected `synchronous: 'yes'` into *every*
+ * POST/PUT, which no `/subscriptions` operation accepts. It now injects only where the API declares
+ * support, so that objection is gone — the `delete()` body is what still makes the split necessary.)
+ * Node-free (fetch/URL/crypto only), so it runs unchanged in a Cloudflare Worker.
  *
  * An event subscription tells NetSapiens to POST change events to a URL you own. Notable API properties
  * that shape this module:

package/dist/nsSubscriptions.js

@@ -314,7 +314,7 @@ export function planSubscriptions(desired, actual, nowMs, opts) {
     const isOurs = (s) => typeof s.postUrl === 'string' && s.postUrl.startsWith(opts.ownedPrefix);
     const ours = actual.filter(isOurs);
     const foreign = actual.filter((s) => !isOurs(s));
-    const key = (domain, model) => `${domain.toLowerCase()}${model}`;
+    const key = (domain, model) => `${domain.toLowerCase()}\u0000${model}`;
     const actions = [];
     const claimed = new Set();
     for (const want of desired) {

package/dist/nsSynchronous.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which NetSapiens v2 write operations accept the `synchronous` request-body flag.
+ *
+ * `synchronous: 'yes'` asks the API to complete the write before replying, so the response is
+ * **200 with the resulting resource inline** — including server-generated fields a caller cannot
+ * otherwise learn without a second read (a new device's SIP registration password is the worked
+ * example). Without it, or on an operation that does not support it, the API replies
+ * **202 Accepted** with a bare `{code, message}` acknowledgement and applies the write behind the
+ * scenes.
+ *
+ * **It is a per-operation capability, not a global one.** Only the operations listed below declare
+ * a `synchronous` property in the v2 OpenAPI specification (core 44.4.10) — 17 of them, almost all
+ * creates. Sending the flag to any other endpoint is inert: NetSapiens ignores unrecognized body
+ * fields and still answers 202. That is harmless but misleading, because it makes code look as
+ * though it has a synchronous guarantee it never had.
+ *
+ * The most consequential absence is **`PUT /domains/{domain}/users/{user}`** — a user *update*
+ * cannot be made synchronous, though a user *create* can. Verified live 2026-08-03: the flag in the
+ * body, as `?synchronous=yes`, as `?synchronous=true`, both at once, and omitted entirely all return
+ * an identical 202 on that endpoint. Any confirmation of a user update has to come from reading the
+ * record back, not from the response.
+ *
+ * Kept as data rather than folded into each method so both this library's write client and other
+ * NetSapiens clients can share one answer instead of drifting apart.
+ */
+/** The HTTP methods any `synchronous`-capable operation uses. */
+export type SynchronousMethod = 'POST' | 'PUT';
+/** One operation that accepts `synchronous`, as a method plus an OpenAPI-style templated path. */
+export interface SynchronousOperation {
+    method: SynchronousMethod;
+    /** Templated path, e.g. `/domains/{domain}/users`. A `{...}` segment matches exactly one path segment. */
+    path: string;
+}
+/**
+ * Every operation declaring `synchronous` in the v2 spec (core 44.4.10), deduplicated — the
+ * specification lists several of these more than once under `#1`…`#4` suffixes for differing
+ * request shapes, which are the same HTTP operation.
+ *
+ * Note the near-misses, which are the whole reason this list is explicit: user and domain **create**
+ * are here, user **update** is not; greeting and MOH **update** are here, device update is not.
+ */
+export declare const SYNCHRONOUS_OPERATIONS: readonly SynchronousOperation[];
+/**
+ * Does `method path` accept `synchronous`?
+ *
+ * `path` is a concrete request path relative to the `/ns-api/v2` base, with its dynamic segments
+ * already filled in and URI-encoded — exactly what a client passes to `post()`/`put()`. Encoding is
+ * what makes the match safe: a value containing a slash arrives as `%2F` and stays one segment, so
+ * it cannot masquerade as a deeper path.
+ *
+ * Unknown paths answer `false`. That is the safe direction: the flag is then omitted, and the caller
+ * gets the 202 it would have received anyway — rather than a promise of a 200 that never arrives.
+ */
+export declare function supportsSynchronous(method: string, path: string): boolean;

package/dist/nsSynchronous.js

@@ -0,0 +1,78 @@
+/**
+ * Which NetSapiens v2 write operations accept the `synchronous` request-body flag.
+ *
+ * `synchronous: 'yes'` asks the API to complete the write before replying, so the response is
+ * **200 with the resulting resource inline** — including server-generated fields a caller cannot
+ * otherwise learn without a second read (a new device's SIP registration password is the worked
+ * example). Without it, or on an operation that does not support it, the API replies
+ * **202 Accepted** with a bare `{code, message}` acknowledgement and applies the write behind the
+ * scenes.
+ *
+ * **It is a per-operation capability, not a global one.** Only the operations listed below declare
+ * a `synchronous` property in the v2 OpenAPI specification (core 44.4.10) — 17 of them, almost all
+ * creates. Sending the flag to any other endpoint is inert: NetSapiens ignores unrecognized body
+ * fields and still answers 202. That is harmless but misleading, because it makes code look as
+ * though it has a synchronous guarantee it never had.
+ *
+ * The most consequential absence is **`PUT /domains/{domain}/users/{user}`** — a user *update*
+ * cannot be made synchronous, though a user *create* can. Verified live 2026-08-03: the flag in the
+ * body, as `?synchronous=yes`, as `?synchronous=true`, both at once, and omitted entirely all return
+ * an identical 202 on that endpoint. Any confirmation of a user update has to come from reading the
+ * record back, not from the response.
+ *
+ * Kept as data rather than folded into each method so both this library's write client and other
+ * NetSapiens clients can share one answer instead of drifting apart.
+ */
+/**
+ * Every operation declaring `synchronous` in the v2 spec (core 44.4.10), deduplicated — the
+ * specification lists several of these more than once under `#1`…`#4` suffixes for differing
+ * request shapes, which are the same HTTP operation.
+ *
+ * Note the near-misses, which are the whole reason this list is explicit: user and domain **create**
+ * are here, user **update** is not; greeting and MOH **update** are here, device update is not.
+ */
+export const SYNCHRONOUS_OPERATIONS = [
+    { method: 'POST', path: '/domains' },
+    { method: 'POST', path: '/domains/{domain}/callqueues' },
+    { method: 'POST', path: '/domains/{domain}/callqueues/{callqueue}/agents' },
+    { method: 'POST', path: '/domains/{domain}/dialplans/{dialplan}/dialrules' },
+    { method: 'POST', path: '/domains/{domain}/moh' },
+    { method: 'PUT', path: '/domains/{domain}/moh/{index}' },
+    { method: 'PUT', path: '/domains/{domain}/sites/{site}' },
+    { method: 'POST', path: '/domains/{domain}/timeframes' },
+    { method: 'POST', path: '/domains/{domain}/users' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/answerrules' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/calls' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/devices' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/greetings' },
+    { method: 'PUT', path: '/domains/{domain}/users/{user}/greetings/{index}' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/moh' },
+    { method: 'PUT', path: '/domains/{domain}/users/{user}/moh/{index}' },
+    { method: 'POST', path: '/domains/{domain}/users/{user}/timeframes' },
+];
+/** Split a path into non-empty segments, ignoring any query string and leading/trailing slashes. */
+const segmentsOf = (path) => (path.split('?')[0] ?? '').split('/').filter(Boolean);
+/** Precomputed segment forms, so a lookup is a comparison rather than a re-parse per call. */
+const TABLE = SYNCHRONOUS_OPERATIONS.map((op) => ({ method: op.method, segments: segmentsOf(op.path) }));
+/**
+ * Does `method path` accept `synchronous`?
+ *
+ * `path` is a concrete request path relative to the `/ns-api/v2` base, with its dynamic segments
+ * already filled in and URI-encoded — exactly what a client passes to `post()`/`put()`. Encoding is
+ * what makes the match safe: a value containing a slash arrives as `%2F` and stays one segment, so
+ * it cannot masquerade as a deeper path.
+ *
+ * Unknown paths answer `false`. That is the safe direction: the flag is then omitted, and the caller
+ * gets the 202 it would have received anyway — rather than a promise of a 200 that never arrives.
+ */
+export function supportsSynchronous(method, path) {
+    const verb = method.toUpperCase();
+    if (verb !== 'POST' && verb !== 'PUT')
+        return false;
+    const actual = segmentsOf(path);
+    return TABLE.some((op) => op.method === verb &&
+        op.segments.length === actual.length &&
+        op.segments.every((seg, i) => seg.startsWith('{') && seg.endsWith('}')
+            ? true // a template segment matches any single segment
+            : seg.toLowerCase() === actual[i].toLowerCase()));
+}

package/dist/nsWriteClient.d.ts

@@ -8,9 +8,12 @@
  * generic post/put/delete core, and is meant to GROW into the full NS write surface (users, DIDs, …) —
  * porting the endpoint/body shapes from the onboarding tool's resource defs as they're needed.
  *
- * Like the onboarding client, POST/PUT inject `synchronous: 'yes'` so a create returns 200 + the created
- * resource inline (with server-generated fields — e.g. a device's `device-sip-registration-password`)
- * instead of a 202 with replication lag. Shares the read client's SSRF guard and `NsApiError`.
+ * POST/PUT inject `synchronous: 'yes'` **only on the operations that accept it** (see
+ * {@link supportsSynchronous}), where it makes the API return 200 + the resulting resource inline —
+ * with server-generated fields such as a device's `device-sip-registration-password` — instead of a
+ * bare 202 acknowledgement. Everywhere else the flag is omitted, because sending it there is inert:
+ * NetSapiens ignores it and still answers 202, which previously made this client look as though all
+ * of its writes were confirmed when most were not. Shares the read client's SSRF guard and `NsApiError`.
  */
 import type { Rec } from './model.js';
 import { type EnsureNsDeviceOptions, type EnsureNsDeviceResult } from './nsDevice.js';
@@ -26,9 +29,15 @@ export declare class NsWriteClient {
     #private;
     constructor(cfg: NsWriteClientConfig);
     get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T>;
-    /** POST with `synchronous:'yes'` injected → 200 + created resource inline. */
+    /**
+     * POST. On an operation that accepts it, `synchronous:'yes'` is injected → 200 + the created
+     * resource inline; otherwise the flag is omitted and the API answers 202 Accepted.
+     */
     post<T = unknown>(path: string, body: Rec): Promise<T>;
-    /** PUT with `synchronous:'yes'` injected. */
+    /**
+     * PUT. Same rule as {@link post} — and note most updates do NOT accept the flag, so their
+     * response is a 202 acknowledgement with no resource body. Confirm those by reading back.
+     */
     put<T = unknown>(path: string, body: Rec): Promise<T>;
     delete<T = unknown>(path: string): Promise<T>;
     /** List a user's devices (normalized to an array). */
@@ -44,6 +53,10 @@ export declare class NsWriteClient {
     /**
      * Update a device in place.
      *
+     * `PUT .../devices/{device}` does **not** accept `synchronous`, so this returns a 202
+     * acknowledgement, not the updated device. Callers must not depend on the response echoing their
+     * change back — {@link ensureNsDevice} falls back to the value it just sent for exactly this reason.
+     *
      * The reason this exists rather than callers using `put()`: rotating
      * `device-sip-registration-password` must **not** be done by deleting and recreating the device, which
      * would discard everything else on it — emergency caller id, the provisioning MAC/model link, SRTP and

package/dist/nsWriteClient.js

@@ -1,5 +1,6 @@
 import { NsApiError, assertBareServer, asArray } from './nsClient.js';
 import { ensureNsDevice } from './nsDevice.js';
+import { supportsSynchronous } from './nsSynchronous.js';
 const enc = encodeURIComponent;
 export class NsWriteClient {
     #baseUrl;
@@ -14,13 +15,25 @@ export class NsWriteClient {
     get(path, query) {
         return this.#request('GET', path, undefined, query);
     }
-    /** POST with `synchronous:'yes'` injected → 200 + created resource inline. */
+    /**
+     * POST. On an operation that accepts it, `synchronous:'yes'` is injected → 200 + the created
+     * resource inline; otherwise the flag is omitted and the API answers 202 Accepted.
+     */
     post(path, body) {
-        return this.#request('POST', path, { synchronous: 'yes', ...body });
+        return this.#request('POST', path, this.#withSynchronous('POST', path, body));
     }
-    /** PUT with `synchronous:'yes'` injected. */
+    /**
+     * PUT. Same rule as {@link post} — and note most updates do NOT accept the flag, so their
+     * response is a 202 acknowledgement with no resource body. Confirm those by reading back.
+     */
     put(path, body) {
-        return this.#request('PUT', path, { synchronous: 'yes', ...body });
+        return this.#request('PUT', path, this.#withSynchronous('PUT', path, body));
+    }
+    /** Add `synchronous:'yes'` only where the API declares support. An explicit caller value wins. */
+    #withSynchronous(method, path, body) {
+        if (!supportsSynchronous(method, path))
+            return body;
+        return { synchronous: 'yes', ...body };
     }
     delete(path) {
         return this.#request('DELETE', path);
@@ -45,6 +58,10 @@ export class NsWriteClient {
     /**
      * Update a device in place.
      *
+     * `PUT .../devices/{device}` does **not** accept `synchronous`, so this returns a 202
+     * acknowledgement, not the updated device. Callers must not depend on the response echoing their
+     * change back — {@link ensureNsDevice} falls back to the value it just sent for exactly this reason.
+     *
      * The reason this exists rather than callers using `put()`: rotating
      * `device-sip-registration-password` must **not** be done by deleting and recreating the device, which
      * would discard everything else on it — emergency caller id, the provisioning MAC/model link, SRTP and

package/dist/policy.d.ts

@@ -13,9 +13,15 @@
  *  - all users in some domains:       { domains: ['acme','acme42'] }
  *  - …optionally with scopes:         { domains:['acme'], scopes:['Office Manager','Basic User'] }
  *  - specific users:                  { users: ['100@acme','101@acme'] }
+ *  - a scope MINUS a few accounts:    { scopes:['Reseller'], notUsers:['105@acme'] }
  *  - only when a given operator is masked in: { operators: ['admin@0000.12345.service'] }
  *  - only while (not) masking:        { masking: true }  /  { masking: false }
  *
+ * `notUsers` is the one NEGATIVE condition, and it exists because the positive form cannot express
+ * "everyone at this scope except these accounts" without enumerating the complement — a list that is
+ * wrong the moment an account is added, and wrong silently. It ANDs with the rest of the rule like
+ * every other condition, so it narrows the rule it sits on and nothing else.
+ *
  * Matching considers the EFFECTIVE principal (scope/domain/id = the masked user when masking);
  * `operators` matches the mask_chain operator, so you can gate on the real reseller behind a mask.
  *
@@ -29,6 +35,16 @@ export interface PolicyRule {
     domains?: string[];
     /** Effective identity (`user@domain`) must be one of these. */
     users?: string[];
+    /**
+     * Effective identity (`user@domain`) must NOT be one of these — a denial that ANDs with the rest of
+     * the rule, narrowing it.
+     *
+     * ⚠️ It is NOT a condition on its own. A rule carrying only `notUsers` never matches, deliberately:
+     * "everybody except X" as a standalone rule would be an allow-all wearing an exception, and this
+     * engine's whole shape is that a rule must say who it admits before it says who it doesn't. Pair it
+     * with `scopes`/`domains`/`users` — see `hasCondition` in {@link ruleMatches}.
+     */
+    notUsers?: string[];
     /** Requires masking, AND the operator's `user@domain` (mask_chain) is one of these. */
     operators?: string[];
     /** Require the masking state to equal this (true = masked, false = not masked). */

package/dist/policy.js

@@ -20,6 +20,8 @@ const scopeInList = (value, list) => {
 export function ruleMatches(p, rule) {
     // A rule with NO matchable condition (e.g. `{}` or only `description`) is NOT allow-all — that would
     // silently grant everyone. Require at least one real condition; a conditionless rule never matches.
+    // `notUsers` is deliberately absent from this list: it subtracts, so counting it would let
+    // `{notUsers:[…]}` mean "everyone else", which is the allow-all this guard exists to prevent.
     const hasCondition = rule.scopes !== undefined ||
         rule.domains !== undefined ||
         rule.users !== undefined ||
@@ -33,6 +35,8 @@ export function ruleMatches(p, rule) {
         return false;
     if (rule.users && !inList(p.id, rule.users))
         return false;
+    if (rule.notUsers && inList(p.id, rule.notUsers))
+        return false;
     if (rule.operators) {
         if (!p.operator || !inList(p.operator.id, rule.operators))
             return false;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.6",
-  "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.",
+  "version": "0.1.8",
+  "description": "Portable, Node-free NetSapiens toolkit: split read/write API clients, 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",
   "author": {
@@ -55,11 +55,12 @@
     "build:watch": "tsc -p tsconfig.json --watch",
     "//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 \u2014 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 && pnpm run test:eligibility && pnpm run test:nsauth && pnpm test:nssubs && pnpm test:nsdevice",
+    "//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 && pnpm run test:nssync && pnpm run test:eligibility && pnpm run test:nsauth && pnpm test:nssubs && pnpm test:nsdevice",
     "test:jwt": "tsx src/jwt.selftest.ts",
     "test:ns": "tsx src/nsClient.selftest.ts",
     "test:nswrite": "tsx src/nsWriteClient.selftest.ts",
+    "test:nssync": "tsx src/nsSynchronous.selftest.ts",
     "test:nsauth": "tsx src/nsAuthClient.selftest.ts",
     "test:principal": "tsx src/principal.selftest.ts",
     "test:resolver": "tsx src/resolver.selftest.ts",