@sonisoft/now-sdk-ext-core 6.0.0 → 6.2.0

package/dist/policy/PolicyEnv.d.ts

@@ -0,0 +1,46 @@
+import { PolicyLayer, Verb } from "./PolicyTypes.js";
+/**
+ * Environment-variable policy layers.
+ *
+ * `NEX_POLICY_DENY` sits at the top of the ladder and cannot be granted past.
+ * `NEX_POLICY_ALLOW` sits near the bottom and exists for backward compatibility, so an
+ * existing CI job can restore its previous behaviour with one variable rather than
+ * editing every command line.
+ *
+ * Named `NEX_POLICY_*` rather than `NEX_ALLOW_WRITE` because `write` and `execute`
+ * collide with ServiceNow ACL vocabulary, and a reader should not have to work out
+ * whether this is about ACLs.
+ */
+export declare const DENY_ENV = "NEX_POLICY_DENY";
+export declare const ALLOW_ENV = "NEX_POLICY_ALLOW";
+export interface ParsedVerbs {
+    readonly verbs: readonly Verb[];
+    /** Tokens that were not recognised. Non-empty means the value was malformed. */
+    readonly unknown: readonly string[];
+}
+/**
+ * Parses a comma-separated verb list.
+ *
+ * `all` expands to every verb. Unrecognised tokens are REPORTED rather than dropped, so
+ * the caller can fail closed — see `denyFromEnvironment`.
+ */
+export declare function parseVerbList(raw: string | undefined): ParsedVerbs;
+/**
+ * The deny layer, built from `NEX_POLICY_DENY`.
+ *
+ * FAILS CLOSED on a malformed value. `NEX_POLICY_DENY=wrtie` denies everything and
+ * warns, rather than silently denying nothing — a typo in the variable that is supposed
+ * to protect production must not quietly disable the protection. That is the whole
+ * reason this function reports `unknown` instead of filtering it away.
+ *
+ * Returns `undefined` when the variable is unset, so the layer is simply absent.
+ */
+export declare function denyFromEnvironment(env?: NodeJS.ProcessEnv, warn?: (message: string) => void): PolicyLayer | undefined;
+/**
+ * The backward-compatibility grant layer, built from `NEX_POLICY_ALLOW`.
+ *
+ * Unrecognised tokens here are dropped with a warning rather than failing closed: this
+ * variable only ever *grants*, so a typo already fails safe — the operation is refused
+ * and the operator sees why.
+ */
+export declare function allowFromEnvironment(env?: NodeJS.ProcessEnv, warn?: (message: string) => void): PolicyLayer | undefined;

package/dist/policy/PolicyEnv.js

