@dszp/netsapiens-lib 0.1.7 → 0.1.9

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,22 @@ export interface PolicyRule {
     domains?: string[];
     /** Effective identity (`user@domain`) must be one of these. */
     users?: string[];
+    /**
+     * Accounts this rule EXCLUDES — 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}.
+     *
+     * ⚠️ **It matches the effective identity OR the operator behind a mask** — the one place this engine
+     * is deliberately asymmetric. Every positive condition sees the EFFECTIVE principal, so a grant
+     * follows the role currently being performed; masquerading is full impersonation and is meant to be.
+     * A denial is not about a role. It names a person, and a denial that evaporates the moment that
+     * person masquerades into someone else is not a denial — it is a suggestion. So this one condition
+     * asks both "who is acting" and "who is behind this", and refuses if either is named.
+     */
+    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,10 @@ export function ruleMatches(p, rule) {
         return false;
     if (rule.users && !inList(p.id, rule.users))
         return false;
+    // Both identities, unlike every positive condition above — see the field's own note. A grant follows
+    // the role being performed; a denial follows the person performing it, through a mask.
+    if (rule.notUsers && (inList(p.id, rule.notUsers) || (p.operator && inList(p.operator.id, rule.notUsers))))
+        return false;
     if (rule.operators) {
         if (!p.operator || !inList(p.operator.id, rule.operators))
             return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dszp/netsapiens-lib",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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",
@@ -55,7 +55,7 @@
     "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": "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",