narai-primitives 2.0.0-rc.1

package/dist/toolkit/policy/config.d.ts

@@ -0,0 +1,38 @@
+import { type ApprovalMode, type PolicyRules } from "./types.js";
+export interface LoadedPolicy {
+    rules: PolicyRules;
+    approval_mode: ApprovalMode;
+}
+export interface LoadPolicyConfigOptions {
+    /** Connector name — shapes the discovery path `~/.<name>-agent/config.yaml`. */
+    name: string;
+    /** Aspects that cannot be downgraded to `"success"` by operator config. */
+    floorAspects?: readonly string[];
+    /** Explicit path (overrides discovery). */
+    explicitPath?: string;
+    /** Working directory for the repo-level lookup. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override home dir (tests). Defaults to `os.homedir()`. */
+    home?: string;
+}
+export interface DiscoveredPaths {
+    user?: string;
+    repo?: string;
+}
+export declare function discoverConfigPaths(name: string, cwd?: string, home?: string): DiscoveredPaths;
+/** Recursive per-key merge. Overlay wins on collision; arrays replace wholesale. */
+export declare function deepMerge<T extends Record<string, unknown>>(base: T, overlay: T): T;
+/**
+ * Top-level validator: accepts a parsed YAML mapping with optional `policy`
+ * and `approval_mode` keys, returns a LoadedPolicy. Unknown top-level keys
+ * pass through silently — this lets connectors add their own sections
+ * (e.g., db-agent's `servers`, `audit`) without the toolkit needing to know
+ * about them.
+ */
+export declare function validatePolicyConfig(raw: unknown, floorAspects?: readonly string[]): LoadedPolicy;
+/**
+ * Discover → merge → validate. Returns `null` if no config is found and no
+ * explicit path is provided; caller falls back to defaults.
+ */
+export declare function loadPolicyConfig(opts: LoadPolicyConfigOptions): LoadedPolicy | null;
+//# sourceMappingURL=config.d.ts.map

package/dist/toolkit/policy/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/toolkit/policy/config.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EAGjB,MAAM,YAAY,CAAC;AAgBpB,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,aAAa,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAsB,EAC3B,IAAI,GAAE,MAAqB,GAC1B,eAAe,CAQjB;AAWD,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,GACT,CAAC,CAWH;AAsGD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,YAAY,CAUd;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,uBAAuB,GAC5B,YAAY,GAAG,IAAI,CAkBrB"}

package/dist/toolkit/policy/config.js