@@ -0,0 +1,92 @@
+import { denyLayer, grantLayer } from "./Policy.js";
+/**
+ * Environment-variable policy layers.
+ *
+ * `NEX_POLICY_DENY` sits at the top of the ladder and cannot be granted past.
+ * `NEX_POLICY_ALLOW` sits near the bottom and exists for backward compatibility, so an
+ * existing CI job can restore its previous behaviour with one variable rather than
+ * editing every command line.
+ *
+ * Named `NEX_POLICY_*` rather than `NEX_ALLOW_WRITE` because `write` and `execute`
+ * collide with ServiceNow ACL vocabulary, and a reader should not have to work out
+ * whether this is about ACLs.
+ */
+export const DENY_ENV = "NEX_POLICY_DENY";
+export const ALLOW_ENV = "NEX_POLICY_ALLOW";
+const ALL = "all";
+const VALID = ["write", "execute"];
+/**
+ * Parses a comma-separated verb list.
+ *
+ * `all` expands to every verb. Unrecognised tokens are REPORTED rather than dropped, so
+ * the caller can fail closed — see `denyFromEnvironment`.
+ */
+export function parseVerbList(raw) {
+    if (raw === undefined) {
+        return { verbs: [], unknown: [] };
+    }
+    const tokens = raw
+        .split(",")
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t.length > 0);
+    if (tokens.includes(ALL)) {
+        return { verbs: [...VALID], unknown: [] };
+    }
+    const verbs = [];
+    const unknown = [];
+    for (const token of tokens) {
+        if (VALID.includes(token)) {
+            verbs.push(token);
+        }
+        else {
+            unknown.push(token);
+        }
+    }
+    return { verbs, unknown };
+}
+/**
+ * The deny layer, built from `NEX_POLICY_DENY`.
+ *
+ * FAILS CLOSED on a malformed value. `NEX_POLICY_DENY=wrtie` denies everything and
+ * warns, rather than silently denying nothing — a typo in the variable that is supposed
+ * to protect production must not quietly disable the protection. That is the whole
+ * reason this function reports `unknown` instead of filtering it away.
+ *
+ * Returns `undefined` when the variable is unset, so the layer is simply absent.
+ */
+export function denyFromEnvironment(env = process.env, warn = () => undefined) {
+    const raw = env[DENY_ENV];
+    if (raw === undefined || raw.trim().length === 0) {
+        return undefined;
+    }
+    const { verbs, unknown } = parseVerbList(raw);
+    if (unknown.length > 0) {
+        warn(`${DENY_ENV} contains unrecognised value(s): ${unknown.join(", ")}. ` +
+            `Denying all changes. Valid values are: ${VALID.join(", ")}, all.`);
+        return denyLayer(`${DENY_ENV} (malformed, failing closed)`, VALID);
+    }
+    return denyLayer(DENY_ENV, verbs);
+}
+/**
+ * The backward-compatibility grant layer, built from `NEX_POLICY_ALLOW`.
+ *
+ * Unrecognised tokens here are dropped with a warning rather than failing closed: this
+ * variable only ever *grants*, so a typo already fails safe — the operation is refused
+ * and the operator sees why.
+ */
+export function allowFromEnvironment(env = process.env, warn = () => undefined) {
+    const raw = env[ALLOW_ENV];
+    if (raw === undefined || raw.trim().length === 0) {
+        return undefined;
+    }
+    const { verbs, unknown } = parseVerbList(raw);
+    if (unknown.length > 0) {
+        warn(`${ALLOW_ENV} contains unrecognised value(s): ${unknown.join(", ")}, ignored. ` +
+            `Valid values are: ${VALID.join(", ")}, all.`);
+    }
+    if (verbs.length === 0) {
+        return undefined;
+    }
+    return grantLayer(ALLOW_ENV, verbs);
+}
+//# sourceMappingURL=PolicyEnv.js.map

package/dist/policy/PolicyEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyEnv.js","sourceRoot":"","sources":["../../src/policy/PolicyEnv.ts"],"names":[],"mappings":"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"}

package/dist/policy/PolicyRefusal.d.ts

@@ -0,0 +1,17 @@
+import { Decision, Verb } from "./PolicyTypes.js";
+export interface PolicyRefusalError extends Error {
+    readonly decision: Decision;
+}
+/** True when `value` is a refusal thrown by ANY copy of this library. */
+export declare function isPolicyRefusal(value: unknown): value is PolicyRefusalError;
+/**
+ * Builds the error thrown when an operation is refused.
+ *
+ * The message states what was needed and what to do about it. It deliberately does NOT
+ * name an MCP tool parameter: on that surface the caller is the model, and a refusal
+ * that advertises its own escape hatch just teaches the model to set it and retry.
+ * The CLI remediation names its flags, because there a human typed the command.
+ */
+export declare function policyRefusal(decision: Decision): PolicyRefusalError;
+/** Convenience for the common single-verb refusal. */
+export declare function refusalFor(verb: Verb, decidingLayer: string, remediation?: string): PolicyRefusalError;

package/dist/policy/PolicyRefusal.js

