@dszp/netsapiens-lib 0.1.8 → 0.3.0

package/src/nsSynchronous.selftest.ts

@@ -0,0 +1,63 @@
+/**
+ * Offline test for the `synchronous` capability table — that concrete, URI-encoded paths match the
+ * templated operations, that the near-misses (user update, device update) answer false, and that the
+ * table itself stays consistent. tsx src/nsSynchronous.selftest.ts
+ */
+import { supportsSynchronous, SYNCHRONOUS_OPERATIONS } from './index.js';
+
+let pass = 0, fail = 0;
+const ok = (c: boolean, m: string) => { c ? pass++ : fail++; console.log(`${c ? '✓' : '✗ FAIL'} ${m}`); };
+
+// ── supported operations ──────────────────────────────────────────────────────
+ok(supportsSynchronous('POST', '/domains'), 'POST /domains (domain create) is supported');
+ok(supportsSynchronous('POST', '/domains/acme.example/users'), 'POST users (user CREATE) is supported');
+ok(supportsSynchronous('POST', '/domains/acme.example/users/100/devices'), 'POST devices (device create) is supported');
+ok(supportsSynchronous('PUT', '/domains/acme.example/sites/HQ'), 'PUT sites is supported (one of the few PUTs)');
+ok(supportsSynchronous('PUT', '/domains/acme.example/users/100/greetings/1'), 'PUT greetings/{index} is supported');
+ok(supportsSynchronous('PUT', '/domains/acme.example/moh/2'), 'PUT domain moh/{index} is supported');
+
+// ── the near-misses that motivate an explicit table ───────────────────────────
+ok(!supportsSynchronous('PUT', '/domains/acme.example/users/100'), 'PUT user (UPDATE) is NOT supported — the case that started this');
+ok(!supportsSynchronous('PUT', '/domains/acme.example/users/100/devices/100r'), 'PUT device (update) is NOT supported');
+ok(!supportsSynchronous('DELETE', '/domains/acme.example/users/100'), 'DELETE is never supported');
+ok(!supportsSynchronous('GET', '/domains/acme.example/users'), 'GET is never supported');
+ok(!supportsSynchronous('POST', '/domains/acme.example/phonenumbers'), 'an unlisted POST is not supported');
+
+// ── path-shape handling ───────────────────────────────────────────────────────
+ok(supportsSynchronous('post', '/domains/acme.example/users'), 'method is case-insensitive');
+ok(!supportsSynchronous('POST', '/domains/acme.example/users/100'), 'segment COUNT must match — collection vs member');
+ok(!supportsSynchronous('POST', '/domains/acme.example/users/100/devices/extra'), 'a deeper path does not match a shorter template');
+ok(supportsSynchronous('POST', '/domains/acme.example/users?foo=bar'), 'a query string is ignored');
+ok(supportsSynchronous('POST', '/domains/acme.example/users/'), 'a trailing slash is ignored');
+
+// An encoded value stays ONE segment, so it cannot masquerade as a deeper path.
+ok(
+  supportsSynchronous('POST', `/domains/${encodeURIComponent('a/b.example')}/users`),
+  'an encoded slash inside a segment still matches the single-segment template',
+);
+ok(
+  !supportsSynchronous('POST', '/domains/a/b.example/users'),
+  'an UNencoded slash does not match — extra segment, correctly rejected',
+);
+
+// ── table integrity ───────────────────────────────────────────────────────────
+ok(SYNCHRONOUS_OPERATIONS.length === 17, `table holds all 17 spec operations (got ${SYNCHRONOUS_OPERATIONS.length})`);
+ok(
+  SYNCHRONOUS_OPERATIONS.every((op) => op.method === 'POST' || op.method === 'PUT'),
+  'every entry is a POST or PUT',
+);
+ok(
+  SYNCHRONOUS_OPERATIONS.every((op) => op.path.startsWith('/')),
+  'every path is rooted (relative to the /ns-api/v2 base)',
+);
+ok(
+  new Set(SYNCHRONOUS_OPERATIONS.map((op) => `${op.method} ${op.path}`)).size === SYNCHRONOUS_OPERATIONS.length,
+  'no duplicate (method, path) entries',
+);
+ok(
+  SYNCHRONOUS_OPERATIONS.every((op) => supportsSynchronous(op.method, op.path.replace(/\{[^}]+\}/g, 'x'))),
+  'every table entry matches its own path with the templates filled in',
+);
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/src/nsSynchronous.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 const SYNCHRONOUS_OPERATIONS: readonly SynchronousOperation[] = [
+  { 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' },
+] as const;
+
+/** Split a path into non-empty segments, ignoring any query string and leading/trailing slashes. */
+const segmentsOf = (path: string): string[] => (path.split('?')[0] ?? '').split('/').filter(Boolean);
+
+/** Precomputed segment forms, so a lookup is a comparison rather than a re-parse per call. */
+const TABLE: ReadonlyArray<{ method: SynchronousMethod; segments: readonly string[] }> =
+  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: string, path: string): boolean {
+  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/src/nsWriteClient.selftest.ts

@@ -0,0 +1,104 @@
+/**
+ * Offline test for NsWriteClient — device create/get/delete against a recording mock fetch (no live
+ * creds). Asserts the exact v2 paths, methods, bodies (incl. where synchronous:'yes' is and is NOT
+ * injected — see nsSynchronous.ts), auth header, URI
+ * encoding, the inline created-device return (with its generated SIP password), error shape, and the
+ * bare-server SSRF guard. tsx src/nsWriteClient.selftest.ts
+ */
+import { NsWriteClient } from './index.js';
+import { NsApiError } from './nsClient.js';
+
+let pass = 0, fail = 0;
+const ok = (c: boolean, m: string) => { c ? pass++ : fail++; console.log(`${c ? '✓' : '✗ FAIL'} ${m}`); };
+
+interface Recorded { method: string; url: string; headers: Record<string, string>; body?: any }
+let last: Recorded = { method: '', url: '', headers: {} };
+const mk = (status: number, body: unknown) =>
+  (async (input: any, init: any = {}) => {
+    last = {
+      method: init.method ?? 'GET',
+      url: String(input),
+      headers: (init.headers ?? {}) as Record<string, string>,
+      body: init.body ? JSON.parse(init.body) : undefined,
+    };
+    return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+  }) as unknown as typeof fetch;
+
+const client = (status = 200, body: unknown = {}) =>
+  new NsWriteClient({ server: 'api.example.com', token: 'tok', fetchImpl: mk(status, body) });
+
+const B = 'https://api.example.com/ns-api/v2';
+
+(async () => {
+  // createDevice → POST .../devices with { device, synchronous:'yes' }, returns the created device inline.
+  const created = await client(200, { device: '100r', 'device-sip-registration-password': 'SEKRET1234567890' })
+    .createDevice('acme.example', '100', '100r');
+  ok(last.method === 'POST', 'createDevice uses POST');
+  ok(last.url === `${B}/domains/acme.example/users/100/devices`, 'createDevice hits the devices collection path');
+  ok(last.body?.device === '100r', 'createDevice body carries the device id');
+  ok(last.body?.synchronous === 'yes', 'createDevice injects synchronous:yes (200 + inline resource, no 202 lag)');
+  ok(last.headers.Authorization === 'Bearer tok', 'createDevice sends bearer auth');
+  ok((created as any)['device-sip-registration-password'] === 'SEKRET1234567890', 'createDevice returns the inline device incl. the generated SIP password');
+
+  // getDevices → GET .../devices (returns an array even for a single object)
+  const list = await client(200, { device: '100r' }).getDevices('acme.example', '100');
+  ok(last.method === 'GET' && last.url === `${B}/domains/acme.example/users/100/devices`, 'getDevices GETs the collection');
+  ok(Array.isArray(list) && (list[0] as any).device === '100r', 'getDevices normalizes a single object to an array');
+
+  // getDevice → GET .../devices/{device}
+  await client(200, { device: '100r' }).getDevice('acme.example', '100', '100r');
+  ok(last.method === 'GET' && last.url === `${B}/domains/acme.example/users/100/devices/100r`, 'getDevice GETs the specific device');
+
+  // deleteDevice → DELETE .../devices/{device}
+  await client(200, {}).deleteDevice('acme.example', '100', '100r');
+  ok(last.method === 'DELETE' && last.url === `${B}/domains/acme.example/users/100/devices/100r`, 'deleteDevice DELETEs the specific device');
+  ok(last.body === undefined, 'deleteDevice sends no body');
+
+  // Path params are URI-encoded.
+  await client(200, []).getDevices('a b.example', '10@0');
+  ok(last.url === `${B}/domains/a%20b.example/users/10%400/devices`, 'path params are URI-encoded');
+
+  // A non-2xx write throws NsApiError carrying status + method.
+  let err: any;
+  try { await client(403, { message: 'nope' }).createDevice('acme.example', '100', '100r'); } catch (e) { err = e; }
+  ok(err instanceof NsApiError && err.status === 403 && err.method === 'POST', 'a non-ok write throws NsApiError with status + method');
+
+  // Bare-server SSRF guard (reused from the read client).
+  let guarded = false;
+  try { new NsWriteClient({ server: 'api.example.com@evil.example', token: 't' }); } catch { guarded = true; }
+  ok(guarded, 'NsWriteClient rejects a non-bare server (SSRF guard)');
+
+
+  // updateDevice → PUT the specific device path, rotating one field in place.
+  await client(200, { device: '100r' }).updateDevice('acme.example', '100', '100r', {
+    'device-sip-registration-password': 'NEWPASSWORD123456',
+  });
+  ok(last.method === 'PUT', 'updateDevice uses PUT');
+  ok(last.url === `${B}/domains/acme.example/users/100/devices/100r`, 'updateDevice hits the specific device path');
+  ok(last.body?.['device-sip-registration-password'] === 'NEWPASSWORD123456', 'updateDevice sends the rotated password');
+  // PUT .../devices/{device} is NOT one of the operations that accept `synchronous`, so the flag is
+  // omitted rather than sent-and-ignored. ensureNsDevice already falls back to the value it sent.
+  ok(!('synchronous' in (last.body ?? {})), 'updateDevice does NOT inject synchronous — device update does not accept it');
+  ok(!('device' in (last.body ?? {})), 'updateDevice does not resend the device id in the body — it is in the path');
+  {
+    // The point of PUT over delete+create: nothing else on the device is touched.
+    await client(200, {}).updateDevice('acme.example', '100', '100r', { 'device-sip-registration-password': 'X' });
+    const keys = Object.keys(last.body ?? {});
+    ok(keys.length === 1 && keys[0] === 'device-sip-registration-password', 'only the named field is sent, so unrelated device settings survive');
+  }
+  {
+    let threw = 0;
+    try {
+      await client(404, { code: 404, message: 'No Route Found' }).updateDevice('acme.example', '100', '100r', { x: 1 });
+    } catch (e: any) {
+      threw = e.status;
+    }
+    ok(threw === 404, 'a 404 (endpoint absent on the release) surfaces as NsApiError so a caller can fall back');
+  }
+  ok(encodeURIComponent('a/b') === 'a%2Fb', 'sanity: path params are encoded by enc()');
+  await client(200, {}).updateDevice('acme.example', '10/0', '10/0r', {});
+  ok(last.url.includes('10%2F0'), 'updateDevice percent-encodes the user and device path segments');
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})();

package/src/nsWriteClient.ts

@@ -0,0 +1,157 @@
+/**
+ * Portable NetSapiens API v2 WRITE client — the separate, explicitly-imported write surface the read-only
+ * `NsClient` deliberately does not have (a consumer holds `NsClient` precisely to know it cannot write).
+ * This realizes the lib's planned split: read and write are two classes; only this one mutates. Node-free
+ * (fetch/URL/crypto only), so it runs unchanged in a Cloudflare Worker.
+ *
+ * Starts with the device methods the portal's Ringotel activation needs (create/get/delete), over a
+ * 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.
+ *
+ * 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 { NsApiError, assertBareServer, asArray } from './nsClient.js';
+import { ensureNsDevice, type EnsureNsDeviceOptions, type EnsureNsDeviceResult } from './nsDevice.js';
+import { supportsSynchronous } from './nsSynchronous.js';
+
+export interface NsWriteClientConfig {
+  /** API host, e.g. "api.example.com". Base URL becomes https://{server}/ns-api/v2. */
+  server: string;
+  /** Bearer token (an API key with write scope). */
+  token: string;
+  /** Injectable for tests / non-global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+const enc = encodeURIComponent;
+
+export class NsWriteClient {
+  readonly #baseUrl: string;
+  readonly #token: string;
+  readonly #fetchImpl: typeof fetch;
+
+  constructor(cfg: NsWriteClientConfig) {
+    this.#baseUrl = `https://${assertBareServer(cfg.server)}/ns-api/v2`;
+    this.#token = cfg.token;
+    this.#fetchImpl = cfg.fetchImpl ?? fetch;
+  }
+
+  // ── generic verbs (the growth surface) ──────────────────────────────────────
+  get<T = unknown>(path: string, query?: Record<string, string | number>): Promise<T> {
+    return this.#request<T>('GET', path, undefined, query);
+  }
+  /**
+   * 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> {
+    return this.#request<T>('POST', path, this.#withSynchronous('POST', path, body));
+  }
+  /**
+   * 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> {
+    return this.#request<T>('PUT', path, this.#withSynchronous('PUT', path, body));
+  }
+
+  /** Add `synchronous:'yes'` only where the API declares support. An explicit caller value wins. */
+  #withSynchronous(method: string, path: string, body: Rec): Rec {
+    if (!supportsSynchronous(method, path)) return body;
+    return { synchronous: 'yes', ...body };
+  }
+  delete<T = unknown>(path: string): Promise<T> {
+    return this.#request<T>('DELETE', path);
+  }
+
+  // ── typed device helpers ────────────────────────────────────────────────────
+  /** List a user's devices (normalized to an array). */
+  getDevices(domain: string, user: string): Promise<Rec[]> {
+    return this.get<unknown>(`/domains/${enc(domain)}/users/${enc(user)}/devices`).then(asArray);
+  }
+  /** Read one device (e.g. to fetch its `device-sip-registration-password`). */
+  getDevice(domain: string, user: string, device: string): Promise<Rec> {
+    return this.get<Rec>(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`);
+  }
+  /**
+   * Create a device (softphone when named `<ext><suffix>`, e.g. `100r`). NS auto-generates the SIP
+   * password when unset; with `synchronous:'yes'` it comes back inline in the response. `extra` allows
+   * optional fields (e.g. an emergency caller-id).
+   */
+  createDevice(domain: string, user: string, device: string, extra: Rec = {}): Promise<Rec> {
+    return this.post<Rec>(`/domains/${enc(domain)}/users/${enc(user)}/devices`, { device, ...extra });
+  }
+  /**
+   * 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
+   * transport settings. A PUT changes the one field and preserves the rest.
+   */
+  updateDevice(domain: string, user: string, device: string, changes: Rec): Promise<Rec> {
+    return this.put<Rec>(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`, changes);
+  }
+
+  /** Delete a device. */
+  deleteDevice(domain: string, user: string, device: string): Promise<Rec> {
+    return this.delete<Rec>(`/domains/${enc(domain)}/users/${enc(user)}/devices/${enc(device)}`);
+  }
+
+  /**
+   * Convenience wrapper over {@link ensureNsDevice} — ensure a device exists and return its SIP password,
+   * optionally rotating it. See that function for the semantics, and for why rotation matters.
+   *
+   * Deliberately a **one-line delegation, not an implementation**. Every other method on this class is
+   * exactly one HTTP request; this one is several with branching, so the logic lives in a standalone
+   * function that composes over any writer (a consumer may have its own client) and that consumers can mock as
+   * a plain 4-method object instead of stubbing a whole client. This method exists only so the capability
+   * is discoverable from the client you already hold.
+   */
+  ensureDevice(opts: EnsureNsDeviceOptions): Promise<EnsureNsDeviceResult> {
+    return ensureNsDevice(this, opts);
+  }
+
+  async #request<T>(method: string, path: string, body?: Rec, query?: Record<string, string | number>): Promise<T> {
+    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
+    // instance throws "Illegal invocation" in workerd (the global fetch requires a global `this`).
+    const doFetch = this.#fetchImpl;
+    const res = await doFetch(url.toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.#token}`,
+        Accept: 'application/json',
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        /* some endpoints return empty / plain bodies */
+      }
+    }
+    if (!res.ok) {
+      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(`${method} ${path} → ${res.status}${hint}: ${detail}`, res.status, path, parsed, method);
+    }
+    return parsed as T;
+  }
+}