@@ -0,0 +1,172 @@
+/**
+ * Operator-facing config loader. Discovers two YAML files for each connector:
+ *
+ *   1. `~/.<name>-agent/config.yaml`   — user-level base
+ *   2. `<cwd>/.<name>-agent/config.yaml` — repo-level overlay (wins on collision)
+ *
+ * Plus an optional explicit path (caller-provided). Returns validated
+ * `PolicyRules` + `ApprovalMode`, or `null` if no config is discovered and no
+ * explicit path is given — callers fall through to `DEFAULT_POLICY` + `"auto"`.
+ *
+ * Safety floor: `admin` can never be `"success"` in config. Connectors can
+ * declare additional floor aspects (e.g., db-agent declares `ddl`, `privilege`);
+ * those aspects are also rejected if set to `"success"`.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { DEFAULT_POLICY, } from "./types.js";
+const VALID_RULES = new Set([
+    "success",
+    "present",
+    "escalate",
+    "denied",
+]);
+const VALID_APPROVAL_MODES = new Set([
+    "auto",
+    "confirm_once",
+    "confirm_each",
+    "grant_required",
+]);
+export function discoverConfigPaths(name, cwd = process.cwd(), home = os.homedir()) {
+    const rel = `.${name}-agent/config.yaml`;
+    const userPath = path.join(home, rel);
+    const repoPath = path.join(cwd, rel);
+    const out = {};
+    if (fs.existsSync(userPath))
+        out.user = userPath;
+    if (fs.existsSync(repoPath))
+        out.repo = repoPath;
+    return out;
+}
+function isPlainObject(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        !Array.isArray(v) &&
+        v.constructor === Object);
+}
+/** Recursive per-key merge. Overlay wins on collision; arrays replace wholesale. */
+export function deepMerge(base, overlay) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(overlay)) {
+        const baseV = base[k];
+        if (isPlainObject(v) && isPlainObject(baseV)) {
+            out[k] = deepMerge(baseV, v);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function readYaml(filePath) {
+    const raw = fs.readFileSync(filePath, { encoding: "utf-8" });
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (exc) {
+        const msg = exc instanceof Error ? exc.message : String(exc);
+        throw new Error(`Failed to parse YAML (${filePath}): ${msg}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (!isPlainObject(parsed)) {
+        throw new Error(`Config must be a YAML mapping (${filePath}), got: ${Array.isArray(parsed) ? "list" : typeof parsed}`);
+    }
+    return parsed;
+}
+function validateRule(field, value, restricted) {
+    if (typeof value !== "string" || !VALID_RULES.has(value)) {
+        throw new Error(`${field}: expected one of [success, present, escalate, denied], got: ${JSON.stringify(value)}`);
+    }
+    const rule = value;
+    if (restricted && rule === "success") {
+        throw new Error(`${field}: 'success' is not permitted (safety floor — cannot be downgraded to success)`);
+    }
+    return rule;
+}
+function validateRules(raw, floorAspects) {
+    if (raw === undefined || raw === null)
+        return { ...DEFAULT_POLICY };
+    if (!isPlainObject(raw)) {
+        throw new Error(`policy: expected an object, got: ${typeof raw}`);
+    }
+    const out = { ...DEFAULT_POLICY };
+    for (const [k, v] of Object.entries(raw)) {
+        switch (k) {
+            case "read":
+                out.read = validateRule("policy.read", v, false);
+                break;
+            case "write":
+                out.write = validateRule("policy.write", v, false);
+                break;
+            case "admin":
+                out.admin = validateRule("policy.admin", v, true);
+                break;
+            case "aspects": {
+                if (!isPlainObject(v)) {
+                    throw new Error(`policy.aspects: expected an object, got: ${typeof v}`);
+                }
+                const aspects = {};
+                const floorSet = new Set(floorAspects);
+                for (const [aspect, rule] of Object.entries(v)) {
+                    aspects[aspect] = validateRule(`policy.aspects.${aspect}`, rule, floorSet.has(aspect));
+                }
+                out.aspects = aspects;
+                break;
+            }
+            default:
+                throw new Error(`policy: unknown key '${k}' (expected: read, write, admin, aspects)`);
+        }
+    }
+    return out;
+}
+function validateApprovalMode(raw) {
+    if (raw === undefined || raw === null)
+        return "auto";
+    if (typeof raw !== "string" || !VALID_APPROVAL_MODES.has(raw)) {
+        throw new Error(`approval_mode: expected one of [auto, confirm_once, confirm_each, grant_required], got: ${JSON.stringify(raw)}`);
+    }
+    return raw;
+}
+/**
+ * Top-level validator: accepts a parsed YAML mapping with optional `policy`
+ * and `approval_mode` keys, returns a LoadedPolicy. Unknown top-level keys
+ * pass through silently — this lets connectors add their own sections
+ * (e.g., db-agent's `servers`, `audit`) without the toolkit needing to know
+ * about them.
+ */
+export function validatePolicyConfig(raw, floorAspects = []) {
+    if (!isPlainObject(raw)) {
+        throw new Error(`config: expected a YAML mapping at root, got: ${typeof raw}`);
+    }
+    return {
+        rules: validateRules(raw["policy"], floorAspects),
+        approval_mode: validateApprovalMode(raw["approval_mode"]),
+    };
+}
+/**
+ * Discover → merge → validate. Returns `null` if no config is found and no
+ * explicit path is provided; caller falls back to defaults.
+ */
+export function loadPolicyConfig(opts) {
+    const floor = opts.floorAspects ?? [];
+    if (opts.explicitPath !== undefined && opts.explicitPath.length > 0) {
+        if (!fs.existsSync(opts.explicitPath)) {
+            throw new Error(`Config file not found: ${opts.explicitPath}`);
+        }
+        return validatePolicyConfig(readYaml(opts.explicitPath), floor);
+    }
+    const paths = discoverConfigPaths(opts.name, opts.cwd, opts.home);
+    if (paths.user === undefined && paths.repo === undefined)
+        return null;
+    let merged = {};
+    if (paths.user !== undefined)
+        merged = deepMerge(merged, readYaml(paths.user));
+    if (paths.repo !== undefined)
+        merged = deepMerge(merged, readYaml(paths.repo));
+    return validatePolicyConfig(merged, floor);
+}
+//# sourceMappingURL=config.js.map

package/dist/toolkit/policy/config.js.map

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

package/dist/toolkit/policy/gate.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure rule → Decision mapping. Stateless; approval-mode state lives in
+ * `./approval.ts` (the factory wires it up per connector invocation).
+ *
+ * Rule combination: kind rule is the base; each aspect rule (if declared)
+ * applies on top via Rule strictness (denied > escalate > present > success).
+ * Note: Rule "present" collapses to Decision "escalate" — extendDecision
+ * hooks intercept escalate to emit ExtendedEnvelope.
+ * Ties go to the first offender so the `reason` message is predictable.
+ */
+import type { ApprovalMode, Classification, Decision, PolicyRules } from "./types.js";
+/** Minimal state needed for approval-mode resolution. Pure-data. */
+export interface ApprovalState {
+    sessionApproved: boolean;
+    hasActiveGrant: (grantType: string) => boolean;
+}
+/**
+ * Evaluate a classification against rules + approval mode, returning a
+ * decision. No side effects — the caller is responsible for emitting audit
+ * events (see `../audit/writer.ts`).
+ */
+export declare function checkPolicy(classification: Classification, rules: PolicyRules, approvalMode: ApprovalMode, approvalState: ApprovalState): Decision;
+/**
+ * Combine multiple per-call decisions (e.g., db-agent classifies each SQL
+ * statement separately). Strictest decision wins; ties by first occurrence.
+ */
+export declare function combineDecisions(decisions: readonly Decision[]): Decision;
+//# sourceMappingURL=gate.d.ts.map

package/dist/toolkit/policy/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/toolkit/policy/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,WAAW,EAEZ,MAAM,YAAY,CAAC;AAWpB,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,cAAc,EAAE,cAAc,EAC9B,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,aAAa,GAC3B,QAAQ,CA0CV;AAuCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,CAYzE"}

package/dist/toolkit/policy/gate.js

@@ -0,0 +1,126 @@
+import { DECISION_RANK } from "./types.js";
+/** Strictness rank for combining Rule values (same order as DECISION_RANK). */
+const RULE_RANK = {
+    success: 0,
+    present: 1,
+    escalate: 2,
+    denied: 3,
+};
+/**
+ * Evaluate a classification against rules + approval mode, returning a
+ * decision. No side effects — the caller is responsible for emitting audit
+ * events (see `../audit/writer.ts`).
+ */
+export function checkPolicy(classification, rules, approvalMode, approvalState) {
+    const kind = classification.kind;
+    const kindRule = rules[kind];
+    // Combine kind rule with the strictest matching aspect rule.
+    let combinedRule = kindRule;
+    let strictestReasonSource = "kind";
+    let offendingAspect = null;
+    if (classification.aspects && rules.aspects) {
+        for (const aspect of classification.aspects) {
+            const aspectRule = rules.aspects[aspect];
+            if (aspectRule === undefined)
+                continue;
+            if (RULE_RANK[aspectRule] > RULE_RANK[combinedRule]) {
+                combinedRule = aspectRule;
+                strictestReasonSource = "aspect";
+                offendingAspect = aspect;
+            }
+        }
+    }
+    // Map the combined rule to a decision.
+    switch (combinedRule) {
+        case "denied":
+            return { status: "denied", reason: denyReason(kind, strictestReasonSource, offendingAspect) };
+        case "escalate":
+            return {
+                status: "escalate",
+                reason: escalateReason(kind, strictestReasonSource, offendingAspect),
+            };
+        // Rule "present" collapses to Decision "escalate" in toolkit 3.0;
+        // extendDecision hooks (e.g. db-agent) intercept escalate to emit
+        // a connector-specific ExtendedEnvelope.
+        case "present":
+            return { status: "escalate", reason: presentReason(kind, strictestReasonSource, offendingAspect) };
+        case "success":
+            // A "success" rule for reads still has to pass the approval mode gate.
+            if (kind === "read") {
+                return resolveApprovalMode(approvalMode, approvalState);
+            }
+            return { status: "success", reason: `${kind} allowed by policy` };
+    }
+}
+/**
+ * Read-specific: given that policy says "success", apply the approval-mode
+ * state machine.
+ *
+ *  - auto: always success
+ *  - confirm_once: escalate until sessionApproved, then success
+ *  - confirm_each: always escalate
+ *  - grant_required: success iff hasActiveGrant("read"), else denied
+ */
+function resolveApprovalMode(mode, state) {
+    switch (mode) {
+        case "auto":
+            return { status: "success", reason: "auto-approved" };
+        case "confirm_once":
+            if (state.sessionApproved) {
+                return { status: "success", reason: "session approved" };
+            }
+            return {
+                status: "escalate",
+                reason: "First read requires confirmation (confirm_once)",
+            };
+        case "confirm_each":
+            return {
+                status: "escalate",
+                reason: "Each read requires confirmation (confirm_each)",
+            };
+        case "grant_required":
+            if (state.hasActiveGrant("read")) {
+                return { status: "success", reason: "active read grant" };
+            }
+            return { status: "denied", reason: "No active read grant" };
+    }
+}
+/**
+ * Combine multiple per-call decisions (e.g., db-agent classifies each SQL
+ * statement separately). Strictest decision wins; ties by first occurrence.
+ */
+export function combineDecisions(decisions) {
+    if (decisions.length === 0) {
+        throw new Error("combineDecisions requires at least one decision");
+    }
+    let winner = decisions[0];
+    for (let i = 1; i < decisions.length; i++) {
+        const d = decisions[i];
+        if (DECISION_RANK[d.status] > DECISION_RANK[winner.status]) {
+            winner = d;
+        }
+    }
+    return winner;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Reason builders — stable strings so tests/evals can assert on them.
+// ───────────────────────────────────────────────────────────────────────────
+function denyReason(kind, source, aspect) {
+    if (source === "aspect" && aspect !== null) {
+        return `${aspect} aspect is denied by policy`;
+    }
+    return `${kind} is denied by policy`;
+}
+function escalateReason(kind, source, aspect) {
+    if (source === "aspect" && aspect !== null) {
+        return `${aspect} aspect requires approval`;
+    }
+    return `${kind} requires approval`;
+}
+function presentReason(kind, source, aspect) {
+    if (source === "aspect" && aspect !== null) {
+        return `${aspect} aspect is displayed but not executed`;
+    }
+    return `${kind} is displayed but not executed`;
+}
+//# sourceMappingURL=gate.js.map

package/dist/toolkit/policy/gate.js.map

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

package/dist/toolkit/policy/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Approval-gate type system. Shared across every connector.
+ *
+ * Wire formats are lowercase string literals so JSON round-trips without a
+ * codec step. The canonical envelope `status` is `success | denied | escalate
+ * | error`; connectors MAY extend with custom status values via the
+ * `extendDecision` hook on `createConnector` (db-agent uses `present_only`).
+ */
+/** The CRUD-ish base axis every connector classifies into. */
+export type Kind = "read" | "write" | "admin";
+/**
+ * Kind plus optional connector-specific aspects (free-form strings).
+ * Aspects layer on top of kind for finer gating (e.g. `unbounded_select`,
+ * `source_code`, `pii`, `bulk_read`). Rule lookup applies kind first, then
+ * the strictest aspect rule that matches wins.
+ */
+export interface Classification {
+    kind: Kind;
+    aspects?: readonly string[];
+}
+/** Wire rules operators set per classification. */
+export type Rule = "success" | "present" | "escalate" | "denied";
+/** Rule without `"success"` — used for safety-floor slots (admin, ddl, privilege). */
+export type RestrictedRule = Exclude<Rule, "success">;
+export interface PolicyRules {
+    read: Rule;
+    write: Rule;
+    admin: RestrictedRule;
+    /** Per-aspect rule map. Absent aspects fall through to the kind's rule. */
+    aspects?: Record<string, Rule>;
+}
+export type ApprovalMode = "auto" | "confirm_once" | "confirm_each" | "grant_required";
+/** Defaults matching db-agent's historical behavior, generalized to CRUD. */
+export declare const DEFAULT_POLICY: PolicyRules;
+/**
+ * A gate decision. `extendDecision` hooks (e.g., db-agent's `present_only`)
+ * widen this by returning an envelope with additional fields; the base
+ * discriminants are fixed.
+ */
+export type Decision = {
+    status: "success";
+    reason: string;
+} | {
+    status: "denied";
+    reason: string;
+} | {
+    status: "escalate";
+    reason: string;
+};
+/** Strictness rank for combining multiple decisions (denied wins). */
+export declare const DECISION_RANK: Record<Decision["status"], number>;
+/** Canonical 7-code error taxonomy used across every connector. */
+export type ErrorCode = "AUTH_ERROR" | "NOT_FOUND" | "RATE_LIMITED" | "TIMEOUT" | "VALIDATION_ERROR" | "CONFIG_ERROR" | "CONNECTION_ERROR";
+/** Success envelope — data payload is connector-specific. */
+export interface SuccessEnvelope {
+    status: "success";
+    action: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Resolution hint attached to non-success envelopes when a curated hardship
+ * pattern matches. Task 6.2 attaches these at runtime.
+ */
+export interface ResolutionHint {
+    pattern_id: string;
+    advice: string;
+    confidence: number;
+    scope: "tenant" | "global";
+}
+/** Gate-deny envelope. */
+export interface DeniedEnvelope {
+    status: "denied";
+    action: string;
+    reason: string;
+    resolution_hint?: ResolutionHint;
+}
+/** Gate-escalate envelope. */
+export interface EscalateEnvelope {
+    status: "escalate";
+    action: string;
+    reason: string;
+    resolution_hint?: ResolutionHint;
+}
+/** Runtime error envelope. */
+export interface ErrorEnvelope {
+    status: "error";
+    action: string;
+    error_code: ErrorCode;
+    message: string;
+    retriable: boolean;
+    resolution_hint?: ResolutionHint;
+}
+/**
+ * Connector-extended envelope. `extendDecision` hooks may emit custom status
+ * values (e.g., `present_only`). The `extension` field carries the
+ * connector-specific payload; arbitrary extra fields are accessed via cast.
+ */
+export interface ExtendedEnvelope {
+    status: string;
+    action: string;
+    message?: string;
+    extension: Record<string, unknown>;
+    resolution_hint?: ResolutionHint;
+}
+export type Envelope = SuccessEnvelope | DeniedEnvelope | EscalateEnvelope | ErrorEnvelope | ExtendedEnvelope;
+//# sourceMappingURL=types.d.ts.map

package/dist/toolkit/policy/types.d.ts.map

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

package/dist/toolkit/policy/types.js

@@ -0,0 +1,22 @@
+/**
+ * Approval-gate type system. Shared across every connector.
+ *
+ * Wire formats are lowercase string literals so JSON round-trips without a
+ * codec step. The canonical envelope `status` is `success | denied | escalate
+ * | error`; connectors MAY extend with custom status values via the
+ * `extendDecision` hook on `createConnector` (db-agent uses `present_only`).
+ */
+/** Defaults matching db-agent's historical behavior, generalized to CRUD. */
+export const DEFAULT_POLICY = {
+    read: "success",
+    write: "present",
+    admin: "denied",
+    aspects: {},
+};
+/** Strictness rank for combining multiple decisions (denied wins). */
+export const DECISION_RANK = {
+    success: 0,
+    escalate: 1,
+    denied: 2,
+};
+//# sourceMappingURL=types.js.map

package/dist/toolkit/policy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/toolkit/policy/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA4CH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,cAAc,GAAgB;IACzC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,EAAE;CACZ,CAAC;AAgBF,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAuC;IAC/D,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;CACV,CAAC"}

package/dist/toolkit/security_check.d.ts

@@ -0,0 +1,15 @@
+export { FETCH_MAX_BYTES_DEFAULT, FETCH_TIMEOUT_MS_DEFAULT, FetchCapExceeded, fetchWithCaps, type FetchCapsOptions, } from "./fetch_helper.js";
+/**
+ * Check that a URL uses an allowed scheme (http or https only).
+ */
+export declare function validateUrl(url: string): boolean;
+/**
+ * Verify that `p` resolves to a location inside `wikiRoot`.
+ * Symlinks are resolved before the prefix comparison, to prevent traversal.
+ */
+export declare function checkPathContainment(p: string, wikiRoot: string): boolean;
+/**
+ * Sanitize a label by stripping control characters, capping length, and HTML-escaping.
+ */
+export declare function sanitizeLabel(label: string, maxLength?: number): string;
+//# sourceMappingURL=security_check.d.ts.map

package/dist/toolkit/security_check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security_check.d.ts","sourceRoot":"","sources":["../../src/toolkit/security_check.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACb,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAI3B;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUhD;AA+CD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWzE;AAkBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,CAK5E"}

package/dist/toolkit/security_check.js

@@ -0,0 +1,109 @@
+/**
+ * security_check — URL validation, path containment, and label sanitization.
+ *
+ * Re-exports the fetch-cap symbols from `fetch_helper` so the two
+ * security-baseline knobs live under one import at call sites.
+ * `fetch_helper` remains the canonical owner; update the numbers there.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export { FETCH_MAX_BYTES_DEFAULT, FETCH_TIMEOUT_MS_DEFAULT, FetchCapExceeded, fetchWithCaps, } from "./fetch_helper.js";
+const ALLOWED_SCHEMES = new Set(["http", "https"]);
+/**
+ * Check that a URL uses an allowed scheme (http or https only).
+ */
+export function validateUrl(url) {
+    if (!url) {
+        return false;
+    }
+    const match = url.match(/^([A-Za-z][A-Za-z0-9+.\-]*):/);
+    if (!match || match[1] === undefined) {
+        return false;
+    }
+    const scheme = match[1].toLowerCase();
+    return ALLOWED_SCHEMES.has(scheme);
+}
+/**
+ * Best-effort realpath that mirrors Python's pathlib.Path.resolve(strict=False).
+ *
+ * Resolves existing symlinks in the path even when the full path does not
+ * exist: walks up from the target until finding an existing ancestor,
+ * realpaths it, then re-appends the non-existent tail.
+ *
+ * TOCTOU note: this function calls `existsSync` / `lstatSync` and then
+ * `realpathSync.native` as two distinct system calls. On POSIX there is
+ * no atomic replacement (Node's fs API does not expose `openat` /
+ * `O_NOFOLLOW`), so on a shared host a malicious local user could swap
+ * a parent directory between the two calls and defeat path containment
+ * checks built on top of this function. Callers must run this helper in
+ * a directory hierarchy under their own control — a developer workstation
+ * or a CI runner with a private filesystem. If multi-user isolation is
+ * required, sandbox the toolchain (container, user namespace, etc.)
+ * rather than relying on this function to police the filesystem.
+ */
+function bestEffortRealpath(p) {
+    const abs = path.resolve(p);
+    const tail = [];
+    let cur = abs;
+    while (cur && cur !== path.dirname(cur)) {
+        let entryExists = fs.existsSync(cur);
+        if (!entryExists) {
+            try {
+                fs.lstatSync(cur);
+                entryExists = true;
+            }
+            catch {
+                /* path truly absent; continue walking up */
+            }
+        }
+        if (entryExists) {
+            const real = fs.realpathSync.native(cur);
+            if (tail.length === 0) {
+                return real;
+            }
+            return path.join(real, ...tail.reverse());
+        }
+        tail.push(path.basename(cur));
+        cur = path.dirname(cur);
+    }
+    return abs;
+}
+/**
+ * Verify that `p` resolves to a location inside `wikiRoot`.
+ * Symlinks are resolved before the prefix comparison, to prevent traversal.
+ */
+export function checkPathContainment(p, wikiRoot) {
+    try {
+        const resolvedPath = bestEffortRealpath(p);
+        const resolvedRoot = bestEffortRealpath(wikiRoot);
+        return (resolvedPath.startsWith(resolvedRoot + path.sep) ||
+            resolvedPath === resolvedRoot);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * HTML-escape a string the same way Python's html.escape(s, quote=True) does.
+ * Ampersand must be escaped first so subsequent replacements don't double-escape.
+ */
+function htmlEscape(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#x27;");
+}
+// Regex matching Unicode general-category "Cc" (control chars): U+0000..U+001F, U+007F..U+009F.
+const CONTROL_CHARS_RE = /[\u0000-\u001F\u007F-\u009F]/g;
+/**
+ * Sanitize a label by stripping control characters, capping length, and HTML-escaping.
+ */
+export function sanitizeLabel(label, maxLength = 256) {
+    let cleaned = label.replace(CONTROL_CHARS_RE, "");
+    cleaned = cleaned.slice(0, maxLength);
+    cleaned = htmlEscape(cleaned);
+    return cleaned;
+}
+//# sourceMappingURL=security_check.js.map