@@ -0,0 +1,69 @@
+/**
+ * Marks an error as a policy refusal.
+ *
+ * `Symbol.for`, not a class and not `instanceof`. This package is published, and a
+ * consumer can easily end up with two copies in `node_modules` — a transitive
+ * dependency on an older major, a pruned install, a bundler that duplicated it. With a
+ * class, `instanceof` then returns false for an error thrown by the *other* copy, and
+ * the failure is silent: `BackgroundScriptExecutor.executeScriptAuto` would stop
+ * recognising a refusal and fall back to `sys_trigger`, executing the very script that
+ * was just refused.
+ *
+ * The registry symbol is global to the process, so it identifies correctly across
+ * copies. This repo already carries the dual-copy exposure with `StaleInstanceError`
+ * (see `RequestHandler.toThrowable`, which goes out of its way to preserve identity);
+ * this is that lesson applied rather than repeated.
+ */
+const POLICY_REFUSAL = Symbol.for("now-sdk-ext.policy-refusal");
+/** True when `value` is a refusal thrown by ANY copy of this library. */
+export function isPolicyRefusal(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return value[POLICY_REFUSAL] === true;
+}
+/**
+ * Builds the error thrown when an operation is refused.
+ *
+ * The message states what was needed and what to do about it. It deliberately does NOT
+ * name an MCP tool parameter: on that surface the caller is the model, and a refusal
+ * that advertises its own escape hatch just teaches the model to set it and retry.
+ * The CLI remediation names its flags, because there a human typed the command.
+ */
+export function policyRefusal(decision) {
+    const verbs = decision.verbs.join(" and ");
+    const detail = decision.remediation
+        ? `${decision.remediation}`
+        : `This operation requires ${verbs} permission, which has not been granted.`;
+    const error = new Error(detail);
+    error.name = "PolicyRefusalError";
+    error[POLICY_REFUSAL] = true;
+    // Non-enumerable AND writable, both load-bearing.
+    //
+    // `stripSecretsFromError` walks `Object.keys(err)` and reassigns every object-valued
+    // child through the redactor. An enumerable, non-writable `decision` made that throw
+    // `Cannot assign to read only property 'decision'` — which replaced the refusal with
+    // a TypeError on the way out, so callers saw a crash instead of a refusal and
+    // `isPolicyRefusal` returned false. Found by the live integration run, not by any
+    // unit test, because nothing in isolation puts a refusal through the redactor.
+    //
+    // Non-enumerable also keeps it out of JSON.stringify and out of log serialisation,
+    // which is where it would otherwise show up as noise.
+    Object.defineProperty(error, "decision", {
+        value: decision,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return error;
+}
+/** Convenience for the common single-verb refusal. */
+export function refusalFor(verb, decidingLayer, remediation) {
+    return policyRefusal({
+        allowed: false,
+        verbs: [verb],
+        decidingLayer,
+        remediation,
+    });
+}
+//# sourceMappingURL=PolicyRefusal.js.map

package/dist/policy/PolicyRefusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyRefusal.js","sourceRoot":"","sources":["../../src/policy/PolicyRefusal.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAMhE,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,OAAQ,KAAiC,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW;QAC/B,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE;QAC3B,CAAC,CAAC,2BAA2B,KAAK,0CAA0C,CAAC;IAEjF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAiD,CAAC;IAChF,KAAK,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,KAAK,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;IAC7B,kDAAkD;IAClD,EAAE;IACF,qFAAqF;IACrF,qFAAqF;IACrF,qFAAqF;IACrF,8EAA8E;IAC9E,kFAAkF;IAClF,+EAA+E;IAC/E,EAAE;IACF,mFAAmF;IACnF,sDAAsD;IACtD,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE;QACrC,KAAK,EAAE,QAAQ;QACf,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;KACrB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,IAAU,EAAE,aAAqB,EAAE,WAAoB;IAC9E,OAAO,aAAa,CAAC;QACjB,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,CAAC,IAAI,CAAC;QACb,aAAa;QACb,WAAW;KACd,CAAC,CAAC;AACP,CAAC"}

package/dist/policy/PolicyTypes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Vocabulary for gating instance mutations.
+ *
+ * This is a GUARDRAIL, not a security boundary. Anything holding the credential can
+ * reach the instance directly — by importing this library and calling the SDK, or with
+ * curl. What it buys is that *inadvertent* mutation stops being the default when an AI
+ * agent is driving, and that an operator can hard-deny from an environment the agent
+ * cannot write to. Do not describe it as anything stronger.
+ */
+/**
+ * What an operation does. Two verbs, deliberately.
+ *
+ * CRUD was considered and rejected: `nex exec`, ATF runs and flow execution all mutate
+ * without being create, edit or delete, so a CRUD vocabulary leaves them homeless.
+ */
+export type Verb = "write" | "execute";
+/**
+ * WHERE the effect lands. Not every write is a write to the instance.
+ *
+ * `pull_script` overwrites a local file, `scope set` changes session state, and the
+ * `auth` commands write the credential store. Gating those as instance writes would
+ * produce false refusals on operations that never touch ServiceNow data, so the target
+ * is carried alongside the verb rather than inventing more verbs.
+ *
+ * Only `instance` is gated today; the rest exist so the distinction is recorded at the
+ * call site rather than rediscovered later.
+ */
+export type Target = "instance" | "local" | "session";
+/** What an operation needs before it may proceed. */
+export interface Requirement {
+    readonly verbs: readonly Verb[];
+    readonly target: Target;
+}
+/** A requirement that needs no permission at all. */
+export declare const READ_ONLY: Requirement;
+/**
+ * A layer's answer.
+ *
+ * `abstain` is distinct from `deny` on purpose — it means "I have no opinion", so a
+ * lower-priority layer still gets to speak. Collapsing the two would make an unset
+ * environment variable behave like an explicit denial.
+ */
+export type LayerAnswer = "grant" | "deny" | "abstain";
+/** One rung of the precedence ladder. */
+export interface PolicyLayer {
+    /** Appears in refusals and the audit log, so make it recognisable to an operator. */
+    readonly name: string;
+    answer(verb: Verb): LayerAnswer;
+}
+/**
+ * The result of a check.
+ *
+ * An object rather than a boolean so the deciding layer can be reported — "why was this
+ * refused" is otherwise unanswerable — and so a future `ApprovalToken` (NEX-76) can be
+ * added as a grant layer without changing this signature.
+ */
+export interface Decision {
+    readonly allowed: boolean;
+    /** The verbs actually required. Empty means the operation needed no permission. */
+    readonly verbs: readonly Verb[];
+    /** Name of the layer that decided. `"default"` when nothing granted. */
+    readonly decidingLayer: string;
+    /** Present only when refused. Written for a human, never naming an MCP parameter. */
+    readonly remediation?: string;
+}

package/dist/policy/PolicyTypes.js

@@ -0,0 +1,15 @@
+/**
+ * Vocabulary for gating instance mutations.
+ *
+ * This is a GUARDRAIL, not a security boundary. Anything holding the credential can
+ * reach the instance directly — by importing this library and calling the SDK, or with
+ * curl. What it buys is that *inadvertent* mutation stops being the default when an AI
+ * agent is driving, and that an operator can hard-deny from an environment the agent
+ * cannot write to. Do not describe it as anything stronger.
+ */
+/** A requirement that needs no permission at all. */
+export const READ_ONLY = Object.freeze({
+    verbs: Object.freeze([]),
+    target: "instance",
+});
+//# sourceMappingURL=PolicyTypes.js.map

package/dist/policy/PolicyTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyTypes.js","sourceRoot":"","sources":["../../src/policy/PolicyTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6BH,qDAAqD;AACrD,MAAM,CAAC,MAAM,SAAS,GAAgB,MAAM,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAoB;IAC3C,MAAM,EAAE,UAAU;CACrB,CAAC,CAAC"}

package/dist/policy/ScanScript.d.ts

@@ -0,0 +1,22 @@
+import { Verb } from "./PolicyTypes.js";
+export interface ScriptScanResult {
+    /** Verbs the script needs BEYOND `execute`. Today this is `["write"]` or `[]`. */
+    readonly verbs: readonly Verb[];
+    /** Why, in the order found. Surfaced to the user so a refusal is explainable. */
+    readonly reasons: readonly string[];
+    /** True when the scan could not resolve something and escalated as a result. */
+    readonly escalated: boolean;
+}
+/**
+ * Reports the extra permission a script needs.
+ *
+ * Call this with the script that will ACTUALLY be sent — after any `{param}`
+ * substitution. Scanning the pre-substitution text is a hole you could drive a
+ * parameter value of `gr.insert()` through.
+ */
+export declare function scanScript(script: string): ScriptScanResult;
+/** Convenience: what a background script needs in total. */
+export declare function requirementForScript(script: string): {
+    verbs: Verb[];
+    reasons: readonly string[];
+};

package/dist/policy/ScanScript.js

@@ -0,0 +1,171 @@
+import { parse } from "acorn";
+/**
+ * Looks at a server-side script and reports what it appears to do.
+ *
+ * ## What this is for
+ *
+ * A background script needs `execute` no matter what. This scan exists to decide
+ * whether it ALSO needs `write` — so a genuinely read-only diagnostic script can run
+ * under `execute` alone, while one containing `gr.insert()` needs both.
+ *
+ * ## What it cannot do — read this before trusting it
+ *
+ * It is unsound, and deliberately so. A server-side script can mutate through routes no
+ * static analysis can follow:
+ *
+ *   - a Script Include: `new global.MyUtil().doThing()` — the write is in another file
+ *   - `gs.eval(someString)`
+ *   - `sn_ws.RESTMessageV2` calling out to anything
+ *   - `workflow.startFlow()`, `gs.getUser().setPreference()`
+ *   - `GlideRecord` reached through a variable this scan never resolves
+ *
+ * So a `write`-free result means "nothing obviously writes", NOT "this cannot write".
+ * That is exactly why `execute` is still required: permitting a script at all is the
+ * real decision, and this scan only narrows what else is needed.
+ *
+ * ## Deny-leaning by construction
+ *
+ * Every case it cannot resolve escalates to `write` rather than passing. A scanner that
+ * defaults permissive on unfamiliar syntax manufactures confidence and is worse than no
+ * scanner — it would let `gr['inse' + 'rt']()` through while looking like it checked.
+ */
+/** Methods that mutate records. Matched on name, on any receiver. */
+const MUTATING_METHODS = new Set([
+    "insert",
+    "update",
+    "updateMultiple",
+    "deleteRecord",
+    "deleteMultiple",
+    "insertWithReferences",
+    "updateWithReferences",
+    "setValue", // stages a change; harmless alone, but never appears without a write
+    "setWorkflow", // disabling business rules is only ever done around a write
+]);
+/** Constructs whose behaviour cannot be known statically. */
+const OPAQUE_CALLS = new Set(["eval", "Function", "GlideEvaluator"]);
+const NONE = { verbs: [], reasons: [], escalated: false };
+function writeResult(reasons, escalated) {
+    return { verbs: ["write"], reasons, escalated };
+}
+/**
+ * Parses with the loosest grammar that works.
+ *
+ * Rhino — what ServiceNow runs server-side — is ES5-era, so most scripts parse at 5.
+ * Newer syntax appears in scripts written against the newer engine, hence the fallback.
+ * If BOTH fail the script is unreadable to us, which escalates rather than passes.
+ */
+function parseScript(script) {
+    for (const ecmaVersion of [5, "latest"]) {
+        try {
+            return { ast: parse(script, { ecmaVersion, silent: true }) };
+        }
+        catch {
+            // try the next grammar
+        }
+    }
+    return { parseError: "could not be parsed" };
+}
+/** Reads a string-valued AST field, or "" when it is anything else. */
+function textOf(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Walks every node without depending on acorn-walk's visitor table. */
+function walk(node, visit) {
+    if (!node || typeof node !== "object") {
+        return;
+    }
+    if (Array.isArray(node)) {
+        for (const child of node) {
+            walk(child, visit);
+        }
+        return;
+    }
+    const record = node;
+    if (typeof record.type === "string") {
+        visit(record);
+    }
+    for (const key of Object.keys(record)) {
+        if (key === "type" || key === "start" || key === "end" || key === "loc") {
+            continue;
+        }
+        walk(record[key], visit);
+    }
+}
+/**
+ * Reports the extra permission a script needs.
+ *
+ * Call this with the script that will ACTUALLY be sent — after any `{param}`
+ * substitution. Scanning the pre-substitution text is a hole you could drive a
+ * parameter value of `gr.insert()` through.
+ */
+export function scanScript(script) {
+    if (typeof script !== "string" || script.trim().length === 0) {
+        return NONE;
+    }
+    const parsed = parseScript(script);
+    if ("parseError" in parsed) {
+        // Unreadable, so unknowable. Escalate.
+        return writeResult(["the script could not be parsed, so its effects are unknown"], true);
+    }
+    const reasons = [];
+    let escalated = false;
+    walk(parsed.ast, (node) => {
+        if (node.type !== "CallExpression") {
+            return;
+        }
+        const callee = node.callee;
+        if (!callee) {
+            return;
+        }
+        // eval(...) / new Function(...) — contents are opaque.
+        const calleeName = textOf(callee.name);
+        if (callee.type === "Identifier" && OPAQUE_CALLS.has(calleeName)) {
+            reasons.push(`calls ${calleeName}(), whose contents cannot be inspected`);
+            escalated = true;
+            return;
+        }
+        if (callee.type !== "MemberExpression") {
+            return;
+        }
+        // gr['inse' + 'rt']() — the property is computed, so the method name is not
+        // knowable. This is the single most likely way to walk past a naive scan.
+        if (callee.computed === true) {
+            const property = callee.property;
+            const isLiteralName = property?.type === "Literal" && typeof property.value === "string";
+            if (!isLiteralName) {
+                reasons.push("calls a method chosen at runtime, which cannot be resolved");
+                escalated = true;
+                return;
+            }
+            const literalName = textOf(property?.value);
+            if (MUTATING_METHODS.has(literalName)) {
+                reasons.push(`calls .${literalName}()`);
+            }
+            return;
+        }
+        const property = callee.property;
+        if (property?.type === "Identifier") {
+            const name = textOf(property.name);
+            if (MUTATING_METHODS.has(name)) {
+                reasons.push(`calls .${name}()`);
+            }
+            if (OPAQUE_CALLS.has(name)) {
+                // gs.eval(...)
+                reasons.push(`calls .${name}(), whose contents cannot be inspected`);
+                escalated = true;
+            }
+        }
+    });
+    if (reasons.length === 0) {
+        return NONE;
+    }
+    return writeResult([...new Set(reasons)], escalated);
+}
+/** Convenience: what a background script needs in total. */
+export function requirementForScript(script) {
+    const scan = scanScript(script);
+    // `execute` always. Running caller-supplied code on the instance is the decision
+    // being made; the scan only decides whether `write` rides along.
+    return { verbs: ["execute", ...scan.verbs], reasons: scan.reasons };
+}
+//# sourceMappingURL=ScanScript.js.map

package/dist/policy/ScanScript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScanScript.js","sourceRoot":"","sources":["../../src/policy/ScanScript.ts"],"names":[],"mappings":"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"}

package/dist/policy/internal/Classify.d.ts

@@ -0,0 +1,16 @@
+import { HTTPRequest } from "../../comm/http/HTTPRequest.js";
+import { Requirement, Verb } from "../PolicyTypes.js";
+/** Matched floor rules, for the audit log and for tests. */
+export declare function floorFor(request: HTTPRequest): {
+    verbs: Verb[];
+    reasons: string[];
+};
+/**
+ * The joined requirement for a request.
+ *
+ * DECLARED replaces the default when present, but the floor is unioned in afterwards so
+ * a declaration can correct a wrong default without ever lowering a floor entry.
+ */
+export declare function classify(request: HTTPRequest): Requirement & {
+    reasons: string[];
+};

package/dist/policy/internal/Classify.js

@@ -0,0 +1,121 @@
+const pathIs = (needle) => (path) => path.split("?")[0].endsWith(needle);
+const pathHas = (needle) => (path) => path.includes(needle);
+/**
+ * Un-lowerable minimums.
+ *
+ * Every entry here exists because the tier-3 default would get it wrong. Adding a new
+ * mutating endpoint that travels as a GET means adding a row here — there is no way to
+ * detect that statically, so it is called out in the contribution checklist and the
+ * audit log is the backstop.
+ */
+const FLOOR = [
+    {
+        why: "background script execution",
+        verbs: ["execute"],
+        matches: (p) => pathIs("/sys.scripts.do")(p),
+    },
+    // NOTE: /xmlhttp.do is deliberately NOT a floor rule, even though the most
+    // destructive call in the library (Application.uninstall) goes through it. The same
+    // endpoint is used to READ — syslog tailing POSTs to it — and a floor rule cannot be
+    // lowered, so listing it here would refuse `nex log` with no way to correct it.
+    // Coverage instead comes from three narrower places: the sysparm_delete_all rule
+    // below catches the uninstall, the tier-3 default makes every other POST a write,
+    // and the two callers that read or execute through it declare so explicitly.
+    {
+        why: "store application install (issued as a GET)",
+        verbs: ["write"],
+        matches: (p) => pathHas("/api/sn_appclient/appmanager/app/install")(p),
+    },
+    {
+        why: "store application update (issued as a GET)",
+        verbs: ["write"],
+        matches: (p) => pathHas("/api/sn_appclient/appmanager/app/update")(p),
+    },
+    {
+        why: "sys_trigger scheduled job — persisting a job outlives the request that made it",
+        verbs: ["write"],
+        matches: (p) => pathHas("/api/now/table/sys_trigger")(p),
+    },
+    {
+        why: "sysparm_delete_all",
+        verbs: ["write"],
+        matches: (_p, q) => "sysparm_delete_all" in q,
+    },
+    {
+        why: "sysparm_delete_when_done",
+        verbs: ["write"],
+        matches: (_p, q) => {
+            const value = q["sysparm_delete_when_done"];
+            if (value === undefined) {
+                return false;
+            }
+            // Only primitives are meaningful here; an object would stringify to
+            // "[object Object]" and match, which would be a false positive.
+            const text = typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+                ? String(value)
+                : "";
+            return text.toLowerCase() !== "false" && text.length > 0;
+        },
+    },
+];
+function normalizeQuery(request) {
+    const out = {};
+    const query = request.query;
+    if (query && typeof query === "object") {
+        for (const [key, value] of Object.entries(query)) {
+            out[key] = value;
+        }
+    }
+    // Some callers put parameters in `fields` (form-encoded) rather than the query
+    // string — Application.uninstall sends sysparm_delete_all that way.
+    const fields = request.fields;
+    if (fields && typeof fields === "object") {
+        for (const [key, value] of Object.entries(fields)) {
+            if (!(key in out)) {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
+}
+/** Matched floor rules, for the audit log and for tests. */
+export function floorFor(request) {
+    const path = typeof request.path === "string" ? request.path : "";
+    const query = normalizeQuery(request);
+    const verbs = new Set();
+    const reasons = [];
+    for (const rule of FLOOR) {
+        if (rule.matches(path, query)) {
+            rule.verbs.forEach((v) => verbs.add(v));
+            reasons.push(rule.why);
+        }
+    }
+    return { verbs: [...verbs], reasons };
+}
+/** Tier 3. GET is assumed to read; anything else is assumed to write. */
+function verbDefault(method) {
+    const verb = (method ?? "get").toLowerCase();
+    return verb === "get" ? [] : ["write"];
+}
+/**
+ * The joined requirement for a request.
+ *
+ * DECLARED replaces the default when present, but the floor is unioned in afterwards so
+ * a declaration can correct a wrong default without ever lowering a floor entry.
+ */
+export function classify(request) {
+    const declared = request.requires;
+    const base = declared ? declared.verbs : verbDefault(request.method);
+    const target = declared?.target ?? "instance";
+    const { verbs: floorVerbs, reasons } = floorFor(request);
+    const verbs = new Set(base);
+    floorVerbs.forEach((v) => verbs.add(v));
+    return {
+        verbs: [...verbs],
+        // A floor match is always about the instance, whatever the caller declared —
+        // otherwise declaring `target: "local"` would be a way to opt out of the floor.
+        target: floorVerbs.length > 0 ? "instance" : target,
+        reasons,
+    };
+}
+//# sourceMappingURL=Classify.js.map