package/src/policy.ts

@@ -0,0 +1,123 @@
+/**
+ * A small, declarative allow-list policy engine over `Principal` — the extensible knob for gating
+ * features by who's asking. Designed so new gates are one object, not new code.
+ *
+ * A `Policy` is a list of `PolicyRule`s; a principal is granted the feature if **any** rule matches
+ * (default DENY — an empty policy or an unknown feature denies). Within a rule, every specified
+ * condition must hold (AND); an omitted condition is a wildcard. All string comparisons are
+ * case-insensitive.
+ *
+ * Conditions, and the shapes they're meant to express:
+ *  - by scope, per-domain:            { scopes: ['Office Manager'] }            // + domain-locked elsewhere
+ *  - one reseller vs all resellers:   { scopes:['Reseller'], users:['admin@0000.12345.service'] }  vs  { scopes:['Reseller'] }
+ *  - 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.
+ *
+ * Portable (no Node). Pure functions.
+ */
+import type { Principal } from './principal.js';
+
+export interface PolicyRule {
+  /** Effective scope must be one of these (case-insensitive). */
+  scopes?: string[];
+  /** Effective domain must be one of these. Use '*' to match any domain. */
+  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). */
+  masking?: boolean;
+  /** Optional human note (documentation / audit; ignored by matching). */
+  description?: string;
+}
+
+/** ANY rule matching grants the feature; `[]` denies. */
+export type Policy = PolicyRule[];
+
+/** Named features → their policy. Unknown feature ⇒ deny (see `can`). */
+export type FeaturePolicies = Record<string, Policy>;
+
+const lc = (s: string) => s.trim().toLowerCase();
+const inList = (value: string, list: string[]): boolean => {
+  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: string): string => {
+  const v = lc(s);
+  return v === 'superuser' || v === 'super-user' || v === 'super user' ? 'super user' : v;
+};
+const scopeInList = (value: string, list: string[]): boolean => {
+  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: Principal, rule: PolicyRule): boolean {
+  // 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 ||
+    rule.operators !== undefined ||
+    rule.masking !== undefined;
+  if (!hasCondition) return false;
+  if (rule.scopes && !scopeInList(p.scope, rule.scopes)) return false;
+  if (rule.domains && !(rule.domains.includes('*') || inList(p.domain, rule.domains))) 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;
+  }
+  if (rule.masking !== undefined && p.masking !== rule.masking) return false;
+  return true;
+}
+
+/** Allowed if any rule matches. Empty/absent policy ⇒ deny (fail closed). */
+export function isAllowed(p: Principal, policy: Policy | undefined): boolean {
+  return !!policy && policy.some((rule) => ruleMatches(p, rule));
+}
+
+/** Check a named feature against a registry. Unknown feature ⇒ deny (fail closed). */
+export function can(p: Principal, feature: string, policies: FeaturePolicies): boolean {
+  return isAllowed(p, policies[feature]);
+}